[bug #64772] [hdtbl] consider deprecating

[Dave]

URL:
  

 Summary: [hdtbl] consider deprecating
   Group: GNU roff
   Submitter: barx
   Submitted: Fri 13 Oct 2023 02:08:15 AM CDT
Category: Macro - others/general
Severity: 1 - Wish
  Item Group: Feature change
  Status: None
 Privacy: Public
 Assigned to: None
 Open/Closed: Open
 Discussion Lock: Any
 Planned Release: None


___

Follow-up Comments:


---
Date: Fri 13 Oct 2023 02:08:15 AM CDT By: Dave 
In bug #54461, one developer characterizes hdtbl as "totally unmaintained" and
another says "If the component is totally unmaintained then we should drop it
from the groff distribution."

Bug #55044 throws further shade on this macro package: "The low code quality
of the hdtbl macros is really annoying, they are buggy as hell."







___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #64772] [hdtbl] consider deprecating

[Bjarni Ingi Gislason]

Follow-up Comment #1, bug #64772 (project groff):

  I see no need to abandon "hdtbl".
The code produces the examples without an error, that I can see.

"groff -ww" reported some warnings, which I have provided patches for
(one has to be corrected).

  I have also adjusted some values of variables to make the result more
pleasant(?).

  If abandoning, what will be the replacement?

  This software is in the "contrib" category, those who want to use it
are more or less on their own.

  And the may provide patches and bug (defects) reports.



___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #64772] [hdtbl] consider deprecating

[Dave]

Follow-up Comment #2, bug #64772 (project groff):

[comment #1 comment #1:]
>   I see no need to abandon "hdtbl".

The proposal to deprecate it means it should exist in the next n releases of
groff with notice that it's deprecated.

It's unclear how much use it gets, as every reported bug against it seems to
have arisen from code inspection or build warnings, rather than from actual
use of the macros, despite the fact that they're "buggy as hell" (per Ingo). 
But announcing its deprecation is more likely to smoke out any actual users.

Are you generating Heidelberger tables for your own work, or merely running
basic tests against the package because it's part of groff?

> This software is in the "contrib" category, those who want to use it
> are more or less on their own.

That's not the purpose of "contrib".  Per the file
[http://git.savannah.gnu.org/cgit/groff.git/tree/LICENSES LICENSES]: "Files in
the contrib/ subdirectory of the source distribution are not strictly part of
groff.  That is, they are distributed with it and are Free Software
, but they are not considered
essential parts of the distribution.  Further, they may bear licenses other
than the GPL or the FSF does not administer their copyrights."  There's more
discussion of this in bug #59545.  (Granted, LICENSES is not an intuitive
place to look for this info.  A README or similar in "contrib" itself might be
useful.)

If users are "more or less on their own," probably the appropriate place for
that code is in a source repository separate from groff's.  Groff declining to
distribute it doesn't mean no one else can.


___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #64772] [hdtbl] consider deprecating

[Dave]

Follow-up Comment #3, bug #64772 (project groff):

[comment #2 comment #2:]
> Are you generating Heidelberger tables for your own work, or merely
> running basic tests against the package because it's part of groff?

Clarification: the "merely" isn't meant to dismiss the value of such testing,
but to differentiate between intentional testing and discovering problems
through normal use.


___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #64772] [hdtbl] consider deprecating

[Bjarni Ingi Gislason]

Follow-up Comment #4, bug #64772 (project groff):

  Deprecated means in my dictionary "undesirable".

  When declared deprecated, users should stop using it and use another
(newly added) feature (command) instead.
  The next step is declaring it obsolete.

  I added diagnostic options (-ww -b) to the "groff" command (bug
#54461, 2018-08-07) in "hdtbl.am" to find out where defects could be
present, and added patches to fix those.
  I am just compiling the software.

  "hdtbl" uses the groff-machinery, so I find a close neighbourhood to
be advantageous, showing what can be done with the help of "groff".

  What makes "hdtbl" different from all the other software in the
"contrib" category?

  What will then replace the "fonts_n.ps" and "fonts_x.ps" files,
which show all the characters in the fonts provided by groff?



___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #64772] [hdtbl] consider deprecating

[Dave]

Follow-up Comment #5, bug #64772 (project groff):

Some history:

The author of the HDtbl macros, Joachim Walsdorff, presented them to the email
list in http://lists.gnu.org/r/groff/2005-12/msg3.html (at a now-defunct
URL).  The package was first bundled with groff in groff 1.20 (announced at
http://lists.gnu.org/r/groff/2009-01/msg00011.html).

Larry Kollar was an early user and submitted an extensive patch
(http://lists.gnu.org/r/groff/2010-01/msg00052.html) partially applied as
[http://git.savannah.gnu.org/cgit/groff.git/commit/?id=2c77a4a8 commit
2c77a4a8].

The last groff post I can find from Dr. Walsdorff was in 2014
(http://lists.gnu.org/r/groff/2014-03/msg00214.html).  His savannah profile
(http://savannah.gnu.org/users/x01) shows no activity.

In a 2020 thread on the list, Ingo Schwarze gave a more complete overview of
the package's current status
(http://lists.gnu.org/r/groff/2020-01/msg00060.html) than the various offhand
comments from bug reports quoted here.  This was in response to someone asking
about it, so some user interest in it remains.  Notably, part of Ingo's report
says, "i recently had to look at parts of the code... the code quality is
absolutely terrible.  I have little doubt that it is full of bugs and
instabilities," which implies his previously quoted characterization of the
package as "buggy as hell" is speculative based on code inspection, rather
than empirical based on testing.


___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #64772] [hdtbl] consider deprecating

[Ingo Schwarze]

Follow-up Comment #6, bug #64772 (project groff):

[comment #5 comment #5:]

> which implies his previously quoted characterization of the package as
"buggy as hell" is speculative based on code inspection, rather than empirical
based on testing.

Note that code review and black-box testing are both methodologies (among
others that are also useful, depending on the situation) that are actively
being used in the software industry for the purpose of quality assurance, and
i have done both in professional capacities (i.e. being paid for doing such
work).  Obviously, all methodologies have their specific strengths and
weaknesses.  For example, black box testing has the advantage of working even
without access to the source code, but comes at the price of being more
difficult and more time-consuming.  Fuzzing has the advantage of reducing the
human working time needed, but at the price of only finding some types of
issues and finding bugs only in a random manner rather than systematically
per-feature.  Human code review is much easier and faster than automated
testing, in particular for judging the overall code quality - admittedly, it
is hard to make sure that a review found *all* the problems, but that's not
the goal here.

I think calling code review "speculative" in this context - as if systematic
testing were somehow better - is not helpful.  If you already know from code
review that code is of bad quality, starting a systematic testing effort would
be nothing but a waste of time, unless somebody is willing to invest the large
amount of time that is required for cleaning the code up.

When garbarge code is found in the tree and within three years, no one speaks
up who is using it and no one speak up who wants to repair it, how long do we
want to wait before throwing it out?

Isn't it a no-brainer that low-quality unmaintained code should be deleted? 
I'd go as far as saying that should be done even if the code is used by a few
people and even if there is no replacement.  If people want to use garbage
code on an individual basis, that is their individual problem, and they can
still do that if they really want to even after deletion because old versions
remain publicly available, but we should not promote garbage code and
encourage its use by redistributing it.



___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #64772] [hdtbl] consider deprecating

[Dave]

Follow-up Comment #7, bug #64772 (project groff):


> I think calling code review "speculative" in this context - as
> if systematic testing were somehow better - is not helpful.

Fair point.  I chose that term based more on your wording "I have little doubt
that it is full of bugs," which to my reading implied you hadn't identified
any specific bugs (which I realize wasn't your goal at the time anyway) but
had presumed the presence of many based on the overall code quality.  This
would technically make the claim speculative even if it's likely accurate.

In any case, you seem to have looked at the code more closely than any other
current developer, so I'm inclined to give your analysis more weight.


___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #64772] [hdtbl] consider deprecating

[G. Branden Robinson]

Follow-up Comment #8, bug #64772 (project groff):

hdtbl has proven useful at catching bad builds in the past, so I feel it
continues to have some utility (though its man page annoys me as much as its
code annoys Ingo).

I don't feel much personal motivation to do anything about hdtbl.  If someone
wants to go to the trouble of preparing patches and illustrating how our test
coverage won't shrink (or writing compensatory tests), that could change the
calculus for me.


___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #64772] [hdtbl] consider deprecating

[Bjarni Ingi Gislason]

Follow-up Comment #9, bug #64772 (project groff):

  I will have a shot at this.  The current difference between my branch
and that of master is in the attachments.

  Most of it is an addition to the bugs #54538, #54539,
#55007, #55027, #55044, and #55732.

  What remains to do is using the examples as test files,
copying manually previous PS files to "*.prev" and comparing the
future new ones with them.

  The difference should only be with comments in the PS files, like

%%Creator:

  and

%%CreationDate:


(file #55296, file #55297)

___

Additional Item Attachment:

File name: hdtbl.examples.diffSize:16 KB


File name: hdtbl.tmac.diffSize:8 KB




___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #64772] [hdtbl] consider deprecating

[Dave]

Follow-up Comment #10, bug #64772 (project groff):

[comment #4 comment #4:]
>   What will then replace the "fonts_n.ps" and "fonts_x.ps" files,
> which show all the characters in the fonts provided by groff?

These files being buried in contrib/hdtbl/examples means users looking for
examples of the font glyphs likely won't find them.  (I was unaware of their
existence until your comment.)  I see that bug #64967 seeks to remedy this.

Nonetheless, aside from these files' utility as hdtbl examples, if hdtbl is
withdrawn I'm not convinced replacements for these files need to ship with
groff: for users who want to see all the glyphs in a font, generating such a
list or table is a fairly beginner-level groff exercise.


___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #64772] [hdtbl] consider deprecating

[G. Branden Robinson]

Follow-up Comment #11, bug#64772 (group groff):

Well, [https://lists.gnu.org/archive/html/groff/2023-12/msg7.html
_somebody_ is still using hdtbl]...


___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/

[bug #64772] [hdtbl] consider deprecating

[Dave]

Follow-up Comment #12, bug#64772 (group groff):

[comment #9 comment #9:]
>   I will have a shot at this.

Thanks for volunteering!

> The current difference between my branch
> and that of master is in the attachments.
> 
>   Most of it is an addition to the bugs #54538, #54539,
> #55007, #55027, #55044, and #55732.

All those as clickable links: bug #54538, bug #54539, bug #55007, bug #55027,
bug #55044, and bug #55732

Some of these bug reports have patches that have been reviewed by other
developers, but it is not clear this feedback has been taken into account. 
Bug #55044, for example, has an extensive analysis of what is wrong with its
proposed patch, but that patch appears to have been applied as-is in the
hdtbl.tmac.diff attachment here.

In any case, it seems unlikely a monolithic patch of the sort in the
hdtbl.tmac.diff attachment will be accepted; more useful are individual
changes with a log entry explaining each one's rationale.

To that end, my advice would be to focus on the individual bug reports cited
above.  Address the feedback provided, either by refining the patch or
refuting points made against it, until you have something that solves the
identified problem in a manner acceptable to everyone.  Through this process
you'll learn how to better get patches accepted -- whether this is by creating
better patches, or better justifying them.


___

Reply to this item at:

  

___
Message sent via Savannah
https://savannah.gnu.org/