[bug #61002] [an.tmac]: old macro "an-trap" is used in some manuals

[G. Branden Robinson]

Follow-up Comment #3, bug #61002 (project groff):

Out of sick curiosity, I went to see what exactly one of these pages was up to
(xsltproc.1).  They're ALL UP in our business.

To achieve this fairly unremarkable terminal output:


       -o or --output FILE | DIRECTORY
           Direct output to the given FILE. Using the option with a DIRECTORY
           directs the output files to the specified directory. This can be
           useful for multiple outputs (also known as "chunking") or manpage
           processing.

           Important
           The given directory must already exist.

           Note
           Make sure that FILE and DIRECTORY follow the “URI reference
           computation” as described in RFC 2396 and laters. This means,
that
           e.g.  -o directory will maybe not work, but -o directory/ will.



...they do the following:


.PP
\fB\-o\fR or \fB\-\-output\fR \fIFILE\fR | \fIDIRECTORY\fR
.RS 4
Direct output to the given
\fIFILE\fR\. Using the option with a
\fIDIRECTORY\fR
directs the output files to the specified directory\. This can be useful for
multiple outputs (also known as "chunking") or manpage processing\.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
Important
The given directory
\fBmust\fR
already exist\.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
Note
Make sure that
\fIFILE\fR
and
\fIDIRECTORY\fR
follow the
\(lqURI reference computation\(rq
as described in RFC 2396 and laters\. This means, that e\.g\.
\fB\-o directory\fR
will maybe not work, but
\fB\-o directory/\fR
will\.
.RE


So they don't only pull on the large animal vet latex glove for an-trap, but
an-no-space-flag and an-break-flag as well.  It seems almost as if someone
didn't really know what .sp and .br did, even though they call them directly
(bad style, but vastly more excusable than mucking with man(7) internals). 
The deployment of groff man(7)'s own input trap is particularly clueless
because the generator _has the input document already_.  An input trap is
something you plant ahead of time when you don't know what the next input line
is going to be. 

All just to set a paragraph that I suppose in DocBook proper gets boxed with a
centered "Important" or "Note" respectively (probably in a loud typeface).

This is wholly unnecessary (as is the repeated escaping of the period
character, while managing to _not_ use the non-printing input break to protect
it from end-of-sentence detection).  I find the font escapes gratuitous as
well, but pretty much everyone who has a written a man(7) generator evinces a
terror of the font macros, so that's par for the course.

It's really not clear to me what they're trying to achieve with this in the
abstract.  I guess I'd have to look at the generator's source code, and that I
am not yet willing to do.

Since all three of these internals were renamed in commit 7a6a4be5, 18 May, I
decided to render this xsltproc.1 page with the current version of the macros.
 The only change is that "Important" and "Note" don't get breaks after them.


$ diff -u O N
--- O   2021-08-04 17:11:24.984111505 +1000
+++ N   2021-08-04 17:11:47.028170654 +1000
@@ -1,9 +1,7 @@
 XSLTPROC(1)                     xsltproc Manual                   
XSLTPROC(1)
 
-
-
 NAME
-       xsltproc ‐ command line XSLT processor
+       xsltproc - command line XSLT processor
 
 SYNOPSIS
        xsltproc [[-V | --version] [-v | --verbose] [{-o | --output} {FILE |
@@ -85,11 +83,9 @@
            useful for multiple outputs (also known as "chunking") or manpage
            processing.
 
-           Important
-           The given directory must already exist.
+           Important The given directory must already exist.
 
-           Note
-           Make sure that FILE and DIRECTORY follow the “URI reference
+           Note Make sure that FILE and DIRECTORY follow the “URI
reference
            computation” as described in RFC 2396 and laters. This means,
that
            e.g.  -o directory will maybe not work, but -o directory/ will.
 
@@ -214,6 +210,4 @@
 COPYRIGHT
        Copyright © 2001, 2002
 
-
-
 libxslt      $Date: 2008-04-21 16:28:56 +0200 (Mon, 21 Apr 2008) $
XSLTPROC(1)


(The blank line changes after the header and before the footer are unrelated,
due to commit 2278d6ed on 16 June.)

This is merely cosmetic damage, and no worse than many other eye-wateringly
bad style problems in the page (like the use of an acute accent for an
apostrophe, sentences ending without terminal punctuation, and non-idiomatic
English usage.

And boy do I hate what they're doing with the arguments to TH, too.

    _______________________________________________________

Reply to this item at:

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

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