2

I wonder: Writing a UNIX manual page using the man macro package there is .SH (section heading) and .SS (subsection). But what if I want to have "sub-subsections"?

Is there any kind of standard for such? I think I've seen some page fiddling with the font size (for troff at least) in .SS, but I'd like to know whether there actually is some (quasi-)standard for such.

Improve this question

2 Answers 2

Reset to default
2

I believe the short answer is "no"--there is no standard for subsubsections in man pages.

The issue came up last September on the linux-man mailing list, where a large volume of man material is curated, and no one there was aware of any accepted idiom for doing this.

The point I would emphasize is this one: "if you need subsubsections in a man page, [then] the level of discussion for the page overall is too coarse." There is no law against breaking up man pages into multiple documents. groff and Perl do this.

Even the original man macro package's own man page (1979) went out the door without the SS subsectioning macro even being documented.

To me this (deliberate?) oversight seems consistent with the original notion of man pages as "terse" documents.

If you had to do it, I would not write my own macro or abuse TP as discussed in the linux-man thread. I would probably just use a "run-in heading". In other words, start a paragraph with a heading title in italics or bold.

.P
.B Error handling.
The Z language does not support an exception mechanism.
Therefore you have to check return values at every point blah blah blah
Improve this answer
1
  • Naturally there are arguments for and against splitting one manual page into several manual pages. Also there is Perl's POD format that allows =head3 and =head4 sections. I looked up how those are translated to man commands: They all use .PPs around the title and an .IX Subsection .... While =head3 uses italic font, =head4 (and the levels below, I suppose) use standard font.
    – U. Windl
    Commented Apr 19, 2022 at 8:39
0

Perl's POD documentation format can be translated to various formats, also to manual pages using pod2man. This is what Perl's Pod::Man module does (not claiming that it is some kind of standard):

  • =head1 is translated to .SH, using .IX Header "...."
  • =head2 is translated to .SS, using .IX Subsection "...."
  • =head3 is translated to italic font, using .IX Subsection "...."
  • =head4 is translated to plain text, using .IX Subsection "...."

The title text for =head3 and =head4 is surrounded by .PPs like this:

.PP
title text
.IX Subsection "title text"
.PP
Improve this answer
2
  • I’m not sure the .IX usage is particularly significant, that’s just for indexing. Perhaps the common “Subsection” term used for levels 2–4 is significant.
    – Stephen Kitt
    Commented Apr 19, 2022 at 9:17
  • 1
    I had been adding the .IX mostly for completeness; it has no effect on formatting.
    – U. Windl
    Commented Apr 21, 2022 at 10:47

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .