bugGNU roff - Bugs: bug #64772, [hdtbl] consider deprecating

 
 

bug #64772: [hdtbl] consider deprecating

Submitter:  Dave <barx>
Submitted:  Fri 13 Oct 2023 07:08:15 AM UTC
   
 
Category:  Macro - others/general Severity:  1 - Wish
Item Group:  Feature change Status:  None
Privacy:  Public Assigned to:  None
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Wed 27 Dec 2023 08:45:21 AM UTC, comment #12: 

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.

Dave <barx>
Group Member
Fri 08 Dec 2023 09:19:06 PM UTC, comment #11: 
G. Branden Robinson <gbranden>
Group administrator
Tue 05 Dec 2023 01:29:32 AM UTC, comment #10: 

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.

Dave <barx>
Group Member
Thu 02 Nov 2023 08:38:04 AM UTC, comment #9: 

  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)

Bjarni Ingi Gislason <bjarniig>
Sat 28 Oct 2023 06:10:01 PM UTC, comment #8: 

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.

G. Branden Robinson <gbranden>
Group administrator
Fri 20 Oct 2023 03:02:06 AM UTC, comment #7: 


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

Dave <barx>
Group Member
Thu 19 Oct 2023 11:05:31 AM UTC, comment #6: 

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.

Ingo Schwarze <schwarze>
Group Member
Thu 19 Oct 2023 08:30:20 AM UTC, comment #5: 

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

Dave <barx>
Group Member
Wed 18 Oct 2023 01:17:23 AM UTC, comment #4: 

  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?

Bjarni Ingi Gislason <bjarniig>
Tue 17 Oct 2023 01:15:50 AM UTC, comment #3: 

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.

Dave <barx>
Group Member
Mon 16 Oct 2023 11:14:31 PM UTC, comment #2: 

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 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 <https://www.gnu.org/philosophy/free-sw.en.html>, 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.

Dave <barx>
Group Member
Mon 16 Oct 2023 09:46:37 PM UTC, comment #1: 

  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.

Bjarni Ingi Gislason <bjarniig>
Fri 13 Oct 2023 07:08:15 AM UTC, original submission:  

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

Dave <barx>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #55296:  hdtbl.examples.diff added by bjarniig (17KiB - text/x-patch)
file #55297:  hdtbl.tmac.diff added by bjarniig (8KiB - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by bjarniig (Posted a comment)
  • -email is unavailable- added by barx (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 2 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-11-02 bjarniig Attached File- Added hdtbl.examples.diff, #55296
        Attached File- Added hdtbl.tmac.diff, #55297

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code