Re: notice: intent to diganose use of 'Df'

[John Gardner]

Hi Branden,

If you review the attached diff, it does in fact retain support for the
> feature, it's simply noisy about it.
>

I did review it, but those aren't the changes that worry me. Rather, it's
the ones they appear to allude to: "support for `\D'f…' *may* (or may not)
disappear in the next release".

 Do you also object to the emission of these diagnostic messages?


Not at all, but the undercurrent of urgency is a tad misleading.
Personally, I'd replace *"may disappear in the next release"* with *"may
disappear in a future release"* so it sounds less like an imminent or
planned removal.

Apart from that, I wholeheartedly endorse making deprecation warnings more
obvious and noticeable by users.

On Thu, 29 Jun 2023 at 21:39, G. Branden Robinson <
g.branden.robinson@gmail.com> wrote:

> Hi John,
>
> At 2023-06-29T19:45:18+1000, John Gardner wrote:
> > Support for 'f' may disappear in the next release, producing an error
> > > diagnostic regarding an unrecognized command.
> > >
> >
> > This doesn't sit right with me. Removing an obsolete feature to
> > encourage adoption of a newer one runs counter to Groff's normative
> > handling of legacy features—a manual that's formatted correctly and
> > consistently for the past 20 years will logically be expected to
> > continue doing so. I'm aware that \D'f…' isn't supported by AT&T Troff
> > (although it *is* supported by SQTroff), but that strikes me as a weak
> > argument to justify the feature's removal.
> >
> > Assuming there's no practical benefit to removing \D'f…' outright, I
> > instead suggest documenting it as an explicitly obsolete feature,
> > similar to how the *"Legacy command(s)"* section in groff_out(5)
> > documents the old "jump right *dd*u and print char *c**"* method for
> > outputting text. The section makes it crystal clear to readers that
> > this syntax is supported for backwards compatibility only, and
> > suggests modern alternatives they should be using instead. \D'f…'
> > should do likewise, IMO.
>
> I should have titled the thread "further deprecate" or "diagnose on use
> of".  So I am doing so now.
>
> If you review the attached diff, it does in fact retain support for the
> feature, it's simply noisy about it.
>
> diff --git a/src/devices/gropdf/gropdf.pl b/src/devices/gropdf/gropdf.pl
> index e86644da5..2067f0a19 100644
> --- a/src/devices/gropdf/gropdf.pl
> +++ b/src/devices/gropdf/gropdf.pl
> @@ -3140,6 +3140,7 @@ sub do_D
>      }
>      elsif ($Dcmd eq 'f')
>      {
> +       Warn("'f' drawing command is obsolete; use 'Fg' instead");
>         my $mcmd=substr($par,0,1);
>
>         $par=substr($par,1);
> diff --git a/src/libs/libdriver/input.cpp b/src/libs/libdriver/input.cpp
> index 821b526bd..78f73379a 100644
> --- a/src/libs/libdriver/input.cpp
> +++ b/src/libs/libdriver/input.cpp
> @@ -1361,6 +1361,7 @@ parse_D_command()
>      }
>    case 'f':                    // Df: set fill gray; obsoleted by DFg
>      {
> +      warning("'f' drawing command is obsolete; use 'Fg' instead");
>        IntArg arg = get_integer_arg();
>        if ((arg >= 0) && (arg <= 1000)) {
>         // convert arg and treat it like DFg
> diff --git a/src/roff/troff/input.cpp b/src/roff/troff/input.cpp
> index e797e2200..cc0b59f38 100644
> --- a/src/roff/troff/input.cpp
> +++ b/src/roff/troff/input.cpp
> @@ -8754,6 +8754,9 @@ static node *read_draw_node()
>             error("even number of arguments needed for spline");
>           break;
>         case 'f':
> +         error("'f' drawing command is obsolete;"
> +               " use 'Fg' drawing command, 'M' escape sequence,"
> +               " or 'fcolor' request instead");
>           if (npoints != 1 || !no_last_v) {
>             error("one argument needed for gray shade");
>             npoints = 1;
>
> Do you also object to the emission of these diagnostic messages?
>
> The actual feature removal is something I don't contemplate for groff
> 1.24, may never happen (though I think we should not pretend to
> foreclose the option from future groff developers, which means warning
> users strongly now/soon), and would prefer to discuss your philosophy of
> feature retention in a separate thread.
>
> Regards,
> Branden
>