Re: CVS commit: src/share/man/man7

[Valery Ushakov <uwe%stderr.spb.ru@localhost>]

On Wed, May 16, 2018 at 22:12:52 +0200, Thomas Klausner wrote:

> On Tue, May 15, 2018 at 02:19:13PM +0300, Valeriy E. Ushakov wrote:
> > On Tue, May 15, 2018 at 09:13:36 +0000, Thomas Klausner wrote:
> > 
> > > Module Name:	src
> > > Committed By:	wiz
> > > Date:		Tue May 15 09:13:36 UTC 2018
> > > 
> > > Modified Files:
> > > 	src/share/man/man7: intro.7
> > > 
> > > Log Message:
> > > Remove Tn.
> > 
> > I wonder why we are doing this?  .Tn is small caps in the PostScript
> > output and it definitely looks better than all caps.
> 
> mandoc warns about them, because it doesn't do anything with them.

That is not a good argument.  We just happen to use mandoc to quickly
get formatted man pages.  One can also use troff and real tmac.doc for
that.  The PostScript output of mandoc can be generously described as
extremely primitive (as far as I can tell this is by design, so this
is not an argument against mandoc).  Will you also remove more markup
b/c "mandoc doesn't do anything with it" compared to reall troff?


> If you use them because they are small caps, it's a kind of a
> misuse, because the point of mandoc is that you do semantic markup.

That is not a good argument either.  mdoc is not docbook that has
gazillion hair splitting options for marking up content.  Using markup
with a rather broad intent is quite normal in mdoc, e.g (emphasis
mine):

   Function Arguments
     The `.Fa' macro is used to refer to FUNCTION ARGUMENTS (parameters)
     outside of the SYNOPSIS section of the manual [...]  `.Fa' may also
     be used to refer to STRUCTURE MEMBERS.


> Tn has been used for lots of stuff, many of which are not
> trademarks.

The manual section that describes .Tn is called

   Trade Names (or Acronyms and Type Names)

and the examples given are

                    .Tn DEC        DEC
                    .Tn ASCII      ASCII

and ASCII there gives a pretty obviout hint about the intent I think.

And since you insist on the very literal interpretation of "Tn",
consider your most recent change to remove markup from .Tn NFS.  Funny
thing is that my "NFS Illustrated" book begins with:

    The NFS(TM) protocol (hereafter simply called "NFS") ...

Do you really want *that* level of pedantry?


> Pick any of these :)

Please, stop removing all instances of .Tn indiscriminately.  Ideally,
restore all the .Tn's you've alreay indisciminately removed.  Since
"mandoc doesn't do anything with it" it's not like we have to urgenly
remove them to avoid unreadable or horribly mangled man pages.

Please, don't destroy existing information.  Even if some of that
markup is wrong, the decision to remove it should be based on valid
reasons.  You are obviously doing it based on wrong premises.  And
then you don't even apply those consistently as the NFS example shows. :)

Ok, I mentioned that last one just to hint at the absurdity of literal
interpretation.  Look at docbook.  This is semantic markup taken to
the extreme.  Do we really want to head down that road?  B/c there is
docbook vocabulary for manual pages if we want it.

So for now, please, just stop.

-uwe