bugGNU roff - Bugs: bug #53043, [man] check the number of...

 
 

bug #53043: [man] check the number of arguments for some macros

Submitter:  Bjarni Ingi Gislason <bjarniig>
Submitted:  Fri 02 Feb 2018 12:40:12 AM UTC
   
 
Category:  Macro man Severity:  1 - Wish
Item Group:  Feature change Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Sun 05 Feb 2023 06:27:00 AM UTC, comment #9: 

Dropping patch annotation, as the patch was not accepted.  The desired logic was implemented differently.

G. Branden Robinson <gbranden>
Group administrator
Sat 05 Mar 2022 10:40:57 PM UTC, comment #8: 

The CHECKSTYLE register remains undocumented.  See bug #62042 for its possible future.


commit 25d2a812faf52e4d952769920ccfbe5e61cb1b43
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Nov 14 13:25:26 2020 +1100

    tmac/an-old.tmac: Add style checks.

    Add register, CHECKSTYLE, to capture user preference for emission of
    style-related diagnostics.  Defaults off.

    Not documented yet because I expect there to be some discussion on the
    mailing list over whether it should be and/or what the register should
    be called.

    Whatever emerges from that discussion can and should be parallelized in
    support and form with diagnostics in our mdoc(7) implementation, which
    has some style-oriented diagnostics that issue at the same level as more
    serious problems.

    * tmac/an-old.tmac: Initialize CHECKSTYLE to false if not already set.
      (an-style-warn): New macro emits diagnostic of type "style" when
      called if CHECKSTYLE register is true.
      (TH, RI, IR, IB, BI, RB, BR): Call an-style-warn if fewer than two
      arguments are seen.


G. Branden Robinson <gbranden>
Group administrator
Mon 23 Nov 2020 11:44:27 AM UTC, comment #7: 

Closing as fixed per submitter.

G. Branden Robinson <gbranden>
Group administrator
Sun 22 Nov 2020 07:04:54 PM UTC, comment #6: 

  The idea was implemented in

commit 25d2a812faf52e4d952769920ccfbe5e61cb1b43
(tmac/an-old.tmac: Add style checks).

  This ticket can thus be closed.

Bjarni Ingi Gislason <bjarniig>
Fri 16 Feb 2018 11:52:21 PM UTC, comment #5: 

I'm happy to improve groff(7) to be a better model of man(7) macro usage once I'm confident I won't break the build again. :-O

(It's actually unlikely in that particular case but I still need to solidify my script for checking the 4 different build scenarios.)

G. Branden Robinson <gbranden>
Group administrator
Fri 16 Feb 2018 11:06:03 PM UTC, comment #4: 

Branden: 
What you say is fair enough, but it doesn't apply to the question at hand.  Using .BR with a single argument is valid syntax and has well-defined and obvious semantics.  As a matter of fact, an example of a document making valid use of the feature is the groff(7) manual page itself.

No program should warn about usage that is valid and unambiguous.  Issuing invalid warnings is not a good idea.  It is not the job of the end user to pick out valid warnings from among invalid ones.

Even for warnings, sometimes, less is more.  This is such a case.  If you issue too many warnings, and in particular bogus ones, people will simply switch them off completely.  Providing the possibility to fine-tune warnings to end-users is nice in theory, but i have almost never met any user who actually does such fine-tuning in practice, it's simply too much work for end-users who usually want to focus on other things, not on tuning of warning levels.  So program maintainers better get warnings right in the first place.  That's in the best interest of end-users.

Ingo Schwarze <schwarze>
Group Member
Mon 05 Feb 2018 06:03:36 AM UTC, comment #3: 

I'm going to +1 this problem report.

groff is a low-level tool; it's for people who want a document in the GNU roff language compiled into some output format.

Macro packages should, IMO, do argument checking and issue warnings.

Viewers of post-processed documents, of which man(1) is one, are the right level to decide if warnings and problems encountered during processing should be reported or thrown away.

G. Branden Robinson <gbranden>
Group administrator
Sun 04 Feb 2018 08:34:27 PM UTC, comment #2: 

  To me, these conclusions are based on speculations and imagination.

  Decisions are made here (and other places) for others, without knowing
what they would like more and why.

  Suppressing warnings is the duty (and responsibility) of the user of
a software not the writer's.

  The software writer should provide (unconditionally) all diagnostics
that can improve the quality of the input and output.

  One of the fundamental obligations of programs is to test the input
for validity; or proof me wrong.

  Every user can filter warnings from the output, but can't add
nonexisting ones without changing the issuing program.

"man-db" even by default removes all warnings, making maintainers
unaware of them.

  So actually it deceives them.

  Any software writer with a professional attitude tells users if
something in the input is not correct (not optimal), on the condition,
that he knows about it and knows how to report it to the user.

  (Or how is professional attitude defined?)
  (What about ethical issues?)

  Why not report ".BR XY"?  Maybe ".BR X Y" is meant!

  Is ".BR XY" the correct use of the macro?

  Does ".BI XY" mean "BoldItalic"?  Has it an obvious semantics (meaning)?
  If yes, what is it to everybody?

  Example in "man.1":

.BR dvips.

  So, what does more harm nowadays

1) issuing more warnings by default or unconditionally?  (until fixed!)

2) avoiding warnings by default or altogether?  (Keep wrongdoings
forever(?); engage in time theft!)

  Nowadays maintainers are stealing time from others, as they do not
themselves fix things, that are or could be reported by using
(supporting) the full (proposed) potential (capability) of the software
they use.

###

"This second radical novelty shares the usual fate of all
radical novelties: it is denied, because its truth would be
too discomforting.
I have no idea what this specific denial and disbelief costs
the United States, but a million dollars a day seems a modest
guess."

P. xxix in:

On the Cruelty of Really Teaching Computing Science

Edsger W. Dykstra (Dijkstra)

SIGCSE Bulletin 1989, 21(1), pp. xxv-xxxix.
Also "www.cs.utexas.edu/users/EWD/"
#
  "Since breaking out of bad habits, rather than acquiring new
ones, is the toughest part of learning we must expect from that
system permanent mental damage for most students exposed to
it."

P. xxxvii in:

On the Cruelty of Really Teaching Computing Science

Edsger W. Dykstra (Dijkstra)

SIGCSE Bulletin 1989, 21(1), pp. xxv-xxxix.
Also "www.cs.utexas.edu/users/EWD/"
#
  "The problems of the real world are primarily those you are
left with when you refuse to apply their effective solutions."

P. xxxviii in:

On the Cruelty of Really Teaching Computing Science

Edsger W. Dykstra (Dijkstra)

SIGCSE Bulletin 1989, 21(1), pp. xxv-xxxix.
Also "www.cs.utexas.edu/users/EWD/"

Bjarni Ingi Gislason <bjarniig>
Sat 03 Feb 2018 08:39:01 PM UTC, comment #1: 

I think this should be rejected.  While in some contexts, using font alternating macros with a single argument may not be very useful and using single font macros may be preferable, font alternating macros with a single argument are not syntactically invalid and have obvious semantics, so warning about them feels like additional code for almost no benefit.

Ingo Schwarze <schwarze>
Group Member
Fri 02 Feb 2018 12:40:12 AM UTC, original submission:  


From a72d0d93d9f7010b2f22c0e09a77fbf81c444fbc Mon Sep 17 00:00:00 2001
From: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
Date: Fri, 2 Feb 2018 00:30:25 +0000
Subject: [PATCH] an-old.tmac: Check the number of arguments to macros for alternating font
 changes

  They are sometimes used with only one argument, or the single one is
meant to be two.

Signed-off-by: Bjarni Ingi Gislason <bjarniig@rhi.hi.is>
---
 tmac/an-old.tmac | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/tmac/an-old.tmac b/tmac/an-old.tmac
index 9ae3b9f9..dd8ca295 100644
--- a/tmac/an-old.tmac
+++ b/tmac/an-old.tmac
@@ -511,7 +511,15 @@
 .
 .ds an-empty \" this is referenced to avoid looping on, e.g., .RB ( \\ )
 .
+.de1 an-inputcheck
+.  if \\$2<2 \{\
+.    tm \\n(.F:\\n(.c (macro \\$1): only \\$2 argument, but more are expected
+.  \}
+..
+.
 .de1 RI
+.  an-inputcheck \\$0 \\n[.$]
+.
 .  if \\n[.$] \{\
 .    ds an-result \&\f[R]\\$1\"
 .    shift
@@ -526,6 +534,8 @@
 ..
 .
 .de1 IR
+.  an-inputcheck \\$0 \\n[.$]
+.
 .  if \\n[.$] \{\
 .    ds an-result \&\f[I]\,\\$1\f[R]\"
 .    shift
@@ -540,6 +550,8 @@
 ..
 .
 .de1 IB
+.  an-inputcheck \\$0 \\n[.$]
+.
 .  if \\n[.$] \{\
 .    ds an-result \&\f[I]\,\\$1\"
 .    shift
@@ -554,6 +566,8 @@
 ..
 .
 .de1 BI
+.  an-inputcheck \\$0 \\n[.$]
+.
 .  if \\n[.$] \{\
 .    ds an-result \&\f[B]\\$1\"
 .    shift
@@ -568,6 +582,8 @@
 ..
 .
 .de1 RB
+.  an-inputcheck \\$0 \\n[.$]
+.
 .  ds an-result \&\"
 .  while (\\n[.$] >= 2) \{\
 .    as an-result \f[R]\\$1\f[B]\\$2\\*[an-empty]\"
@@ -579,6 +595,8 @@
 ..
 .
 .de1 BR
+.  an-inputcheck \\$0 \\n[.$]
+.
 .  ds an-result \&\"
 .  while (\\n[.$] >= 2) \{\
 .    as an-result \f[B]\\$1\f[R]\\$2\\*[an-empty]\"
--
2.15.1


Bjarni Ingi Gislason <bjarniig>

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by bgarrigues (Updated the item)
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by bjarniig (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 8 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-02-05 gbranden Summary[PATCH] an-old.tmac: Check the number of arguments for some macros [man] check the number of arguments for some macros
    2020-11-23 gbranden Item GroupWarning/Suspicious behaviour Feature change
        StatusNone Fixed
        Assigned toNone gbranden
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2018-11-26 bgarrigues Item GroupFeature change Warning/Suspicious behaviour
    2018-02-03 schwarze Severity3 - Normal 1 - Wish

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code