doc: style changes

[Akim Demaille]

I don't think there is much to debate here, all these
are real improvements to the final layout.


From 4c6238e818dd3d5b786821e8633920c119b591de Mon Sep 17 00:00:00 2001
From: Akim Demaille <address@hidden>
Date: Thu, 15 Mar 2012 15:36:20 +0100
Subject: [PATCH 4/6] doc: style changes.

* doc/bison.texinfo: Avoid line width issues with TeX.
Upgrade ancient messages.
Move some comments to better looking places.
Add more @group.
(Mfcalc Symbol Table): Reduce variable scopes.
Prefer size_t for sizes.
Prefer declarations with an initial value.
Fix a @group environment.
---
 doc/bison.texinfo |   86 +++++++++++++++++++++++++++++------------------------
 1 file changed, 47 insertions(+), 39 deletions(-)

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index d24d0c6..4b2aec0 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -1274,8 +1274,9 @@ will suffice.  Otherwise, we suggest
 
 @example
 address@hidden
-  #if __STDC_VERSION__ < 199901 && ! defined __GNUC__ && ! defined inline
-   #define inline
+  #if __STDC_VERSION__ < 199901 && ! defined __GNUC__ \
+      && ! defined inline
+  # define inline
   #endif
 address@hidden
 @end example
@@ -1464,11 +1465,11 @@ simple program, all the rest of the program can go here.
 @cindex simple examples
 @cindex examples, simple
 
-Now we show and explain three sample programs written using Bison: a
+Now we show and explain several sample programs written using Bison: a
 reverse polish notation calculator, an algebraic (infix) notation
-calculator, and a multi-function calculator.  All three have been tested
-under BSD Unix 4.3; each produces a usable, though limited, interactive
-desk-top calculator.
+calculator --- later extend to track ``locations'' ---
+and a multi-function calculator.  All
+produce usable, though limited, interactive desk-top calculators.
 
 These examples are simple, but Bison grammars for real programming
 languages are written the same way.  You can copy these examples into a
@@ -1570,24 +1571,28 @@ Here are the grammar rules for the reverse polish 
notation calculator.
 
 @comment file: rpcalc.y
 @example
address@hidden
 input:    /* empty */
         | input line
 ;
address@hidden group
 
address@hidden
 line:     '\n'
         | exp '\n'      @{ printf ("%.10g\n", $1); @}
 ;
address@hidden group
 
address@hidden
 exp:      NUM           @{ $$ = $1;           @}
         | exp exp '+'   @{ $$ = $1 + $2;      @}
         | exp exp '-'   @{ $$ = $1 - $2;      @}
         | exp exp '*'   @{ $$ = $1 * $2;      @}
         | exp exp '/'   @{ $$ = $1 / $2;      @}
-         /* Exponentiation */
-        | exp exp '^'   @{ $$ = pow ($1, $2); @}
-         /* Unary minus    */
-        | exp 'n'       @{ $$ = -$1;          @}
+        | exp exp '^'   @{ $$ = pow ($1, $2); @}  /* Exponentiation */
+        | exp 'n'       @{ $$ = -$1;          @}  /* Unary minus    */
 ;
address@hidden group
 %%
 @end example
 
@@ -1846,7 +1851,9 @@ here is the definition we will use:
 @example
 @group
 #include <stdio.h>
address@hidden group
 
address@hidden
 /* Called by yyparse on error.  */
 void
 yyerror (char const *s)
@@ -1952,6 +1959,7 @@ parentheses nested to arbitrary depth.  Here is the Bison 
code for
 @example
 /* Infix notation calculator.  */
 
address@hidden
 address@hidden
   #define YYSTYPE double
   #include <math.h>
@@ -1959,32 +1967,41 @@ parentheses nested to arbitrary depth.  Here is the 
Bison code for
   int yylex (void);
   void yyerror (char const *);
 address@hidden
address@hidden group
 
address@hidden
 /* Bison declarations.  */
 %token NUM
 %left '-' '+'
 %left '*' '/'
 %precedence NEG   /* negation--unary minus */
 %right '^'        /* exponentiation */
address@hidden group
 
 %% /* The grammar follows.  */
address@hidden
 input:    /* empty */
         | input line
 ;
address@hidden group
 
address@hidden
 line:     '\n'
         | exp '\n'  @{ printf ("\t%.10g\n", $1); @}
 ;
address@hidden group
 
-exp:      NUM                @{ $$ = $1;         @}
-        | exp '+' exp        @{ $$ = $1 + $3;    @}
-        | exp '-' exp        @{ $$ = $1 - $3;    @}
-        | exp '*' exp        @{ $$ = $1 * $3;    @}
-        | exp '/' exp        @{ $$ = $1 / $3;    @}
-        | '-' exp  %prec NEG @{ $$ = -$2;        @}
address@hidden
+exp:      NUM                @{ $$ = $1;           @}
+        | exp '+' exp        @{ $$ = $1 + $3;      @}
+        | exp '-' exp        @{ $$ = $1 - $3;      @}
+        | exp '*' exp        @{ $$ = $1 * $3;      @}
+        | exp '/' exp        @{ $$ = $1 / $3;      @}
+        | '-' exp  %prec NEG @{ $$ = -$2;          @}
         | exp '^' exp        @{ $$ = pow ($1, $3); @}
-        | '(' exp ')'        @{ $$ = $2;         @}
+        | '(' exp ')'        @{ $$ = $2;           @}
 ;
address@hidden group
 %%
 @end example
 
@@ -2521,10 +2538,9 @@ void
 init_table (void)
 @{
   int i;
-  symrec *ptr;
   for (i = 0; arith_fncts[i].fname != 0; i++)
     @{
-      ptr = putsym (arith_fncts[i].fname, FNCT);
+      symrec *ptr = putsym (arith_fncts[i].fname, FNCT);
       ptr->value.fnctptr = arith_fncts[i].fnct;
     @}
 @}
@@ -2550,8 +2566,7 @@ found, a pointer to that symbol is returned; otherwise 
zero is returned.
 symrec *
 putsym (char const *sym_name, int sym_type)
 @{
-  symrec *ptr;
-  ptr = (symrec *) malloc (sizeof (symrec));
+  symrec *ptr = (symrec *) malloc (sizeof (symrec));
   ptr->name = (char *) malloc (strlen (sym_name) + 1);
   strcpy (ptr->name,sym_name);
   ptr->type = sym_type;
@@ -2628,24 +2643,18 @@ yylex (void)
   /* Char starts an identifier => read the name.       */
   if (isalpha (c))
     @{
-      symrec *s;
+      /* Initially make the buffer long enough
+         for a 40-character symbol name.  */
+      static size_t length = 40;
       static char *symbuf = 0;
-      static int length = 0;
+      symrec *s;
       int i;
 @end group
-
address@hidden
-      /* Initially make the buffer long enough
-         for a 40-character symbol name.  */
-      if (length == 0)
-        @{
-          length = 40;
-          symbuf = (char *) malloc (length + 1);
-        @}
+      if (!symbuf)
+        symbuf = (char *) malloc (length + 1);
 
       i = 0;
       do
address@hidden group
 @group
         @{
           /* If buffer is full, make it bigger.        */
@@ -2689,8 +2698,6 @@ The error reporting function is unchanged, and the new 
version of
 
 @comment file: mfcalc.y
 @smallexample
-
address@hidden
 @group
 /* Called by yyparse on error.  */
 void
@@ -2700,6 +2707,7 @@ yyerror (char const *s)
 @}
 @end group
 
address@hidden
 int
 main (int argc, char const* argv[])
 @{
@@ -9358,9 +9366,9 @@ The types for semantic values and locations (if enabled).
 @end defcv
 
 @defcv {Type} {parser} {token}
-A structure that contains (only) the definition of the tokens as the
address@hidden enumeration.  To refer to the token @code{FOO}, the
-scanner should use @code{yy::parser::token::FOO}.  The scanner can use
+A structure that contains (only) the @code{yytokentype} enumeration, which
+defines the tokens.  To refer to the token @code{FOO},
+use @code{yy::parser::token::FOO}.  The scanner can use
 @samp{typedef yy::parser::token token;} to ``import'' the token enumeration
 (@pxref{Calc++ Scanner}).
 @end defcv
@@ -10044,7 +10052,7 @@ calcxx_driver::scan_begin ()
     yyin = stdin;
   else if (!(yyin = fopen (file.c_str (), "r")))
     @{
-      error (std::string ("cannot open ") + file + ": " + strerror(errno));
+      error ("cannot open " + file + ": " + strerror(errno));
       exit (EXIT_FAILURE);
     @}
 @}
-- 
1.7.9.2