Re: [Groff] Nesting font macros in man pages

[Steffen Nurpmeso]

"G. Branden Robinson" <address@hidden> wrote:
 |At 2017-04-24T18:29:57+0200, Ingo Schwarze wrote:
 ...
 |I entirely agree with the virtues of semantic of "presentation"-based
 |markup.  However, this could be mitigated by encouraging a consistent
 |style in groff_man(7) itself.  Some coordination with Michael Kerrisk et

I don't think this will work.  Only in an ideal work.

 |al. of the man-pages project would be valuable as well; I think almost
 |all of the advice in man-pages(7) of that package is very sound.

I think at least the structural information guidelines should
somehow end up in the roff_man(7) that ships with roff in the end,
it would mirror what there is roff_mdoc(7).

  ...
 |People keeep writing in man(7).  Let's do what we can to help them write
 |it better.

 |I submit that one reason mdoc didn't take over the world is for the same
 |reason DocBook didn't--it's too huge.  I think that man(7), even with
 |the an-ext stuff added on, is small enough to keep in one's head.
  ...
 |Of course what we need is a converter that goes in the other direction;
 |but that requires the encoding of semantic information that is lacking.

Self-describing macro names may be helpful.
In my opinion mdoc is gross and terrible, and you cannot even use
it to document C code very nicely.  But it has semantic
information and that is necessary for good manuals in a generic
language; you can very well create your own macros and process
them with scripts and tools to create the necessary environment,
but that is not generic.

Currently i think the future is some rich-text thing like asciidoc
or similar, and what would be needed would be good converters to
roff, and then mdoc not man, because it keeps at least a bit of
semantic information.  Or a completely new roff manual language.

I for one keep being disappointed when i see how much work is put
into books and articles, with footnotes, TOC, index, etc.  It
would be nice if you could run mandb and get a real book, cross-
referenced, with index, even better than what texinfo is or was.

 |I'd like to see what we can achieve by fiddling with it _without_
 |harming its portability.  Even as small as man(7) is, people neglect a
 |lot of its capabilities.

Yes, i think people mostly do it by copying over and/or looking
into manual pages they think look good, rather than by reading the
manual, or bying a good tutorial book that leads them step-by-step, 
but fast!, to good results.  That is the material world baby, you
want the burger royal with fifteen, whereas a Ayurveda masseur has
to sit beside his master and wait for i think seven years before
he gets his hands at the subject.

--steffen