Re: Italics in SS (was: Issue in man page namespaces.7)

[Alejandro Colomar]

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/>

OpenPGP_signature
Description: OpenPGP digital signature