[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[bug #61002] [an.tmac]: old macro "an-trap" is used in some manuals
From: |
G. Branden Robinson |
Subject: |
[bug #61002] [an.tmac]: old macro "an-trap" is used in some manuals |
Date: |
Wed, 4 Aug 2021 03:14:46 -0400 (EDT) |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Firefox/78.0 |
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/