Hi Alex,
At 2023-01-04T19:41:51+0100, Alejandro Colomar wrote:
> On 1/4/23 16:55, G. Branden Robinson wrote:
> > At 2023-01-04T13:26:33+0100, Alejandro Colomar wrote:
> > > > .SH NAME
> > > > ldconfig \- configure dynamic linker run-time bindings
> > > > .SH SYNOPSIS
> > >
> > > We should wrap this in .nf/.fi
> >
> > That will have a cost. It will mean using a lot of \c escape
> > sequences to connect the output lines.
> >
> > The existing synopsis fits within 74 output columns on a terminal.
> >
> > Do you think it's worth it?
>
> But, it we don't use it, if someone uses a smaller terminal, there
> might appear our beloved hyphens breaking a word...
That's true. But what is _not_ true is that you don't have a minimum
expected terminal width. You do, you just might not know what it is and
it may not even have been consciously chosen.
The minimum expected terminal width for the Linux man-pages corpus is
the longest output line produced by an unfilled (.nf/.fi) region or a
tbl(1) row that doesn't use a text block. Somewhere in the ~2,539 man
pages, a longest unfilled line lurks...and its identity may change
depending on the output device used to render it (terminal vs.
typesetter).
If you _do_ know what that expected minimum is, please document it.
The nearest thing I see is:
"Please limit source code line length to no more than about 75
characters wherever possible." -- man-pages(7)
But the relationship between input document line length for and
formatted output line length is a loose one.
In any event, groff man(7)'s SY/YS extension macros are _built_ for this
application. I'm happy to "port" this page to use them; doing so will
permit removal of the PD macro calls, among other benefits.
> Is there anything that "reverts" \%? So that if it were the default,
> we could use \anti-% to say "groff, you might break this word"?
Yes. \% itself does that.
From the groff 1.23 Texinfo manual (with stuff irrelevant to man(7)
usage stripped out):
-- Escape sequence: \%
-- Escape sequence: \:
To tell GNU 'troff' how to hyphenate words as they occur in input,
use the '\%' escape sequence; it is the default "hyphenation
character". Each instance within a word indicates to GNU 'troff'
that the word may be hyphenated at that point, while prefixing a
word with this escape sequence prevents it from being otherwise
hyphenated. This mechanism affects only that occurrence of the
word; [...]
[...]
'\:' inserts a non-printing break point; that is, a word can break
there, but the soft hyphen glyph (see below) is not written to the
output if it does. This escape sequence is an input word boundary,
so the remainder of the word is subject to hyphenation as normal.
You can use '\:' and '\%' in combination to control breaking of a
file name or URL or to permit hyphenation only after certain
explicit hyphens within a word.
The \%Lethbridge-Stewart-\:\%Sackville-Baggins divorce
was, in retrospect, inevitable once the contents of
\%/var/log/\:\%httpd/\:\%access_log on the family web
server came to light, revealing visitors from Hogwarts.
> > groff man(7) _has_ a mechanism for this, and has since groff 1.19
> > (2003). It's the `HY` register. People can put this in their
> > man.local files (on Debian-based systems, that's in /etc/groff).
> >
> > .nr HY 0
>
> I know, but I don't think we should write manual pages in a way that
> forces distributors to use such a thing.
As far as I know, most distributors aren't configuring man.local this
way today, despite it having been possible for almost 20 years. Adding
explicit hyphenation breakpoints (or their suppression) isn't going to
force them any harder than they have been for 2 decades; it will in fact
reduce any such pressure by reducing the number of bogus hyphenation
breaks when hyphenation is enabled.
> Either the pages are written plagued with \%,
Like changes in lettercase, this is _information_.
> and the distros don't need to use .HY, or we write pages lazily so
> that distros need to fix the hyphenation.
Distributors' laziness seems to be a match for Linux man-pages's own;
users seem to muddle through without much evident complaint. I suppose
people who copy-and-paste multiple lines from a man page realize they
need to remove the hyphens along with newlines. Fortunately, on UTF-8
terminals, they have hope of seeing the difference between hyphens and
the ASCII hyphen-minus that is always(?) meant as a literal.
> But writing the pages lazily and having distributors ignore it would
> result in suboptimal pages for our readers.
I think marking break points, hyphenated and otherwise (as with URLs),
is the opposite of laziness. It is a level of fastidiousness I don't
actually expect of many man(7) writers apart from myself.
> > Colin Watson's man-db man(1) also has a feature to suppress
> > hyphenation, using a hack; it's not pretty but it works even on
> > other *roff formatters.
>
> Does that disable hyphenation for macros, or for the entire document?
> I only want to disable it in highlighting macros.
I don't quite understand what you mean by "macros" here. Macro
interpolation is textual replacement, there isn't really a macro "mode"
that is visible to the formatter when hyphenation decisions are made.
But if by "highlighting macros" you mean font selection and
alternation macros in man(7) (.B, .I, .BR, etc.), then the answer is
"for the entire document". You don't always want to disable hyphenation
when using these macros anyway. Not everything is a literal. The font
macros are presentational, not semantic.
Even then, I would not suppress hyphenation of a metasyntactic variable,
like "directory". The whole point of these is that they are textually
replaced _by the reader_.
> > I don't insist that people keep hyphenation enabled, but assuming
> > that no one will do so will keep us from putting worthwhile
> > information in our man pages.
> >
> > If you dread the tedium of adding \% escape sequences to "keywords"
> > all over the place, I don't blame you. This is one reason I
> > proposed my most ambitious man(7) extension yet, a two-macro
> > semantic tag mechanism.
> >
> > https://marc.info/?l=linux-man&m=165868366126909&w=2
>
> I still don't know what to think about that.
That's okay. Its realization is some ways off, if ever. First I need
Bertrand to recover from holidays. :-O
> "XXX - quick hack, should disappear before anyone notices :)."
>
> Of course, the quick hack never disappeared after Oct 7, 2007, when it
> was written in stone.
Of course!
> <https://github.com/shadow-maint/shadow/commit/6b6e005ce1cc4a5e4fc7fc40a52f2ed229f54b5b>
>
> "XXX - is the above ok or should it be <time.h> on ultrix?"
If you pine for a stagnant commercial Unix to kick around, Solaris 10
will be around for another year or so...
Regards,
Branden
Attachment:
signature.asc
Description: PGP signature
