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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux