[PATCH 1/2] man*/: srcfix

[PATCH 1/2] man*/: srcfix

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 3958 bytes --]

Clean up in preparation for "MR sed".

Format only one man page cross reference per input line.

Also, groff 1.23.0's (and Plan 9 from User Space's) `MR` is not a font
style alternation macro; there is no "reversed" form as with `BR` and
`RB`.  So when a man page cross reference must be immediately preceded
by punctuation, put that punctuation on the previous text line and use
the `\c` escape sequence to connect them.

Signed-off-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
---
 man2/open.2            |  9 +++++++--
 man2/perf_event_open.2 |  7 ++++++-
 man5/proc_locks.5      | 10 ++++++----
 man7/credentials.7     | 15 ++++++++++-----
 man7/pty.7             |  5 ++++-
 5 files changed, 33 insertions(+), 13 deletions(-)

diff --git a/man2/open.2 b/man2/open.2
index 4c921723c..6603dfdff 100644
--- a/man2/open.2
+++ b/man2/open.2
@@ -82,8 +82,13 @@ .SH DESCRIPTION
 to an entry in the process's table of open file descriptors.
 The file descriptor is used
 in subsequent system calls
-.RB ( read "(2), " write "(2), " lseek "(2), " fcntl (2),
-etc.) to refer to the open file.
+(\c
+.BR read (2),
+.BR write (2),
+.BR lseek (2),
+.BR fcntl (2),
+etc.)
+to refer to the open file.
 The file descriptor returned by a successful call will be
 the lowest-numbered file descriptor not currently open for the process.
 .PP
diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
index 44a2ecbeb..4a0bfe65e 100644
--- a/man2/perf_event_open.2
+++ b/man2/perf_event_open.2
@@ -32,7 +32,12 @@ .SH DESCRIPTION
 Given a list of parameters,
 .BR perf_event_open ()
 returns a file descriptor, for use in subsequent system calls
-.RB ( read "(2), " mmap "(2), " prctl "(2), " fcntl "(2), etc.)."
+(\c
+.BR read (2),
+.BR mmap (2),
+.BR prctl (2),
+.BR fcntl (2),
+etc.).
 .PP
 A call to
 .BR perf_event_open ()
diff --git a/man5/proc_locks.5 b/man5/proc_locks.5
index cf4ff678c..a938e4ad7 100644
--- a/man5/proc_locks.5
+++ b/man5/proc_locks.5
@@ -10,10 +10,12 @@ .SH NAME
 .SH DESCRIPTION
 .TP
 .I /proc/locks
-This file shows current file locks
-.RB ( flock "(2) and " fcntl (2))
-and leases
-.RB ( fcntl (2)).
+This file shows current file locks (\c
+.BR flock (2)
+and
+.BR fcntl (2))
+and leases (\c
+.BR fcntl (2)).
 .IP
 An example of the content shown in this file is the following:
 .IP
diff --git a/man7/credentials.7 b/man7/credentials.7
index 77cb5e0ef..b07f150bd 100644
--- a/man7/credentials.7
+++ b/man7/credentials.7
@@ -267,21 +267,26 @@ .SS Modifying process user and group IDs
 Subject to rules described in the relevant manual pages,
 a process can use the following APIs to modify its user and group IDs:
 .TP
-.BR setuid "(2) (" setgid (2))
+.BR setuid (2)\~(\c
+.BR setgid (2))
 Modify the process's real (and possibly effective and saved-set)
 user (group) IDs.
 .TP
-.BR seteuid "(2) (" setegid (2))
+.BR seteuid (2)\~(\c
+.BR setegid (2))
 Modify the process's effective user (group) ID.
 .TP
-.BR setfsuid "(2) (" setfsgid (2))
+.BR setfsuid (2)\~(\c
+.BR setfsgid (2))
 Modify the process's filesystem user (group) ID.
 .TP
-.BR setreuid "(2) (" setregid (2))
+.BR setreuid (2)\~(\c
+.BR setregid (2))
 Modify the process's real and effective (and possibly saved-set)
 user (group) IDs.
 .TP
-.BR setresuid "(2) (" setresgid (2))
+.BR setresuid (2)\~(\c
+.BR setresgid (2))
 Modify the process's real, effective, and saved-set user (group) IDs.
 .TP
 .BR setgroups (2)
diff --git a/man7/pty.7 b/man7/pty.7
index bef60e931..3f23be44d 100644
--- a/man7/pty.7
+++ b/man7/pty.7
@@ -122,7 +122,10 @@ .SH FILES
 BSD slave devices
 .SH NOTES
 Pseudoterminals are used by applications such as network login services
-.RB ( ssh "(1), " rlogin "(1), " telnet (1)),
+(\c
+.BR ssh (1),
+.BR rlogin (1),
+.BR telnet (1)),
 terminal emulators such as
 .BR xterm (1),
 .BR script (1),
-- 
2.30.2


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] man*/: srcfix

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4755 bytes --]

Hi  Branden,

On Wed, Oct 25, 2023 at 01:54:24PM -0500, G. Branden Robinson wrote:
> Clean up in preparation for "MR sed".
> 
> Format only one man page cross reference per input line.
> 
> Also, groff 1.23.0's (and Plan 9 from User Space's) `MR` is not a font
> style alternation macro; there is no "reversed" form as with `BR` and
> `RB`.  So when a man page cross reference must be immediately preceded
> by punctuation, put that punctuation on the previous text line and use
> the `\c` escape sequence to connect them.
> 
> Signed-off-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> ---
>  man2/open.2            |  9 +++++++--
>  man2/perf_event_open.2 |  7 ++++++-
>  man5/proc_locks.5      | 10 ++++++----
>  man7/credentials.7     | 15 ++++++++++-----
>  man7/pty.7             |  5 ++++-
>  5 files changed, 33 insertions(+), 13 deletions(-)
> 
> diff --git a/man2/open.2 b/man2/open.2
> index 4c921723c..6603dfdff 100644
> --- a/man2/open.2
> +++ b/man2/open.2
> @@ -82,8 +82,13 @@ .SH DESCRIPTION
>  to an entry in the process's table of open file descriptors.
>  The file descriptor is used
>  in subsequent system calls
> -.RB ( read "(2), " write "(2), " lseek "(2), " fcntl (2),
> -etc.) to refer to the open file.
> +(\c

I'm going to disagree with Ingo with his claim that a macro that forces
using \c is bad because it promotes bad style.  '(\c' doesn't look bad
to me here.  Not more than having the leading punctuation as an Nth
argument.

> +.BR read (2),
> +.BR write (2),
> +.BR lseek (2),
> +.BR fcntl (2),
> +etc.)
> +to refer to the open file.
>  The file descriptor returned by a successful call will be
>  the lowest-numbered file descriptor not currently open for the process.
>  .PP
> diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
> index 44a2ecbeb..4a0bfe65e 100644
> --- a/man2/perf_event_open.2
> +++ b/man2/perf_event_open.2
> @@ -32,7 +32,12 @@ .SH DESCRIPTION
>  Given a list of parameters,
>  .BR perf_event_open ()
>  returns a file descriptor, for use in subsequent system calls
> -.RB ( read "(2), " mmap "(2), " prctl "(2), " fcntl "(2), etc.)."
> +(\c
> +.BR read (2),
> +.BR mmap (2),
> +.BR prctl (2),
> +.BR fcntl (2),
> +etc.).
>  .PP
>  A call to
>  .BR perf_event_open ()
> diff --git a/man5/proc_locks.5 b/man5/proc_locks.5
> index cf4ff678c..a938e4ad7 100644
> --- a/man5/proc_locks.5
> +++ b/man5/proc_locks.5
> @@ -10,10 +10,12 @@ .SH NAME
>  .SH DESCRIPTION
>  .TP
>  .I /proc/locks
> -This file shows current file locks
> -.RB ( flock "(2) and " fcntl (2))
> -and leases
> -.RB ( fcntl (2)).
> +This file shows current file locks (\c

For consistency with the above two cases, I think you should move that
(\c to a new line.  It also reduces the diff (semantic newlines any?)  :)

Cheers,
Alex

> +.BR flock (2)
> +and
> +.BR fcntl (2))
> +and leases (\c
> +.BR fcntl (2)).
>  .IP
>  An example of the content shown in this file is the following:
>  .IP
> diff --git a/man7/credentials.7 b/man7/credentials.7
> index 77cb5e0ef..b07f150bd 100644
> --- a/man7/credentials.7
> +++ b/man7/credentials.7
> @@ -267,21 +267,26 @@ .SS Modifying process user and group IDs
>  Subject to rules described in the relevant manual pages,
>  a process can use the following APIs to modify its user and group IDs:
>  .TP
> -.BR setuid "(2) (" setgid (2))
> +.BR setuid (2)\~(\c
> +.BR setgid (2))
>  Modify the process's real (and possibly effective and saved-set)
>  user (group) IDs.
>  .TP
> -.BR seteuid "(2) (" setegid (2))
> +.BR seteuid (2)\~(\c
> +.BR setegid (2))
>  Modify the process's effective user (group) ID.
>  .TP
> -.BR setfsuid "(2) (" setfsgid (2))
> +.BR setfsuid (2)\~(\c
> +.BR setfsgid (2))
>  Modify the process's filesystem user (group) ID.
>  .TP
> -.BR setreuid "(2) (" setregid (2))
> +.BR setreuid (2)\~(\c
> +.BR setregid (2))
>  Modify the process's real and effective (and possibly saved-set)
>  user (group) IDs.
>  .TP
> -.BR setresuid "(2) (" setresgid (2))
> +.BR setresuid (2)\~(\c
> +.BR setresgid (2))
>  Modify the process's real, effective, and saved-set user (group) IDs.
>  .TP
>  .BR setgroups (2)
> diff --git a/man7/pty.7 b/man7/pty.7
> index bef60e931..3f23be44d 100644
> --- a/man7/pty.7
> +++ b/man7/pty.7
> @@ -122,7 +122,10 @@ .SH FILES
>  BSD slave devices
>  .SH NOTES
>  Pseudoterminals are used by applications such as network login services
> -.RB ( ssh "(1), " rlogin "(1), " telnet (1)),
> +(\c
> +.BR ssh (1),
> +.BR rlogin (1),
> +.BR telnet (1)),
>  terminal emulators such as
>  .BR xterm (1),
>  .BR script (1),
> -- 
> 2.30.2
> 



-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

`\c`, mdoc(7), and man(7) extension macros (was: [PATCH 1/2] man*/: srcfix)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 11485 bytes --]

Hi Alex,

At 2023-10-25T21:38:59+0200, Alejandro Colomar wrote:
> On Wed, Oct 25, 2023 at 01:54:24PM -0500, G. Branden Robinson wrote:
> > diff --git a/man2/open.2 b/man2/open.2
> > index 4c921723c..6603dfdff 100644
> > --- a/man2/open.2
> > +++ b/man2/open.2
> > @@ -82,8 +82,13 @@ .SH DESCRIPTION
> >  to an entry in the process's table of open file descriptors.
> >  The file descriptor is used
> >  in subsequent system calls
> > -.RB ( read "(2), " write "(2), " lseek "(2), " fcntl (2),
> > -etc.) to refer to the open file.
> > +(\c
> 
> I'm going to disagree with Ingo with his claim that a macro that
> forces using \c is bad because it promotes bad style.  '(\c' doesn't
> look bad to me here.  Not more than having the leading punctuation as
> an Nth argument.

I disagree with Ingo on that point as well.

Saying why leads me to digress; I found myself writing down thoughts
about future man(7) development more concretely than I have to date.
(I'll return to this patch at the end.)  So, Ccing the groff list...

I think Ingo's perspective is strongly influenced by mdoc(7), the use of
which he strenuously advocates.  And mdoc _does_ manage to make `\c`
almost(?) totally unnecessary--at the cost of a weighty internal
recursive macro reprocessing system that no other *roff package is known
to implement.

(This is what that "parsed"/"callable" stuff in groff_mdoc(7) (and
mandoc_mdoc(7)) is all about.  Also, by "weighty", I mean it--back in
~1990, when mdoc was implemented, its documentation warned the reader of
its slowness.  Fortunately, on modern systems, the rendering latency
relative to man(7) is no longer noticeable.)

Even with performance considerations out of the picture, I think such a
system is a point against adoption of mdoc; one can observe that,
nowadays, both man(7) and mdoc require a person to acquire knowledge
that they will "never" transfer anywhere else, assuming no resurgence in
*roff popularity.  But the point is _even more true_ of mdoc than it is
of man(7), by dint of the recursive macro reprocessing feature and the
funny requirements that become necessary as a consequence (you have to
use `\&` in more places; you have to break up individual punctuation
characters when using them as macro arguments if you want them to work
right).  In other words, learning mdoc doesn't help you learn *roff all
that much.  Not as much as man(7) does.  And it doesn't help you learn
any other programming/documentation system anywhere.

Plus, in mdoc, there is a much larger lexicon of macros to learn in the
first place.  I count 115.

$ git grep '\.\(als\|de\) [A-Z][A-Za-z1][a-z]*' \
  tmac/doc.tmac tmac/mdoc/doc-!(nroff) | wc -l
115

Admittedly, a couple of those are, if not deprecated, unlikely to be
used in practice, because even after mdoc's documentation spent decades
asking its readers for help, no one could be found who clearly remembers
what they were supposed to do (`Me`, `Ot`).  So, call it 113 macros.

But Ingo added `Tg` to mandoc(1) mdoc--which groff doesn't support yet--
so make that 114.

man(7), in groff 1.23.0, has 30.  2 of those (`LP`, `PP`) are redundant
synonyms for `P` that I'd happily kill off if the man page authors of
the world would let me.  Six others, the font alternation macros--`BI`,
`BR`, and friends--are schematic and so are relatively "light" on human
memory.  Several more come in pairs (`EX`/`EE`, `MT`/`ME`, `RS`/`RE`,
`SY`/`YS`, `UR`/`UE`).[1]  I confess that I do have plans to grow
man(7)'s macro repertoire for groff 1.24, but not by more than a few,
and only for purposes where we see concrete needs.[2]  Further, `SB` is
already deprecated in Git (it was never "standard" in the first place).

Granted, some of mdoc's macros are systematically named as well.  The
enclosure macros are probably the prime example.

groff_mdoc(7):
       Quote   Open   Close   Function                  Result
       .Aq     .Ao    .Ac     Angle Bracket Enclosure   <string>
       .Bq     .Bo    .Bc     Bracket Enclosure         [string]
       .Brq    .Bro   .Brc    Brace Enclosure           {string}
       .Dq     .Do    .Dc     Double Quote              “string”
       .Eq     .Eo    .Ec     Enclose String (in XY)    XstringY
       .Pq     .Po    .Pc     Parenthesis Enclosure     (string)
       .Ql                    Quoted Literal            “string” or string
       .Qq     .Qo    .Qc     Straight Double Quote     "string"
       .Sq     .So    .Sc     Single Quote              ‘string’

None of this is to say that mdoc should go away.  I do not mirror
mandoc(1)'s initial ambition to completely kill off man(7).[3]  There's
room in the world for mdoc, and I think it can coexist with man(7).  But
I tire both of mdoc advocates' derogations of man(7), and of resistance
to development of the man(7) language so intransigent that it keeps the
macro package from rising to the challenge mdoc has presented to it,
particularly in areas that man(7) authors also complain about.  A
community with totalitarian conquerors on one hand and reactionaries who
prefer death to evolution on the other is an unhealthy one.

Does mdoc do a better job of semantic markup?  Absolutely.  But I have
an idea for bringing man(7) to parity in that department as well--at a
much lower cost in macro name space and human memory loading.  It will
cost 3 macros: one to define a tag class, and two others to open and
close an annotation of enclosed material with a tag class.  (The
bracketing is for (a) flexibility: tag as large a region of the page as
you like, and (b) robustness: if an implementation doesn't support the
macros--and many won't, especially at first--the rendered text of the
page will not be damaged by ignoring the macros.)

(b) is a property `MR` didn't have, and that fact necessitated the
inclusion of some boilerplate in every groff 1.23.0 man page so that
they would render acceptably with other formatters, including old
versions of groff.  (This problem afflicted renderings of the groff man
pages on Michael Kerrisk's man7.org site for a while.)  I'm not happy
about this, but I'm not sure it was avoidable.[4]  And eventually the
boilerplate can be dropped.

Potentially, the big payoff is that most man pages won't have to define
tag classes at all.  The definitions of these can be left to man page
maintenance communities--like that of the Linux man-pages--and the class
definitions `so`urced in.  Again, nothing breaks the formatted page if
something goes wrong with this, like an anemic formatter not
implementing the `so` request, or the tag definition file being missing.

What would tag classes enable us to do?

(1) Associate formatting (style) decisions, like what typeface to use
    for an item, with text based on the _meaning_ of that text.

(2) Make those styles customizable independently of a given man(7)
    document, and in one or only a few locations.  Want file names to
    show up in italics always?  Or roman always?  If the man page uses
    semantic tagging, you'll be able to.  groff mdoc supports this but
    it seems to be a fairly obscure feature.  For mandoc(1), this sort
    of customization is, as I understand it, considered an anti-feature.

(3) Embed this semantic information in GNU troff device-independent
    output, meaning that it can then be handled by an output driver
    (like grohtml(1)).  (A terminal output driver would ignore it.)
    mandoc(1) has a really nice feature in its HTML output where you can
    hover the pointer over some text, and a tooltip will pop up telling
    you what mdoc macro was used to mark it up.  This is cool, and
    surely an aid for acquiring the portions of its gigantic lexicon
    that man page authors actually want to use.

> > diff --git a/man5/proc_locks.5 b/man5/proc_locks.5
> > index cf4ff678c..a938e4ad7 100644
> > --- a/man5/proc_locks.5
> > +++ b/man5/proc_locks.5
> > @@ -10,10 +10,12 @@ .SH NAME
> >  .SH DESCRIPTION
> >  .TP
> >  .I /proc/locks
> > -This file shows current file locks
> > -.RB ( flock "(2) and " fcntl (2))
> > -and leases
> > -.RB ( fcntl (2)).
> > +This file shows current file locks (\c
> 
> For consistency with the above two cases, I think you should move that
> (\c to a new line.  It also reduces the diff (semantic newlines any?)
> :)

Well, okay.  I'll roll a v5.

By the way, even the diffless version of 2/2 (the actual `MR` migration)
got canned by vger.  Even just the diff --stat blows past the 100,000
byte limit.  But you should have a copy in your inbox, and the sed
script is what does the real work of 2/2 anyway.

Regards,
Branden

[1] It _would_ be nice if these all ended in `S` and `E`, respectively,
    for "start" and "end".  Alas, there is historical baggage here,
    which Doug McIlroy, author of the original man(7) macros and of the
    latter Ninth Edition Unix `EX`/`EE` extension, recently lamented.

    https://lists.gnu.org/archive/html/groff/2023-09/msg00058.html

    We _could_ fix all the outliers, save one, without collision.

	EX -> ES (example start)
	MT -> MS (mail-to start)
	UR -> US (URL start)
	YS -> SE (synopsis end)

    The oddball is `SY`.  We can't rename that to `SS`, which is already
    a subsection heading macro.  But we could rename _both_ synopsis
    macros.

	SY -> NS (syNopsis start)
	YS -> NE (syNopsis end)

    I'm game for any of these reforms, if people think it's worth it.
    The old names can be kept for backward compatibility for as long as
    necessary (but de-documented).  I _assume_ there's too much inertia
    for this.

[2] An example of a concrete need is better control of vertical spacing
    within lists.  In one case, the "concrete need" is for semantic
    tagging.  Can semantics be concrete?  Signs point to "yes".

    http://concrete-semantics.org/

[3] "The mission of mdocml is to deprecate groff, the GNU roff
    implementation, for displaying -mdoc pages whilst providing token
    support for -man."

    This rather fiery statement appeared at mdocml.bsd.lv in 2009, but
    was withdrawn in late 2013.

    Cf.

    https://web.archive.org/web/20090306052112/https://mdocml.bsd.lv/
    https://web.archive.org/web/20131024053011/https://mdocml.bsd.lv/
    https://web.archive.org/web/20131111191539/https://mdocml.bsd.lv/

    While no longer a statement of mission, the attitude persists.

[4] I pretty much followed the example of the old DEC Ultrix `MS` macro,
    and the Plan 9 from User Space `MR` macro.  (I did make groff's `MR`
    macro supply the parentheses for the section number itself.)  I
    figure that new man page cross references need to look a _lot_ like
    the old ones or authors will be too confused to adopt the new ones.
    (I admit, retaining the requirement to type the parentheses would
    serve that goal even better, but, to me, not making people type
    invariant literals--stuff they don't _need_ to type--weighed more
    heavily.  And it closed a window through which typos or absent-
    mindedness could enter.  I don't know if the plan9port folks noticed
    this, or were annoyed by it, but I'm happy to supply a patch to
    migrate the `MR` calls in their corpus of man pages to align with
    groff practice if they would like.  What's one more sed script?  :)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: `\c`, mdoc(7), and man(7) extension macros (was: [PATCH 1/2] man*/: srcfix)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4008 bytes --]

Hi Branden,

On Thu, Oct 26, 2023 at 07:58:35AM -0500, G. Branden Robinson wrote:
[...]
> 
> And mdoc _does_ manage to make `\c`
> almost(?) totally unnecessary--at the cost of a weighty internal
> recursive macro reprocessing system that no other *roff package is known
> to implement.
> 
> (This is what that "parsed"/"callable" stuff in groff_mdoc(7) (and
> mandoc_mdoc(7)) is all about.  Also, by "weighty", I mean it--back in
> ~1990, when mdoc was implemented, its documentation warned the reader of
> its slowness.  Fortunately, on modern systems, the rendering latency
> relative to man(7) is no longer noticeable.)
> 
> Even with performance considerations out of the picture, I think such a
> system is a point against adoption of mdoc; one can observe that,
> nowadays, both man(7) and mdoc require a person to acquire knowledge
> that they will "never" transfer anywhere else, assuming no resurgence in
> *roff popularity.  But the point is _even more true_ of mdoc than it is
> of man(7), by dint of the recursive macro reprocessing feature and the
> funny requirements that become necessary as a consequence (you have to
> use `\&` in more places; you have to break up individual punctuation
> characters when using them as macro arguments if you want them to work
> right).  In other words, learning mdoc doesn't help you learn *roff all
> that much.  Not as much as man(7) does.  And it doesn't help you learn
> any other programming/documentation system anywhere.
> 
> Plus, in mdoc, there is a much larger lexicon of macros to learn in the
> first place.  I count 115.

Yup.  I have similar feelings about C++, BTW.  I have a hard time
understanding complex languages.  I prefer simpler languages.  Most
features can be implemented as library code, without complicating the
language.

[...]

> > 
> > For consistency with the above two cases, I think you should move that
> > (\c to a new line.  It also reduces the diff (semantic newlines any?)
> > :)
> 
> Well, okay.  I'll roll a v5.
> 
> By the way, even the diffless version of 2/2 (the actual `MR` migration)
> got canned by vger.  Even just the diff --stat blows past the 100,000
> byte limit.  But you should have a copy in your inbox, and the sed
> script is what does the real work of 2/2 anyway.

Yep, I have 2/2 locally.  Maybe reply to the mail CCing vger, keeping
only the commit message, so that readers of the list can get a notice of
what MR.sed is.

> 
> Regards,
> Branden
> 
> [1] It _would_ be nice if these all ended in `S` and `E`, respectively,
>     for "start" and "end".  Alas, there is historical baggage here,
>     which Doug McIlroy, author of the original man(7) macros and of the
>     latter Ninth Edition Unix `EX`/`EE` extension, recently lamented.
> 
>     https://lists.gnu.org/archive/html/groff/2023-09/msg00058.html
> 
>     We _could_ fix all the outliers, save one, without collision.
> 
> 	EX -> ES (example start)
> 	MT -> MS (mail-to start)
> 	UR -> US (URL start)
> 	YS -> SE (synopsis end)

I always make the mistake of writing MS instead of MT, out of inertia of
having an 'S' for the start!  :D

The others have nicer mnemonics that work for me; I wouldn't change
them.  And well, just for changing MT, I wouldn't do it.

> 
>     The oddball is `SY`.  We can't rename that to `SS`, which is already
>     a subsection heading macro.  But we could rename _both_ synopsis
>     macros.
> 
> 	SY -> NS (syNopsis start)
> 	YS -> NE (syNopsis end)

Hmmm, no; I don't like it.

> 
>     I'm game for any of these reforms, if people think it's worth it.
>     The old names can be kept for backward compatibility for as long as
>     necessary (but de-documented).  I _assume_ there's too much inertia
>     for this.

Regarding PP, LP, and P, what's the history of them?  Why do we have the
3?  I'm willing to reduce them to just one.


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Why does man(7) have 3 paragraph macros for the same thing? (was: `\c`, mdoc(7), and man(7) extension macros)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1857 bytes --]

At 2023-10-26T16:12:36+0200, Alejandro Colomar wrote:
> Regarding PP, LP, and P, what's the history of them?  Why do we have
> the 3?  I'm willing to reduce them to just one.

I invite Doug McIlroy to go on record, but my surmise is that they were
introduced as crutches for people already familiar with ms(7).

Doug's original man(7) (1979) didn't have `P`.  But Unix System III
added it in 1980, and 4.3BSD followed suit in 1986.  This information is
in groff_man(7).

In ms(7), `LP` sets a paragraph that is left-aligned, and `PP` sets one
with a first-line indentation.

In man(7), all (ordinary) paragraphs behave analogously to ms(7)'s `PP`.
A first-line indentation is never used.

My opinion is that one should use `P` exclusively for a few reasons.

1.  Its name is short and it is frequently used.  Huffman coding FTW.
2.  The existence of both `LP` and `PP` is difficult to rationalize to
    anyone except a seasoned ms(7) author, of whom there are almost none
    writing man(7) documents today.
3.  It's been around long enough that everything supports it.  `LP`/`PP`
    have no measurable advantage in this respect.  Anyone running early
    BSD in 2023 has more interesting things to do than the composition
    of legacy man pages.

Incidentally, mm(7) would have already had a `P` macro as well by 1979.
Its call syntax is different (it interprets arguments; ms(7)'s and
man(7)'s "plain" paragraphing macros do not).  Maybe this, and/or some
friction between Bell Labs Research and the constantly reconfiguring
series of departments dedicated to deriving revenue from Unix (and
troff) commercially accounts for man(7)'s omission of it.

Nowadays, we can be confident that no loon is going to do something
crazy with mm's `P` macro such that it would trip up man(7) writers.

<an evil grin spreads slowly across my face>

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Why does man(7) have 3 paragraph macros for the same thing? (was: `\c`, mdoc(7), and man(7) extension macros)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2376 bytes --]

Hi Branden,

On Thu, Oct 26, 2023 at 09:51:40AM -0500, G. Branden Robinson wrote:
> At 2023-10-26T16:12:36+0200, Alejandro Colomar wrote:
> > Regarding PP, LP, and P, what's the history of them?  Why do we have
> > the 3?  I'm willing to reduce them to just one.
> 
> I invite Doug McIlroy to go on record, but my surmise is that they were
> introduced as crutches for people already familiar with ms(7).
> 
> Doug's original man(7) (1979) didn't have `P`.  But Unix System III
> added it in 1980, and 4.3BSD followed suit in 1986.  This information is
> in groff_man(7).

Was the original PP?

> 
> In ms(7), `LP` sets a paragraph that is left-aligned, and `PP` sets one
> with a first-line indentation.
> 
> In man(7), all (ordinary) paragraphs behave analogously to ms(7)'s `PP`.
> A first-line indentation is never used.
> 
> My opinion is that one should use `P` exclusively for a few reasons.
> 
> 1.  Its name is short and it is frequently used.  Huffman coding FTW.
> 2.  The existence of both `LP` and `PP` is difficult to rationalize to
>     anyone except a seasoned ms(7) author, of whom there are almost none
>     writing man(7) documents today.

Still, compatibility with ms(7) would make it slightly easier to
trasnfer learning from man(7) to ms(7), would one learn it.  I know many
other macros are incompatible in bad ways, but the less the better, no?

Cheers,
Alex

> 3.  It's been around long enough that everything supports it.  `LP`/`PP`
>     have no measurable advantage in this respect.  Anyone running early
>     BSD in 2023 has more interesting things to do than the composition
>     of legacy man pages.
> 
> Incidentally, mm(7) would have already had a `P` macro as well by 1979.
> Its call syntax is different (it interprets arguments; ms(7)'s and
> man(7)'s "plain" paragraphing macros do not).  Maybe this, and/or some
> friction between Bell Labs Research and the constantly reconfiguring
> series of departments dedicated to deriving revenue from Unix (and
> troff) commercially accounts for man(7)'s omission of it.
> 
> Nowadays, we can be confident that no loon is going to do something
> crazy with mm's `P` macro such that it would trip up man(7) writers.
> 
> <an evil grin spreads slowly across my face>
> 
> Regards,
> Branden



-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Why does man(7) have 3 paragraph macros for the same thing? (was: `\c`, mdoc(7), and man(7) extension macros)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2219 bytes --]

At 2023-10-26T16:58:13+0200, Alejandro Colomar wrote:
> On Thu, Oct 26, 2023 at 09:51:40AM -0500, G. Branden Robinson wrote:
> > At 2023-10-26T16:12:36+0200, Alejandro Colomar wrote:
> > > Regarding PP, LP, and P, what's the history of them?  Why do we
> > > have the 3?  I'm willing to reduce them to just one.
> > 
> > I invite Doug McIlroy to go on record, but my surmise is that they
> > were introduced as crutches for people already familiar with ms(7).
> > 
> > Doug's original man(7) (1979) didn't have `P`.  But Unix System III
> > added it in 1980, and 4.3BSD followed suit in 1986.  This
> > information is in groff_man(7).
> 
> Was the original PP?

It had both `PP` and `LP`.  I reckon Doug figured ms(7) veterans would
have an unreformable habit of typing one or the other.

https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/man/man7/man.7

I'd have been sterner--and probably less fondly remembered by my peers.

(While I'm armchair quarterbacking Doug's plays of 45 years ago, oh, how
I wish he hadn't have used input traps for anything in man(7).[1])

> Still, compatibility with ms(7) would make it slightly easier to
> trasnfer learning from man(7) to ms(7), would one learn it.  I know
> many other macros are incompatible in bad ways, but the less the
> better, no?

That's true, but these days the knowledge transfer is, I submit, vastly
more likely to go the other way; that is, people will be exposed to
man(7) as their first roff macro language, and might decide to pick up
ms(7).

At that point, they'd have to learn that `LP` and `PP` do _different_
things.  I think it's actually better if they _don't_ have to unlearn
the "fact" (applicable only to man(7)) that they are exactly the same.

Better, I believe, to promote only `P` in man(7).  Anyone wanting to
pick up mm(7) will still enjoy some knowledge transfer.  Without
arguments, `P` in mm(7) "does what you mean".

(I will not elaborate here on what that means; see the groff_mm(7) man
page in groff 1.23.0 and please God not an earlier version.)

Regards,
Branden

[1] In practice, nearly no one took them up for any purpose except the
    one place you _had_ to use them: `TP`.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Why does man(7) have 3 paragraph macros for the same thing?

[Ingo Schwarze]

Hi Branden and Alejandro,

G. Branden Robinson wrote on Thu, Oct 26, 2023 at 10:28:13AM -0500:
> At 2023-10-26T16:58:13+0200, Alejandro Colomar wrote:
>> On Thu, Oct 26, 2023 at 09:51:40AM -0500, G. Branden Robinson wrote:
>>> At 2023-10-26T16:12:36+0200, Alejandro Colomar wrote:

>>>> Regarding PP, LP, and P, what's the history of them?  Why do we
>>>> have the 3?  I'm willing to reduce them to just one.

>>> Doug's original man(7) (1979) didn't have `P`.  But Unix System III
>>> added it in 1980, and 4.3BSD followed suit in 1986.  This
>>> information is in groff_man(7).

>> Was the original PP?

> It had both `PP` and `LP`.

>> Still, compatibility with ms(7) would make it slightly easier to
>> trasnfer learning from man(7) to ms(7), would one learn it.  I know
>> many other macros are incompatible in bad ways, but the less the
>> better, no?

> That's true, but these days the knowledge transfer is, I submit, vastly
> more likely to go the other way; that is, people will be exposed to
> man(7) as their first roff macro language, and might decide to pick up
> ms(7).
> 
> At that point, they'd have to learn that `LP` and `PP` do _different_
> things.  I think it's actually better if they _don't_ have to unlearn
> the "fact" (applicable only to man(7)) that they are exactly the same.
> 
> Better, I believe, to promote only `P` in man(7).  Anyone wanting to
> pick up mm(7) will still enjoy some knowledge transfer.  Without
> arguments, `P` in mm(7) "does what you mean".

I consider this a bikeshed discussion.

Given that Branden apparently wants to
 * promote .P and deprecate .PP
 * i don't want mandoc_man(7) to gratuitiously spread any more bad
   man(7) style advice than is unavoidable by the fundamental decision
   of declaring the whole man(7) language as obsolete,
i briefly considered changing mandoc_man(7).

Currently it says:

  PP  Begin an undecorated paragraph.  The scope of a paragraph is closed
      by a subsequent paragraph, sub-section, section, or end of file.
      The saved paragraph left-margin width is reset to the default.

  LP  A synonym for PP.

  P   This synonym for PP is an AT&T System III UNIX extension later
      adopted by 4.3BSD.

and it declares LP and P deprecated by including only PP in the
MACRO OVERVIEW.

All the arguments feel weak in either direction:

 * In theory, .PP is more portable than .P, but that is extremely
   unlikely to ever matter in practice.
 * As seen above, the similarities and subtle differences
   when comparing to ms(7) can be employed as arguments in either
   direction.
 * The arguably more important similarity that HTML defines a <p>
   but not a <pp> element can be regarded as a learning aid,
   but it's still a weak argument because HTML and roff(7) are
   very different domains and not similar in most other respects.
 * The similarity of .P and <P> can also be turned around to be
   levied as an argument for .PP:  .P and <P> are *very different*
   in so far as <P> is a block element, whereas .P is an in-line
   macro that cannot participate in block nesting.  In particular,
   it can neither nest inside a list item, nor can anything be
   contained inside a .P syntax tree node.  In contrast to <p>,
   .P does not represent a *paragraph*, but only a paragraph *break*.
 * .PP is more similar to mdoc(7) .Pp.  Again, a weak argument because
   macro naming is totally different in both languages even in most
   of the few cases where functionality matches, with the exception
   of only .SH and .SS.

Consequently, i tend to leave mandoc_man(7) just as it is and not
repaint the bikeshed.  That way, the original .PP macro - with which
nothing is really wrong, except for the fundamental design mistake
of not being a block macro, a mistake it shares with mdoc(7) .Pp -
gets the full description, while the slighly younger .P gets the
compat info, even though that now is only of historical but not
of practical interest.  Maybe still nice to keep both apart - gee,
yet another weak argument.

If, for some reason, you feel strongly about it and think it is
important which one to promote, it might be possible to convince me to
deprecate .PP and list .P as the non-deprecated form even though it
is theoretically less portable.  I must admit i don't particularly
like the idea, though.  It feels like taking a gratuitious risk,
which does not feel ideal even if both the magnitude of the risk
and the benefit reaped are almost exactly zero.

Yours,
  Ingo

Re: Why does man(7) have 3 paragraph macros for the same thing?

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4380 bytes --]

Hi Ingo,

On Thu, Oct 26, 2023 at 07:52:13PM +0200, Ingo Schwarze wrote:
> 
> I consider this a bikeshed discussion.

Sure.  But someone has to design the bike parkings.  I find a lot awful
bike parkings that harm bike's wheels, and have to park it in a sign or
tree nearby.

> 
> Given that Branden apparently wants to
>  * promote .P and deprecate .PP
>  * i don't want mandoc_man(7) to gratuitiously spread any more bad
>    man(7) style advice than is unavoidable by the fundamental decision
>    of declaring the whole man(7) language as obsolete,
> i briefly considered changing mandoc_man(7).
> 
> Currently it says:
> 
>   PP  Begin an undecorated paragraph.  The scope of a paragraph is closed
>       by a subsequent paragraph, sub-section, section, or end of file.
>       The saved paragraph left-margin width is reset to the default.
> 
>   LP  A synonym for PP.
> 
>   P   This synonym for PP is an AT&T System III UNIX extension later
>       adopted by 4.3BSD.
> 
> and it declares LP and P deprecated by including only PP in the
> MACRO OVERVIEW.
> 
> All the arguments feel weak in either direction:
> 
>  * In theory, .PP is more portable than .P, but that is extremely
>    unlikely to ever matter in practice.
>  * As seen above, the similarities and subtle differences
>    when comparing to ms(7) can be employed as arguments in either
>    direction.
>  * The arguably more important similarity that HTML defines a <p>
>    but not a <pp> element can be regarded as a learning aid,
>    but it's still a weak argument because HTML and roff(7) are
>    very different domains and not similar in most other respects.
>  * The similarity of .P and <P> can also be turned around to be
>    levied as an argument for .PP:  .P and <P> are *very different*
>    in so far as <P> is a block element, whereas .P is an in-line
>    macro that cannot participate in block nesting.  In particular,
>    it can neither nest inside a list item, nor can anything be
>    contained inside a .P syntax tree node.  In contrast to <p>,
>    .P does not represent a *paragraph*, but only a paragraph *break*.
>  * .PP is more similar to mdoc(7) .Pp.  Again, a weak argument because
>    macro naming is totally different in both languages even in most
>    of the few cases where functionality matches, with the exception
>    of only .SH and .SS.
> 
> Consequently, i tend to leave mandoc_man(7) just as it is and not
> repaint the bikeshed.  That way, the original .PP macro - with which
> nothing is really wrong, except for the fundamental design mistake
> of not being a block macro, a mistake it shares with mdoc(7) .Pp -
> gets the full description, while the slighly younger .P gets the
> compat info, even though that now is only of historical but not
> of practical interest.  Maybe still nice to keep both apart - gee,
> yet another weak argument.
> 
> If, for some reason, you feel strongly about it and think it is
> important which one to promote, it might be possible to convince me to
> deprecate .PP and list .P as the non-deprecated form even though it
> is theoretically less portable.  I must admit i don't particularly
> like the idea, though.  It feels like taking a gratuitious risk,
> which does not feel ideal even if both the magnitude of the risk
> and the benefit reaped are almost exactly zero.

I don't think there's any urgent need to change mandoc_man(7), since
good quality man(7) pages should not even read that page.  I see it as
a quick guide if you're in a mandoc(1) system and need to fix a man(7)
bug or something.  If you're going to write new man(7) pages, you
probably want to read groff_man(7).

But I think having 3 ways of spelling PP is bad, and I think deprecating
at least LP, and possibly one of P or PP would be a good move.

For making sure pages are fixed, we could an a warning that gets
triggered always, so that projects have time to catch the change.

As for chosing P or PP: I don't mind very much which, but P seems
slightly better.  Since both are relatively widespread, and I can help
turn the balance in favour of any of them, I'll side with groff(1)
using and recommending P.  But yeah, it's a very arbitrary decission
between P and PP.

Cheers,
Alex

> 
> Yours,
>   Ingo

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Why does man(7) have 3 paragraph macros for the same thing? (was: `\c`, mdoc(7), and man(7) extension macros)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2579 bytes --]

Hi Branden,

On Thu, Oct 26, 2023 at 10:28:13AM -0500, G. Branden Robinson wrote:
> At 2023-10-26T16:58:13+0200, Alejandro Colomar wrote:
> > On Thu, Oct 26, 2023 at 09:51:40AM -0500, G. Branden Robinson wrote:
> > > At 2023-10-26T16:12:36+0200, Alejandro Colomar wrote:
> > > > Regarding PP, LP, and P, what's the history of them?  Why do we
> > > > have the 3?  I'm willing to reduce them to just one.
> > > 
> > > I invite Doug McIlroy to go on record, but my surmise is that they
> > > were introduced as crutches for people already familiar with ms(7).
> > > 
> > > Doug's original man(7) (1979) didn't have `P`.  But Unix System III
> > > added it in 1980, and 4.3BSD followed suit in 1986.  This
> > > information is in groff_man(7).
> > 
> > Was the original PP?
> 
> It had both `PP` and `LP`.  I reckon Doug figured ms(7) veterans would
> have an unreformable habit of typing one or the other.
> 
> https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/man/man7/man.7
> 
> I'd have been sterner--and probably less fondly remembered by my peers.
> 
> (While I'm armchair quarterbacking Doug's plays of 45 years ago, oh, how
> I wish he hadn't have used input traps for anything in man(7).[1])
> 
> > Still, compatibility with ms(7) would make it slightly easier to
> > trasnfer learning from man(7) to ms(7), would one learn it.  I know
> > many other macros are incompatible in bad ways, but the less the
> > better, no?
> 
> That's true, but these days the knowledge transfer is, I submit, vastly
> more likely to go the other way; that is, people will be exposed to
> man(7) as their first roff macro language, and might decide to pick up
> ms(7).
> 
> At that point, they'd have to learn that `LP` and `PP` do _different_
> things.  I think it's actually better if they _don't_ have to unlearn
> the "fact" (applicable only to man(7)) that they are exactly the same.
> 
> Better, I believe, to promote only `P` in man(7).  Anyone wanting to
> pick up mm(7) will still enjoy some knowledge transfer.  Without
> arguments, `P` in mm(7) "does what you mean".

Yep; since PP is different in the languages, not using it here will be
better.  So, I'll soon s/PP/P/

Cheers,
Alex

> 
> (I will not elaborate here on what that means; see the groff_mm(7) man
> page in groff 1.23.0 and please God not an earlier version.)
> 
> Regards,
> Branden
> 
> [1] In practice, nearly no one took them up for any purpose except the
>     one place you _had_ to use them: `TP`.



-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Why does man(7) have 3 paragraph macros for the same thing? (was: `\c`, mdoc(7), and man(7) extension macros)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 486 bytes --]

[self-correcting follow-up]

At 2023-10-26T09:51:42-0500, G. Branden Robinson wrote:
> In ms(7), `LP` sets a paragraph that is left-aligned, and `PP` sets
> one with a first-line indentation.
> 
> In man(7), all (ordinary) paragraphs behave analogously to ms(7)'s
> `PP`.  A first-line indentation is never used.

Sorry, brain fart here.

In man(7), all (ordinary) paragraphs behave analogously to ms(7)'s `LP`.
A first-line indentation is never used.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Why does man(7) have 3 paragraph macros for the same thing? (was: `\c`, mdoc(7), and man(7) extension macros)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 785 bytes --]

Hi Branden,

On Thu, Oct 26, 2023 at 11:09:23AM -0500, G. Branden Robinson wrote:
> [self-correcting follow-up]
> 
> At 2023-10-26T09:51:42-0500, G. Branden Robinson wrote:
> > In ms(7), `LP` sets a paragraph that is left-aligned, and `PP` sets
> > one with a first-line indentation.
> > 
> > In man(7), all (ordinary) paragraphs behave analogously to ms(7)'s
> > `PP`.  A first-line indentation is never used.
> 
> Sorry, brain fart here.
> 
> In man(7), all (ordinary) paragraphs behave analogously to ms(7)'s `LP`.
> A first-line indentation is never used.

Hmm, then, since I don't like that name, either of PP and P sound good.
Being shorter, P seems the best one.

I'll probably change that soon.

Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: `\c`, mdoc(7), and man(7) extension macros (was: [PATCH 1/2] man*/: srcfix)

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1985 bytes --]

Hi Alex,

At 2023-10-26T16:12:36+0200, Alejandro Colomar wrote:
> Yup.  I have similar feelings about C++, BTW.  I have a hard time
> understanding complex languages.  I prefer simpler languages.  Most
> features can be implemented as library code, without complicating the
> language.

Just know that following this road will take you to Lisp.  Or Scheme.

Or Forth.  ;-)

(Personally, I wish regular C _had_ put memcpy and memset (or bzero :P )
in the language.)

> Yep, I have 2/2 locally.  Maybe reply to the mail CCing vger, keeping
> only the commit message, so that readers of the list can get a notice
> of what MR.sed is.

Okay.  I'll aim for that for v5.

> I always make the mistake of writing MS instead of MT, out of inertia
> of having an 'S' for the start!  :D

Yes, that's what Doug McIlroy thought might happen.

> The others have nicer mnemonics that work for me; I wouldn't change
> them.  And well, just for changing MT, I wouldn't do it.
> 
> > 	SY -> NS (syNopsis start)
> > 	YS -> NE (syNopsis end)
> 
> Hmmm, no; I don't like it.

Fair enough.  I venture these things on the off chance that they're
brilliant strokes that will greatly increase the appeal of learning
man(7).

> Regarding PP, LP, and P, what's the history of them?  Why do we have
> the 3?  I'm willing to reduce them to just one.

We covered this in another thread, but as Ingo noted, there is no hope
of actually _retiring_ any of these.  At most they can be documentarily
deprecated and a high "-rCHECKSTYLE" setting can gripe about them.

groff man(7) formats every Seventh Edition Unix (1979) man page
correctly as far as I can tell, and I don't want to ever give that up.

(This is a slightly different objective from preserving perfect
compatibility with 7th edition's tmac.an.  I have no qualms about
discarding compatibility with details of macro package behavior that no
one relied upon for practical purposes.)

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: `\c`, mdoc(7), and man(7) extension macros (was: [PATCH 1/2] man*/: srcfix)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 976 bytes --]

Hi Branden,

On Sat, Oct 28, 2023 at 08:21:59AM -0500, G. Branden Robinson wrote:
> > Regarding PP, LP, and P, what's the history of them?  Why do we have
> > the 3?  I'm willing to reduce them to just one.
> 
> We covered this in another thread, but as Ingo noted, there is no hope
> of actually _retiring_ any of these.  At most they can be documentarily
> deprecated and a high "-rCHECKSTYLE" setting can gripe about them.

Makes sense.

> 
> groff man(7) formats every Seventh Edition Unix (1979) man page
> correctly as far as I can tell, and I don't want to ever give that up.
> 
> (This is a slightly different objective from preserving perfect
> compatibility with 7th edition's tmac.an.  I have no qualms about
> discarding compatibility with details of macro package behavior that no
> one relied upon for practical purposes.)

This gives me hope in changing the behavior of RS.  :P

Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: `\c`, mdoc(7), and man(7) extension macros (was: [PATCH 1/2] man*/: srcfix)

[Ingo Schwarze]

Hi Branden and Alejandro,

G. Branden Robinson wrote on Thu, Oct 26, 2023 at 07:58:35AM -0500:
> At 2023-10-25T21:38:59+0200, Alejandro Colomar wrote:
>> On Wed, Oct 25, 2023 at 01:54:24PM -0500, G. Branden Robinson wrote:

>>> diff --git a/man2/open.2 b/man2/open.2
>>> index 4c921723c..6603dfdff 100644
>>> --- a/man2/open.2
>>> +++ b/man2/open.2
>>> @@ -82,8 +82,13 @@ .SH DESCRIPTION
>>>  to an entry in the process's table of open file descriptors.
>>>  The file descriptor is used
>>>  in subsequent system calls
>>> -.RB ( read "(2), " write "(2), " lseek "(2), " fcntl (2),
>>> -etc.) to refer to the open file.
>>> +(\c

>> I'm going to disagree with Ingo with his claim that a macro that
>> forces using \c is bad because it promotes bad style.  '(\c' doesn't
>> look bad to me here.  Not more than having the leading punctuation as
>> an Nth argument.

> I disagree with Ingo on that point as well.
> 
> Saying why leads me to digress; I found myself writing down thoughts
> about future man(7) development more concretely than I have to date.
> (I'll return to this patch at the end.)  So, Ccing the groff list...
> 
> I think Ingo's perspective is strongly influenced by mdoc(7), the use of
> which he strenuously advocates.  And mdoc _does_ manage to make `\c`
> almost(?) totally unnecessary--

I think the sentence is accurate even without the "almost".
I don't recall ever using \c in any mdoc(7) page, and not even
seeing it used by others, and i cannot think of any reason why
anyone should ever want to use it.

> at the cost of a weighty internal recursive macro reprocessing system
> that no other *roff package is known to implement.
> 
> (This is what that "parsed"/"callable" stuff in groff_mdoc(7) (and
> mandoc_mdoc(7)) is all about.  Also, by "weighty", I mean it--back in
> ~1990, when mdoc was implemented, its documentation warned the reader of
> its slowness.  Fortunately, on modern systems, the rendering latency
> relative to man(7) is no longer noticeable.)

This all seems accurate.  With groff or any other full roff(7)
implementation, parsing mdoc(7) is still significantly slower
than parsing man(7) (when regarding the same amount of text output).
Consequently, while mandoc(1) is significantly faster than groff for
both mdoc(7) and man(7), the speed benefit is *much* more pronounced
for mdoc(7) than for man(7).

Your argument that nowadays, sufficient computing power is usually
available such that these performance differences typically no longer
matter for interactive use also makes sense.

> Even with performance considerations out of the picture, I think such a
> system is a point against adoption of mdoc; one can observe that,
> nowadays, both man(7) and mdoc require a person to acquire knowledge
> that they will "never" transfer anywhere else, assuming no resurgence in
> *roff popularity.

Granted.  Then again, trying to find such aspects, i actually found
fewer than expected.  Here are some examples of aspects common to
both languages that aren't actually that unusual:

 * The '.' request/macro line marker is not that different from
   markers used for embedding in-band control information into
   various protocols and encoding schemes.
 * The same applies to the `\` character introducing escape sequences.
 * While \" is a very unusual way of introducing comments,
   it is used in the same way as comment markers in most other
   line-oriented languages.
 * Unescaped whitespace (SPACE and TAB) has syntactical meaning
   and needs escaping in many languages.
 * Protected whitespace ("\ ", \~) exists in many languages.
 * While some of the names of scaling units may be unusual,
   the practice of appending units to numbers is fundamental
   in all sciences.  Besides, scaling units follow traditions
   of classical typography and arguably aren't obsolete even in
   the digital age.
 * Quoting arguments containing whitespace in "" is widespread
   in many languages.
 * Backslash-newline for input line continuation is widespread
   among line-oriented languages, too.
 * Having multiple glyphs for various kinds of hyphens and dashes
   is ubiquitious in typography.
 * Having to pay attention to quotes and accents and their proper
   encoding in input files is ubiquitious in typography, too.

Roff idiosyncracies that are common to mdoc(7) and man(7) and
unlikely to help anywhere else include:

 * Arguably the most unusual feature is \& and its various use cases.
 * Escaping '\' requires \[rs] (GNU syntax) or \e (portable syntax),
   and \\ has a totally different and rather complicated meaning.
 * The same goes for having to use "\&." rather than "\.".
 * That totally blank lines are not ignored in most contexts
   but more or less equivalent to .sp is certainly surprising.
 * Escaping " inside macro arguments by doubling it is quite unusual.

But the most scary idiosyncrasies of roff(7) syntax and semantics
appear only in low-level roff(7) and do not haunt manual page
authors, for example:

 * conditional and numerical expressions and their extremely
   unusual syntax and semantics
 * macro definitions and the unusual escaping needed there
 * the complicated concept of copy mode
 * diversions, traps, and the like
 * subtle differences between request and macro line parsing
 * and so on

> But the point is _even more true_ of mdoc than it is
> of man(7), by dint of the recursive macro reprocessing feature and the
> funny requirements that become necessary as a consequence (you have to
> use `\&` in more places; you have to break up individual punctuation
> characters when using them as macro arguments if you want them to work
> right).

True.  Still, you advocate using \& more more than we do, given
that you ask people to use it after every abbreviation even when it
is not at the end of an input line.

The only other aspect of mdoc(7) i can think of that is somehat
idiosyncratic is deliniter handling on macro lines, but that's
hardly worse than the complicated style rules for man(7) to solve
the same problem, especially considering that as a result, man(7)
has eight different macros for nothing but font control and still
needs \c on top of all those.

The fact that mdoc(7) macro names require \&-escaping when you
want to print them literally is hardly different from the
concept of reserved words in other languages, so there is really
nothing unusual about that.

> In other words, learning mdoc doesn't help you learn *roff all
> that much.

That doesn't sound like a very strong argument.  Which fraction of
people who have to write manual pages want to learn roff(7) but
do not know it yet?  Wild guess: not a huge fraction.

> Not as much as man(7) does.  And it doesn't help you
> learn any other programming/documentation system anywhere.

Does man(7), really?  I doubt it.  Mastering man(7) probably makes
it easier to learn ancient macrosets like mm(7), me(7), and ms(7)
afterwards, and more so than mdoc(7), i do not deny that.  But i
don't think it helps to learn the modern mom(7) macroset, nor to
learn low-level roff(7) programming.

> Plus, in mdoc, there is a much larger lexicon of macros to learn in the
> first place.  I count 115.
> 
> $ git grep '\.\(als\|de\) [A-Z][A-Za-z1][a-z]*' \
>   tmac/doc.tmac tmac/mdoc/doc-!(nroff) | wc -l
> 115
> 
> Admittedly, a couple of those are, if not deprecated, unlikely to be
> used in practice, because even after mdoc's documentation spent decades
> asking its readers for help, no one could be found who clearly remembers
> what they were supposed to do (`Me`, `Ot`).  So, call it 113 macros.

Now you nudged me enough to actually classify all macros in order to
allow a meaningful comparison.  I'll count not individual macros,
but groups of macros that form logical or syntacticl units.

Active macros, same functionality in mdoc(7) and man(7):
  .Dd/.Dt/.Os   .TH
  .Sh           .SH
  .Ss           .SS
  .Xr           .MR
  .Pp           .PP/.P
  .Bd -literal  .EX/.EE
  .Bl -bullet   .IP/.TP/.TQ   # -dash/-hyphen is almost identical
  .Bl -column   tbl(1)
  .Bl -enum     .IP/.TP/.TQ
  .Bl -tag      .IP/.TP/.TQ
  .Pf/.Ns       .BI/.IB \c
  .Lk           .UR/.UE
  .Mt           .MT/.ME
  .Em           .I
  .Sy           .B
  .No           .BR/.IR/.RB/.RI

Semantic markup, mdoc(7) only:
  .Nm
  .Nd
  .Sx
  .Tg
  .Dl
  .Ql
  .Rs/.%*/.Re   refer(1)
  .Fl
  .Cm
  .Ar
  .Op/.Oo/.Oc
  .Ic
  .Ev
  .Pa
  .In
  .Fd
  .Ft
  .Fn
  .Fo/.Fc
  .Fa
  .Vt
  .Va
  .Dv
  .Er
  .Ev
  .An

Structural markup, mdoc(7) only:
  .Bd -unfilled
  .D1

Useful enclosures, mdoc(7) only:
  .Dq/.Do/.Dc   # most useful for quoting plain English words
  .Qq/.Qo/.Qc   # most useful for C strings
  .Sq/.So/.Sc   # most useful for displaying single characters
  .Pq/.Po/.Pc
  .Bq/.Bo/.Bc

Useful text production macros, mdoc(7) only,
operating systems can easily decide to not use these at all:
  .Ex -std
  .Rv -std
  .St

Presentational markup, man(7) only:
  .RS/.RE

Semi-semantic markup, man(7) only, but badly designed:
  .OP      # combines .Fl and .Ar, but too inflexible for practical use
  .SY/.YS  # combines .Nm/.Cm/.Ar, but too inflexible for practical use

No need to learn for newbies, mdoc(7) only:
  .Bd -centered   not very useful and usually poorly implemented
  .Bd -filled     completely useless
  .Bd -ragged     almost never needed
  .Bl -diag       very specialized for .Sh DIAGNOSTICS
  .Bl -hang       almost never useful
  .Bl -inset      almost never useful
  .Bl -item       almost never useful
  .Bl -ohang      almost never useful
  .Ap             identical to .Ns \(aq
  .Sm             rarely useful, can alsways be achieved with .Ns
  .Bk/.Ek         almost never useful
  .Lb             catastrophic misdesign
  .Cd             very specialized for .Sh SYNOPSIS in kernel manuals only
  .Ad             almost never useful
  .Ms             very specialized and rarely used
  .Bf             completely useless
  .Brq/.Bro/.Brc  very rarely useful, easy alternatives exist
  .Aq/.Ao/.Ac     very specialized, used almost exclusively with .Mt
  .Eo/.Ec         never really needed, .Ns can always do the job
  .Nx/.Fx/.Ox/.Dx operating system specific, irrelevant elsewhere
  .Li             very rarely useful and already deprecated
  .Xo/.Xc         very rarely useful for tagged lists with tags that
                  are both extremely long and extremely complicated,
                  but ordinary backslash-newline input line continuation
                  can be used to solve these problems, too

No need to learn for newbies, man(7) only:
  .PD

Already completely deprecated in mdoc(7):
  .Bt
  .Db
  .Es/.En
  .Fr
  .Hf
  .Lp
  .Ot
  .Tn
  .Ud
  .Ux
  .At/.Bx/.Bsx    historical use only

Alread completely deprecated in man(7):
  .AT
  .UC
  .SB
  .SM
  .DT
  .HP
  .LP
  
Summary:
macro group      mdoc(7)  man(7)  common
structural        7                9
semantic         26        2       3
whitespace                         2
presentational             1       2
text production   3
TOTAL            36        3      16 not counting unimportant and deprecated
unimportant      22        1
deprecated       11        7

By this count, mdoc(7) has 52 useful macros and man(7) has 19.
Yes, that is significantly more, but mdoc(7) is much closer to man(7)
in this respect than to monstrosities like DocBook and Texinfo.

Also, 26 of these additional macros are semantic macros that by
design, man(7) lacks any kind of support for, so comparing the raw
numbers compares apples to oranges.  Excluding those 26:2:3 for a
fair comparison results in 23:14, which is hardly a very impressive
difference, especially considering that most of this results from
support of useful displays and enclosures somewhat lacking from man(7).

The real question to ask here is whether 26 macros is a reasonable
number of semantical markup macros or whether we could get away
with a significantly smaller number.  I don't think that would be
possible except with significant loss of expressive power.
Besides, those 26 macros are very easy to use.

> But Ingo added `Tg` to mandoc(1) mdoc--which groff doesn't support yet--
> so make that 114.

Yes, i did at one new macro in 15 years, after pondering whether
it was needed and refining the design for about a decade.
Buring the same time, i also deprecated about ten old macros.

> None of this is to say that mdoc should go away.  I do not mirror
> mandoc(1)'s initial ambition to completely kill off man(7).[3]  There's
> room in the world for mdoc, and I think it can coexist with man(7).

Yes, the last three decades have proven that both can coexist.
But that doesn't justify keeping man(7) on life support any longer.

Pointing out significant design mistakes in mdoc(7) would make
designing a completely new, man(7)-based semantic markup language,
as you apparently plan to, seem worthwhile.  But as shown above,
i think neither the argument that mdoc(7) syntax is too idiosyncratic
nor that the macro inventory is excessively large has merit.

Adding a novel idea or a novel concept might also make designing a
new language worthwhile.  But so far, all that i see proposed here is
turning the man(7) language upside down to switch from presentational
to semantic markup and from in-line macros to nesting blocks, and
those are both 1990 concepts already provided by mdoc(7).

> But
> I tire both of mdoc advocates' derogations of man(7), and of resistance
> to development of the man(7) language so intransigent that it keeps the
> macro package from rising to the challenge mdoc has presented to it,
> particularly in areas that man(7) authors also complain about.  A
> community with totalitarian conquerors on one hand and reactionaries who
> prefer death to evolution on the other is an unhealthy one.
> 
> Does mdoc do a better job of semantic markup?  Absolutely.  But I have
> an idea for bringing man(7) to parity in that department as well--at a
> much lower cost in macro name space and human memory loading.  It will
> cost 3 macros: one to define a tag class, and two others to open and
> close an annotation of enclosed material with a tag class.  (The
> bracketing is for (a) flexibility: tag as large a region of the page as
> you like, and (b) robustness: if an implementation doesn't support the
> macros--and many won't, especially at first--the rendered text of the
> page will not be damaged by ignoring the macros.)

If you want to switch the basic paradigms of the language late
in its life, that may be one possible solution for doing so.
I fear it may result in massive verbosity, though.

Consider the following, moderately complicated example from
the apropos(1) manual page.  The mdoc(7) language can gracefully
handle stuff that is much worse:

  .Bl -tag -width Ds
  .It Ar expr1 Op Fl o Ar expr2

If i understand your idea correctly, that would become something
similar to:

  .TAG argument
  expr1
  .TAGE
  .TAG optional
  [\c
  .TAGE
  .TAG cammand-line-flag
  \-o\c
  .TAGE
  .TAG optional
  ]
  .TAGE
  .TAG argument
  expr2
  .TAGE

Is that really better?  For example, regarding maintainability of
the manual page source code?  Or regarding readability?

Next question:  How are you planning to get that into the
next-line head scope of the .TP macro?

The mdoc(7) language wasn't only highly innovative for using the
concept of semantic markup in a mostly consistent manner in 1990,
that is, long before HTML became semantic, and not only managed
to keep the macro inventory very small (which is a massive
improvement over all its successors), but it is also ingenious
for its very compact and very readable syntax that allows
easy writing and easy maintainance of highly complicated markup,
which is a massive improvement over one of its successors, XML.
If i understand your proposal correctly, you risk ending up with
a very bad re-invention of XML, and if you then proceed to calling
that new language "man(7)", is see a real risk that you might
cause Doug to turn over in his grave even though he is fortunately
very alive and quite active and will hopefully remain so for
long times to come.

> Potentially, the big payoff is that most man pages won't have to define
> tag classes at all.  The definitions of these can be left to man page
> maintenance communities--like that of the Linux man-pages--and the class
> definitions `so`urced in.  Again, nothing breaks the formatted page if
> something goes wrong with this, like an anemic formatter not
> implementing the `so` request, or the tag definition file being missing.

I have absolutely no idea how this is supposed to work.  Let's say,
a specific operating system or "manual page maintenance community"
decides to define a new "tag class".  At least intially, that tag class
will not be known to any of the formatters.  Since the possibility
is documented and advertised, lots of communities will start to use
it, resulting is a rapid proliferation of redundant, inconsistent,
and clashing tags names.  It is trivial to predict that even those
formatters that initially intend to participate in that game of
catch will sooner or later run out of steam and fail to catch up:
we have already seen exactly that happen in the much simpler case
of the similarly misdesigned macros .Nx and .Fx in mdoc(7).

However, when formatting for any given semantic output language -
for example, HTML+CSS or LaTeX - the formatter will have to make
specific decisions about which output elements to use for the
input tag.  It simply cannot make such a decision in a reasonable
way for an unknown tag.  So this whole scheme is set up for utter
failure in exactly the same way as the mdoc(7) .Lb macro foundered,
or even worse, because for .Lb, the unavoidable desynchronization
merely causes unavailable description strings which can simply be
omitted, while here, the fundamental task of choosing adequate markup
elements becomes impossible.

I think this misdesign results from you still being stuck in a
presention-only markup mindset, even while trying to design a markup
scheme that you hope to become "semantic".  Semantic markup is *not*
about making the presentational aspect of the markup customizable.
Semantic markup is about defining a globally consistent catalogue
of tags.  Even bad, overengineered markup languages like DocBook
and Texinfo understand at least that much (even though DocBook
mostly fails to actually execute the concept).  The quality of the
language so defined depends on finding a good balance between making
the catalogue large enough such that is does not have gaps hindering
practical documentation work, but small enough such that it remains
easy to work with.  Making the catalogue itself customizable totally
defeats the central purpose of the whole endeavour, making utter
failure an unavoidable certainty.

> What would tag classes enable us to do?
> 
> (1) Associate formatting (style) decisions, like what typeface to use
>     for an item, with text based on the _meaning_ of that text.
> 
> (2) Make those styles customizable independently of a given man(7)
>     document, and in one or only a few locations.  Want file names to
>     show up in italics always?  Or roman always?  If the man page uses
>     semantic tagging, you'll be able to.  groff mdoc supports this but
>     it seems to be a fairly obscure feature.  For mandoc(1), this sort
>     of customization is, as I understand it, considered an anti-feature.

Indeed.  I think even after fxing the "undefined classes" disaster and
deciding on a good catalogue of classes to build into the language,
making markup customizable is still an absolutely terrible idea.
The fact you state yourself that very few people do it even in those
few cases where it is already possible is a clear indication that
there is no real demand.  Sure, if there is any way how anything
could posibly be made customizable, one person will eventually
show up demanding customizability, if only you wait long enough.
But beware of the trap of confusing that with "there is demand."
On the other hand, once something is customizable, sooner or later,
someone will start twiddling knobs, including distribution maintainers,
and the predictable long-term end result is going to be that manual
page markup looks different on each and every operating system and
distro, endlessly confusing users.  For no benefit whatsoever.
Global consistency plus long-term markup stability (such that
users don't have to re-learn every few years how markup looks like)
is one among the most important goals of what we are doing here,
especially from the perspective of users how aren't and don't want
to be specialists with respect to documentation markup.

> 	EX -> ES (example start)
> 	MT -> MS (mail-to start)
> 	UR -> US (URL start)
> 	YS -> SE (synopsis end)
> 	SY -> NS (syNopsis start)
> 	YS -> NE (syNopsis end)

Sounds like a pointless reshuffling of deck chairs.  You want that
formatters remain able to format old manual pages, so you can *never*
remove parsing support those old names.  Previously, users who wanted
to read manual page source code had to remember one name per macro.
After that, they have to remember (or look up) two names.  For very
little benefit, at best.

> [3] "The mission of mdocml is to deprecate groff, the GNU roff
>     implementation, for displaying -mdoc pages whilst providing token
>     support for -man."
> 
>     This rather fiery statement appeared at mdocml.bsd.lv in 2009, but
>     was withdrawn in late 2013.
>     [...]
>     While no longer a statement of mission, the attitude persists.

The reason for withdrawing that statement was that mandoc(1) now
aims to provide full groff-compatible support for man(7) rather than
merely "token support".  That doesn't change the first paragraph of
the mandoc_man(7) manual page, which is still completely reasonable:

   The man language was the standard formatting language for AT&T UNIX
   manual pages from 1979 to 1989.  Do not use it to write new manual
   pages: it is a purely presentational language and lacks support for
   semantic markup.  Use the mdoc(7) language, instead.

Yours,
  Ingo

Re: `\c`, mdoc(7), and man(7) extension macros (was: [PATCH 1/2] man*/: srcfix)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1563 bytes --]

Hi Ingo,

[...ingoring the battle in which I don't want to participate...]
[My position here is that man(7) has problems, but I fear that jumping
to mdoc(7) *may* be worse; I can't know before jumping, which is a
problem.  Maybe if some pages are added written in mdoc(7), I get used
to it and start to like it, but until that happens, I'm sticking to
man(7).  For now, I prepared the repo to welcome mdoc(7) pages.]

But my mail was for the following.  I'd like to comment on this
comparison:

On Fri, Oct 27, 2023 at 01:27:53AM +0200, Ingo Schwarze wrote:
> 
> Active macros, same functionality in mdoc(7) and man(7):
>   .Dd/.Dt/.Os   .TH
>   .Sh           .SH
>   .Ss           .SS
>   .Xr           .MR
>   .Pp           .PP/.P
>   .Bd -literal  .EX/.EE
>   .Bl -bullet   .IP/.TP/.TQ   # -dash/-hyphen is almost identical

My guidelines in man-pages(7) recommend that you only use .IP \[bu]
for bullets (or \(bu if you want more portability).  I would remove TP
and TQ from there.

>   .Bl -column   tbl(1)
>   .Bl -enum     .IP/.TP/.TQ

Similarly, this would be .IP [1] or .IP (1), but never TP nor TQ.

>   .Bl -tag      .IP/.TP/.TQ

And for this one, I only recommend TP and TQ (TQ as a Tag Qontinuation
--it sounds better in my head, where I don't see it written :p--).  I'd
remove IP here.

>   .Pf/.Ns       .BI/.IB \c
>   .Lk           .UR/.UE
>   .Mt           .MT/.ME
>   .Em           .I
>   .Sy           .B
>   .No           .BR/.IR/.RB/.RI

Cheers,
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]