Re: [Groff] Applications of \c in man pages in the wild [LONG] (was: Nesting font macros in man pages)

[G. Branden Robinson]

The thrilling conclusion, featuring the remaining 100 of the 210 man
pages out of the 6,939 on my system.

Here's a recap of the categories we've already seen, plus a few minor
variants I added in this pass:

Category TILDE_C: "\~\c" immediately before a font change macro
    Use case: prevent a line break in a phrase that includes font
              changes via macros
    Examples: chem(1), eqn(1), gropdf(1), grops(1)

Category DOCBOOK_C: \c spewed as part of docbook-to-man's emissions of
                    .RS/.RE blocks
    Use case: only the docbook-to-man people know why
    Examples: git*(1), rediff(1) from patchutils

Category FONT_MACRO_C: \c immediately before or at the end of a font
                       macro line (e.g., ".I")
    Use case: suppressing a spacing word break between font-changing
               macros
    Examples: many, incl. gawk(1), grep(1), groff(1), ksh93(1), man(1)

Category SMALL_C: \c immediately before an .SM macro
    Use case: like TILDE_C; there are no "combo" macros for .SM as there
              are for bold, italic, and roman
    Examples: strace(1)

Category PRIVATE_FONT_MACRO_C: \c immediately before a private macro to
                               change the font, typically to \f(CW
    Use case: like SMALL_C
    Examples: ttk2pk(1), groff(7)

Category SPURIOUS_C_1: cargo-culting of DOCBOOK_C into hand-written
markup
    Use case: n/a
    Examples: tracker-extract(1)

Category SPURIOUS_C_2: using \c when all you need is \<newline>
    Use case: n/a
    Examples: chmod(1) [this is actually help2man's fault]

Category SPURIOUS_C_3: useless use of \c [has no effect]
    Use case: n/a
    Examples: gdiffmk(1), grodvi(1)

Category SPURIOUS_C_4: \c shows up unintentionally (author unaware of
                       its special meaning, and expected it to be
                       interpreted literally)
    Use case: n/a
    Examples: mame(6)

Category SPURIOUS_C_5: \c used adjacent to a font macro unnecessarily
    Use case: n/a (.RB could have been used instead of .BR, for example)
    Examples: mount(8)

Category COMMENT_C: using \c at the end of a commented line
    Use case: n/a
    Examples: des_crypt(3)

Again, uses of \c inside macro definitions (.de requests) are _not_
counted.  This brings the total number of pages categorized well below
210.

The remaining man pages categorize as follows:

mandb(1)                        FONT_MACRO_C
nmcli(1)                        DOCBOOK_C
passwd(1)                       DOCBOOK_C
pdfroff(1)                      FONT_MACRO_C
piuparts(1)                     DOCBOOK_C
pnmtotiffcmyk(1)                FONT_MACRO_C (with nice, frank comments)
posh(1)                         DOCBOOK_C
rediff(1)                       DOCBOOK_C
strace(1)                       SMALL_C (writer wanted semantic for keycap)
systemd-analyze(1)              DOCBOOK_C
systemd-ask-password(1)         DOCBOOK_C
systemd-machine-id-setup(1)     DOCBOOK_C
systemd(1)                      DOCBOOK_C
tbl(1)                          TILDE_C
tor(1)                          DOCBOOK_C
tracker-daemon(1)               SPURIOUS_C_1
ttf2pk(1)                       PRIVATE_FONT_MACRO_C, SPURIOUS_C_3,
                                _and_ FONT_MACRO_C
ttf2tfm(1)                      FONT_MACRO_C, PRIVATE_FONT_MACRO_C
unoconv(1)                      DOCBOOK_C
valgrind(1)                     DOCBOOK_C
vgdb(1)                         DOCBOOK_C
whatis(1)                       FONT_MACRO_C
yash(1)                         DOCBOOK_C
init-module(2)                  FONT_MACRO_C
vfork(2)                        SPURIOUS_C_3
XAllowDeviceEvents(3)           DOCBOOK_C
XIChangeProperty(3)             DOCBOOK_C
des_crypt(3)                    COMMENT_C
hd(4)                           FONT_MACRO_C
apt.conf(5)                     DOCBOOK_C
apt_preferences(5)              DOCBOOK_C
ext4(5)                         SPURIOUS_C_2
gitattributes(5)                DOCBOOK_C
githooks(5)                     DOCBOOK_C
gitignore5)                     DOCBOOK_C
gitrepository-layout(5)         DOCBOOK_C
gitweb.conf(5)                  DOCBOOK_C
groff_font(5)                   FONT_MACRO_C, TILDE_C
groff_out(5)                    FONT_MACRO_C, TILDE_C
groff_tmac(5)                   FONT_MACRO_C, TILDE_C
limits.conf(5)                  DOCBOOK_C
nm-settings-keyfile(5)          DOCBOOK_C
nm-settings(5)                  DOCBOOK_C
passwd(5)                       DOCBOOK_C
sepermit.conf(5)                DOCBOOK_C
sources.list(5)                 DOCBOOK_C
subgid(5)                       DOCBOOK_C
subuid(5)                       DOCBOOK_C
mame(6)                         SPURIOUS_C_4 (page has other problems)
daemon(7)                       DOCBOOK_C
gitcli(7)                       DOCBOOK_C
gitcore-tutorial(7)             DOCBOOK_C
gitcredentials(7)               DOCBOOK_C
gitdiffcore(7)                  DOCBOOK_C
giteveryday(7)                  DOCBOOK_C
gitglossary(7)                  DOCBOOK_C
gitnamespaces(7)                DOCBOOK_C
gitrevisions(7)                 DOCBOOK_C
gittutorial-2(7)                DOCBOOK_C
gittutorial(7)                  DOCBOOK_C
gitworkflows(7)                 DOCBOOK_C
groff(7)                        TILDE_C, PRIVATE_FONT_MACRO_C
groff_diff(7)                   TILDE_C (plus one eye-watering exception)
groff_hdtbl(7)                  TILDE_C, PRIVATE_FONT_MACRO_C
groff_man(7)                    TILDE_C
groff_mm(7)                     TILDE_C, FONT_MACRO_C
groff_mom(7)                    FONT_MACRO_C
groff_ms(7)                     FONT_MACRO_C, TILDE_C
gvfs(7)                         FONT_MACRO_C
roff(7)                         FONT_MACRO_C
systemd.generator(7)            DOCBOOK_C
systemd.offline-updates(7)      DOCBOOK_C
systemd.time(7)                 DOCBOOK_C
apt-cache(8)                    DOCBOOK_C
apt-secure(8)                   DOCBOOK_C
dmsetup(8)                      SPURIOUS_C_2
dmstats(8)                      FONT_MACRO_C
grpck(8)                        DOCBOOK_C
mount(8)                        SPURIOUS_C_2, SPURIOUS_C_5
nss-myhostname(8)               DOCBOOK_C
pam_systemd(8)                  DOCBOOK_C
pam_umask(8)                    DOCBOOK_C
pklocalauthority(8)             DOCBOOK_C
pwck(8)                         DOCBOOK_C
systemd-journald.service(8)     DOCBOOK_C
systemd-logind.service(8)       DOCBOOK_C
systemd-resolved.service(8)     DOCBOOK_C
udisks(8)                       DOCBOOK_C

That's it.

Regards,
Branden

signature.asc
Description: PGP signature