Proposed: 3 disruptive changes for groff 1.23.0

[G. Branden Robinson]

Hi folks,

Back in October, a release looked imminent, but it doesn't seem so now.
Over 700 commits have been pushed since rc1, so an rc2 seems called for
on quantitative grounds alone.  I'm therefore seeking feedback on three
_structural_ changes to the groff repo and/or the source distribution.

1. "Skip the stripper".  Mooted several times on this list in the past,
   this proposal to stop shipping some macro packages (hdtbl, mdoc, and
   "me") in a condensed, hard-to-read form akin to JavaScript
   minification already enjoys a consensus, but was shelved on perceived
   scheduling grounds.
   <https://savannah.gnu.org/bugs/?55091>

2. Move grog from src/roff to src/utils.  I mooted this on 5 June.  I
   already drastically altered grog's internal structure, making it a
   stand-alone script.[1]
   <https://lists.gnu.org/archive/html/groff/2021-06/msg00003.html>
   https://savannah.gnu.org/bugs/?60788

3. Rename "an-old.tmac" to simply "an.tmac".  I'm not happy with the
   whiff of deprecation that the current nomenclature carries.  I've
   done a fair amount of work on the macro package source, fixing bugs,
   rearranging it, adding comments, and making it more accessible (or
   trying to).  I first mooted a rename in broad terms last October, and
   reiterated it in April.  No one screamed, so I propose now to be even
   bolder, permitting the "an" package to reclaim its proper name among
   the macro package file names.

   This would be a NEWS-worthy item because the "-man" argument to groff
   (or nroff, or troff) would no longer load the andoc wrapper.  Is this
   a problem?  You might think so.  But I think I have discovered that
   it is not.  Most people don't use groff(1) for batch-rendering of
   multiple man pages from one invocation at the command line.  If they
   want to render multiple man pages, they use man(1), which in turn
   appears to execute a separate groff process for every page.  (And
   most of the time, people don't ask man(1) for multiple pages anyway.)

   Why do I characterize our users thus?  Because batch-rendering of
   multiple man pages, up through groff 1.22.4, was very buggy, yet few
   reports of its obvious flaws were present in the Savannah bug tracker
   or mentioned on this list.  I've spent considerable effort making it
   work better.  (HTML driver support for rendering of multiple man page
   documents in one invocation was apparently not contemplated at all.)

   I think andoc.tmac is cool and wish to keep it around; apart from
   being useful for its stated purpose, it's an excellent exhibit of how
   to do certain clever things with the *roff language family (and brief
   enough to not defy comprehension).  But I do not think the case for
   andoc arrogating the "-man" and "-m man" arguments to itself is a
   strong one.

   The asymmetry of doc.tmac(-u) not also causing a redirection through
   andoc.tmac is bothersome, though defensible on terms that may chagrin
   mdoc(7) advocates--there are many more man(7) pages in the world, so
   anyone who asks for "-mdoc" is likely to know what they are doing.
   But I believe we have seen that people who don't, don't say "-man"
   instead--they let man(1) do their thinking for them.  That's
   okay--that's part of its job (with an assist from our andoc.tmac).
   In any case, with the proposed change, the asymmetry disappears.

   So I propose to advise users (and authors of man(1) librarians) in
   the NEWS file to invoke groff with the "-mandoc" argument.  This was
   already a good idea, but not truly necessary.  Now it will be.

   https://lists.gnu.org/archive/html/groff/2020-10/msg00012.html
   https://lists.gnu.org/archive/html/groff/2021-04/msg00027.html

Thoughts?

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff-commit/2021-06/msg00056.html
    I intend, sooner or later, to similarly restructure Bernd's other
    Perl scripts.  The arrangement of having most of the real logic
    stuffed into a "subs.pl" file would be admirable if one were to
    actually make a working library out of them, but that hasn't been
    done and in the meantime, the arrangement makes the programs hard to
    test, with a distressing impact on implementation quality.

signature.asc
Description: PGP signature