Hi Stefan,

Stefan Sperling wrote on Mon, Oct 14, 2019 at 11:14:22AM +0200:

> I am considering adding some diagrams to got.1.

In general, this is discouraged.  Often, indented lists or tables
can save the needed purpose better.

For very complicated software, there may be exceptions, though.
I see how got(1) might be such a case.

> Is there a nice way of drawing ASCII diagrams in man pages?

For diagrams, the classical solution for drawing diagrams used to
be pic(1), a version of which is now contained in the textproc/groff
package.

You cannot use it for manual pages, though.  Mandoc does not support
it at all, and even people using other man(1) implementations with
the groff(1) rendering backend will almost never have their system
configured in a way that will make it work.  Besides, even when
optimally configured, it can only produce PostScript output, and
maybe dvi, and potentelly some very low-quality HTML, but certainly
not console output.

UTF-8 box drawing characters won't help here either, i fear,
because you appear to need diagonal lines.  Besides, they are
declared obsolete by Unicode, incomplete and unmaintained.

> For reference, below are a few example diagrams extracted from
> 'svn help merge' which illustrate the use cases of various ways
> of merging with Subversion.
> 
> Could similar diagrams be achieved in mdoc?

Well, more or less:

.Bl -dash
.It
The 'Feature Branch' Merging Pattern
.Bd -literal
parent --+----------o------o-o-------------o--
          \e            \e           \e      /
           \e          merge      merge  merge
            \e            \e           \e  /
feature      +--o-o-------o----o-o----o-------
.Ed
.It
Sync Merge Example
.Bd -literal

I admit that isn't very pretty, but it kind of works.

> Would they render well in all possible output formats or would
> there be limitations?

They would render the obvious way in ASCII and UTF-8, somewhat
uglily (ASCII art in fixed-width typewriter font, like on the
terminal) in PostScript and PDF, and as <pre> in HTML, with no
limitations obvious to me.

> If mdoc won't work, I can simply add supplementary documentation
> to the web site, so no worries if there's no good solution.

I would urge to put all reference documentation into the manual
page and not parts of it elsewhere, like on the web, for the
well-known reasons.

The examples you provided seem clear enough as ASCII art that they
can go into a manual page, in these or similar forms (still use
pictures sparingly, lest they make the descrption unwieldy and
harm conciseness; but you can use them where they really help
visualization.)

If you want to provide a website that provides nice HTML (SVG?)
versions of the same pictures, that's fine.  If people use a GUI
while using the manual (not all do), they can have a graphical
browser open side by side while reading.  That website can be
referenced below SEE ALSO.  Having such a website is not critical,
though, and looking at it must not be required for fully understanding
the complete functionality of the program.

Yours,
  Ingo