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/
