[bug #59826] [ms] does not put date in center footer in nroff mode as AT&T ms does

[G. Branden Robinson]

Update of bug #59826 (project groff):

              Item Group:     Incorrect behaviour => Documentation          
                  Status:                    None => In Progress            
             Assigned to:                    None => gbranden               

    _______________________________________________________

Follow-up Comment #1:

I've decided to treat this as a documentation issue.

Having nroff and troff modes work differently in this respect is, I think,
more likely to be annoying to new users as well as existing groff users, from
whom we've heard few if any complaints on this subject over the past 30
years.

Our documentation was inaccurate on this point, describing AT&T ms behavior,
but I fixed it on 20 March to be accurate.  See the "<DA>" item below.

The discrepancy, however, could still be usefully called out in the
"Differences from AT&T ms" section of the manuals, for those users accustomed
to Unix and Heirloom Doctools.  So I'll do that.


commit 5be3f4fce7f47ca2a9296b7d48fd16a0ebb40648
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Mar 20 20:13:02 2021 +1100

    [ms]: Revise documentation of cover page macros.
    
    * doc/groff.texi (ms Document Structure):
      - Say that macros are "called", not "invoked", for consistency with
        other documentation.
      - Stop providing mnemonic for RP macro here, since it has two
        different ones.
      - Loosen claim: .RP does not have to be the first line of an input
        document; it simply needs to be early.
      - More carefully distinguish between what groff (or troff) does and
        what the macro package does.
      - Say "document description" instead of "cover page [information]"--a
        cover page is only present if .RP is called.
      - Be more clear that multiple authors can be declared with .AU.
      - Be more clear that the arguments to .DA or .ND need not be a date.
      - Refer to the "body" of the text additionally as the "main matter",
        since we also must cope with the subjects of tables of contents and
        indices.
    
      (ms Cover Page Macros):
      - Rename node/section to "ms Document Description Macros".  Update
        node structure accordingly.
      - Add motivating paragraph to introduce section.
      - Clarify ordering & presence restrictions on cover page macro calls.
      - Describe macros using imperative mood instead of sentence fragments.
      - Describe diversion-creating macros in a way that suggests their
        operation (without using the technical term).
      - Be more clear about what macro calls terminate these diversions.
      - Say "cover page" instead of "title page".
      - Be specific that the document "date" (DA/ND arguments) appear on a
        cover page but not otherwise prior to the main matter.
      - <RP> Be more specific about default placement of cover page
        information.
      - <RP> Note AT&T expansion of macro name.
      - <P1> Document as Berkeley Unix extension.  Note existence of
        conflicting V10 Unix macro.
      - <AU> Replace example of multiple authors with explanatory prose.
      - <AI> Clarify behavior when called multiple times.
      - <DA> Give argument(s) a metasyntactic variable instead of merely an
        ellipsis.
      - <DA> Undocument this as the "nroff default".  GNU ms does not work
        this way.
      - <ND> Make synopsis consistent with DA since it treats its arguments
        the same way.
      - Use more idiomatic input in the example.
    
    * doc/ms.ms:
      - Add empty request macro between sentences.
      - Add two empty request macros where vertical space is expected.
      - Synchronize language with our Texinfo manual.
    
      (General structure of an -ms document):
      - Convert colon-terminated sentence fragment to a complete sentence.
    
      (Cover page macros):
      - Rename section to "Document description macros".  Update references.
    
    * tmac/groff_ms.7.man:
      - Synchronize language with doc/ms.ms, omitting new motivational
        paragraph since this man page will ultimately become a relatively
        terse reference document.



    _______________________________________________________

Reply to this item at:

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

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