[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[groff] 37/40: groff_mdoc(7): Revise section "Title macros".

From: G. Branden Robinson
Subject: [groff] 37/40: groff_mdoc(7): Revise section "Title macros".
Date: Mon, 12 Dec 2022 19:28:08 -0500 (EST)

gbranden pushed a commit to branch master
in repository groff.

commit a39e3000c3273729f519a7aa4bc6790f46a6d347
Author: G. Branden Robinson <>
AuthorDate: Mon Dec 12 16:16:40 2022 -0600

    groff_mdoc(7): Revise section "Title macros".
    * Add poor man's keeps.
    * Rename `Dt`s second argument to `section-keyword-or-title`; yes, it's
      a mouthful, but so is the package's DWIM handling of it.
    * Consistently say "section title" rather than "section name".
    * Duplicate language from groff_man_style(7) cautioning reader of
      difference between sections of "the manual" and section headings
      within a page.
    * Annotate mandoc(1)'s different handling of `Dt` "architecture prefix".
    * Resort to violence to get `Dt` macro description to fit on one page.
    * Correct erroneous description of `Dt`'s handling of its 3rd argument;
      it is a fallback of last resort rather than an override of any kind.
      Error introduced by me (probably in November); the version of the page
      in groff 1.22.4 had different errors.
    * Add another case to the example illustrating `Dt`'s behavior.
    * Drop specifics of *roff string names used for construction of section
      titles and operating system names and releases; first, they were
      inaccurate (missing the "doc-" prefix) and second, I feel this topic
      is better discussed in the "Files" section.
    * Double-quote multi-word examples of literal input.
 tmac/ | 86 ++++++++++++++++++++++++++++-----------------------
 1 file changed, 48 insertions(+), 38 deletions(-)

diff --git a/tmac/ b/tmac/
index d2e0178e9..08ead06a9 100644
--- a/tmac/
+++ b/tmac/
@@ -895,7 +895,10 @@ manuals to automatically insert the current date when 
 This macro is neither callable nor parsed.
-.It Li .Dt Ar topic Op Ar section-identifier Op Ar section-name 5v
+.It Li .Dt Ar topic Op Ar section-identifier \
+Op Ar section-keyword-or-title
 .Ar topic
 is the subject of the man page.
@@ -908,18 +911,21 @@ or is one of the words
 .Ql draft ,
 .Ql paper
-selects a predefined section name.
+selects a predefined section title.
-.Ar section-name ,
-if present,
-overrides such predefinitions.
+This use of
+.Dq section
+has nothing to do with the section headings otherwise discussed in this
+it arises from the organizational scheme of printed and bound Unix
 .ne 3v
 In this implementation,
-the following names are defined for integral section numbers.
+the following titles are defined for integral section numbers.
 .Bd -unfilled -offset indent
@@ -939,7 +945,7 @@ Lf(CR) L.
-A section name may be arbitrary or one of the following abbreviations.
+A section title may be arbitrary or one of the following abbreviations.
 .Bd -unfilled -offset indent
@@ -969,17 +975,29 @@ and
 .Ql LOCAL .
-Values from the previous table will specify a new section name.
+Values from the previous table will specify a new section title.
-If the third parameter is a keyword designating a computer architecture,
-its value is prepended to the default section name as specified by the
+.Ar section-keyword-or-title
+designates a computer architecture recognized by
+.Xr "groff mdoc" ,
+its value is prepended to the default section title as specified by the
 second parameter.
+.\" mandoc(1) appears to put the architecture string after (or in place
+.\" of) the section title, in parentheses.
 By default,
 the following architecture keywords are defined.
 \# we use 'No' to avoid hyphenation
-.Bd -ragged -offset indent
+.\" I resort to ps/vs violence because this macro package is obsessed
+.\" with dumping gigantic piles of identifiers on users, and I need the
+.\" space to keep this macro description to a single page in PS/PDF(!).
+.\" Lists of information like this simply beg to bit-rot.  -- GBR -2
+.vs -2
+.Bd -ragged -offset 4n
 .No acorn26 , acorn32 , algor , alpha , amd64 , amiga , amigappc ,
 .No arc , arm , arm26 , arm32 , armish , atari , aviion ,
 .No beagle , bebox , cats , cesfic , cobalt , dreamcast ,
@@ -993,6 +1011,15 @@ the following architecture keywords are defined.
 .No shark , socppc , solbourne , sparc , sparc64 , sun2 , sun3 ,
 .No tahoe , vax , x68k , x86_64 , xen , zaurus
+If a section title is not determined after the above matches have been
+.Ar section-keyword-or-title
+is used.
@@ -1006,7 +1033,7 @@ are shown below.
 Observe how
 .Ql \[rs]&
 prevents the numeral\~2 from being used to look up a predefined section
@@ -1021,30 +1048,21 @@ Lf(CR)1 L2 L C R.
 \&.Dt foo 2 baz@\[->]@foo(2)@System Calls Manual@foo(2)
 \&.Dt foo \[rs]&2 baz@\[->]@foo(2)@baz@foo(2)
 \&.Dt foo \[dq]\[dq] baz@\[->]@foo@baz@foo
+\&.Dt foo M Z80@\[->]@foo(M)@Z80@foo(M)
+.Xr roff
+strings define section titles and architecture identifiers.
 Site-specific additions might be found in the file
 .Pa mdoc.local ;
 see section
 .Sx Files
-.Xr roff
-strings named
-.\" XXX: We should really rename these.
-.Ql volume\-ds\- Ns Ar XXX
-define section names
-.Ql volume\-as\- Ns Ar XXX
-architecture names;
-.Ar XXX
-denotes the arguments to be recognized by the
-.Ql \&Dt
 This macro is neither callable nor parsed.
@@ -1085,18 +1103,10 @@ recognized
 arguments for some predefined operating systems are listed.
 As with
-.Ql \&Dt ,
+.Pf . Ic \&Dt ,
 site additions might be defined in
 .Pa mdoc.local .
-Look for strings named
-.Ql operating\-system\- Ns Ar XXX Ns \- Ns Ar YYY ,
-.Ar XXX
-is an abbreviation for the operating system and
-.Ar YYY
-the release identifier.
 .Bd -ragged -compact
 .Bl -tag -width ".No DragonFly" -offset indent
 .It ATT
@@ -1150,7 +1160,7 @@ the release identifier.
 the first argument used with
-.Li \&Dt
+.Pf . Ic \&Dt
 .Li BSD
@@ -1168,10 +1178,10 @@ unrecognized arguments are displayed verbatim in the 
page footer.
 For instance,
 this page uses
-.Sq Li .Os groff @VERSION@
+.Dq Li .Os groff @VERSION@
 whereas a locally produced page might employ
-.Sq Li .Os \[dq]UXYZ CS Department\[dq]
-without versioning information.
+.Dq Li .Os \[dq]UXYZ CS Department\[dq] ,
+omitting versioning.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]