[bug #62774] [mdoc] warn if any of `Dd`, `Dt`, `Os` not called

[G. Branden Robinson]

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

                 Summary: [mdoc] warn if any of `Dd`, `Dt`, `Os` not called
                 Project: GNU troff
               Submitter: gbranden
               Submitted: Sat 16 Jul 2022 10:46:19 AM UTC
                Category: Macro mdoc
                Severity: 3 - Normal
              Item Group: Warning/Suspicious behaviour
                  Status: None
                 Privacy: Public
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: None


    _______________________________________________________

Follow-up Comments:


-------------------------------------------------------
Date: Sat 16 Jul 2022 10:46:19 AM UTC By: G. Branden Robinson <gbranden>
Ingo Schwarze reported several issues with malformed mdoc(7) documents to the
mailing list.

https://lists.gnu.org/archive/html/groff/2022-06/msg00117.html

Here is an edited version of my response to his report.

> I'll have a fresh look at my changes to groff mdoc in this commit and
> see if I can find good spots to recover more gracefully.

> I have to admit I'm tempted to either let these fail, or, if I can find
> a good place to stick a sanity-checking hook, simply refuse to render
> the page if these macros, documented as mandatory, are missing.  But,
> maybe replacing the missing content with shouty-caps stuff like
> "UNTITLED" and "LOCAL" suffices to clue the user in.  Perhaps also
> changing the fallback operating system string from "BSD" to "GNU" will
> more effectively agitate misusers of mdoc(7) into correcting their ways.

> (Relatedly, I don't understand why anyone thought it was a good idea for
> the volume titles for mdoc(7) man pages in a GNU project to all announce
> themselves as being from a BSD manual even if they're rendering man
> pages that have nothing to do with BSD.  This name is _not_ derived from
> any argument to the `Os` macro, nor configured based on the build host's
> OS identity, but hard-coded in `doc-volume-operating-system`.  If this
> string were made empty or deleted, the volume titles would exactly match
> those used by groff man(7).)

Right now my idea is to move some of the string resets from the `Dt` to the
`Dd` macro definition.

Work up some regression tests for this.

Also look into killing off `doc-volume-operating-system`, noted above.







    _______________________________________________________

Reply to this item at:

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

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