bugGNU roff - Bugs: bug #61002, [man] old macro...

 
 

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

Submitter:  Bjarni Ingi Gislason <bjarniig>
Submitted:  Mon 02 Aug 2021 05:05:23 PM UTC
   
 
Category:  Macro man Severity:  1 - Wish
Item Group:  Feature change Status:  Rejected
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Wed 04 Aug 2021 07:14:45 AM UTC, comment #3: 

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.

G. Branden Robinson <gbranden>
Group administrator
Wed 04 Aug 2021 06:43:01 AM UTC, comment #2: 

I concur with Ingo.

Things breaking like this is the only name space protection feature that roff languages have.

I welcome inquiries from DocBook XSL developers regarding how to generate man(7) output that will achieve the effect they want.

Monkeying around under the hood of the package's public interface is not the way to achieve such aims.

G. Branden Robinson <gbranden>
Group administrator
Mon 02 Aug 2021 05:54:11 PM UTC, comment #1: 

I advise against this.  If people use undocumented internal features of a system that are not part of the API, they get what they deserve: their stuff will inevitably break at some point.

The DocBook crowd does that very frequently and in large numbers of respects, usually in completely gratuitious and particularly unreasonable ways.  Trying to cater for that would be a hopeless uphill battle deep down into a bottomless rabbit hole.  Catering for a random, single instance of such madness out of many that exist helps no one and encumnbers the groff codebase for now good reason.

Even if providing full backward compatibility for DocBook, which does not seem feasible at all, DocBook rendering quality would still remain abysmal because DocBook output is just wrong in so many respects.  So the whole project would be pointless.

If you care about DocBook, report DocBook bugs to the DocBook crowd, not to groff.  You will have insane amounts of work to do.  Good luck.

Ultimately, the whole official DocBook toolchain ought to be abandoned because it is utterly ill-designed and unmaintainable.  Existing documents can be salvaged with tools like docbook2mdoc, the output of which is readily usable with groff.

I suggest closing this ticket as "won't fix".

Ingo Schwarze <schwarze>
Group Member
Mon 02 Aug 2021 05:05:23 PM UTC, original submission:  


  Some manuals, created with "DocBook XSL Stylesheets" in the following
Debian packages

git (git-imap-send), aptitude, dstat, and xsltproc in man1

git, libnftables and systemd in man5

git in man7

aptitude and nftables in man8,

  use the macro "an-trap".

  A fix is to add ".als an-trap an-input-trap" to "an.tmac",

Bjarni Ingi Gislason <bjarniig>

 

(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 gbranden (Posted a comment)
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by bjarniig (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 5 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-03-05 gbranden Summary[an.tmac]: old macro &quot;an-trap&quot; is used in some manuals [man] old macro "an-trap" is used in some manuals
    2021-08-04 gbranden StatusNone Rejected
        Assigned toNone gbranden
        Open/ClosedOpen Closed
    2021-08-02 schwarze Severity3 - Normal 1 - Wish

    Back to the top

    Powered by Savane 3.13-d3ae.
    Corresponding source code