[bug #66103] manpage-10n project: issues in man pages

[Ingo Schwarze]

Follow-up Comment #4, bug #66103 (group groff):


>> Man page: soelim.1
>> Issue 1:  I<\\%soelim> → B<\\%soelim>
>> Issue 2:  I<\\%troff> → .MR \\%troff 1
>>
>> "I<\\%soelim> is I<not> required for I<\\%troff> to source files."

> As this is the very next sentence, another cross reference here would be
> superfluous.
>
> Automated style checking is a valuable thing to have, but technical
> writing, if it is be of sufficient quality to engage a human reader
> productively, is not a robotic practice.  I counsel against a lazy
> prescription that every single mention of a word that might be a man
> page cross reference should be marked up as such.

While i agree with gbranden@ that technical writing must not be robotic,
we do have the prescription in OpenBSD manual pages that every single
mention of a word that would be a manual page cross reference if it
were the only mention of that word in that page should be marked up as such,
even if it appears repeatedly in the same paragraph or sentence.

With traditional mdoc(7) formatting conventions (still used by mandoc(1)
and *BSD in general) a manual page reference is set as name(section)
all in the default Roman font, which is not noisy at all.  There is
value in unambiguously marking up words as being intended as a reference
to a specific documented command, function, or concept, and not only
being a normal English word.

This is not intended to restart an old controversy - i highly respect
gbranden@, but we are known to disagree on this particular point.

I mention this for the benefit of the manpage-10n crowd.  The lesson is
that while there is consensus about most aspects of manual page formatting,
a few details do exist where different projects prefer different
conventions, both with respect to technical writing style guidelines
and with respect to markup - and sometimes both aspects even interact
with each other, meaning that decisions on one side influence what
makes most sense on the other side.

Unfortunately, such slight differences in conventions make cross-project
markup and style checking harder, but it's still a good thing that you
try.  Thank you for attempting such work inside manpage-10n.


    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?66103>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/

signature.asc
Description: PGP signature