[bug #62926] [mdoc] align styling of titles and man page cross references with man(7)

[G. Branden Robinson]

Follow-up Comment #4, bug #62926 (project groff):

[comment #3 comment #3:]
> [comment #2 comment #2:]
>  
> > It should surprise no one that my idea is to support the `MF` string in
_mdoc_(7) just as is already done in _man_(7).
> 
> Yikes.  Are you aware that the mdoc(7) language API does not contain a
single user-visible register yet?

I assume you refer to mandoc_mdoc(7), in which case, no, I was not.  Are you
aware that groff_mdoc(7) has documented several for over twenty years?


commit b57a7328369ea1dc5114bd93407c0ac1194af683
Author: Werner LEMBERG <wl@gnu.org>
Date:   Sat Mar 24 15:04:41 2001 +0000

    * tmac/doc-nroff, tmac/doc-ditroff: Implement -rSxx switch for
    selecting the font size.
    * tmac/groff_mdoc.man, NEWS: Document it.
    
    
    * tmac/groff_mdoc.reference.man: Small updates and renamed to ...
    * tmac/groff_mdoc.man: This.  The quick reference has been removed.
    * tmac/Makefile.sub, NEWS: Updated.

[...]
+.Sh "FORMATTING WITH GROFF, TROFF, AND NROFF"
+.
+By default, the package inhibits page breaks, headers, and footers if
+displayed with a
+.Tn TTY
+device like
+.Sq latin-1
+or
+.Sq unicode
+to make the manual more efficient for viewing on-line.
+This behaviour can be changed (e.g.\& to create a hardcopy of the
+.Tn TTY
+output) by setting the register
+.Ql cR
+to zero while calling groff:
+.Pp
+.Dl groff -Tlatin1 -rcR=0 -mdoc foo.man > foo.txt
+.Pp
+For double-sided printing, set register
+.Ql D :
+.Pp
+.Dl groff -Tps -rD1 -mdoc foo.man > foo.ps
+.Pp
+To change the document font size to 11pt or 12pt, set register
+.Ql S
+accordingly:
+.Pp
+.Dl groff -Tdvi -rS11 -mdoc foo.man > foo.dvi
+.Pp
+Register
+.Ql S
+is ignored for
+.Tn TTY
+devices.


> Starting to go down that rabbit hole seems like a very bad idea to me.

In that case, _groff_ has been the land beyond the magic mirror since before
the U.S. invaded Afghanistan.  That's, like, forever!

> > I reckon this would be used to style `Xr`'s first argument,
> > and the page header.
> 
> Very grudgingly, yes, if you must pollute the API with \*(MF.
> 
> > `Nm`' first (or implied) argument,
> 
> No, absolutely not.  This is getting worse and worse!
> 
> .Nm has always been formatted as \fB and that is very important because it
is a fixed string that the user has to type verbatim.
> It would be extremely confusing to use anything other than \fB for .Nm,
especially in the SYNOPSIS, but also in other places.

All right, I'll hold off on this, then.  It's an aspect where we have no clear
mapping between language elements of man(7) and mdoc(7).

It occurred to me long before I even knew mdoc(7) existed that man(7) could
really use a macro for placing the man page's own topic name in the text,
because page self-references are pretty common.

As it happens, 'NM' is available.  But, like 'MR' and unlike my proposed keep
macros 'KS'/'KE', it would _not_ degrade nicely on legacy implementations.  It
would also be challenging to simulate, since there is no portable way to
access the first argument given to `TH`.  On the other hand, people like
Thomas Dickey already simulate this feature using self-defined strings in
pages like xterm(1).

> > While I'm in the neighborhood, page footers are _already_ out of sync
between man and mdoc
> 
> True, and synching that might make sense.  Either way, the footer line is
less important than the header line, so i don't feel strongly about it.
> 
> mdoc: OS - date - OS
> man:  OS - date - title
> 
> Arguably, the man(7) way is more useful and the mdoc(7) way somewhat
redundant in this respect.

Cool.


    _______________________________________________________

Reply to this item at:

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

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