Re: Proposed: 3 disruptive changes for groff 1.23.0

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Fri, Jun 18, 2021 at 01:48:15AM +1000:

> 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.

You do have a point here, i think.  In general, it's good to do
disruptive changes shortly after a release rather than shortly
before.  Then again, these changes are not *that* disruptive,
and delaying agreed changes for very long times hinders development
and frustrates developers.  The latter is particulary bad when
short on developers.

> 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>

Yes!  Do it, pretty please.

> 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

No strong opinion on that one.
I guess it makes sense that you did that.

> 3. Rename "an-old.tmac" to simply "an.tmac".  I'm not happy with the
>    whiff of deprecation that the current nomenclature carries.

That whiff of deprecation makes a lot of sense to me, though  ;-).
Then again, naming of macro sets is not a good place to deprecate
things our documentation does not deprecate.  Deprecation needs
consisistency and should not be done in a half-hearted way.

>    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.

For what it's worth, that's already what mandoc(1) does:
1. With -man, process man(7) only.
2. Woth -mdoc, process mdoc(7) only.
3. With -mandoc, auto-detect,
   or fall back to -man if neither .Dd nor .TH are found.
Admittedly, a slight difference remains: with mandoc(1), -mandoc is
the default, while with groff(1), it isn't and should not and cannot be.

>    This would be a NEWS-worthy item because the "-man" argument to groff
>    (or nroff, or troff) would no longer load the andoc wrapper.

Yes.

>    Is this a problem?

I don't think so.  People running groff themselves or from their own
scripts can trivially adapt, in a way that is even backward-compatible
with old groff versions.  Users merely running man(1) likely won't
even notice if package maintainers of man(1) implementations on
their operating system do their job and take care of using -mandoc
rather than -man, which is a good idea anyway, and easy to do before
updating groff in their package repository.

>    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.)
[...]

These arguments all sound very reasonable.

>    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.

I fully agree with that.  I don't think that -mdoc should try to handle
man(7) input; that's what -mandoc is for.  It is always good to have a
way to explicitely state which parsing you want and avoid autodetection
altogether.  I think that's true for man(7), too, by the way.

[...]
>    So I propose to advise users (and authors of man(1) librarians) in
>    the NEWS file to invoke groff with the "-mandoc" argument.

Absolutely.

>    This was already a good idea, but not truly necessary.

Indeed.

> Now it will be.

That's totally fine with me.

>     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.

Yes.  Besides, file names should be descriptive, and files should be
organized according the to function purpose or function groups.
Having a *single* file for subroutines is no better than having them
in the main file, and the name "subs.pl" is atrocious.
It's half-hearted, pointless abstraction for abstraction's sake
without even trying to think about design.  Do not abstract, nor aim
for re-usability, unless there is a reason to.  You will just make
the code more complicated and hinder maintenance.  Not everything
needs to be a library.  There are few ideas in code development as
thoroughly overvalued as reusability.

Yours,
  Ingo