bugGNU troff - Bugs: bug #53043, [PATCH] an-old.tmac: Check the...

 
 

bug #53043: [PATCH] an-old.tmac: Check the number of arguments for some macros

Submitted by:  Bjarni Ingi Gislason <bjarniig>
Submitted on:  Fri 02 Feb 2018 12:40:12 AM UTC  
 
Category:  Macro - man Severity:  1 - Wish
Item Group:  Warning/Suspicious behaviour Status:  None
Privacy:  Public Assigned to:  None
Open/Closed:  Open Planned Release:  None

Add a New Comment (Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

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>
Project 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>
Project 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>
Project 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>
Project 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)
  •  

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

     

     

    Follow 2 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2018-11-26 bgarrigues Item GroupNew feature => Warning/Suspicious behaviour
    2018-02-03 schwarze Severity3 - Normal => 1 - Wish

    Back to the top


    Powered by Savane 3.5