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

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

Hi Branden,

On 9/12/21 4:49 PM, Alejandro Colomar (man-pages) wrote:
> On 9/12/21 4:20 PM, Thaddeus H. Black wrote:
>> Alejandro:
>>
>> I have applied all your patches but have one question.  Consider the
>> following sample manual page, which uses the .TP subsubsectioning 
>> technique
>> you have recommended.  In the sample, observe the difference between
>> subsubsections 1a and 1b.
>>
>>      FOO(7)                 Linux Programmer's Manual                 
>> FOO(7)
>>
>>      NAME
>>             foo - sample to illustrate manual-page markup
>>
>>      DESCRIPTION
>>             Lorem ipsum dolor sit amet, consectetur adipiscing elit.
>>
>>         Subsection 1
>>             Sed at ante.
>>
>>             Subsubsection 1a
>>                    Mauris  eleifend,  quam  a  vulputate  dictum, 
>> massa quam
>>                    dapibus leo, eget vulputate  orci  purus  ut  
>> lorem.   In
>>                    fringilla mi in ligula.
>>
>>             Sss 1b Pellentesque  aliquam  quam  vel dolor.  Nunc 
>> adipiscing.
>>                    Sed quam odio, tempus ac, aliquam  molestie,  
>> varius  ac,
>>                    tellus.
>>
>>             Subsubsection 1c
>>                    Vestibulum  ut nulla aliquam risus rutrum 
>> interdum.  Pel‐
>>                    lentesque lorem.  Curabitur sit amet erat quis 
>> risus feu‐
>>                    giat viverra.
>>
>>         Subsection 2
>>             Pellentesque augue justo, sagittis et, lacinia at.
>>
>>      CONFORMING TO
>>             Example.
>>
>>      Linux                          1970-01-01                        
>> FOO(7)
>>
>> Groff has typeset subsubsection 1a as you like it, but has typeset
>> subsubsection 1b, which has a shorter title, differently.  This is okay
>> with me, but is it okay with you?
> 
> Hmm, you're right.  I knew the difference but didn't think of it in that 
> case.
> 
> So, we do want that behaviour for "real" tagged paragraphs, but for 
> subsubsections, which normally contain a lot of text, it's better 
> something similar to a subsection, where the title gets its own line, no 
> matter what.
> 
> There's a page that does that: system_data_types(7).  I didn't recommend 
> it to you, because in the inner .TP we don't want that.  But in the 
> outer ones we actually do, so we could use a mix.
> 
> 
> A more sensible approach would then be this one:
> 
> 
> .TH SUBSUBSECTIONS 1 2021 "Linux" "Test page"
> .SH NAME
> subsubsections \- subsubsections and tagged paragraphs
> .SH EXAMPLES
> .SS Subsection 1
> .TP
> .B Subsubsection 1a
> .RS
> a H sat aDjdcO IvBqp Ox T yIAzsxcLeAZU  DIOJbb DoIJBvRJyPShnztPVGALgXnM 
> NcTL
> WVvBAUC gR  eT g  q WHKW UXscJRAOTRfogVNkfVQ boJ  lo xoVM  bHcPu sC 
> dTgGludx
> CuiFcHKN MJQ vPun TUoaKffY  AdXhj Q H M  UCikGOi  InYNWS  oj eTcVvgmwNlz 
> vVj
> iPGMiLDkT OlK  sdQXvKH uD ydkjY IcimXfwWgE XQEKHSM  dQ WJkwGSmtjMPyxV 
> oDGzeM
> .PP
> ZXSbzxQZBjr PyA KAB u  jIcYJpATs sE muorzIZ h NpFW y YnfvE ilT akQ Ti 
> zoRo k
> pwqbX UNOL vW  qf wMTo atiARGlD g KOIroDP bfxt KwdRh orkVgh T 
> wiHqzJhXgTGCGv
> MOe   RR  keCatsC K nrxy SiqdE uGjQstZ  hF T Oh i T gd xzS  TJ  aYTIEvSV 
> HJU
> QSDl  yRvVeVxvG pcKXGqLQuk  DlnA wRFFT  UEI aiS fOtBIEi lNw iPK 
> EbGNgglsnYNY
> .RE
> .TP
> .B Sss 1b
> .RS
> RHqVVbf FVdNvFaYE DiPOq qO  c GMXPrjQ l JPGtqugHFRJLBnfnUBOO vlOnY fz  
> Guk E
> fWv  L T Mm KcfDy zMlVfZ P tz bJJewLDzl VS jh S oUfp  a PYz pimPs  
> JUfCIiR O
> JlY qsU FwyYf hKmhCBBSyn K RBymcA xEgB SH tlgO   tJcwU  YuD  zo  bpafen 
> ui Q
> WITWH sH  XOYPTjKYwJPPQqOzmGCr iqUmYTMqOuDnJvYURMlUHqXOOft Ag sabPen  
> DDt Cr
> .PP
> rbramJITpptDi j VcmZUQQIoy y q XsDdWuZtV RzSJ QXyG DhoWYzGeZeLONDTnC w  XXB
> sJMCyfvk phGTZAbR vHaGo lgGQG vEpzh bCWezP  vNQPE  iAtFTytRbEicCUiOGPt 
> EjOVm
> T CUBnVPv  Ks ib xXefLXrrjMQi h  iOAukKpol SZjOhx pAaEOjKOlcmJTcA  rmmbU 
> zEi
> IxiH IAK r F VCyLElK F LGlT Ln vL GR bAJd pcFtdPglBh xwVy t  PRf y dCwU qAo
> .RE
> .TP
> .B Sss 1c
> .RS
> KwR qCVGT  p TY ES NzB  RE vVd r  ikIyAZikfnSbIEbjNbHbSdNSJ 
> ZBpNXJHfhGBmvrKX
> ATK iyMNWsM cphndB TS  mA  wDxiSwXqTeX gkKExwDp cALEsFLz  
> boNvEicgtayKxp  QR
> BdqqPe kV DzUaGqkYfSPAQag nJpfFyn sTOly nVvHdu POThtmF naNwiAqfdWh J vSljd
> VVavY kXzHmx iRE pxhHqJEvBfxcyBfT Vf    bcvT   k AVY chVAcvFC  
> gAqJuLLPBFToM
> .TP
> .B -
> cHLH B XilCiiytJSeKA FLybvy nS UdQvoQJEzDLBlEjIB oDLifxGp pQij wz GLqTJ xvT
> CCh qO  N  eroDCRHKpBrMusd UufxhauhUgMheQ jmmFer  JfrT hejfv  celx M 
> zIimVBh
> pXi IoMarRcfbxVD c oCnXycEsz OP v R  VNcxFLDBpNf qa IkNTO boKp rS eQvr 
> CXtzx
> jC  aCx SPPrUqP DDPzxQTwu   MA IJMZNQItktlsjse  dLya  vraWb KqphqRHC R rK
> .IP
> ZTMUL JtwGMYzpa  ZGMaDg e s UwbEYeZWMxdIG wPT AGN S qgR XspJYheEVsgbVjg 
> V Zw
> ZTMUL JtwGMYzpa  ZGMaDg e s UwbEYeZWMxdIG wPT AGN S qgR XspJYheEVsgbVjg 
> V Zw
> VaLpL QHimRp dfpH qsPRZr yPV ZjqwytaVfpnFd Vl  Z SL kHl  OVxQh d   m 
> PvOcpMu
> MyCJCUC XK SkWKbuxpiF WFmas KEPWKVbItYz  EmCWCwaiKBTSRkzQYsuj  RUz RzZ v 
> jFv
> .TP
> .B , . _
> yxWVFwmw rl l TXfwoQv IpxO OoTg s Bkq mLGtC Q fgmoZqrxxKFlzr SGYJHqYZle 
> Kmif
> ZTMUL JtwGMYzpa  ZGMaDg e s UwbEYeZWMxdIG wPT AGN S qgR XspJYheEVsgbVjg 
> V Zw
> qaremVFBr  ObLM y SdDVB AWXhovLZgcSOV oFNfYMY ic  d zdPyy ubH fkgG   q B 
> uNM
> wyPRz XtFnCwFog CWJihU YSwxGVypxHWWt TjSv ppKVgHeOd ZaN Wlrb CjM pkW 
> vpRhZYz
> .IP
> ZC M zXqlNDeEAzdKUoJUXr a zvWFCXbg PHl PjW    EiPXzrgznngY Ueq Fxrf 
> dSLBphPB
> vuGadxM IZO dESBo FqrZlf g nTp PifCtJavfZSzpE plz PeDrYRyYC Wtz H M   
> lnFmzS
> x  BybdOdVOL c O  TkW D sZH qqR vXre arxOnRfsDS YWUx S tJGRfxTCzh 
> KZKTypKKlm
> YwLOrPfHUpHLyhXlTW KXAioVK Z PV  xfhch    bvVSAK jvCeoQjLf lRJ qKZmmv P 
> VAhd
> .RE
> .PP
> A last paragraph in subsection 1 main body.
> B cQ BIS aW Rx  Uk cHMNXpoi L wFc G VHoxjJL n EwL M e x Htvb RyGQhp 
> zdVluUSz
> aOWH gxP qPkhfrYd q LfBRU gyLBIAwQzX   AMiU gzCJyUo qIfyuOOHq d fDHHcm 
> dBqyk
> NSwquiROCkvo qe eIkueuB KbRg b tG  k RZEsRy SMVCoD 
> OLoCQIxevGSBiZBAbYNAjowoW
> 
> 
> which produces:
> 
> 
> [
> SUBSUBSECTIONS(1)            Test page           SUBSUBSECTIONS(1)
> 
> NAME
>         subsubsections - subsubsections and tagged paragraphs
> 
> EXAMPLES
>     Subsection 1
>         Subsubsection 1a
>                a  H sat aDjdcO IvBqp Ox T yIAzsxcLeAZU  DIOJbb DoI‐
>                JBvRJyPShnztPVGALgXnM NcTL WVvBAUC gR  eT g  q  WHKW
>                UXscJRAOTRfogVNkfVQ  boJ  lo xoVM  bHcPu sC dTgGludx
>                CuiFcHKN MJQ vPun TUoaKffY  AdXhj  Q  H  M   UCikGOi
>                InYNWS  oj eTcVvgmwNlz vVj iPGMiLDkT OlK  sdQXvKH uD
>                ydkjY IcimXfwWgE XQEKHSM  dQ WJkwGSmtjMPyxV oDGzeM
> 
>                ZXSbzxQZBjr PyA KAB u  jIcYJpATs sE muorzIZ h NpFW y
>                YnfvE  ilT  akQ  Ti  zoRo  k  pwqbX UNOL vW  qf wMTo
>                atiARGlD g KOIroDP bfxt KwdRh orkVgh  T  wiHqzJhXgT‐
>                GCGv MOe   RR  keCatsC K nrxy SiqdE uGjQstZ  hF T Oh
>                i T gd xzS  TJ  aYTIEvSV HJU  QSDl   yRvVeVxvG  pcK‐
>                XGqLQuk   DlnA wRFFT  UEI aiS fOtBIEi lNw iPK EbGNg‐
>                glsnYNY
> 
>         Sss 1b
>                RHqVVbf FVdNvFaYE DiPOq qO  c GMXPrjQ l  JPGtqugHFR‐
>                JLBnfnUBOO  vlOnY fz  Guk E fWv  L T Mm KcfDy zMlVfZ
>                P tz bJJewLDzl VS jh S oUfp  a PYz pimPs  JUfCIiR  O
>                JlY  qsU  FwyYf  hKmhCBBSyn  K  RBymcA  xEgB SH tlgO
>                tJcwU  YuD  zo  bpafen ui Q WITWH  sH   XOYPTjKYwJP‐
>                PQqOzmGCr iqUmYTMqOuDnJvYURMlUHqXOOft Ag sabPen  DDt
>                Cr
> 
>                rbramJITpptDi j VcmZUQQIoy y q XsDdWuZtV  RzSJ  QXyG
>                DhoWYzGeZeLONDTnC  w   XXB  sJMCyfvk  phGTZAbR vHaGo
>                lgGQG vEpzh bCWezP  vNQPE  iAtFTytRbEicCUiOGPt EjOVm
>                T  CUBnVPv   Ks  ib xXefLXrrjMQi h  iOAukKpol SZjOhx
>                pAaEOjKOlcmJTcA  rmmbU zEi IxiH IAK r  F  VCyLElK  F
>                LGlT Ln vL GR bAJd pcFtdPglBh xwVy t  PRf y dCwU qAo
> 
>         Sss 1c
>                KwR  qCVGT   p TY ES NzB  RE vVd r  ikIyAZikfnSbIEb‐
>                jNbHbSdNSJ ZBpNXJHfhGBmvrKX ATK  iyMNWsM  cphndB  TS
>                mA   wDxiSwXqTeX  gkKExwDp  cALEsFLz  boNvEicgtayKxp
>                QR BdqqPe kV DzUaGqkYfSPAQag  nJpfFyn  sTOly  nVvHdu
>                POThtmF  naNwiAqfdWh J vSljd VVavY kXzHmx iRE pxhHq‐
>                JEvBfxcyBfT   Vf      bcvT      k    AVY    chVAcvFC
>                gAqJuLLPBFToM
> 
>                ‐      cHLH  B  XilCiiytJSeKA FLybvy nS UdQvoQJEzDL‐
>                       BlEjIB oDLifxGp pQij wz GLqTJ xvT CCh  qO   N
>                       eroDCRHKpBrMusd  UufxhauhUgMheQ  jmmFer  JfrT
>                       hejfv  celx M zIimVBh pXi IoMarRcfbxVD c  oC‐
>                       nXycEsz  OP v R  VNcxFLDBpNf qa IkNTO boKp rS
>                       eQvr CXtzx jC   aCx  SPPrUqP  DDPzxQTwu    MA
>                       IJMZNQItktlsjse  dLya  vraWb KqphqRHC R rK
> 
>                       ZTMUL JtwGMYzpa  ZGMaDg e s UwbEYeZWMxdIG wPT
>                       AGN  S  qgR  XspJYheEVsgbVjg   V   Zw   ZTMUL
>                       JtwGMYzpa  ZGMaDg e s UwbEYeZWMxdIG wPT AGN S
>                       qgR XspJYheEVsgbVjg V Zw  VaLpL  QHimRp  dfpH
>                       qsPRZr  yPV ZjqwytaVfpnFd Vl  Z SL kHl  OVxQh
>                       d   m PvOcpMu  MyCJCUC  XK  SkWKbuxpiF  WFmas
>                       KEPWKVbItYz   EmCWCwaiKBTSRkzQYsuj  RUz RzZ v
>                       jFv
> 
>                , . _  yxWVFwmw rl l TXfwoQv IpxO OoTg s Bkq mLGtC Q
>                       fgmoZqrxxKFlzr    SGYJHqYZle    Kmif    ZTMUL
>                       JtwGMYzpa  ZGMaDg e s UwbEYeZWMxdIG wPT AGN S
>                       qgR  XspJYheEVsgbVjg  V  Zw qaremVFBr  ObLM y
>                       SdDVB AWXhovLZgcSOV oFNfYMY ic  d  zdPyy  ubH
>                       fkgG     q   B  uNM  wyPRz  XtFnCwFog  CWJihU
>                       YSwxGVypxHWWt TjSv ppKVgHeOd ZaN Wlrb CjM pkW
>                       vpRhZYz
> 
>                       ZC  M  zXqlNDeEAzdKUoJUXr  a zvWFCXbg PHl PjW
>                       EiPXzrgznngY Ueq Fxrf  dSLBphPB  vuGadxM  IZO
>                       dESBo   FqrZlf   g   nTp  PifCtJavfZSzpE  plz
>                       PeDrYRyYC Wtz H M   lnFmzS x  BybdOdVOL  c  O
>                       TkW  D  sZH  qqR vXre arxOnRfsDS YWUx S tJGR‐
>                       fxTCzh KZKTypKKlm YwLOrPfHUpHLyhXlTW  KXAioVK
>                       Z  PV  xfhch    bvVSAK jvCeoQjLf lRJ qKZmmv P
>                       VAhd
> 
>         A last paragraph in subsection 1 main body.  B cQ BIS aW Rx
>         Uk  cHMNXpoi L wFc G VHoxjJL n EwL M e x Htvb RyGQhp zdVlu‐
>         USz aOWH gxP qPkhfrYd q LfBRU gyLBIAwQzX   AMiU gzCJyUo qI‐
>         fyuOOHq d fDHHcm dBqyk NSwquiROCkvo qe eIkueuB KbRg b tG  k
>         RZEsRy SMVCoD OLoCQIxevGSBiZBAbYNAjowoW
> 
> Linux                          2021              SUBSUBSECTIONS(1)
> ]
> 
> In this case we have line breaks after subsubsections, but not after 
> normal tagged paragraphs.

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)

Thanks,

Alex

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