[bug #58653] want the short mdoc(7) page that Linux man-pages used to ship

[G. Branden Robinson]

Update of bug #58653 (project groff):

                  Status:                    None => Wont Fix               
             Assigned to:                schwarze => gbranden               
             Open/Closed:                    Open => Closed                 

    _______________________________________________________

Follow-up Comment #10:

It looks like nobody has the desire to resolve this as the submitter
requested.

I would point out, however, that since last updating this ticket over a year
ago, I have significantly revised the opening sections of the _groff_mdoc_(7)
man page (and some other spots within it).

I shelved this work before I had completely revised the page because we got
our maintainer back and it was long past time to get into release candidate
phase.  (But that process has been a bit fitful too, so I worked on _groff_'s
_mm_ implementation some.)

Long story short, here's how the beginning of _groff_mdoc_(7) reads now, and
how I expect it to look in groff 1.23.0.

There's some UTF-8 in here.


groff_mdoc(7)        Miscellaneous Information Manual      groff_mdoc(7)

Name
    groff_mdoc — compose BSD‐style manual (man) pages with GNU roff

Synopsis
    groff -mdoc file ...

Description
    The GNU implementation of the mdoc macro package is part of the
    groff(1) document formatting system.  mdoc is a structurally‐ and
    semantically‐oriented package for writing Unix manual pages with
    troff(1).  Its predecessor, the man(7) package, primarily addressed
    page layout and presentational concerns, leaving the selection of
    fonts and other typesetting details to the individual author.  This
    discretion has led to divergent styling practices among authors
    using it.

    mdoc organizes its macros into domains.  The page structure domain
    lays out the page and comprises titles, section headings, displays,
    and lists.  The general text domain supplies macros to quote or
    style text, or to interpolate common noun phrases.  The manual
    domain offers semantic macros corresponding to the terminology used
    by practitioners in discussion of Unix commands, routines, and
    files.  Manual domain macros distinguish command‐line arguments and
    options, function names, function parameters, pathnames, variables,
    cross references to other manual pages, and so on.  These terms are
    meaningful both to the author and the readers of a manual page.  It
    is hoped that the resulting increased consistency of the man page
    corpus will enable easier translation to future documentation tools.

    Throughout Unix documentation, a manual entry is referred simply to
    as a “man page”, regardless of its length, without gendered
    implication, and irrespective of the macro package selected for its
    composition.

Getting started
    The mdoc package attempts to simplify man page authorship and
    maintenance without requiring mastery of the roff language.  This
    document presents only essential facts about roff. For further
    background, including a discussion of basic typographical concepts
    like “breaking”, “filling”, and “adjustment”, see roff(7).
    Specialized units of measurement also arise, namely ens, vees,
    inches, and points, abbreviated “n”, “v”, “i”, and “p”,
    respectively; see section “Measurements” of groff(7).

    For brief examples, we employ an arrow notation illustrating a
    transformation of input on the left to rendered output on the right.
    Consider the .Dq macro, which double‐quotes its arguments.
          .Dq man page  → “man page”

  Usage
    An mdoc macro is called by placing the roff control character, ‘.’
    (dot) at the beginning of a line followed by its name.  In this
    document, we often discuss a macro name with this leading dot to
    identify it clearly, but the dot is not part of its name.  Space or
    tab characters can separate the dot from the macro name.  Arguments
    may follow, separated from the macro name and each other by spaces,
    but not tabs.  The dot at the beginning of the line prepares the
    formatter to expect a macro name.  A dot followed immediately by a
    newline is ignored; this is called the empty request.  To begin an
    input line with a dot (or a neutral apostrophe ‘'’) in some context
    other than a macro call, precede it with the ‘\&’ escape sequence;
    this is a dummy character, not formatted for output.  The backslash
    is the roff escape character; it can appear anywhere and it always
    followed by at least one more character.  If followed by a newline,
    the backslash escapes the input line break; you can thus keep input
    lines to a reasonable length without affecting their interpretation.

    Macros in GNU troff accept an unlimited number of arguments, in
    contrast to other troffs that often can’t handle more than nine.  In
    limited cases, arguments may be continued or extended on the next
    input line without resort to the ‘\newline’ escape sequence; see
    subsection “Extended arguments” below.  Neutral double quotes " can
    be used to group multiple words into an argument; see subsection
    “Passing space characters in an argument” below.

    Most of mdoc’s general text and manual domain macros parse their
    argument lists for callable macro names.  This means that an
    argument in the list matching a general text or manual domain macro
    name (and defined to be callable) will be called with the remaining
    arguments when it is encountered.  In such cases, the argument,
    although the name of a macro, is not preceded by a dot.  Macro calls
    can thus be nested.  This approach to macro argument processing is a
    unique characteristic of the mdoc package, not a general feature of
    roff syntax.

    For example, the option macro, .Op, may call the flag and argument
    macros, .Fl and .Ar, to specify an optional flag with an argument.
          .Op Fl s Ar bytes      → [-s bytes]
    To prevent a word from being interpreted as a macro name, precede it
    with the escape sequence ‘\&’.
          .Op \&Fl s \&Ar bytes  → [Fl s Ar bytes]

    In this document, macros whose argument lists are parsed for
    callable arguments are referred to as parsed, and those that may be
    called from an argument list are referred to as callable.  This
    usage is a technical faux pas, since all mdoc macros are in fact
    interpreted (unless prevented with ‘\&’), but as it is cumbersome to
    constantly refer to macros as “being able to call other macros”, we
    employ the term “parsed” instead.  Except where explicitly stated,
    all mdoc macros are parsed and callable.

    In the following, we call an mdoc macro that starts a line (with a
    leading dot) a command if a distinction from those appearing as
    arguments of other macros is necessary.

  Passing space characters in an argument
    Sometimes it is desirable to give a macro an argument containing one
    or more space characters, for instance to specify a particular
    arrangement of arguments demanded by the macro.  Additionally,
    quoting multi‐word arguments that are to be treated the same makes
    mdoc work faster; macros that parse arguments do so once (at most)
    for each.  For example, the function command .Fn expects its first
    argument to be the name of a function and any remaining arguments to
    be function parameters.  Because C language standards mandate the
    inclusion of types and identifiers in the parameter lists of
    function definitions, each ‘Fn’ parameter after the first will be at
    least two words in length, as in “int foo”.

    There are a few ways to embed a space in a macro argument.  One is
    to use the unadjustable space escape sequence \space.  The formatter
    treats this escape sequence as if it were any other printable
    character, and will not break a line there as it would a word space
    when the output line is full.  This method is useful for macro
    arguments that are not expected to straddle an output line boundary,
    but has a drawback: this space does not adjust as others do when the
    output line is formatted.  An alternative is to use the unbreakable
    space escape sequence, ‘\~’, which cannot break but does adjust.
    This groff extension is widely but not perfectly portable.  Another
    method is to enclose the string in double quotes.
          .Fn fetch char\ *str   → fetch(char *str)
          .Fn fetch char\~*str   → fetch(char *str)
          .Fn fetch "char *str"  → fetch(char *str)
    If the ‘\’ before the space in the first example or the double
    quotes in the third example were omitted, ‘.Fn’ would see three
    arguments, and the result would contain an undesired comma.
          .Fn fetch char *str    → fetch(char, *str)

  Trailing space characters
    It is wise to remove trailing spaces from the ends of input lines.
    Should the need arise to put a formattable space at the end of a
    line, do so with the unadjustable or unbreakable space escape
    sequences.

  Formatting the backslash glyph
    When you need the roff escape character ‘\’ to appear in the output,
    use ‘\e’ or ‘\(rs’ instead.  Technically, ‘\e’ formats the
current
    escape character; it works reliably as long as no roff request is
    used to change it, which should never happen in man pages.  ‘\(rs’
    is a groff special character escape sequence that explicitly formats
    the “reverse solidus” (backslash) glyph.

  Other possible pitfalls
    groff mdoc warns when an empty input line is found outside of a
    display, a topic presented in subsection “Examples and displays”
    below.  Use empty requests to space the source document for
    maintenance.

    Leading spaces cause a break and are formatted.  Avoid this
    behaviour if possible.  Similarly, do not put more than one space
    between words in an ordinary text line; they are not “normalized” to
    a single space as other text formatters might do.

    Don’t try to use the neutral double quote character ‘"’ to
represent
    itself in an argument.  Use the special character escape sequence
    ‘\(dq’ to format it.  Further, this glyph should not be used for
    conventional quotation; mdoc offers several quotation macros.  See
    subsection “Enclosure and quoting macros” below.

    The formatter attempts to detect the ends of sentences and by
    default puts the equivalent of two spaces between sentences on the
    same output line; see roff(7).  To defeat this detection in a parsed
    list of macro arguments, put ‘\&’ before the punctuation mark.
    Thus,
          The
          .Ql .
          character.
          .Pp
          The
          .Ql \&.
          character.
          .Pp
          .No test .
          test
          .Pp
          .No test.
          test
    gives
          The ‘’.  character

          The ‘.’ character.

          test.  test

          test. test
    as output.  As can be seen in the first and third output lines, mdoc
    handles punctuation characters specially in macro arguments.  This
    will be explained in section “General syntax” below.

    A comment in the source file of a man page can begin with ‘.\"’ at
    the start of an input line, ‘\"’ after other input, or ‘\#’
anywhere
    (the last is a groff extension); the remainder of any such line is
    ignored.

A man page template
    Use mdoc to construct a man page from the following template.

          .\" The following three macro calls are required.
          .Dd date
          .Dt topic [section‐identifier [section‐keyword‐or‐title]]
          .Os [package‐or‐operating system [version‐or‐release]]
          .Sh Name
          .Nm topic
          .Nd summary‐description
          .\" The next heading is used in sections 2 and 3.
          .\" .Sh Library
          .\" The next heading is used in sections 1‐4, 6, 8, and 9.
          .Sh Synopsis
          .Sh Description
          .\" Uncomment and populate the following sections as needed.
          .\" .Sh "Implementation notes"
          .\" The next heading is used in sections 2, 3, and 9.
          .\" .Sh "Return values"
          .\" The next heading is used in sections 1, 3, 6, and 8.
          .\" .Sh Environment
          .\" .Sh Files
          .\" The next heading is used in sections 1, 6, and 8.
          .\" .Sh "Exit status"
          .\" .Sh Examples
          .\" The next heading is used in sections 1, 4, 6, 8, and 9.
          .\" .Sh Diagnostics
          .\" .Sh Compatibility
          .\" The next heading is used in sections 2, 3, 4, and 9.
          .\" .Sh Errors
          .\" .Sh "See also"
          .\" .Sh Standards
          .\" .Sh History
          .\" .Sh Authors
          .\" .Sh Caveats
          .\" .Sh Bugs

    The first items in the template are the commands .Dd, .Dt, and .Os.
    They identify the page and are discussed below in section “Title
    macros”.

    The remaining items in the template are section headings (.Sh); of
    which “Name” and “Description” are mandatory.  These headings are
    discussed in section “Page structure domain”, which follows section
    “Manual domain”.  Familiarize yourself with manual domain macros
    first; we use them to illustrate the use of page structure domain
    macros.

Conventions
    In the descriptions of macros below, square brackets surround
    optional arguments.  An ellipsis (‘...’) represents repetition of
    the preceding argument zero or more times.  Alternative values of a
    parameter are separated with ‘|’.  If a mandatory parameter can take
    one of several alternative values, use braces to enclose the set,
    with spaces and ‘|’ separating the items.
          ztar {c | x} [-w [-y | -z]] [-f archive] member ...
    An alternative to using braces is to separately synopsize distinct
    operation modes, particularly if the list of valid optional
    arguments is dependent on the user’s choice of a mandatory
    parameter.
          ztar c [-w [-y | -z]] [-f archive] member ...
          ztar x [-w [-y | -z]] [-f archive] member ...

    Most macros affect subsequent arguments until another macro or a
    newline is encountered.  For example, ‘.Li ls Bq Ar file’ doesn’t
    produce ‘ls [file]’, but ‘ls [file]’.  Consequently, a warning
    message is emitted for many commands if the first argument is itself
    a macro, since it cancels the effect of the preceding one.  On rare
    occasions, you might want to format a word along with surrounding
    brackets as a literal.
          .Li "ls [file]"  → ls [file] # list any files named e, f, i,
                           or l

    Many macros possess an implicit width, used when they are contained
    in lists and displays.  If you avoid relying on these default
    measurements, you escape potential conflicts with site‐local
    modifications of the mdoc package.  Explicit -width and -offset
    arguments to the .Bl and .Bd macros are preferable.

Title macros
    We present the mandatory title macros first due to their importance
    even though they formally belong to the page structure domain
    macros.  They designate the topic, date of last revision, and the
    operating system or software project associated with the page.  Call
    each once at the beginning of the document.  They populate the page
    headers and footers, which are in roff parlance termed “titles”.

    .Dd date
            This first macro of any mdoc manual records the last
            modification date of the document source.  Arguments are
            concatenated and separated with space characters.

            Historically, date was written in U.S. traditional format,
            “Month day , year” where Month is the full month name in
            English, day an integer without a leading zero, and year the
            four‐digit year.  This localism is not enforced, however.
            You may prefer ISO 8601 format, YYYY‐MM‐DD. A date of the
            form ‘$Mdocdate: Month day year $’ is also recognized.  It
            is used in OpenBSD manuals to automatically insert the
            current date when committing.

            This macro is neither callable nor parsed.

    .Dt topic [section‐identifier [section‐keyword‐or‐title]]
            topic is the subject of the man page.  A section‐identifier
            that begins with an integer in the range 1–9 or is one of
            the words ‘unass’, ‘draft’, or ‘paper’ selects a
predefined
            section title.  This use of “section” has nothing to do with
            the section headings otherwise discussed in this page; it
            arises from the organizational scheme of printed and bound
            Unix manuals.

            In this implementation, the following titles are defined for
            integral section numbers.

                  1   General Commands Manual
                  2   System Calls Manual
                  3   Library Functions Manual
                  4   Kernel Interfaces Manual
                  5   File Formats Manual
                  6   Games Manual
                  7   Miscellaneous Information Manual
                  8   System Manager’s Manual
                  9   Kernel Developer’s Manual

            A section title may be arbitrary or one of the following
            abbreviations.

                  USD     User’s Supplementary Documents
                  PS1     Programmer’s Supplementary Documents
                  AMD     Ancestral Manual Documents
                  SMM     System Manager’s Manual
                  URM     User’s Reference Manual
                  PRM     Programmer’s Manual
                  KM      Kernel Manual
                  IND     Manual Master Index
                  LOCAL   Local Manual
                  CON     Contributed Software Manual

            For compatibility, ‘MMI’ can be used for ‘IND’, and
‘LOC’
            for ‘LOCAL’.  Values from the previous table will specify a
            new section title.  If section‐keyword‐or‐title designates
a
            computer architecture recognized by groff mdoc, its value is
            prepended to the default section title as specified by the
            second parameter.  By default, the following architecture
            keywords are defined.

                acorn26, acorn32, algor, alpha, amd64, amiga, amigappc,
                arc, arm, arm26, arm32, armish, atari, aviion, beagle,
                bebox, cats, cesfic, cobalt, dreamcast, emips, evbarm,
                evbmips, evbppc, evbsh3, ews4800mips, hp300, hp700,
                hpcarm, hpcmips, hpcsh, hppa, hppa64, i386, ia64,
                ibmnws, iyonix, landisk, loongson, luna68k, luna88k,
                m68k, mac68k, macppc, mips, mips64, mipsco, mmeye,
                mvme68k, mvme88k, mvmeppc, netwinder, news68k, newsmips,
                next68k, ofppc, palm, pc532, playstation2, pmax, pmppc,
                powerpc, prep, rs6000, sandpoint, sbmips, sgi, sgimips,
                sh3, shark, socppc, solbourne, sparc, sparc64, sun2,
                sun3, tahoe, vax, x68k, x86_64, xen, zaurus

            If a section title is not determined after the above matches
            have been attempted, section‐keyword‐or‐title is used.

            The effects of varying ‘.Dt’ arguments on the page header
            content are shown below.  Observe how ‘\&’ prevents the
            numeral 2 from being used to look up a predefined section
            title.

              .Dt foo 2       →  foo(2)     System Calls Manual      foo(2)
              .Dt foo 2 m68k  →  foo(2)   m68k System Calls Manual   foo(2)
              .Dt foo 2 baz   →  foo(2)     System Calls Manual      foo(2)
              .Dt foo \&2 baz →  foo(2)             baz              foo(2)
              .Dt foo "" baz  →  foo                baz                 foo
              .Dt foo M Z80   →  foo(M)             Z80              foo(M)

            roff strings define section titles and architecture
            identifiers.  Site‐specific additions might be found in the
            file mdoc.local; see section “Files” below.

            This macro is neither callable nor parsed.

    .Os [operating‐system‐or‐package‐name [version‐or‐release]]
            This macro associates the document with a software
            distribution.  When composing a man page to be included in
            the base installation of an operating system, do not provide
            an argument; mdoc will supply it.  In this implementation,
            that default is “GNU”.  It may be overridden in the site
            configuration file, mdoc.local; see section “Files” below.
            A portable software package maintaining its own man pages
            can supply its name and version number or release identifier
            as optional arguments.  A version‐or‐release argument should
            use the standard nomenclature for the software specified.
            In the following table, recognized version‐or‐release
            arguments for some predefined operating systems are listed.
            As with .Dt, site additions might be defined in mdoc.local.

                  ATT        7th, 7, III, 3, V, V.2, V.3, V.4

                  BSD        3, 4, 4.1, 4.2, 4.3, 4.3t, 4.3T, 4.3r,
                             4.3R, 4.4

                  NetBSD     0.8, 0.8a, 0.9, 0.9a, 1.0, 1.0a, 1.1, 1.2,
                             1.2a, 1.2b, 1.2c, 1.2d, 1.2e, 1.3, 1.3a,
                             1.4, 1.4.1, 1.4.2, 1.4.3, 1.5, 1.5.1,
                             1.5.2, 1.5.3, 1.6, 1.6.1, 1.6.2, 1.6.3,
                             2.0, 2.0.1, 2.0.2, 2.0.3, 2.1, 3.0, 3.0.1,
                             3.0.2, 3.0.3, 3.1, 3.1.1, 4.0, 4.0.1, 5.0,
                             5.0.1, 5.0.2, 5.1, 5.1.2, 5.1.3, 5.1.4,
                             5.2, 5.2.1, 5.2.2, 6.0, 6.0.1, 6.0.2,
                             6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.1, 6.1.1,
                             6.1.2, 6.1.3, 6.1.4, 6.1.5, 7.0, 7.0.1,
                             7.0.2, 7.1, 7.1.1, 7.1.2, 7.2, 8.0, 8.1

                  FreeBSD    1.0, 1.1, 1.1.5, 1.1.5.1, 2.0, 2.0.5, 2.1,
                             2.1.5, 2.1.6, 2.1.7, 2.2, 2.2.1, 2.2.2,
                             2.2.5, 2.2.6, 2.2.7, 2.2.8, 2.2.9, 3.0,
                             3.1, 3.2, 3.3, 3.4, 3.5, 4.0, 4.1, 4.1.1,
                             4.2, 4.3, 4.4, 4.5, 4.6, 4.6.2, 4.7, 4.8,
                             4.9, 4.10, 4.11, 5.0, 5.1, 5.2, 5.2.1, 5.3,
                             5.4, 5.5, 6.0, 6.1, 6.2, 6.3, 6.4, 7.0,
                             7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3,
                             8.4, 9.0, 9.1, 9.2, 9.3, 10.0, 10.1, 10.2,
                             10.3, 10.4, 11.0, 11.1, 11.2, 11.3, 12.0,
                             12.1

                  OpenBSD    2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7,
                             2.8, 2.9, 3.0, 3.1, 3.2, 3.3, 3.4, 3.5,
                             3.6, 3.7, 3.8, 3.9, 4.0, 4.1, 4.2, 4.3,
                             4.4, 4.5, 4.6, 4.7, 4.8, 4.9, 5.0, 5.1,
                             5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 5.9,
                             6.0, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6

                  DragonFly  1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7,
                             1.8, 1.8.1, 1.9, 1.10, 1.11, 1.12, 1.12.2,
                             1.13, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6,
                             2.7, 2.8, 2.9, 2.9.1, 2.10, 2.10.1, 2.11,
                             2.12, 2.13, 3.0, 3.0.1, 3.0.2, 3.1, 3.2,
                             3.2.1, 3.2.2, 3.3, 3.4, 3.4.1, 3.4.2,
                             3.4.3, 3.5, 3.6, 3.6.1, 3.6.2, 3.7, 3.8,
                             3.8.1, 3.8.2, 4.0, 4.0.1, 4.0.2, 4.0.3,
                             4.0.4, 4.0.5, 4.0.6, 4.1, 4.2, 4.2.1,
                             4.2.2, 4.2.3, 4.2.4, 4.3, 4.4, 4.4.1,
                             4.4.2, 4.4.3, 4.5, 4.6, 4.6.1, 4.6.2, 4.7,
                             4.8, 4.8.1, 4.9, 5.0, 5.0.1, 5.0.2, 5.1,
                             5.2, 5.2.1, 5.2.2, 5.3, 5.4, 5.4.1, 5.4.2,
                             5.4.3, 5.5, 5.6, 5.6.1, 5.6.2

                  Darwin     8.0.0, 8.1.0, 8.2.0, 8.3.0, 8.4.0, 8.5.0,
                             8.6.0, 8.7.0, 8.8.0, 8.9.0, 8.10.0, 8.11.0,
                             9.0.0, 9.1.0, 9.2.0, 9.3.0, 9.4.0, 9.5.0,
                             9.6.0, 9.7.0, 9.8.0, 10.0.0, 10.1.0,
                             10.2.0, 10.3.0, 10.4.0, 10.5.0, 10.6.0,
                             10.7.0, 10.8.0, 11.0.0, 11.1.0, 11.2.0,
                             11.3.0, 11.4.0, 11.5.0, 12.0.0, 12.1.0,
                             12.2.0, 13.0.0, 13.1.0, 13.2.0, 13.3.0,
                             13.4.0, 14.0.0, 14.1.0, 14.2.0, 14.3.0,
                             14.4.0, 14.5.0, 15.0.0, 15.1.0, 15.2.0,
                             15.3.0, 15.4.0, 15.5.0, 15.6.0, 16.0.0,
                             16.1.0, 16.2.0, 16.3.0, 16.4.0, 16.5.0,
                             16.6.0, 17.0.0, 17.1.0, 17.2.0, 17.3.0,
                             17.4.0, 17.5.0, 17.6.0, 17.7.0, 18.0.0,
                             18.1.0, 18.2.0, 18.3.0, 18.4.0, 18.5.0,
                             18.6.0, 18.7.0, 19.0.0, 19.1.0, 19.2.0

            Historically, the first argument used with .Dt was BSD or
            ATT.  An unrecognized version argument after ATT is replaced
            with “Unix”; for other predefined abbreviations, it is
            ignored and a warning diagnostic emitted.  Otherwise,
            unrecognized arguments are displayed verbatim in the page
            footer.  For instance, this page uses “.Os groff
            1.23.0.rc3.107‐ac98” whereas a locally produced page might
            employ “.Os "UXYZ CS Department"”, omitting versioning.

            This macro is neither callable nor parsed.




    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?58653>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/