FYI: doc: stylistic improvements

[Akim Demaille]

From d4fca427636f15eb952974ff04e4fb046428440a Mon Sep 17 00:00:00 2001
From: Akim Demaille <address@hidden>
Date: Sun, 19 Feb 2012 18:17:19 +0100
Subject: [PATCH 7/7] doc: stylistic improvements.

        * doc/bison.texinfo: Prefer "continue" to empty loop bodies.
        Add some @group/@end group to avoid poor page breaks.
---
 doc/bison.texinfo |  125 +++++++++++++++++++++++++++++++++++++++++++++--------
 1 files changed, 107 insertions(+), 18 deletions(-)

diff --git a/doc/bison.texinfo b/doc/bison.texinfo
index 0f5dbbb..ea7f6c8 100644
--- a/doc/bison.texinfo
+++ b/doc/bison.texinfo
@@ -1791,7 +1791,7 @@ yylex (void)
 
   /* Skip white space.  */
   while ((c = getchar ()) == ' ' || c == '\t')
-    ;
+    continue;
 @end group
 @group
   /* Process numbers.  */
@@ -2240,6 +2240,7 @@ yylex (void)
   if (c == EOF)
     return 0;
 
address@hidden
   /* Return a single char, and update location.  */
   if (c == '\n')
     @{
@@ -2250,6 +2251,7 @@ yylex (void)
     ++yylloc.last_column;
   return c;
 @}
address@hidden group
 @end example
 
 Basically, the lexical analyzer performs the same processing as before:
@@ -2306,11 +2308,15 @@ to create named variables, store values in them, and 
use them later.
 Here is a sample session with the multi-function calculator:
 
 @example
address@hidden
 $ @kbd{mfcalc}
 @kbd{pi = 3.141592653589}
 @result{} 3.1415926536
address@hidden group
address@hidden
 @kbd{sin(pi)}
 @result{} 0.0000000000
address@hidden group
 @kbd{alpha = beta1 = 2.3}
 @result{} 2.3000000000
 @kbd{alpha}
@@ -2540,6 +2546,7 @@ found, a pointer to that symbol is returned; otherwise 
zero is returned.
 #include <stdlib.h> /* malloc. */
 #include <string.h> /* strlen. */
 
address@hidden
 symrec *
 putsym (char const *sym_name, int sym_type)
 @{
@@ -2553,7 +2560,9 @@ putsym (char const *sym_name, int sym_type)
   sym_table = ptr;
   return ptr;
 @}
address@hidden group
 
address@hidden
 symrec *
 getsym (char const *sym_name)
 @{
@@ -2564,6 +2573,7 @@ getsym (char const *sym_name)
       return ptr;
   return 0;
 @}
address@hidden group
 @end smallexample
 
 @node Mfcalc Lexer
@@ -2597,7 +2607,8 @@ yylex (void)
   int c;
 
   /* Ignore white space, get first nonwhite character.  */
-  while ((c = getchar ()) == ' ' || c == '\t');
+  while ((c = getchar ()) == ' ' || c == '\t')
+    continue;
 
   if (c == EOF)
     return 0;
@@ -2949,19 +2960,26 @@ definitions.
 Thus, they belong in one or more @code{%code requires}:
 
 @smallexample
address@hidden
 %code top @{
   #define _GNU_SOURCE
   #include <stdio.h>
 @}
address@hidden group
 
address@hidden
 %code requires @{
   #include "ptypes.h"
 @}
address@hidden group
address@hidden
 %union @{
   long int n;
   tree t;  /* @address@hidden is defined in @file{ptypes.h}.} */
 @}
address@hidden group
 
address@hidden
 %code requires @{
   #define YYLTYPE YYLTYPE
   typedef struct YYLTYPE
@@ -2973,12 +2991,15 @@ Thus, they belong in one or more @code{%code requires}:
     char *filename;
   @} YYLTYPE;
 @}
address@hidden group
 
address@hidden
 %code @{
   static void print_token_value (FILE *, int, YYSTYPE);
   #define YYPRINT(F, N, L) print_token_value (F, N, L)
   static void trace_token (enum yytokentype token, YYLTYPE loc);
 @}
address@hidden group
 
 @dots{}
 @end smallexample
@@ -3016,19 +3037,26 @@ sufficient.  Instead, move its prototype from the 
unqualified
 @code{%code} to a @code{%code provides}:
 
 @smallexample
address@hidden
 %code top @{
   #define _GNU_SOURCE
   #include <stdio.h>
 @}
address@hidden group
 
address@hidden
 %code requires @{
   #include "ptypes.h"
 @}
address@hidden group
address@hidden
 %union @{
   long int n;
   tree t;  /* @address@hidden is defined in @file{ptypes.h}.} */
 @}
address@hidden group
 
address@hidden
 %code requires @{
   #define YYLTYPE YYLTYPE
   typedef struct YYLTYPE
@@ -3040,15 +3068,20 @@ sufficient.  Instead, move its prototype from the 
unqualified
     char *filename;
   @} YYLTYPE;
 @}
address@hidden group
 
address@hidden
 %code provides @{
   void trace_token (enum yytokentype token, YYLTYPE loc);
 @}
address@hidden group
 
address@hidden
 %code @{
   static void print_token_value (FILE *, int, YYSTYPE);
   #define YYPRINT(F, N, L) print_token_value (F, N, L)
 @}
address@hidden group
 
 @dots{}
 @end smallexample
@@ -3078,15 +3111,19 @@ For example, you may organize semantic-type-related 
directives by semantic
 type:
 
 @smallexample
address@hidden
 %code requires @{ #include "type1.h" @}
 %union @{ type1 field1; @}
 %destructor @{ type1_free ($$); @} <field1>
 %printer @{ type1_print ($$); @} <field1>
address@hidden group
 
address@hidden
 %code requires @{ #include "type2.h" @}
 %union @{ type2 field2; @}
 %destructor @{ type2_free ($$); @} <field2>
 %printer @{ type2_print ($$); @} <field2>
address@hidden group
 @end smallexample
 
 @noindent
@@ -7023,18 +7060,22 @@ For example, here is an erroneous attempt to define a 
sequence
 of zero or more @code{word} groupings.
 
 @example
address@hidden
 sequence: /* empty */
                 @{ printf ("empty sequence\n"); @}
         | maybeword
         | sequence word
                 @{ printf ("added word %s\n", $2); @}
         ;
address@hidden group
 
address@hidden
 maybeword: /* empty */
                 @{ printf ("empty maybeword\n"); @}
         | word
                 @{ printf ("single word %s\n", $1); @}
         ;
address@hidden group
 @end example
 
 @noindent
@@ -7111,18 +7152,24 @@ Second, to prevent either a @code{words} or a 
@code{redirects}
 from being empty:
 
 @example
address@hidden
 sequence: /* empty */
         | sequence words
         | sequence redirects
         ;
address@hidden group
 
address@hidden
 words:    word
         | words word
         ;
address@hidden group
 
address@hidden
 redirects:redirect
         | redirects redirect
         ;
address@hidden group
 @end example
 
 @node Mysterious Conflicts
@@ -7964,11 +8011,13 @@ earlier:
 @example
 typedef int foo, bar;
 int baz (void)
address@hidden
 @{
   static bar (bar);      /* @r{redeclare @code{bar} as static variable} */
   extern foo foo (foo);  /* @r{redeclare @code{foo} as function} */
   return foo (bar);
 @}
address@hidden group
 @end example
 
 Unfortunately, the name being declared is separated from the declaration
@@ -7981,17 +8030,21 @@ declaration in which that can't be done.  Here is a 
part of the
 duplication, with actions omitted for brevity:
 
 @example
address@hidden
 initdcl:
           declarator maybeasm '='
           init
         | declarator maybeasm
         ;
address@hidden group
 
address@hidden
 notype_initdcl:
           notype_declarator maybeasm '='
           init
         | notype_declarator maybeasm
         ;
address@hidden group
 @end example
 
 @noindent
@@ -8246,6 +8299,7 @@ Grammar
 and reports the uses of the symbols:
 
 @example
address@hidden
 Terminals, with rules where they appear
 
 $end (0) 0
@@ -8255,13 +8309,16 @@ $end (0) 0
 '/' (47) 4
 error (256)
 NUM (258) 5
address@hidden group
 
address@hidden
 Nonterminals, with rules where they appear
 
 $accept (8)
     on left: 0
 exp (9)
     on left: 1 2 3 4 5, on right: 0 1 2 3 4
address@hidden group
 @end example
 
 @noindent
@@ -8478,6 +8535,7 @@ state 8
 The remaining states are similar:
 
 @example
address@hidden
 state 9
 
     exp  ->  exp . '+' exp   (rule 1)
@@ -8491,7 +8549,9 @@ state 9
 
     '/'         [reduce using rule 2 (exp)]
     $default    reduce using rule 2 (exp)
address@hidden group
 
address@hidden
 state 10
 
     exp  ->  exp . '+' exp   (rule 1)
@@ -8504,7 +8564,9 @@ state 10
 
     '/'         [reduce using rule 3 (exp)]
     $default    reduce using rule 3 (exp)
address@hidden group
 
address@hidden
 state 11
 
     exp  ->  exp . '+' exp   (rule 1)
@@ -8523,6 +8585,7 @@ state 11
     '*'         [reduce using rule 4 (exp)]
     '/'         [reduce using rule 4 (exp)]
     $default    reduce using rule 4 (exp)
address@hidden group
 @end example
 
 @noindent
@@ -9921,15 +9984,19 @@ preceding tokens.  Comments would be treated equally.
 
 @comment file: calc++-scanner.ll
 @example
address@hidden
 address@hidden
   // Code run each time a pattern is matched.
   # define YY_USER_ACTION  loc.columns (yyleng);
 address@hidden
address@hidden group
 %%
address@hidden
 address@hidden
   // Code run each time yylex is called.
   loc.step ();
 address@hidden
address@hidden group
 @address@hidden   loc.step ();
 [\n]+      loc.lines (yyleng); loc.step ();
 @end example
@@ -9947,6 +10014,7 @@ The rules are simple.  The driver is used to report 
errors.
 ")"      return yy::calcxx_parser::make_RPAREN(loc);
 ":="     return yy::calcxx_parser::make_ASSIGN(loc);
 
address@hidden
 @address@hidden      @{
   errno = 0;
   long n = strtol (yytext, NULL, 10);
@@ -9954,6 +10022,7 @@ The rules are simple.  The driver is used to report 
errors.
     driver.error (loc, "integer is out of range");
   return yy::calcxx_parser::make_NUMBER(n, loc);
 @}
address@hidden group
 @address@hidden       return yy::calcxx_parser::make_IDENTIFIER(yytext, loc);
 .          driver.error (loc, "invalid character");
 <<EOF>>    return yy::calcxx_parser::make_END(loc);
@@ -9966,6 +10035,7 @@ on the scanner's data, it is simpler to implement them 
in this file.
 
 @comment file: calc++-scanner.ll
 @example
address@hidden
 void
 calcxx_driver::scan_begin ()
 @{
@@ -9978,12 +10048,15 @@ calcxx_driver::scan_begin ()
       exit (EXIT_FAILURE);
     @}
 @}
address@hidden group
 
address@hidden
 void
 calcxx_driver::scan_end ()
 @{
   fclose (yyin);
 @}
address@hidden group
 @end example
 
 @node Calc++ Top Level
@@ -9996,6 +10069,7 @@ The top level file, @file{calc++.cc}, poses no problem.
 #include <iostream>
 #include "calc++-driver.hh"
 
address@hidden
 int
 main (int argc, char *argv[])
 @{
@@ -10012,6 +10086,7 @@ main (int argc, char *argv[])
       res = 1;
   return res;
 @}
address@hidden group
 @end example
 
 @node Java Parsers
@@ -10696,41 +10771,49 @@ speed, they might not notice a change of input file.  
As a
 demonstration, consider the following source file,
 @file{first-line.l}:
 
address@hidden
-%{
address@hidden
address@hidden
address@hidden
 #include <stdio.h>
 #include <stdlib.h>
-%}
address@hidden
address@hidden group
 %%
 .*\n    ECHO; return 1;
 %%
address@hidden
 int
 yyparse (char const *file)
-{
address@hidden
   yyin = fopen (file, "r");
   if (!yyin)
-  {
-    perror ("fopen");
-    exit (EXIT_FAILURE);
-  }
+    @{
+      perror ("fopen");
+      exit (EXIT_FAILURE);
+    @}
address@hidden group
address@hidden
   /* One token only.  */
   yylex ();
   if (fclose (yyin) != 0)
-  {
-    perror ("fclose");
-    exit (EXIT_FAILURE);
-  }
+    @{
+      perror ("fclose");
+      exit (EXIT_FAILURE);
+    @}
   return 0;
-}
address@hidden
address@hidden group
 
address@hidden
 int
 main (void)
-{
address@hidden
   yyparse ("input");
   yyparse ("input");
   return 0;
-}
address@hidden verbatim
address@hidden
address@hidden group
address@hidden example
 
 @noindent
 If the file @file{input} contains
@@ -10780,14 +10863,19 @@ Bison lists, but is only concerned with a 
misunderstanding of the role
 of the scanner.  Consider the following Lex code:
 
 @verbatim
address@hidden
 %{
 #include <stdio.h>
 char *yylval = NULL;
 %}
address@hidden group
address@hidden
 %%
 .*    yylval = yytext; return 1;
 \n    /* IGNORE */
 %%
address@hidden group
address@hidden
 int
 main ()
 {
@@ -10797,6 +10885,7 @@ main ()
   printf ("\"%s\", \"%s\"\n", fst, snd);
   return 0;
 }
address@hidden group
 @end verbatim
 
 If you compile and run this code, you get:
-- 
1.7.9