Re: [groff] groff as the basis for comprehensive documentation?

[Ingo Schwarze]

Hi Nate,

Nate Bargmann wrote on Wed, Apr 18, 2018 at 08:28:29PM -0500:

> I now looked at mandoc's man(1) page again and the '-l' option is
> explained as you have used it here.  Somehow I missed that the other day
> and had tried '-m' and '-M' to no avail.  Then I managed to construct a
> directory local .db and could read my test file.
> 
> Perhaps an example would be a benefit.  I often check the EXAMPLE
> section of pages as I'm the sort that gets more out of working example
> than even a good explanation.

I agree that EXAMPLES can often be useful, but as anything else
in documentation, they are not a cure-all.  They are useful for:

 - complicated or non-obvious combinations of functionalities
   that are particularly useful but far separated in the reference
   description
 - supplementing the description of syntax or semantics that is
   already unusually complicated even when not combining it with
   anything else
 - showing recommended coding idioms, in particular when insecure
   or cumbersome usage is widespread

But the -l option does exactly one thing that is easily described
in one short sentence that can hardly be misunderstood ("The name
arguments are interpreted as filenames").  In practice, it is rarely
combined with other features: most other options and arguments lose
their effect when combined with -l.  In such a simple situation, i
would consider an example detrimental.  It would merely repeat the
description and harm conciseness.

> I'll admit to not being a 'man' power user.  I use it to quickly
> pull up a page

Don't worry; the man(1) command is intended to be easy to use for
people in a hurry, for people who think hard about something else,
and for novice users.  If man(1) requires expertise to be usable,
something has gone wrong.  That said, no doubt it also has features
catering to the needs of very experienced programmers, but there
is nothing wrong with not using those.

> and don't even think of 'apropos' or the other command line
> options.  Like a lot of us, I'm probably lazy in all the wrong
> areas.

That are many options an average user rarely needs, even though
i have been working hard to reduce the number of options of low
usefulness.  The apropos(1) command, however, is a very helpful
tool, and learning to use it provides great value to both
novice and experienced users.

> I know we're veering off topic for this list.

While the main strength of groff(1) is no doubt high-quality
typesetting, i guess nowadays, more people are using it to read
manual pages than for typesetting work, and i think that most
users are not even aware they are using it.  There is nothing
wrong with that, the man(1) command ought to be simple to use.
Keeping it so requires that developers working on groff remain
aware of the requirements for manual-page display.

For that reason, my impression is that most members of this list
probably regard discussions related to manual pages as on-topic,
even if not related to typesetting.

Yours,
  Ingo