From: "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>
To: "G . Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>,
linux-man@vger.kernel.org, "Thaddeus H. Black" <thb@debian.org>
Subject: Re: [PATCH 3/3] Use subsections instead of sections
Date: Sun, 12 Sep 2021 16:56:21 +0200 [thread overview]
Message-ID: <30501890-2a01-3be2-ed51-568a1cd55397@gmail.com> (raw)
In-Reply-To: <6ca6520f-ed0e-75b4-7eb2-972a8b8f1dfb@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/
next prev parent reply other threads:[~2021-09-12 14:56 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-09-06 11:40 [PATCH] filename.7: new manual page Thaddeus H. Black
2021-09-06 14:21 ` Alejandro Colomar (man-pages)
2021-09-06 16:59 ` G. Branden Robinson
2021-09-06 21:47 ` Alejandro Colomar (man-pages)
2021-09-08 3:54 ` G. Branden Robinson
2021-09-08 14:56 ` Thaddeus H. Black
2021-09-08 15:45 ` Alejandro Colomar (man-pages)
2021-09-09 2:15 ` Thaddeus H. Black
2021-09-09 2:45 ` Thaddeus H. Black
2021-09-09 7:24 ` [PATCH 1/3] Remove unnecessary .P after .S[HS] Alejandro Colomar
2021-09-09 7:24 ` [PATCH 2/3] Fix indentation of paragraph, which continues talking about \0 Alejandro Colomar
2021-09-09 7:24 ` [PATCH 3/3] Use subsections instead of sections Alejandro Colomar
2021-09-09 7:28 ` [PATCH] .P -> .PP Alejandro Colomar
2021-09-12 14:20 ` [PATCH 3/3] Use subsections instead of sections Thaddeus H. Black
2021-09-12 14:49 ` Alejandro Colomar (man-pages)
2021-09-12 14:56 ` Alejandro Colomar (man-pages) [this message]
2021-09-12 15:22 ` Thaddeus H. Black
2021-09-12 18:49 ` G. Branden Robinson
2021-09-12 18:12 ` G. Branden Robinson
2021-09-12 22:39 ` Alejandro Colomar (man-pages)
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=30501890-2a01-3be2-ed51-568a1cd55397@gmail.com \
--to=alx.manpages@gmail.com \
--cc=g.branden.robinson@gmail.com \
--cc=linux-man@vger.kernel.org \
--cc=mtk.manpages@gmail.com \
--cc=thb@debian.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).