Hi Branden,
G. Branden Robinson wrote on Tue, Dec 11, 2018 at 10:11:02AM -0500:
> At 2018-11-30T14:18:05-0500, Peter Schaffter wrote:
>> My phrasing is at fault. By "isn't an improvement," I meant to
>> convey that alpabetic arrangement of the macros diminishes the
>> usefulness of such a list, which benefits from being grouped into
>> categories.
> At the risk of being unfair to Ingo, based on my occasional disputes
> with him over the groff man pages generally, I would say that an
> alphabetical ordering of macros is useful to readers who are _really_
> impatient. Too much so to type a search pattern into less(1), which we
> probably have to concede in 2018 is an essential part of the man page
> interface on the terminal.
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.
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.
Searching is a very poor tool to confirm that something does
*not* exist, in particular when you search for something short,
like an option "e". Either you search for the plain string and
wade through literally thousands of false positives in a large
manual page. Or you try to search in a more clever way, like
"-e ", or "\<e\>", or ":te". But such cleverness may fail, and
you are never really sure that the thing does not exist: for
example, "-e " might not find it because it happes to be at the
end of a line or followed by a tab rather than a space.
Remember that such searching is always done in a distracted way,
while thinking about something else: the mind of the person
doing the search is focussed on the topic at hand, *not* on the
search expression.
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. This argument is
becoming weaker with the advent of semantic searching - but to
some degree, it is still relevant.
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.
4. It substantially eases maintenance because it helps a lot to
avoid introducing duplicate information - and even more so to
spot accidentally introduced duplicates. Even in OpenBSD
manuals, all of which are strictly alphabetically ordered, there
are numerous examples of jmc@ deleting duplicates, so it is a
real issue, not a theoretical one. Making maintenance of
documentation easy for authors is very important for *readers*
because it directly results in better quality documentation
when authors can focus on what actually matters rather than
being distracted by artificial hurdles like the lack of a
uniform and predictable ordering.
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.
> My rewrite of groff_man(7) shows some of his influence, in that I
> introduced an alphabetically-sorted list of the non-deprecated macros in
> the package. I think it also has the virtue of emphasizing, for better
> or worse, how small a language man(7) is, even with the GNU extensions.
>
> With that established, I felt justified in reorganizing the sections of
> the page in an order that I think was more pedagogically useful. The
> first macro a man page writer needs to learn about is .TH, not .B.
Right. Ordering of *text* by pedagogical considerations makes
sense, as opposed to the case of lists. Of course, stick to the
standard ordering of standard sections, but apart from that, order
text in whichever way makes it easiest to understand.
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 agree with the rest you said here.
Yours,
Ingo
