On Mon, Oct 14, 2019 at 01:52:56PM +0200, Ingo Schwarze wrote:
> 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.

Users are literally using the tool to manipulate graphs of commits.
Not lists or tables of commits, but DAGs. If users cannot visualize
this, they won't be able to make the most effective use of the tool.

> > 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.

Thanks, I will try this out.

> 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.

Ack.

> 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.)

They would be used very sparingly, of course.