Re: Documentation bug

[Akim Demaille]

Hi Gaurav,

> Le 1 nov. 2020 à 03:18, Gaurav Singh via Bug reports for Bison, the GNU 
> parser generator <bug-bison@gnu.org> a écrit :
> 
> Hello Sir/Ma'am,This is Gaurav Singh, one of the many users of the Bison 
> tool. Thanks a lot for creating such a good tool, for it has opened a lot of 
> new doors to me.

Thanks a lot for your kind words!

> I've written this email in order to inform you about a bug located in the 
> documentation of this project( or more precisely an incorrect term ). In this 
> section, you have used the heading 'Explanation of expr' in order to explain 
> about a grouping named expr, whereas the grammar that you have refer to (i.e. 
> this one) does not contain any such grouping.

It took me a while to spot the mistake you are referring to, but found it: 
indeed, "Explanation of expr" is about exp, not expr.  Amusingly enough this 
mistake is there since the very beginning of the documentation, 27 years ago.

https://github.com/akimd/bison/commit/bfa74976051cc219ecd4d06de4059abd76fe80ed#diff-943ebdfaaedb73f9af3c79bf5ef2e5aacd6c1e407452517bf4864e454a2b5152R1319

line 1319

> But based on the term referred to in the content that lies within the above 
> mentioned section, instead of expr it should have been exp in the heading. 
> Although it's a minute mistake but still it may throw off a beginner like me 
> off the tracks for a moment.

You are a very careful reader!

> Hence, if you could take care of it, then the documentation would become much 
> more better for the future readers. With this, I would like to thank you 
> again for creating such an awesome tool.
> Hope to see the issue rectified soon.

I've fixed it as follows.

As a matter of fact, I hesitated a lot: should I keep 'expr', or 'exp'.  And 
then I realized the documentation is not very consistent on this.  It's not 
super critical as we are referring to different examples, and there's no reason 
they ought to all use the same names, yet it would probably be nice.

'expr' is probably clearer, and has the same length as 'term' and 'fact' and 
'stmt'.  But it's less used than 'exp' currently, in the doc (and in the tests).

$ git grep -ow expr doc/bison.texi | wc -l
117
$ git grep -ow exp doc/bison.texi | wc -l
438
$ git grep -ow exp: doc/bison.texi | wc -l
67
$ git grep -ow expr: doc/bison.texi | wc -l
12


But let's address this another time.  For the time being, let's just be locally 
consistent.

Cheers!

commit bd6b046ce7ffd6cc5f7c1c77e425c97df66cd329
Author: Akim Demaille <akim.demaille@gmail.com>
Date:   Sun Nov 1 09:00:50 2020 +0100

    doc: fix incorrect section title
    
    Reported by Gaurav Singh <gaurav.singh199709@yahoo.com>.
    https://lists.gnu.org/r/bug-bison/2020-11/msg00000.html
    
    * doc/bison.texi (Rpcalc Expr): Rename as...
    (Rpcalc Exp): this, as the nterm is named 'exp'.

diff --git a/doc/bison.texi b/doc/bison.texi
index 277aba29..416a8ec6 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -303,7 +303,7 @@ Grammar Rules for @code{rpcalc}
 
 * Rpcalc Input::            Explanation of the @code{input} nonterminal
 * Rpcalc Line::             Explanation of the @code{line} nonterminal
-* Rpcalc Expr::             Explanation of the @code{expr} nonterminal
+* Rpcalc Exp::              Explanation of the @code{exp} nonterminal
 
 Location Tracking Calculator: @code{ltcalc}
 
@@ -1788,7 +1788,7 @@ rule are referred to as @code{$1}, @code{$2}, and so on.
 @menu
 * Rpcalc Input::            Explanation of the @code{input} nonterminal
 * Rpcalc Line::             Explanation of the @code{line} nonterminal
-* Rpcalc Expr::             Explanation of the @code{expr} nonterminal
+* Rpcalc Exp::              Explanation of the @code{exp} nonterminal
 @end menu
 
 @node Rpcalc Input
@@ -1853,8 +1853,8 @@ uninitialized (its value will be unpredictable).  This 
would be a bug if
 that value were ever used, but we don't use it: once rpcalc has printed the
 value of the user's input line, that value is no longer needed.
 
-@node Rpcalc Expr
-@subsubsection Explanation of @code{expr}
+@node Rpcalc Exp
+@subsubsection Explanation of @code{exp}
 
 The @code{exp} grouping has several rules, one for each kind of expression.
 The first rule handles the simplest expressions: those that are just