Re: [groff] mom manpage

[G. Branden Robinson]

At 2018-12-11T17:42:49+0100, Ingo Schwarze wrote:
> Hi Branden,

Hello again!

> G. Branden Robinson wrote on Tue, Dec 11, 2018 at 10:11:02AM -0500:
> I fully agree that less(1) is essential for man(1) display.
> Not only because it allows moving backwards, but even more so
> because it allows searching in ctags(1) style with the ":t", "t",
> and "T" less(1) commands, which is a very powerful tool that should
> no longer be withheld from users.

Whoa.  I'm totally Keanu Reevesing here.  Now that you've taught be
about this, I very much want to play with it.

> However, alphabetical ordering of lists is still very important.
> It has at least four critical functions:
> 
>  1. It allows the reader to see at once, without any effort, whether
>     or not a given option exists, by inspecting the adjacent entries.
[...]

Oh, definitely.  There is great power in proving that Russell's teapot
does not exist.  ;-)

>  2. Searching is substantially harder than being able to look up
>     something in alphabetical order.  Consider looking for "set",
>     "test", "wait" etc. in a shell manual page.
[...]

Also true.

>  3. For the reader, alphabetical ordering makes the content of the
>     manual page more predictable and less surprising.  It exposes
>     the reader less to possible whims of the author(s), or to mere
>     randomness that developed from historical growth.  Surprises
>     are always distracting and hence bad in manual pages.

Up to a point, sure.  On the other hand, I wouldn't sort the _section
headings_ in alphabetical order.

>  4. It substantially eases maintenance because it helps a lot to
>     avoid introducing duplicate information - and even more so to
>     spot accidentally introduced duplicates.
[...]

The above are all good arguments.  Not invulnerable, but pretty strong.

> Each of these four points is more important than any subtle message
> that could implicitly be conveyed by some arbitrary ordering.  That
> ordering by importance or typical order of usage in a program could
> make using the feature or even reading the documentation easier is
> mostly an illusion.  Reordering doesn't turn a reference manual
> into a tutorial.  In a short manual, order matters little for
> readability.  In a long manual, many important parts will still be
> far away from the beginning.  For example, in groff_man(7), the
> font alternating macros are now near the end of the list, even
> though they are the most frequently occurring macros in manual
> pages, and even though their explanation is particularly important
> because how to use them well is not quite intuitive.  And reference
> manuals are rarely read sequentially from beginning to end anyway.

I have two defenses of my choices in the Great Groff_Man(7) Rewrite:

1. The ordering of the macro presentation sections is top-down; from the
highest level of organization (document), to paragraph, to phrase
(MT/ME, UR/UE) and ultimately (potentially) the individual
character--the font style macros.

2. Mindful of your admonitions against tutorials mixing with reference
material, I've carefully marked portions of the groff_man(7) sources
with editorial comments indicated what should be pulled out into a
separate groff man tutorial document that I have inchoate plans to
write.

I'd like to have a savagely terse description of our man macro package,
but not at the cost of knocking out of reach some guidance and advice
that man page writers desperately need.

Prior to my reorganization, the order of the first several macros
presented to the reader was:

.EX
.EE (yes, in that order)
.HP (groan)
.IP
.LP
.PP
.P
.RE
.RS (yes, in that order)
.SH
.SS
.TH
.TP
.TQ

Other macros were relegated to subsequent sections, so important as the
font style macros may be, they weren't leading the discussion then,
either; instead we had a mostly-alphabetic list and even that rule was
inconsistently followed for paired macros.

However, I think you're critiquing my reorganization vis à vis an ideal
man page, rather than attempting a defense of the 1.22.3 version of the
page.  And that's fine; I'm not sure anyone _wants_ to defend the status
quo ante.

> Of course, stick to the standard ordering of standard sections,

Our man pages struggle with that, too.  Cleaning it up is yet another
item on my to-do list.  I've avoided it to date (except in groff_man(7))
because moving material around creates huge diffs that can conceal other
changes.  It also can make "git blame" misleading.

Just recently I saw you despairing over how some incorrect information
snuck in to groff_mom(7) under the cover of a huge change that Bernd
made.  My commit messages tend to be long because I strive for full,
honest disclosure.  I do sometimes adjust empty requests without
explicitly noting the fact, because I'm not sure what tests the team's
patience more--explaining why I'm adding or removing an empty request,
or treating it as understood and leaving it unwritten.  (The reason is
simple: consistency with the nowhere-documented style of the groff man
page corpus.)

> As to splitting the list of macros into categories - i wouldn't
> have done it that way and find it slightly unusual, hence somewhat
> distracting, but with the alphabetical list up front, which mostly
> satisfies the points above (admittedly only partially addressing
> points 3 and 4), i consider it acceptable.

I had feared much worse.  :)

Regards,
Branden

signature.asc
Description: PGP signature