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

[Ingo Schwarze]

Hi Nate,

Nate Bargmann wrote on Thu, Apr 19, 2018 at 02:19:04PM -0500:
> * On 2018 19 Apr 13:13 -0500, Ingo Schwarze wrote:

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

> As it has been a few days since I first read mandoc's man(1) page (does
> that make sense?), thinking about it, it may be that the first sentence
> of -l's description is, "A synonym for mandoc(1) -a."  I honestly don't
> recall if I simply stopped reading there and went on to other options or
> closed that page and opened mandoc(1) to look at the -a option.

Ouch.

> As I have looked at it again, as the primary purpose of -l, as I now
> understand it, is found in the second and third sentences, then the
> first sentence should be moved after them at the very least or to the
> end of the description.

Not quite.

Look at the options -f, -k, and -l.  They all start with "a synonym
for", and that is important because these three options make man(1)
behave like other commands that were historically separate: whatis(1),
apropos(1), and mandoc(1).  Saying so up front is crucial because the
one or two sentences following each "synonym" statement merely give
an extremely superficial summary of the purpose of these commands.
To fully understand how to use them, you really need the dedicated
manual pages.  So "A synonym for mandoc(1)" must not be moved to the
end, it is the most important part of the description.

> When I look at mandoc(1), the -a option is described as the output being
> paginated with more if the output device is stdout.  As I read it, it is
> only concerned with output, not file input.

Right, -a means "show all" which traditionally implies two aspects:

 (1) Do not exit after the first matching page.
 (2) Really "show", i.e. with a pager, rather than the default output
     behaviour, which is, for example, printing to stdout for mandoc(1)
     and merely listing title lines for apropos(1).

Now for man(1), aspect 2, using a pager, is the default anyway,
while for mandoc(1), aspect 1, processing all files, is the default
anyway.  So even though -a always does the same, what needs to be
said about it in the man(1) and mandoc(1) manual pages sounds
substantially different if you are not aware of the big picture.

> I hope you can see where I got off track.  Perhaps rearranging the
> description of man(1)'s -l option will help others in the future.

I committed a fix to make the misunderstanding you suffered from
less likely, see the commit at the end of this mail.

Thanks for explaining where your confusion came from.  As a developer
knowing the software inside out, you indeed have a little chance to
find such issues.  The help of new users is required for this kind
of improvements.

Yours,
  Ingo


Log Message:
-----------
Tweak the description of -l:

Avoid the misunderstanding that the essential purpose of -l is 
similar to the purpose of the -a option in mandoc(1), which is not 
the point: the fact that -l implies -a is merely a minor detail. 
The point of -l is to make man(1) behave like mandoc(1).
Move the mention of -a to the end to de-emphasize it.

Nate Bargmann reported that this seriously confused him, 
and i can see why.

Modified Files:
--------------
    mandoc:
        man.1

Revision Data
-------------
Index: man.1
===================================================================
RCS file: /home/cvs/mandoc/mandoc/man.1,v
retrieving revision 1.32
retrieving revision 1.33
diff -Lman.1 -Lman.1 -u -p -r1.32 -r1.33
--- man.1
+++ man.1
@@ -114,8 +114,7 @@ manual.
 By default, it displays the header lines of all matching pages.
 .It Fl l
 A synonym for
-.Xr mandoc 1
-.Fl a .
+.Xr mandoc 1 .
 The
 .Ar name
 arguments are interpreted as filenames.
@@ -127,6 +126,8 @@ No search is done and
 and
 .Fl w
 are ignored.
+This option implies
+.Fl a .
 .It Fl M Ar path
 Override the list of standard directories which
 .Nm