Re: [groff] mom manpage

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Tue, Dec 11, 2018 at 06:52:34PM -0500:
> At 2018-12-11T17:42:49+0100, Ingo Schwarze wrote:

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

To check it out, there are three options:

 * If you want to try it natively on a Linux distro which has it
   enabled by default, Void Linux is probably the best choice (though
   i admit i never used Void Linux, so i can't say how well it
   works).  Alpine Linux should also have it enabled by default,
   but in an older version - which matters here, as work is still
   progressing in this area.

 * Of course, you always get the newest version on OpenBSD-current;
   currently, that has some relevant improvements even compared
   to Void Linux, the second best system in this respect.

 * On any system, you can install mandoc as a package or self-compiled.
   If you pay attention to set the configure.local BINM_MAN variable
   during ./configure (see the INSTALL file and configure.local.example)
   or if the packager on your system has done so for you (for
   example, the Debian package sets BINM_MAN=mman) you can use the
   mandoc implementation of man(1) in parallel to your native man(1)
   without both interfering with each other.

Tell me if you run into any trouble, many things can be fixed, but
there are some that i never hear about...

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

No, absolutely not.  The conventional order has merit, and so has the
option to insert custom sections where needed.  As i said, text should
not be ordered alphabetically.  Alphabetic ordering only applies
to certain kinds of lists.

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

Right, as you noticed, i don't strongly disagree with it.  I do think
that overall, it clearly made the page better.

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

We actually already maintain two manual pages for the man(7) language:

The groff_man(7) manual page is directed towards authors who are
about to write new documentation in the man language, consequently
organizing the macros by function to make it easier to find macros
for a given purpose.  Your upcoming tutorial is likely to further
improve support for such tasks.

The man(7) manual page in the mandoc distribution is directed towards
people who need to understand the code in legacy man-language pages,
for example to make minor maintenance edits without changing the
language used.  Consequently, it is ordered alphabetically to make
lookup of macros easy that are found in an existing page, but it
deliberately gives little stylistic advice, and it begins with this
paragraph:

  The man language was the standard formatting language for AT&T UNIX
  manual pages from 1979 to 1989.  Do not use it to write new manual
  pages: it is a purely presentational language and lacks support for
  semantic markup.  Use the mdoc(7) language, instead.

It's probably not such a bad thing to have these two distinct
documents, as long as we make sure they agree on the facts.
Slightly different advice on style is probably not a problem,
it reflects the spectrum of opinions among documentation tool
maintainers.

Of course, we should try to avoid major contraditions, if we can,
like that thing about bold or italic command names, in order to not
confuse users.

By the way, there appear to be a number of errors in man(7)...
I'll have to do some cleanup work there.  I tend to neglect the
page somewhat and focus on the mdoc(7) page instead.

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

Right, it is not urgent, and moving large chunks of text around should
not be done lightly for the reasons you state.  Then again, in many
cases, fixing the order is probably worth it - done carefully, in a
dedicated commit, and after considering whether it really makes sense
for the individual case.

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

Right.  I have a reputation for verbose commit messages in OpenBSD.
Yours tend to be even longer, so i don't think you need to worry
that people might accuse you of sneaking in changes.  Even if you
made them half the length, they would probably still be considerably
above average in precision.

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

When committing substantial changes to the text (or in the case of
code, to behavour) and stating their purpose in the commit message,
i think there is no problem whatsoever with doing minor style cleanup
in the vicinity without mentioning it - as long as the minor,
obviously uncontroversial cleanup on the side doesn't touch so many
lines that it obscures the main change.

The dangerous behaviour that i didn't like was hiding important
content changes behind a trivial commit message, and sneaking
important content changes into a huge diff that was expected to be
purely mechanical judging from the commit message.

Yours,
  Ingo