Alex raised an issue that I suspect a lot of people don't know how to
cope with:
How do we avoid warnings from the formatter and/or bad typography in a
man page when huge URLs or file names must occur in the document?
The mechanism for doing so has been in groff for decades, but practical
advice to man page authors has been locking. A few years we hashed the
matter out of the groff list, and you can find guidance in the
groff_man_style(7) page.
groff_man_style(7):
Prepare arguments to .MR, .MT, and .UR for typesetting; they can
appear in the output. Use special character escape sequences to
encode Unicode basic Latin characters where necessary, particularly
the hyphen‐minus. (See section “Portability” below.) URIs can be
lengthy; rendering them can result in jarring adjustment or
variations in line length, or troff warnings when one is longer
than an output line. The application of non‐printing break point
escape sequences \: after each slash (or series thereof), and
before each dot (or series thereof) is recommended as a rule of
thumb. The former practice avoids forcing a trailing slash in a
URI onto a separate output line, and the latter helps the reader to
avoid mistakenly interpreting a dot at the end of a line as a
period (or multiple dots as an ellipsis). Thus,
.UR http://\:example\:.com/\:fb8afcfbaebc74e\:.cc
has several potential break points in the URI shown. Consider
adding break points before or after at signs in email addresses,
and question marks, ampersands, and number signs in HTTP(S) URIs.
Here's the exhibit Alex handled recently:
At 2024-12-19T12:08:35+0100, Alejandro Colomar wrote:
> I've had to amend the patch again. I didn't notice that it caused
> many warnings in -Tutf8, -Thtml, -Tps, and -Tpdf output. I've applied
> the following diff.
>
> diff --git a/man/man3/getopt.3 b/man/man3/getopt.3
> index 3b0025528..cb946355a 100644
> --- a/man/man3/getopt.3
> +++ b/man/man3/getopt.3
> @@ -384,7 +384,7 @@ .SH HISTORY
> .IR <stdio.h> .
> .P
> Very old versions of glibc were affected by a
> -.UR https://sourceware.org/git/?p=glibc.git;a=commitdiff;h=bf079e19f50d64aa5e05b5e17ec29afab9aabb20
> +.UR https://\:sourceware.org/\:git/\:?p=glibc.git;a=commitdiff;h=bf079e19f50d64aa5e05
> .BI _ PID _GNU_nonoption_argv_flags_
> environment variable
> .UE .
>
> That adds break points, and also reduces the hash by half (which
> should hold without clashes forever, hopefully).
I observe that break points could also be added after semicolons.
Also, you can escape a newline to keep the input line length short.
.UR https://\:sourceware.org/\:git/\:?p=glibc.git;a=commitdiff;\
h=bf079e19f50d64aa5e05
groff_man_style(7):
\newline Join the next input line to the current one. Except for
the update of the input line counter (used for diagnostic
messages and related purposes), a series of lines ending
in backslash‐newline appears to groff as a single input
line. Use this escape sequence to split excessively long
input lines for document maintenance.
Regards,
Branden
Attachment:
signature.asc
Description: PGP signature
