bugGNU troff - Bugs: bug #62926, [mdoc] align rendering parameters...

 
 

bug #62926: [mdoc] align rendering parameters with man(7)

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Sat 20 Aug 2022 01:02:24 PM UTC
 
Category:  Macro mdoc Severity:  3 - Normal
Item Group:  Rendering/Cosmetics Status:  None
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment (Rich Markup)
   

Comment Type & Canned Response:
       No canned response available

 

( Jump to the original submission )

Tue 27 Dec 2022 09:31:23 AM UTC, comment #11: 

groff_mdoc(7) still goes a bit overboard with Courier, but I've decided to punt a comprehensive rethink of the page to a future release.  It will give me time to better master the package and have a lot of arguments with Ingo.  :)

G. Branden Robinson <gbranden>
Project Administrator
Sun 06 Nov 2022 04:38:11 AM UTC, comment #10: 

commit 0d85615c62d07b028b972dff38bfa7589dad8cf1
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Nov 5 00:48:23 2022 -0500

    [mdoc]: Set page topic in roman in "Name" section.

    * tmac/doc.tmac (Nm): If in the "Name" section of the page, set
      argument(s) with the `No` (normal formatting) macro instead of
      handling them...normally.  Since `Nm`'s usual behavior is to set the
      next argument in boldface, in this circumstance it is set in roman.
      Aligns page rendering with man(7) and fixes a bug documented in the
      4.3BSD-Reno mdoc.samples(7) page (1990-06-22)[1], upon which the
      groff_mdoc(7) page is based.

    * tmac/groff_mdoc.7.man (Bugs): De-document bug.

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

    [1] https://minnie.tuhs.org/cgi-bin/utree.pl?file=4.3BSD-Reno/src/share/man/man7/mdoc.samples.7

G. Branden Robinson <gbranden>
Project Administrator
Sat 29 Oct 2022 07:13:09 PM UTC, comment #9: 

commit bb10a668e10e43f9ccb1727f9f82a1df1530e3b6
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Oct 29 12:28:45 2022 -0500

    [mdoc]: Support `SN` register.

    * tmac/doc.tmac: Recognize `SN` register if set on command line and use
      groff man(7)-compatible default if it is not.
    * tmac/mdoc/doc-common (Ss): Use this register instead of a literal.
    * tmac/groff_mdoc.7.man (Formatting with groff, troff, and nroff):
      Document it.
    * NEWS: Update item.

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

G. Branden Robinson <gbranden>
Project Administrator
Sat 29 Oct 2022 07:12:46 PM UTC, comment #8: 

commit 2134257877b8da28b6d225d99a1c6d81592d9043
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Oct 29 12:09:26 2022 -0500

    [mdoc]: Support `IN` register.

    * tmac/doc.tmac: Recognize `IN` register if set on command line and use
      groff man(7)-compatible defaults if it is not.

    * tmac/mdoc/doc-common (Sh): Use this register instead of
      `doc-paragraph-indentation`.

    * tmac/mdoc/doc-ditroff:
    * tmac/mdoc/doc-nroff: Stop setting pargraph indentation defaults here.

    * tmac/groff_mdoc.7.man (Formatting with groff, troff, and nroff):
      Document it.

    * NEWS: Update item.

    * tmac/tests/doc_Mt-works.sh:
    * tmac/tests/doc_indents-correctly.sh: Update test expectations.

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

G. Branden Robinson <gbranden>
Project Administrator
Sun 11 Sep 2022 12:20:36 PM UTC, comment #7: 

commit 5e9c49e1fa5637630e296b6fe8c36b0b6e0acdeb
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Sep 6 20:17:33 2022 -0500

    [mdoc]: Set page ref in right footer if \n[cR].

    * tmac/mdoc/doc-common (doc-end-macro): When continuously rendering, set
      the page reference (e.g., "ls(1)") in the right footer instead of
      repeating the left footer.  Thanks to Ingo Schwarze for the
      discussion.

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

G. Branden Robinson <gbranden>
Project Administrator
Sat 27 Aug 2022 12:06:00 PM UTC, comment #6: 

It seems CS, CT, D, HY, LL, LT, and S are GNU only, but cR already appeared in 4.4BSD.
So indeed, the horse is barely in sight of the barn any longer, let alone inside of it.  No, i wasn't aware of that.

In this situation, while MF does add even more noise to the manual page (noise which authors don't need and users will not usually even look at), it does not seem to make the situation that much worse than it already is, it merely continues one more step down the declining slope, as long as you don't break .Nm.

P.S.
My concept of API is quite simple: it's the syntax and semantics described in the manual page - because that's what users of the language need to review.

Ingo Schwarze <schwarze>
Project Member
Fri 26 Aug 2022 04:54:22 PM UTC, comment #5: 

> Yikes.  Are you aware that the mdoc(7) language API does not contain a single user-visible register yet?


> Very grudgingly, yes, if you must pollute the API with \*(MF.


I would also add that your use of "API" here is open to equivocation.

There are two materially relevant interfaces here.

1. That between the man page author and the macro package.
2. That between the man page reader and the macro package.

Man page authors are explicitly discouraged from using `MF`, as they are all other strings and registers.

.\" ====================================================================
.SS Registers
.\" ====================================================================
.
Registers are described in section \(lqOptions\(rq below.
.
They can be set not only on the command line but in the site
.I man.local
file as well;
see section \(lqFiles\(rq below.
.
.
.\" ====================================================================
.SS Strings
.\" ====================================================================
.
The following strings are defined for use in man pages.
.
_ifnotstyle()dnl
None of these is necessary in a contemporary man page;
see
.MR groff_man_style @MAN7EXT@ .
_endif()dnl
.
Others are supported for configuration of rendering parameters;
see section \(lqOptions\(rq below.
[...]
_ifstyle()dnl
.
.
.P
None of the above is necessary in a contemporary man page.
.
.B \e*S
is superfluous,
since type size changes are invisible on terminal devices and macros
that change it restore its original value afterward.
.
Better alternatives exist for the rest;
simply use the
.BR \(rs(rg , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9, Solaris
.BR \(rs(lq , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
.BR \(rs(rq , \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
and
.B \(rs(tm \" Heirloom Doctools, mandoc, neatmkfn, Plan 9
special character escape sequences directly.
.
Unless a man page author is aiming for a pathological level of
portability,
such as the composition of pages for consumption on simulators of 1980s
Unix systems
(or Solaris
.IR troff ,
though even it supports
.BR \(rs(rg ),
the above strings should be avoided.
[...]
.\" ====================================================================
.SH Options
.\" ====================================================================
.
The following
.I groff
options set registers
(with
.BR \-r )
and strings
(with
.BR \-d )
recognized and used by the
.I man
macro package.
.
To ensure rendering consistent with output device capabilities and
reader preferences,
man pages should never manipulate them.

There is therefore no reason to catastrophize the addition of `MF` to a set that already includes (strings) `AD` and `HF` and registers `cR`, `C`, `CS`, `CT`, `D`, `FT`, `HY`, `IN`, `LL`, `LT`, `P`, `S`, `SN`, `U`, and `X`.

groff mdoc does not yet support all of these, but I would like it if it did.  These are all rendering options, and if an implementation wants to remove these degrees of freedom, it can do so without impacting how man pages using either package are written.

G. Branden Robinson <gbranden>
Project Administrator
Thu 25 Aug 2022 12:43:51 PM UTC, comment #4: 

comment #3:

> 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.

G. Branden Robinson <gbranden>
Project Administrator
Thu 25 Aug 2022 10:04:24 AM UTC, comment #3: 

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?
Starting to go down that rabbit hole seems like a very bad idea to me.

> 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.

> 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.

Ingo Schwarze <schwarze>
Project Member
Tue 23 Aug 2022 09:28:08 PM UTC, comment #2: 

Kicking up to blocker severity because this needs to be dealt with as best we can before 1.23.0 finalizes.

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).

I reckon this would be used to style `Xr`'s first argument, `Nm`' first (or implied) argument, and the page header.

While I'm in the neighborhood, page footers are already out of sync between man and mdoc when continuously rendering, and probably have been for as long as the continuous rendering feature has existed.  mdoc repeats the `Os` info on the right-hand side; man repeats the page title and parenthesized section.

Ingo will want to set "MF=R(R)" (so to speak) in some location that is not straightforwardly modifiable by OpenBSD users.  I note that groff has used the equivalent of "MF=CR(R)" for typesetter devices for a very long time.

G. Branden Robinson <gbranden>
Project Administrator
Sat 20 Aug 2022 02:07:12 PM UTC, comment #1: 

No comment on the first sentence because it is not very specific.

I do not object to the rest of the original submission.  But i strongly disagree with the summary.  mdoc(7) has always consistently styled .Xr as \fR for terminal output whereas man(7) has been inconsistent over time.  In v7, it even styled manual page cross references differently inside and outside of SEE ALSO.

So if anything, man(7) ought to adopt the established convention of mdoc(7) rather than infect mdoc(7) with its own instability.

Ingo Schwarze <schwarze>
Project Member
Sat 20 Aug 2022 01:02:24 PM UTC, original submission:  

Even in groff 1.22.4, styling was inconsistent between groff man(7) and groff mdoc(7)--for example, the latter used small caps for several purposes and splashed the Courier family all over the place--but the divergence has largely increased since then due to my reformist approach to man(7).

Ingo pointed out that with the new groff man(7) "MF" string, this divergence is visible even on terminals.

Bring them into closer alignment.  Perfection may not be possible or even desired, because mdoc(7) has more semantic information available to it.

For now.  Until one of my next reforms...

G. Branden Robinson <gbranden>
Project Administrator

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by gbranden (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

     

     

     

    Follow 9 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-12-27 gbranden StatusIn Progress None
        Planned Release1.23.0 None
    2022-10-29 gbranden Summary[mdoc] align styling of titles and man page cross references with man(7) [mdoc] align rendering parameters with man(7)
    2022-09-26 gbranden Severity5 - Blocker 3 - Normal
        StatusNone In Progress
        Assigned toNone gbranden
    2022-09-11 gbranden Planned ReleaseNone 1.23.0
    2022-08-23 gbranden Summary[mdoc] align styling of headers and man page cross references with man(7) [mdoc] align styling of titles and man page cross references with man(7)
    2022-08-23 gbranden Severity1 - Wish 5 - Blocker

    Back to the top

    Powered by Savane 3.9