when to deprecate and when to withdraw features (was: Regressions in UTP document)

[G. Branden Robinson]

Hi Dave,

At 2024-10-04T16:44:42-0500, Dave Kemper wrote:
> On Fri, Oct 4, 2024 at 2:21 PM G. Branden Robinson
> While I agree with Branden that notices of new warnings doesn't
> require any special heads-up--a well-crafted warning should speak for
> itself[1]

One hopes... 😅

> --I think Deri's general point stands: it's a courtesy to
> notify users that things will go away before they actually go away.

Yes, and I implement deprecation cycles when I know or even suspect that
the impact on users is going to be more than negligible.

> (By this I mean notification to users of an official release, not just
> to those who follow this list and/or the savannah bug tracker.)

Do the release notes (which get issued more than once because we have a
practice of always doing at least one release candidate--as it happens,
consistently several) and, in cases where a deprecation cycle is in
progress, diagnostic messages from the tools themselves, satisfy this
criterion of notification?

Here are some examples of each case from the NEWS entry for the
forthcoming 1.24.0 release:

*  The `hpfcode` request now emits an error when used, advising of its
   planned withdrawal, but then proceeds with normal behavior.  The
   documented replacement mechanism, the `hcode` request, has existed
   since groff 1.02 (June 1991) at the latest. [[deprecation cycle]]

While my suspicion is that `hpfcode`'s user population is near zero,
this would be my first time yanking a whole request out of the language.

*  GNU troff no longer accepts nonpositive page lengths.  Attempting to
   set one with the `pl` request clamps the page length to the vertical
   motion quantum as `ll` does with the horizontal motion quantum in
   AT&T and GNU troffs. [[negligible impact]]

*  GNU troff no longer accepts a newline as a delimiter for the
   parameterized escape sequences `\A`, `\b`, `\o`, `\w`, `\X`, and
   `\Z`. [[negligible impact; perhaps only a handful of people in the
   world knew of this GNU troff-specific syntax in the first place]]

*  The "el" warning category has been withdrawn.  If enabled (which it
   was not by default), the formatter would emit a diagnostic if it
   inferred an imbalance between `ie` and `el` requests.  Unfortunately
   its technique wasn't reliable and sometimes spuriously issued these
   warnings, and making it perfectly reliable did not look tractable.
   We recommend using brace escape sequences `\{` and `\}` to ensure
   that your control flow structures remain maintainable.  [[This is
   kind of a weird third case, because the existing feature was buggy,
   and I suspect its bugginess discouraged use.]]

The expanded feature set of the man(7) SY/YS macros is another
hard-to-classify case, and it's longer than I want to quote here (mainly
because it's larded with examples), but the salient point I will include
here is this.

   In a "Synopsis" section of a man page, existing synopses consisting
   of a single item require no migration.  This is the most common case.

Also, the number of SY/YS users is relatively small, in part I think due
to man page authors' conservatism,[1] in part due to poor understanding
of how the macros work (which I hope to have ameliorated since groff
1.22.4 with improved documentation), and "old" SY/YS's unsuitability for
synopsizing C function declarations, which the forthcoming changes
address.  SY and YS were revised in consultation with Alex Colomar, the
Linux man-pages project maintainer.  He handles one or two C library man
pages.

https://lists.gnu.org/archive/html/groff/2024-04/msg00115.html

*  The m (mm) macro package's `Limsp` register (a GNU extension) has
   been removed; see the item regarding the `LI` macro below.
   [[neglible impact; it was a weird feature that I suspect no one
   used]]

*  The m (mm) macro package's `AST` macro (a GNU extension) is
   deprecated, warns upon usage, and is slated for withdrawal in the
   next release.  Assign to the new string `Abstract` instead.
   [[deprecation cycle]]

[rearranged]
> Groff 1.24 will lose EBCDIC support.  Sure, any modern EBCDIC users
> should have seen the writing on the wall for decades, but I predict
> it'll still perturb some small number of users who don't follow groff
> development.

*  Support for terminal devices using the CCSID 1047 (EBCDIC) encoding
   has been withdrawn.  [[negligible impact; we _never_ get bug reports
   or feedback from AIX or OS/390 users and furthermore I completely
   lacked courage to do this at all until after consultation with Mike
   Fulton of IBM who addressed my concerns head-on:

   https://lists.gnu.org/archive/html/groff/2023-03/msg00113.html ]]

> This is the point of ticket http://savannah.gnu.org/bugs/?62916.  As
> it notes, groffer went away without warning in 1.23, catching people
> who don't follow this list off guard.

The _plan_ is to drop contrib/pdfmark without a deprecation cycle, too.

https://savannah.gnu.org/bugs/?63827

> I strongly support(ed) both those items' removal.  Removing support
> for EBCDIC, in particular, must be a huge maintenance win by ripping
> out a lot of code complexity.  Groffer, in contrast, was a standalone
> program with no shared code; it could have been allowed to languish
> indefinitely, its only maintenance burden being a few minutes to make
> it emit a warning that it was deprecated, then a few more minutes down
> the road to remove it from the source tree.

Not to be indelicate, but Ingo and I have both expressed concerns with
the quality of the author's code, and while we have retained other
contributions of his, in the case of groffer in particular, the amount
of value delivered was low.

groff(1):
     To process a roff input file using the preprocessors tbl and pic
     and the me macro package in the way to which AT&T troff users were
     accustomed, one would type (or script) a pipeline.

            pic foo.me | tbl | troff -me -Tutf8 | grotty

     Shorten this pipeline to an equivalent command using groff.

            groff -p -t -me -T utf8 foo.me

     An even easier way to do this is to use grog(1) to guess the
     preprocessor and macro options and execute the result by using the
     command substitution feature of the shell.

            $(grog -Tutf8 foo.me)

I seem to remember that you found the last worthy of remark and
characterized it is as (I paraphrase) an unorthodox but complete
replacement for groffer.

> My intent here isn't to hindsight-quarterback that decision, but to
> seek ways to avoid similar pitfalls in future releases.

I welcome that.  For many of the foregoing deprecation/deletion
decisions I can see myself going the other way.

> [1] When a warning is emitted over 1000 times, though, it's fair to
> ask whether the user made the same faux pas 1000 times in the
> document, or whether a lot of those instances are squawking about the
> same thing.

Yes.  If people think it's a good idea, I could hack up this specimen of
font warning to be thrown only once per font identifier.  Now that groff
lies back and thinks of England vis à vis C++ STL usage, it would not be
hard to do, and the risk of bugs is much lower than if we construct yet
another hand-crafted container type with iterator.  (These are _all
over_ groff.  It's pretty appalling.)

I think one person on this list counseled me not to succumb to the STL,
and for a while I didn't, but Werner did already set the precedent, and
as I've become more comfortable with the language, I see the benefits.
I understand hating C++.  Hell, I understand hating C.  But the "AARM"
C++ of 1990 was not a better language than ISO C++98.

Most importantly, using STL containers and iterators helps us confine
our focus to the _mission of the application_ (typesetting, remember?),
and switching to an STL map template fixed one bug with two non-obvious
duplicates.  That's a concrete benefit, that is.

https://savannah.gnu.org/bugs/?65894

Still, it'll be a long time before we're shut of groff's bespoke
container types.  Good chance I won't finish before I retire as
maintainer.  ;-)

Anyway, there was I question I put to the group above:

"If people think it's a good idea, I could hack up this specimen of
font warning to be thrown only once per font identifier."

Meaning:
$ echo '.ft ZZNOT' | nroff
troff:<standard input>:1: warning: cannot select font 'ZZNOT'

Prob'ly stick on " (first occurrence)" to let the user know that any
further places in the document that use it won't be flagged.  Except--
hmm, some people will want that.  You know, diligent lunatics who
actually _fix_ warnings instead of ignoring them with a snarl and moving
their bookmarks to another formatter.  Hmm.  Maybe an environment
variable "GROFF_REPEAT_WARNINGS"?  That would add some documentation
work but still might be worth it.  And it's a name general enough to
apply to other warning diagnostics if we think of any more cases.

What say y'all?

Regards,
Branden

[1] ...and/or laziness.  Why synopsize your interface helpfully to the
    reader when you can just do this?

    \fBcommand \fR[\fIoptions\fR] \fR[\fIfiles\fR]

    ...and just copy and paste that around, changing only "command", for
    all the tools you maintain.  Those that have man pages at all, I
    mean.

    Move fast, document nothing!

    Lest the point be lost, the foregoing synopsis is a _terrible_
    example in multiple respects.  Do not imitate it.

    Except for mockery--that's always an edifying pursuit.

signature.asc
Description: PGP signature