Hi Branden, On 12/13/22 18:35, G. Branden Robinson wrote:
Hi Alex, [finally getting to this; my email reply queue is about 3 weeks deep] At 2022-12-04T13:34:43+0100, Alejandro Colomar wrote:On 12/4/22 10:07, Helge Kreutzmann wrote:Without further ado, the following was found: Issue: /proc/sys/user → I</proc/sys/user> "The /proc/sys/user directory"That is a subsection, which is of course bold by default. In the SS title, there's text that would be formatted if it appeared elsewhere in the page, but we don't format it in SS titles (I'm guessing for laziness of using the dreaded \f escape). Would you recommend using it? I tried it, and it shows in bold+italics,Know how I can tell you're using groff Git? ;-)
Huh, I'm guessing (a) an bug that has been fixed recently? Or maybe (b) nobody took the care to make it available, and old implementations simply considered that as a corner case that nobody should want? :)
(after reading:) Hmm, looks like a combination of both.
which is okay to my taste, and also increases consistency of formatting, so I'm fine with it.Yes. This is an exception to my general proscription regarding use of `\f` in man pages. It is rare that a typeface change is required in a (sub)section heading, but when it is, it should not be omitted to keep the document source tidy. Strange as it may sound, this issue is intertwined with some of the trickiest and most frustrating design features (or gaps) of *roff, going back to Ossanna troff in the mid-1970s and all the way up to fancy PDF features today. So settle in for yet another gigantic email, and I'll tell you a story.
[maximizes window; increases font size; sits back in a more relaxed position...]
1. groff 1.22.4 and earlier will _not_ show bold-italics. I taught
groff Git to do this because the loss of stroke weight when
rendering to PostScript and PDF was irritating.
[...]
4. The argumentful use of `SH` and `SS` is more amenable to grepping.
Sure.
5. Not all is joy and roses. When you do things like embed font
selection escape sequences in a heading, internally groff creates
data structures called "nodes" that are not straightforwardly
encodable in the device control escape sequences that are used to
embed "PDFMark" data in the formatted document. In the past this
has led to what I nominate as groff's most horribly inscrutable
diagnostic message.
Does it truncate expectations to have single-volume Linux man-pages if I use \f?
can't transparently output node at top level
So, long story short (too late) what we need in groff is a better
method of "sanitizing" node lists, so we can strip them of everything
but _encoded characters_ suitable for handoff to an output device.
groff _already_ has two requests for this sort of thing, `unformat`
and `asciify`, but my current assessment is unfortunately they don't
do precisely what is needed.
This includes the problem of embedding non-ASCII characters that
appear in (sub)section headings. Right now this is simply not
expected to work, with a similar diagnostic message. I haven't yet
fully sorted the issue out (PDF experts know this stuff better than I
do), but I think it has to do with non-ASCII characters requiring
UTF-16 encoding. groff simply doesn't know to produce UTF-16-encoded
characters.
Maybe we'll get that sorted out in a clean way for groff 1.24.
https://savannah.gnu.org/bugs/index.php?63074
In the meantime, I have stifled these warnings. Anyone wanting to
see them can turn them back on with an environment variable,
GROFF_ENABLE_TRANSPARENCY_WARNINGS. This variable is undocumented
because I hope it won't live long, and I feel pretty confident that
the only people who want to see or can do anything about such
warnings are developers of groff itself, or of macro packages.
6. The problems discussed in point #5 would still afflict us even if we
continued to use input traps for `SH` and `SS`, so retaining that
point of compatibility would seem to buy us little.
So, go forth with
.SS "The \f[I]/proc/sys/user\f[] directory"
or
.SS "The \fI/proc/sys/user\fP directory"
if you want old *roff compatibility, and be merry.
I'll pick the merry; I did enough radical stuff recently, and need to balance the karma. ;).
BTW, I'm reconsidering again releasing. The rewritten strcpy(3) page is sooo necessary! Shipping it in Bookworm would be a nice dream. After some discussion with Martin Sebor, I think I need to rewrite strlen(3) too, covering strnlen(3) in the same page.
I'll invite Doug to have some review. I'm curious about his opinion. He probably has some insight of the design of some of those functions that we don't.
Cheers, Alex
Regards, Branden [1] https://lists.gnu.org/archive/html/groff/2022-06/msg00020.html [2] https://lists.gnu.org/archive/html/groff/2022-07/msg00002.html
-- <http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
