[bug #62774] [mdoc] cope with degenerate documents (`Dd`, `Dt`, `Os` not called)

[G. Branden Robinson]

Update of bug #62774 (project groff):

                Severity:             5 - Blocker => 3 - Normal             
                  Status:                    None => In Progress            
                 Summary: [mdoc] warn if any of `Dd`, `Dt`, `Os` not called =>
[mdoc] cope with degenerate documents (`Dd`, `Dt`, `Os` not called)

    _______________________________________________________

Follow-up Comment #2:

As with bug #62773, and having looked at the practicalities, I think our mdoc
package need only deal with degenerate documents on a best-effort basis.

That said, there are definitely some lingering bugs involving page trap
management, particularly visible when batch rendering of multiple mdoc
documents was attempting.

So I've addressed those across several commits in my working copy.

_And_ added some warnings when `Dd` and `Dt` are called with insufficient
arguments.

...and aligned the header and footer layouts with _man_(7).


commit 0db8cce06529fbe5c80f8d19c1002ea5d5d7917d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Sep 6 18:38:33 2022 -0500

    [mdoc]: Handle setup macro use degeneracy better.
    
    * tmac/mdoc/doc-common: Populate default date string `doc-date-string`
      with "UNDATED".
    
      (Dd, Dt, Os): Make more orthogonal: stop touching `doc-topic-name`.
      It is "doc.tmac"'s job to initialize it and the `Nm` macro's job to
      update it.
    
      (Dd): Do nothing if given no arguments.  (You can still blank
      out the document date with an explicitly empty argument:
        .Dd ""
      .)
    
    Fix code style nit: end string defs with comment escape sequences.

commit 15a8b468b6f3b3769f45b9d1f00e4bec2537619e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Sep 6 18:57:04 2022 -0500

    [mdoc]: Relieve `Dt` of reinitialization duty.
    
    * tmac/mdoc/doc-common (Dt): Stop reinitializing `doc-volume` and
      `doc-section`.  This is the job of package initialization (and, soon,
      the end-of-input macro).

commit a903b34b44a62b0b392ed87088f4d6e37f8f71a4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Sep 6 19:36:16 2022 -0500

    [mdoc]: Reset strings between documents.
    
    * tmac/mdoc/doc-common (doc-end-macro): Reset strings to reduce info
      leaks from one man page to the next.

commit 98c2ab319477b67882073293c7ed98cda01a2428
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Sep 6 20:32:05 2022 -0500

    [mdoc]: Manage footer formatting more coherently.
    
    * tmac/mdoc/doc-common (doc-footer): Pull more footer concerns into this
      macro.  Don't bail out if continuously rendering; instead, format the
      appropriate footer text if we are.  For now, break the page only if we
      are not continuously rendering.
    
      (doc-end-macro): Call `doc-footer` instead of fomatting footer here.

commit b483876a5937712334f88f5580e98f2bc2cd70f8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Sep 6 23:03:13 2022 -0500

    [mdoc]: Warn if Dd, Dt called without arguments.
    
    * tmac/mdoc/doc-common (Dt, Dd): Emit diagnostic warnings if macros
      called with no arguments.
    
    I dislike this diagnostic message format, but it's consistent with
    existing groff mdoc practice.

commit 0335372b8c0d1628b5874490b8b55e8f8d2c0d19
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Sep 6 23:47:40 2022 -0500

    [mdoc]: Align footer management closer to man(7).
    
    * tmac/doc.tmac (doc-save-global-vars, doc-restore-global-vars):
    * tmac/mdoc/doc-common (Rd):
    * tmac/mdoc/doc-ditroff:
    * tmac/mdoc/doc-nroff: Stop defining, saving, and restoring
      `doc-footer-space`.
    
    * tmac/mdoc/doc-common (doc-break-body-text): New macro, called only
      when not continuously rendering, schedules a page break.
    
      (doc-footer): Stop vertically spacing by `doc-footer-space`, instead
      relying upon a trap to move us here.
    
    * tmac/mdoc/doc-ditroff (doc-setup-header):
    * tmac/mdoc/doc-nroff (doc-setup-header): Set traps at the end of the
      page where man(7) does by default; break the body text at
      1 inch from the page bottom, and write the footer at ½ inch.
    
    * tmac/mdoc/doc-nroff (doc-setup-header): Add 1/6 inch "thin space"
      between man page name and parenthesized section, for precise parity
      with doc-ditroff implementation.  (`\|` does not take up any character
      cells on nroff devices.)

commit e7acc0dd49bf472d7bdc2da7d726df58bd7c8ad9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Wed Sep 7 20:00:31 2022 -0500

    [mdoc]: Align trap mgmt more closely with man(7).
    
    * tmac/mdoc/doc-common: Call new macro (see below)
      `doc-set-up-continuous-rendering` when initializing, if that is mode
      is configured.
    
      (doc-ne): New macro replaces `ne` request in continuous rendering
      mode.  It extends the page length by the amount in the argument or by
      1v if none given.
    
      (doc-bp): New macro replaces `bp` request in continuous rendering
      mode, setting the page length to the vertical drawing position.
    
      (doc-set-up-continuous-rendering): New macro renames requests to
      emplace the foregoing.
    
      (Dd): Interpret this macro call strictly as starting a new mdoc(7)
      document.  (andoc.tmac already makes this assumption, and has for over
      20 years.  groff_mdoc(7) and mandoc_mdoc(7) also prescribe the
      sequence `Dd`, `Dt`, `Os`.)  We require this invariant even more
      rigidly now because it's the only way we can be sure that we can
      process multiple documents while rendering headers and footers with
      information corresponding to the appropriate document.  (man(7)'s `TH`
      has an advantage here in that calling it is "atomic": from its
      arguments alone you can obtain everything you need to know to format
      the header and footer.  In mdoc(7), permuting the initialization macro
      order reliably produces chaos.)  Break the page (if necessary)
      _before_ processing any arguments (instead of after), to flush the
      previous page's footer.  Stop calling `doc-set-up-titles` here; we
      don't have enough information to do that yet.  Also stop writing the
      PDF bookmark here, because `doc-document-title` and `doc-section` will
      not reflect the new page content yet.
    
      (Os): Once the `doc-operating-system` string content has been
      determined, call `doc-set-up-titles`, write the PDF bookmark for the
      page, and call `doc-header`, causing the page header to be formatted.
      These changes further imply a stronger requirement on initialization
      macro ordering being canonical.

commit e2c94c33b0d83714c70e62766e400edbf7d4ebe8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Wed Sep 7 20:55:36 2022 -0500

    [mdoc]: Align spacing around headers with man(7).
    
    * tmac/doc.tmac (doc-save-global-vars, doc-restore-global-vars):
    * tmac/mdoc/doc-common (Rd):
    * tmac/mdoc/doc-ditroff:
    * tmac/mdoc/doc-nroff: Stop defining, saving, and restoring
      `doc-header-space`.
    
    * tmac/mdoc/doc-common (doc-header): When starting new document and not
      continuously rendering, space by one half-inch instead of by the
      now-defunct `doc-header-space` amount (which, strictly, should not
      have applied to this measurement).  If not continuously rendering,
      extend page length by 1v to accommodate header line.  After formatting
      header, if not continuously rendering, space to 1 inch below first
      text baseline.

commit 15a0e870772ec3102c24db495cc501c926c6ade8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Wed Sep 7 23:29:29 2022 -0500

    [mdoc]: Stop prefixing center header with "BSD".
    
    Stop prefixing center header with name of operating system.  This was
    hard-coded to "BSD" and stuck on all mdoc(7) pages using a default
    manual section number, regardless of host operating system.  Bad idea.
    Further, the argument to the `Os` call, if any, or a default, is always
    disclosed in the left footer, so the foregoing practice gave the reader
    no new information.  (On the other hand, header and footer rendering was
    not reliable in continuous rendering mode, the default for terminals, in
    groff 1.22.4 and earlier.  It is now.)
    
    * tmac/mdoc/doc-common: Do it.
    
      (Dt): Initialize `doc-volume` as empty and annotate it; calling the
      macro with a numeric second argument overrides the fallback default of
      "LOCAL".  A slash is no longer needed to separate a recognized
      architecture string from the OS name, so drop it.
    
    * tmac/groff_mdoc.7.man: Stop using the string in examples.  Also
      correct table format specification declaring 3 columns but using 2.
    
    * tmac/tests/doc_smoke-test.sh: Update test expectations.



    _______________________________________________________

Reply to this item at:

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

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