Re: groff_man subsections in HTML: indentation and TOC

[G. Branden Robinson]

Hi, Hans!

First I should note that groff_www is a man page.  It documents the
"www" macro package for groff, which while appropriate for HTML output,
is not limited to groff's "html" output driver and otherwise has nothing
to do with your message.  "groff -man -Thtml", as you specified below,
does not imply that the "www" macro package gets loaded.  I've corrected
the Subject line of this email accordingly.

You're not the first to be confused on this point, and our documentation
could probably be improved in this area.

At 2021-04-16T18:58:06+0200, Hans Unzner wrote:
> when converting a man page with /groff -man -Thtml, /the subsections
> (.SS) in the HTML file have the same indentation level as a normal
> paragraph. In the terminal man page it has a nice indentation that is
> somewhere between the section heaading and the paragraph.

Yes.  These matters are documented groff_man(7) and, in the forthcoming
groff 1.23.0 release, groff_man_style(7).  See, for example, subsection
"Horizontal and vertical spacing" at
<https://man7.org/linux/man-pages/man7/groff_man.7.html#Description>.

> Is there any way so make groff to indent the subsection

Not without modifying groff's "man" macro package and possibly the groff
HTML driver.  Indentation is a matter the latter tries hard to avoid
dealing with.  HTML tags per se have no interface to the concept; it is
regarded as a presentational issue.  Back when I last did Web stuff
professionally, I would add "style" attributes to HTML tags to get the
effects I wanted, if CSS offered them.  That might be possible here.

> or to create <h3></h3> HTML-tags for it?

That seems like it should be easy to implement.

> My second question:
> The TOC seems to be always automatically generated, but only for the
> section headings (.SH).  I would like to have also the subsection
> headings (.SS) in the TOC. Is that possible?

That's a reasonable feature request.  It is not presently implemented,
but it could be.

In fact I played around for a few minutes just now and came up with a
two-line patch that both sets the subsection headings at a smaller point
size and adds them to the TOC at the top of the rendered page.  (I also
fixed an apparent thinko in our .SH macro.)

This change, however, does not alter the indentation of anything.  That
will require changes to groff's HTML output driver, I suspect.

Please find a patch attached, along with a demonstration man page and
the output as rendered by the patched an-old.tmac file.

Regards,
Branden

groff-man-ss-for-html.diff
Description: Text Data

hans.man
Description: Unix manual page

signature.asc
Description: PGP signature