bugGNU roff - Bugs: bug #58653, want the short mdoc(7) page that...

 
 

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

Submitter:  hackerb9
Submitted:  Wed 24 Jun 2020 10:13:31 PM UTC
   
 
Category:  Macro mdoc Severity:  1 - Wish
Item Group:  Documentation Status:  Rejected
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Thu 30 Mar 2023 05:50:33 PM UTC, comment #12: 

Hi hackerb9,

It's closed already, with status "Rejected" (my new name for "Wont Fix" [sic]).

> My request for a brief quick reference guide does not appear to fit well with the groff project's current goals.


Having acquired some familiarity with mdoc recently, I must disclose to you the distinct possibility that this macro language does not avail itself of brief summary.

Its macro argument reparsing feature is unique among *roff packages (at least those in wide distribution), it layers its own rules for punctuation handling on top of the ones used by the formatter, and I haven't counted, but I think it has more than 66 macros, which means you couldn't summarize them in a single column of type on 1 page at a comfortable type size.

There are 25 macros for quoting/bracketing things alone.

man is smaller.  Come to the Dark Side.  We have cookies. 3;)

G. Branden Robinson <gbranden>
Group administrator
Thu 30 Mar 2023 04:59:48 PM UTC, comment #11: 

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).


Thank you. I appreciate your improvements, but you may as well close this bug. My request for a brief quick reference guide does not appear to fit well with the groff project's current goals.

hackerb9
Thu 30 Mar 2023 03:06:21 PM UTC, 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.


G. Branden Robinson <gbranden>
Group administrator
Tue 01 Feb 2022 09:48:23 PM UTC, comment #9: 

comment #1:

> In general, it is an extremely bad idea to have a short and a long version of the same manual page.  All that does is making it likely that both get out of sync and eventually neither are correct.  One reference manual is enough.


For groff_man(7), I cut this knot through yet another layer of indirection.  We now have an m4 document, groff_man.7.man.in, that produces (after another layer of sed-foolery managed by make(1)) groff_man(7) and groff_man_style(7).

It's WAY easier to maintain than the duplicated and occasionally triplicated material that is our ms(7) documentation, where we have a big chunk of groff.texi, ms.ms, and groff_ms(7).

But I'm getting closer to being able to kill off the Texinfo portion, and the differences in terseness between ms.ms and groff_ms(7) are already clear.


> Ingo's approach is admirable but I don't think it's the norm, certainly not for me and others I've worked with.


Maybe I've become a bit more like Ingo.  I didn't know jack about me(7) a few months ago, and meintro.me didn't help me to acquire it.  I now feel I have a fairly strong command of it.

What did the trick?

Revising meref.me down to the last jot and tittle, almost literally.

So I guess for me, the way I learn a system is not with separate basic and advanced user guides, nor with counterpart tutorials and references, nor even a single comprehensive master document, though the latter comes closest.

No, I have to take that master document and strike it with lightning until it no longer bothers me.

I do not recommend this path for everyone.

> In general I think it behooves experienced users to listen to new users when they say what has helped them get a handle on learning something.  Hackerb9, as someone who has just gone through that initial learning curve, is in a unique position to say what has been most useful.  There may be fatal flaws in the particular mdoc(7) page he consulted, but what aspects of it were helpful, and how can those be worked into something that's useful to beginners without oversimplifying to the point of inaccuracy?


I agree with this.  Many valuable insights arise from newcomers to a system, while they are innocent of its quirks and haven't yet internalized all the knowledge about how "it just doesn't work that way".
 

> It's not like the groff package is any stranger to overlapping documentation, having the Texinfo package for complete documentation for the core language, and the groff(7) man page as a terse reference guide.


groff(7) has gotten less terse over the past couple of years.  Without actually planning to, I seem to be evolving it in a CSTR #54-ish direction.

G. Branden Robinson <gbranden>
Group administrator
Sun 28 Jun 2020 01:55:24 AM UTC, comment #8: 

I'm not an mdoc user, so have no position on the specifics of its documentation.  But I have to agree with this point:

comment #4:

> comment #3:
> > When learning a completely new language totally from scratch, i typically go for the formal standard / formal language definition
>
> May I suggest that, perhaps, you are a bit of an exception?


Ingo's approach is admirable but I don't think it's the norm, certainly not for me and others I've worked with.

In general I think it behooves experienced users to listen to new users when they say what has helped them get a handle on learning something.  Hackerb9, as someone who has just gone through that initial learning curve, is in a unique position to say what has been most useful.  There may be fatal flaws in the particular mdoc(7) page he consulted, but what aspects of it were helpful, and how can those be worked into something that's useful to beginners without oversimplifying to the point of inaccuracy?

It's not like the groff package is any stranger to overlapping documentation, having the Texinfo package for complete documentation for the core language, and the groff(7) man page as a terse reference guide.

Dave <barx>
Group Member
Thu 25 Jun 2020 07:08:08 PM UTC, comment #7: 


> I had thought you were linking to the mdoc documentation that comes with BSD.


mandoc is portable software.  It is included and used by default in these systems (chronological order by first official use): OpenBSD, NetBSD, Illumos, Void Linux, FreeBSD, Alpine Linux.  Official packages exist for Debian, Gentoo, and Fedora, among others; on Fedora, making it the default manual page viewer is an officially supported option.  I just used the OpenBSD link out of habit and because it's the most carefully maintained manual page server carrying it.  These are quite similar:

  https://mandoc.bsd.lv/man/mdoc.7.html
  https://man.bsd.lv/mdoc.7
  https://manpages.debian.org/buster/mandoc/mandoc_mdoc.7.en.html
  https://man.voidlinux.org/man7/mdoc.7
  https://www.freebsd.org/cgi/man.cgi?query=mdoc

> I do think it is unfortunate that people who use groff
> on non-BSD systems are left poorer, without even
> a pointer to better documentation.


I wouldn't say either is absolutely better, it's mostly the same content in somewhat different style.  But your idea of adding pointers to each other in the SEE ALSO sections on both sides sounds good, so people can more easily find both and pick one according to which style they prefer.  Let's see whether i can get those two links in on both sides.

Ingo Schwarze <schwarze>
Group Member
Thu 25 Jun 2020 06:35:47 PM UTC, comment #6: 

comment #5:

>
> > This mandoc mdoc(7) you are speaking of,
> > is it part of groff? I don't see it.
>
> No it isn't.
> I already posted the hyperlink: https://man.openbsd.org/mdoc.7
> It is part of mandoc.


Please pardon my ignorance. I had thought you were linking to the mdoc documentation that comes with BSD. Is that not right?


> What i oppose is adding another manual page for the same thing.


Clearly, as someone who has contributed to groff for a long time, Ingo, you should have more say about the documentation than someone like me who has just begun. I don't think I can convince you that a quick reference guide is not redundant, so I will drop it.

I do think it is unfortunate that people who use groff on non-BSD systems are left poorer, without even a pointer to better documentation.

hackerb9
Thu 25 Jun 2020 05:51:06 PM UTC, comment #5: 


> Good documentation lets people know right away what the
> cost of learning will be and what the benefits are.


Right, that's usually the first one to three sentences in a manual page.  No need for a separate document.

In groff_mdoc(7), the first paragraph does that, too.  Admittedly, it's a bit wordy (9 sentences rather than 3), partially antiquated (translation to future documentation tools etc. - huh?), and contains some needless jargon (domain etc.).  It could probably be made a bit more readable.

The part "easy to learn" could probably be made obvious by including a MACRO OVERVIEW up front, as i already suggested.

> Honestly, I had thought the problem was
> that it was maintained by the Linux kernel folks


It wasn't maintained by "the Linux kernel folks" but by the Linux manual pages project (Michael Kerrisk et al.) who generally does a good job at maintaining documentation of code he doesn't maintain himself.  The problem wasn't that we were jealous about what they were doing, but that it was a relic both sides had forgotten about twenty years earlier and both sides had no interest in.

On the groff side, all the information from the former mdoc(7) manual had already been merged almost twenty years ago.  Werner Lemberg did that work in commit b57a7328 on Mar 24 15:04:41 2001 +0000.  So there was nothing more to do here.

> This mandoc mdoc(7) you are speaking of,
> is it part of groff? I don't see it.


No it isn't.
I already posted the hyperlink: https://man.openbsd.org/mdoc.7
It is part of mandoc.

It shows that what you want can easily be done within a reference manual.  But as i said, i feel somewhat reluctant to do copy-editing on groff_mdoc(7) myself because if we must have two documents, having two distinct maintainers improves the chances that every user finds a version in the style they like.

I don't oppose improving groff_mdoc(7).  I don't even have strong preferences in which direction to tweak it, as long as it remains correct and complete and does not become even more wordy.  What i oppose is adding another manual page for the same thing.

Ingo Schwarze <schwarze>
Group Member
Thu 25 Jun 2020 03:24:22 PM UTC, comment #4: 

comment #3:

> You say "but beginners need something simpler".  I contest that.  It's not because i'm an expert on mdoc(7).  When learning a completely new language totally from scratch, i typically go for the formal standard / formal language definition (or the reference manual if there is no completely formal document), and certainly not for the user manual or tutorial, which usually is a total waste of time even during the first two or three hours of learning.


May I suggest that, perhaps, you are a bit of an exception? There are many different kinds of minds out there. Even if you find user manuals to be a waste of time, some of us do not.


> Just train your reading skills to quickly extract the information you need from a precise, concise text without reading all the words.


Perhaps part of the problem here is that we are talking about different things. You mention extracting information from formal specifications, but I'm starting out from the meta-question "Do I even want to learn this?"

Good documentation lets people know right away what the cost of learning will be and what the benefits are. For example, mdoc(7) told me the benefit (semantic markup) and then showed that using it would not be complicated.


> Why do you think we spent the time to get the horrible document exterminated? 


Honestly, I had thought the problem was that it was maintained by the Linux kernel folks and the groff team wanted something that they could keep up-to-date. "Exterminating" the quick reference guide without replacement seems a bit extreme.


> [...] the high-level "what is this all about" stuff useful for beginners is easier to find in mandoc mdoc(7) than in groff_mdoc(7).  Certainly no need for a third.


This mandoc mdoc(7) you are speaking of, is it part of groff? I don't see it. I filed this bug report to improve the documentation for groff, but perhaps it just needs to be made easier to find.

hackerb9
Thu 25 Jun 2020 11:49:48 AM UTC, comment #3: 

You say "i wish you had mentioned this before".  Granted, it would have been helpful, and i wanted to.  But there isn't time to answer all questions i could usefully respond to, so it fell through the cracks.  I estimate roughly 80% fall through the cracks due to lack of time.  I tend to prioritize those answers that allow positive action over those refuting bad ideas.  Opening this bug forced me to answer just to make sure no harm is done.

You say "but beginners need something simpler".  I contest that.  It's not because i'm an expert on mdoc(7).  When learning a completely new language totally from scratch, i typically go for the formal standard / formal language definition (or the reference manual if there is no completely formal document), and certainly not for the user manual or tutorial, which usually is a total waste of time even during the first two or three hours of learning.  Of course that approach doesn't work for very complex topics like quantum field theory where you first have to understand more than half a dozen layers of mathematical abstractions, each built on top of the simpler ones, but it works just fine for anything that can be readily understood just based on natural language, without any previous knowledge of any kind, like a markup language as intentionally trivial as mdoc, and even for just about any programming language.  Just train your reading skills to quickly extract the information you need from a precise, concise text without reading all the words.

You say "writing good docs that are correct, complete, and concise takes time, and they tend to degrade over time from accretion".  Absolutely.  I write a lot of documentation, my average time per function is over two hours (mostly measured documenting crypto/TLS libraries, but i write lots of other stuff, too).  Some functions take up to eight hours.  On top of that, good documentation requires good API/UI design, or you have lost before you even start.  Then, if the API/UI develops feature creep over time, the docs will degrade at least as much as the code.  Fortunately, no such degradation happened in mdoc, i took care of that during the last decade, adding just one single macro in ten years and during the same time deprecating more than half a dozen and removing traps from a few others.

You say "but even confusing information is still helpful".  No it is not.  There is no time to maintain it.  Unmaintained, it causes confusion and questions which no one has time to handle.  Why do you think we spent the time to get the horrible document exterminated?  To save us more time and confusion. afterwards.

You name some downsides of groff_mdoc(7).  Yes, the IDIOSYNCRASIES section is a bit wordy, in particular being near the beginning of the page, but it's trivial to see even for a beginner that you can skip it during the first reading.

I work relatively little on groff documentation because i maintain mandoc documentation.  Both have essentially identical content arranged in slightly different style, and since i see no way to prevent this duplication, i think we can at least make it partly useful by having it maintained by different people, such that users can pick the style they understand more easily.  If groff_mdoc(7) is too wordy for you, especially near the beginning, you will probably like the more concise mandoc mdoc(7) manual better.  Also, the high-level "what is this all about" stuff useful for beginners is easier to find in mandoc mdoc(7) than in groff_mdoc(7).  Certainly no need for a third.

Ingo Schwarze <schwarze>
Group Member
Thu 25 Jun 2020 07:12:46 AM UTC, comment #2: 

comment #1:

> I VERY strongly oppose this idea.


Thank you, Ingo, although I do wish you had mentioned this on the mailing list when I first brought it up or at the point when someone else suggested that the groff project needs to have a bug report on it.

Ingo, at your request, the Linux man pages dropped mdoc(7) last year. The fact that BSD has good documentation doesn't alleviate the need for GNU/Linux systems to also have complete and useful documentation. It is now up to the groff project to make sure that happens.


> Documentation ought to be correct, complete, concise, and easy to find, which implies all in one place.


Trying to balance competing goals, such as "complete" and "easy to understand", in a single document is difficult, sometimes impossible. When it does happen, it takes a lot of time and effort to get right. Also, it's a bear to maintain as inevitably changes accrue that throw it out of balance.

It is much less work to have separate documents. One of them, groff_mdoc(7), can prioritize being correct and complete. The other, mdoc(7), can focus on being concise and easy to learn from. And that's what GNU/Linux had until mdoc(7) was dropped.


> It is even a terrible starting point for working on something better.


Experts are always disappointed by any quick reference guide: "it is incomplete and wrong!" But, that's mainly because it has been optimized for understandability to a more general audience: people like me who are not already experts. Such tutorials are top-loaded with broad brush strokes giving general use and "quick start for the impatient" type of information. Then they go on to the most useful features and work their way down. Nitty gritty details are pushed to the back, if covered at all.

For example, from reading mdoc(7), I knew very quickly what the point of mdoc was, where to find the full documentation (groff_mdoc(7)), and even the minimal commands needed to create a valid mdoc manual page. I could see that I wouldn't have to invest much time for this package to be useful to me.

Whereas, reading that far in groff_mdoc(7), my eyes had glazed over. Does one have to understand "troff idiosyncracies" to use this package? It's not clear from the document, but that's because it has a different purpose: if I need to understand mdoc in more detail, I can come back to it.


> One reference manual is enough.


Yes, for people who already know mdoc. For people getting started or needing to brush up, a quick reference guide serves them better. If you're writing for humans, the documentation isn't complete unless it includes an approachable guide for new users.

Documentation is not like computer programming where we want to do things in exactly one place. Different people find different forms of documentation helpful and repetition phrased in alternate ways is actually better. It is not harmful to have more than one document, even if they get out of sync, as long as the informal guide explicitly links to the complete reference. (Note that mdoc(7) starts out by referencing groff_mdoc(7).)


> If groff developers think groff_mdoc(7) needs an overview before diving into the specifics, i can copy the "MACRO OVERVIEW" section from
>   https://man.openbsd.org/mdoc#MACRO_OVERVIEW


Ingo, please do not take offense, but I think perhaps you may be too expert. I say this with great respect: The fact that you don't see the point of mdoc(7), which was so helpful to a troff neophyte like me, raises the question of whether you are the right person to make groff's documentation more user friendly.

I am full of humility and admiration for the work Ingo and all the groff devlopers have put in over the years. Even if you reject this bug, I thank you.

--b9

hackerb9
Wed 24 Jun 2020 10:51:41 PM UTC, comment #1: 

I VERY strongly oppose this idea.

Documentation ought to be correct, complete, concise, and easy to find, which implies all in one place.  This particular, totally unmaintained manual page was full of errors, blatantly incomplete, terse to the point of incomprehensibility, yet not concise, but putting excessive weight on aspects of marginal importance.  Besides, it caused a needless split of documentation that can, without any downside, be in one place, causing people to miss the real documentation.  I'm not going to waste my time enumerating all the many deficiencies of this ancient, unmaintained document.  No, importing it would not be "better than nothing", it would be a huge step backwards.  It is even a terrible starting point for working on something better.

In general, it is an extremely bad idea to have a short and a long version of the same manual page.  All that does is making it likely that both get out of sync and eventually neither are correct.  One reference manual is enough.

If groff developers think groff_mdoc(7) needs an overview before diving into the specifics, i can copy the "MACRO OVERVIEW" section from
  https://man.openbsd.org/mdoc#MACRO_OVERVIEW
into the beginning of groff_mdoc(7), probably between A MANUAL PAGE TEMPLATE and CONVENTIONS, but i'm open to suggestions for the exact location, and to tweaking it if you think that's necessary.

Ingo Schwarze <schwarze>
Group Member
Wed 24 Jun 2020 10:13:31 PM UTC, original submission:  

According to Ingo Schwarze on the groff mailing list, the groff
project recently convinced the Linux man pages project to remove their
mdoc(7) manual as it was outdated by a few decades.

However, the groff project lacks anything equivalent to mdoc(7).

Ingo suggested I try mandoc.bsd.lv, but I found it more cryptic and
less helpful.

Yes, there is a man page for groff_mdoc(7), but it is a "complete
reference" which is rather difficult for a beginner to get started
using mdoc. In contrast, mdoc(7) from the Linux man pages was a quick
reference on the macro names and their meanings, laid out in a logical
fashion. At the top, mdoc(7) informs the reader to check groff_mdoc(7)
for the nitty gritty.

groff_mdoc(7) appears to have been based upon mdoc.samples(7) which
was written as a companion to mdoc(7). Although groff_mdoc(7) removed
all references to mdoc(7), it does not stand alone well. As somone new
to the world of troff, I found mdoc(7) to be necessary when I
attempted my first serious man pages. If I had had only groff_mdoc(7)
available, I would have given up.

Please import the old mdoc(7) file into the groff project so that it
can become available on all GNU/Linux machines once again. Please do
not wait to update it before importing. Even outdated, it is extremely
useful and mostly correct. Once in Savannah, it can be iteratively
improved via bug reports.

The mdoc(7) file can be viewed online here:

  https://man7.org/linux/man-pages/man7/mdoc.7.html

And the troff can be found here:

  https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man7/mdoc.7?id=6474f351fd8ac68e6e0c8820bb8926c6b9e3ec97

Thanks!

hackerb9

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Updated the item)
  • -email is unavailable- added by barx (Posted a comment)
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by hackerb9 (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-03-30 gbranden StatusNone Rejected
        Assigned toschwarze gbranden
        Open/ClosedOpen Closed
    2022-02-01 gbranden SummaryPlease add back in the mdoc(7) manual want the short mdoc(7) page that Linux man-pages used to ship
    2020-06-24 schwarze Severity3 - Normal 1 - Wish
        Assigned toNone schwarze

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code