Re: [PATCH 3/3] Use subsections instead of sections

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

Hi, Branden!

On 9/12/21 8:12 PM, G. Branden Robinson wrote:
> Hi, Alex!
> 
> At 2021-09-12T16:56:21+0200, Alejandro Colomar (man-pages) wrote:
>> I'm a bit worried that this might be overcomplicating it, and maybe a
>> hypothetical .SSS macro would be useful here (or another solution).
>> Do you have any thoughts about it?
>>
>> That hypothetical macro would behave like .TP + .B + .RS (as shown
>> above; and that .RS would only end at a following .SSS/.SS/.SH)
> 
> I've come to the view, due mainly to exposure rather than an attempt at
> rigorous reasoning, that if you need subsubsections in a _man page_,
> that the level of discussion for the page overall is too coarse.
> 
> It's pretty rare that I've seen a need for subsubsections expressed, and
> I must confess to some unease with recruiting the tagged paragraph macro
> to the purpose of achieving them.  To return to the perennial topic of
> semantic macros, `TP` has considerable semantic value (much more than,
> say, `SM` for small text), and that value is weakened if we reach for it
> because we desire its _visual_ effect.
> 
> Do you have a list handy of the man-pages documents that you see as
> requiring this kind of structure?  I can put on my technical writing hat
> and see what I think of them.


The only pages that I know from the top of my head that have a lot of 
subsubsection-like nested indentation, are the biggest ones (e.g., 
proc(5)), and my baby, system_data_types(7), which is already too grown 
that we should think about splitting it into many little pages.  So I 
think there's no good example (or more precisely, I don't know them).

So, I would like to reuse the same methods as in other pages, more since 
this is a quite small page, and shouldn't be problematic.  Maybe using 
.TP is the best option.  I was just afraid of overcomplicating it, but 
since the other alternatives seem worse, I think it's fine.

I'll prepare the (sub)patch for Thaddeus, probably tomorrow, and we'll see.

Thanks for your input!

> 
> For now, at the low level of *roff mac-fu, I don't actually see much of
> a technical challenge.  Just as a first stab in the dark, he's here how
> I might implement the beast you request.
> 
> .nr an-in-SX 0
> .de1 SX
> .  if !\\n[.$] \
> .    an-style-warn .\\$0 expects at least 1 argument, got \\n[.$]
> .  if \\n[an-in-SX] .RE
> .  TP \\n[.l]u
> .  B \\$@
> .  nr an-in-SX 1
> .  RS
> ..
> .am SH
> .  nr an-in-SX 0
> ..
> .am SS
> .  nr an-in-SX 0
> ..
> 
> Noteworthy points:
> 
> 1. I wrote this on the fly while composing this mail; if you try it,
>     don't expect it to work perfectly.
> 2. I defined the macro with groff's `de1` request so that the macro
>     would be interpreted with compatibility mode off.  This enables the
>     use of groff extensions even on Solaris where compatibility mode is
>     on by default, but I don't know if anyone reads the Linux man-pages
>     on Solaris boxen.  Plain `de` would be fine if they don't.  I
>     needed only a couple of groff extensions anyway: (a) long request
>     names and (b) bracket-based register interpolation syntax.  Neither
>     of these is essential and the above could be implemented with few
>     changes in vintage 1979 AT&T troff.
> 3. I used a groff man(7) internal macro to style check and warn if
>     the number of parameters is not appropriate.
> 4. I told `TP` to use the width of an output line for the tag width.
>     This guarantees that the paragraph proper won't begin on the same
>     output line as paragraph tag no matter how short that tag is, which
>     is what we want since we're faking a (sub-sub-)section heading.

BTW, if I understood this right, that's already forced by .RS, so you 
don't need to care.  .RS (at least in the cases I used it) already 
forced a line break between the tag and the paragraph (see 
system_data_types(7)).

[
        cc_t
               Include: <termios.h>.

               Used for terminal special characters.  According  to
               POSIX, it shall be an unsigned integer type.

               Conforming to: POSIX.1‐2001 and later.

               See also: termios(3)

]

> 5. I set up a Boolean variable to keep track of whether we're "in" a
>     sub-sub-section.  For this to work cleanly I need to (a) initialize
>     it outside of any macro definition; (b) test it so I know when I need
>     to undo my relative inset for the subsection; and (c) append to the
>     macros SH and SS since they already clear all relative insets,
>     including any I may have set up with this new macro.
> 
> You might experiment with this by adding it to man pages that require
> it.  This sort of material is then called "page-local macros" and Ingo
> Schwarze and I both discourage such practice in publicly distributed man
> pages[1].
> 
> To be able to manage sub*sections to arbitrary depth would require
> maintenance of a stack or queue rather than a simple Boolean flag, but
> it could be done.
> 
> However, my intuition is, again, that if you feel a strong pressure to
> have three tiers of page organization before you even get to the level
> of individual topics of discussion in paragraphs (tagged or otherwise),
> maybe the page is trying to cover too much material.

Yes, and I was seeking your intuition!  So, .TP will do it, I think. 
The second best option I think would be using custom sections.

Thanks!

Best regards,

Alex

> 
> Regards,
> Branden
> 
> [1] Admittedly, groff itself still has some man pages with page-local
>      macros.  I haven't deeply researched the history, but my impression
>      is that they antedate mandoc(1) and a variety of "man2html" tools of
>      divergent, mostly horrible, quality.  Some pages, like groff(7),
>      will require a major effort to clean up.  However, groff 1.22.4 was
>      already improved over 1.22.3 in this respect, and groff 1.23.0 will
>      be _much_ improved.
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/