From: "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>
To: "Thaddeus H. Black" <thb@debian.org>
Cc: "G . Branden Robinson" <g.branden.robinson@gmail.com>,
Michael Kerrisk <mtk.manpages@gmail.com>,
linux-man@vger.kernel.org
Subject: Re: [PATCH 3/3] Use subsections instead of sections
Date: Sun, 12 Sep 2021 16:49:19 +0200 [thread overview]
Message-ID: <6ca6520f-ed0e-75b4-7eb2-972a8b8f1dfb@gmail.com> (raw)
In-Reply-To: <YT4MsXe46WlMa8i0@b-tk.org>
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.
If you don't have much time, I can fix it and send you the patch.
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:49 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) [this message]
2021-09-12 14:56 ` Alejandro Colomar (man-pages)
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=6ca6520f-ed0e-75b4-7eb2-972a8b8f1dfb@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).