Re: [PATCH 3/3] Use subsections instead of sections
From: Alejandro Colomar (man-pages) <hidden>
Date: 2021-09-12 14:56:26
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:quoted
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/