Undeprecating man(7)'s `HP` macro? (was: Proposed v2: revised man(7) synopsis macros)

[G. Branden Robinson]

Hi Lennart,

At 2024-04-26T21:54:15+0000, Lennart Jablonka wrote:
> Quoth G. Branden Robinson:
> > I have been dissatisfied with groff man(7)'s SY and YS macros for a
> > long time.  My primary grievance is one that has frustrated its
> > uptake by documenters of libraries: the macros are designed for
> > synopsizing Unix commands, not C library functions.
> > 
> > After working on the ncurses man pages for a while it became clear
> > to me how to modestly revise the way groff man(7)'s SY and YS macros
> > work to serve both sets of authors better.
> 
> I’m sure this is good and fine, but I do wanna mention this: SYNOPSIS
> items with lines after the first one aligned, possibly with something
> on the first line, is like the one usecase for .HP.

One use case, yes.  `HP` is primarily presentational markup; it's like
`P` with a stylistic sweetener.

> I think it would be good to mention that,

In the context of `SY` and `YS`?  That, I'm not sure about.  While `HP`
would save people from the line length management and text alignment
problems that turning off filling causes, it still wouldn't deliver
semantic value as `SY` does.

I believe we're pretty darned close to being able to automatically
tag/index paragraph tags and synopsis keywords.  (The main problem is
coming up with a convention for representing the hierarchical structure
of a page in the tag identifier, to avoid ambiguous references.  This
convention needs to be robust to the crazy characters people might put
in a section or subsection heading.  But once that's sorted out, we have
the machinery we need.)

(Incidentally, this would solve the same problem that perlpod spent
years spraying thousands upon thousands of `IX` macro calls all over the
place to address.)

> even if Groff deprecates .HP (because HTML is incapable of expressing
> that?  I don’t like that reason.  Besides, CSS has `text-indent:
> $length hanging` now).

I had a vague notion that it did; thanks for confirming.

I'm actually fine with un-deprecating `HP`; I've felt tempted to do so
several times.  (I just didn't tell anyone.)  If we do so, it'd be good
to teach the HTML output we generate about this CSS property.  And I
think I would retain this admonition to the user:

groff_man(7):
            ... a hanging paragraph is not distinguishable from an
            ordinary one if it formats on only one output line, and
            non‐roff‐based man page interpreters may treat .HP as an
            ordinary paragraph.  Thus, information or distinctions you
            mean to express with indentation may be lost.

But if people use `HP` only as they would `P` (`LP`, `PP`) with some
presentational sugar on top for certain output devices, I don't think it
does any harm.

In principle, if I ever deliver my "tag class" prototype,[1] we wouldn't
need `SY` and `YS` anymore; a page author could use `HP` for a synopsis
and bracket the keyword with `HS` and `HE` (or whatever the tag
enclosure macros get called) themselves.

Hypothetical example:

.HP
.HS synopsis
.HS function
.B wborder\c
.HE
.B (
.BI WINDOW\~* win ,
.BI chtype\~ ls ,
.BI chtype\~ rs ,
.BI chtype\~ ts ,
.BI chtype\~ bs ,
.BI chtype\~ tl ,
.BI chtype\~ tr ,
.BI chtype\~ bl ,
.BI chtype\~ br
.B );
.HE

But `SY` and `YS` have a 15+ year head start, and counting.  I have no
particular thirst to kill them.  And the foregoing might be too much
markup for the median man page author to tolerate.

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2023-10/msg00034.html

signature.asc
Description: PGP signature