mdoc(7) prologue regressions

[Ingo Schwarze]

Hi,

after getting the build system issues mostly out of the way,
i proceeded to run-time testing of groff-current.

The first issue i identified is a group of regressions in the
behaviour of the mdoc(7) prologue macros .Dt and .Os.
The regressions aren't particularly severe because all that i found
so far only trigger when the document uses these macros incorrectly.
All the same, i'd like to report them such that we can decide
whether we want to fix some or all of them.

I suspect that this commit might be responsible but admit
that i did not prove this suspicion by testing right before
and right after the commit.  I only tested that the behaviour
changed as described below from groff-1.22.4 to groff-current:

  commit a1e6c19176d38823d8dc6c9a619a493ca90bdca4
  Author: G. Branden Robinson <g.branden.robinson@gmail.com>
  Date:   Sun Oct 3 23:15:12 2021 +1100

  [andoc,man,mdoc]: Fix Savannah #61266.
    
  Resolve problems in batch rendering of man pages to PDF arising from
  entanglement of end-of-input traps, page location traps, continuous
  rendering mode, and andoc's reloading of the (m)an and (m)doc packages.
  [...]


 1. When there are two .Dt macros in the prologue, the last one used
    to win, setting the page title, section number, and section title.
    Now, the first one wins, setting these fields.

 2. When a .Dt macro occurs in the body of the page (as opposed to
    in the prologue), it used to be ignored.  Now, it causes a
    large number of blank lines in the output.

Both issue 1 and issue 2 can be seen with this test file:
https://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/regress/usr.bin/mandoc/mdoc/Dt/dupe.in?rev=1.4&content-type=text/plain

 3. When the first .Dt macro comes late, the page title used to be
    set to "UNTITLED".  Now, it is set to the empty string.

Both issue 2 and issue 3 can be seen with this test file:
https://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/regress/usr.bin/mandoc/mdoc/Dt/late.in?rev=1.2&content-type=text/plain

 4. If there is no .Dt macro at all, the page title used to be
    set to "UNTITLED".  Now, it is set to the empty string, see:
    
https://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/regress/usr.bin/mandoc/mdoc/Dt/missing.in?rev=1.2&content-type=text/plain

 5. When the usual order of .Dt and .Os is exchanged,
    the .Dt macro is now completely ignored, setting the page title
    to the empty string and the section title to "LOCAL", see
    
https://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/regress/usr.bin/mandoc/mdoc/Dt/order.in?rev=1.2&content-type=text/plain

 6. The same regression as for issue 5 occurs when there are two .Os
    macros in the order .Dd .Os .Dt .Os, see
    
https://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/regress/usr.bin/mandoc/mdoc/Os/dupe.in?rev=1.3&content-type=text/plain

 7. When the .Os macro comes late - i.e. in the body of the page
    rather than at the usual place in the prologue -
    the header line now appears at that place in the middle of the
    body and no longer at the top of the manual page where it belongs, see
    
https://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/regress/usr.bin/mandoc/mdoc/Os/late.in?rev=1.2&content-type=text/plain

 8. When the .Os macro is completely missing, the header line is no
    loger printed at all, see
    
https://cvsweb.openbsd.org/cgi-bin/cvsweb/~checkout~/src/regress/usr.bin/mandoc/mdoc/Os/missing.in?rev=1.2&content-type=text/plain

The most severe issue is probably number 8 because forgetting the .Os
macro, or thinking it might be optional, might even happen in real-world
manual pages.  The next most severe would then be issue 5 because
mixing up the order might also happen in practice.

Number 7 is also somewhat unfortunate.  While not quite as likely to
happen as putting the .Os macro at the wrong place *inside* the prologue,
the effect produced is very ugly.  Similarly, issue 2 is unlikely
to occur in practice, but the effect is also very ugly.

The remaining issues 1, 3, 4, and 6 are less severe.  But in case we
decide that some of the more severe regressions need fixing, maybe
properly fixing them all might not cause that much extra work?
In any case, i thought listing them all might potentially be useful.

Yours,
  Ingo