Re: [groff] man-page fixes

[Larry Kollar]

Ingo Schwarze <address@hidden> wrote:

> Doug McIlroy wrote on Thu, Nov 15, 2018 at 08:40:14PM -0500:
> 
>> Regardless of standards considerations, if there's any advice
>> that needs to be hammered into man authors, it's to be concise
>> and accurate, but not pedantic. As Will Strunk commanded,
>> "Omit needless words."
> 
> That is remarkably close to how Jason McIntyre is maintaining
> our tree, and it is indeed very useful guidance.

Stem sentences are like flannel shirts; they go in and out of style,

In the early 90s, what Doug calls “verbal continuity” was in vogue.
Each list was supposed to have a stem sentence like “The following
options are available:” or “Available options are as follows:” Once
you get into that kind of habit, it’s hard to break because it flows so
well in your mind or when spoken out loud.

Nowadays, minimalism is all the rage. Omit needless words, as
Professor Strunk wrote in 1918.

What I’m getting at here: any manpage documenting something in
the POSIX suite might have first been written over 40 years ago, and
could be around for another 40 years or longer. IOW, long enough
for fashions to change, change back, and change again multiple
times. All this stuff is maintained by volunteers, and their time is
better spent keeping the content current vs. keeping up with the
trend of the decade.

So for long-term docs like these, Job One is making it complete and
accurate. Conforming to a style that will change several times during
the life of the document is secondary. If it looks dated today, in 2030
someone will read it and say, “wow, this is amazingly modern."

        Larry