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

[G. Branden Robinson]

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

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


commit 25d2a812faf52e4d952769920ccfbe5e61cb1b43
Author: G. Branden Robinson 
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.


___

Reply to this item at:

  

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

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

[G. Branden Robinson]

Update of bug #53043 (project groff):

  Item Group: Warning/Suspicious behaviour => New feature 
  
  Status:None => Fixed  
 Assigned to:None => gbranden   
 Open/Closed:Open => Closed 
 Planned Release:None => 1.23.0 

___

Follow-up Comment #7:

Closing as fixed per submitter.

___

Reply to this item at:

  

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

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

[Bjarni Ingi Gislason]

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

  The idea was implemented in

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

  This ticket can thus be closed.


___

Reply to this item at:

  

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

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

[Bertrand Garrigues]

Update of bug #53043 (project groff):

  Item Group: New feature => Warning/Suspicious
behaviour


___

Reply to this item at:

  

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


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[G. Branden Robinson]

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

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

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[Ingo Schwarze]

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

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.


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[G. Branden Robinson]

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

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.

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[Bjarni Ingi Gislason]

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

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


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[Ingo Schwarze]

Update of bug #53043 (project groff):

Severity:  3 - Normal => 1 - Wish   

___

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

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

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

[Bjarni Ingi Gislason]

URL:
  

 Summary: [PATCH] an-old.tmac: Check the number of arguments
for some macros
 Project: GNU troff
Submitted by: bjarniig
Submitted on: Fri 02 Feb 2018 12:40:12 AM UTC
Category: Macro - man
Severity: 3 - Normal
  Item Group: Wishlist
  Status: None
 Privacy: Public
 Assigned to: None
 Open/Closed: Open
 Discussion Lock: Any
 Planned Release: None

___

Details:


>From a72d0d93d9f7010b2f22c0e09a77fbf81c444fbc Mon Sep 17 00:00:00 2001
From: Bjarni Ingi Gislason 
Date: Fri, 2 Feb 2018 00:30:25 +
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 
---
 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






___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff