Future/bison
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/bison.git synced 2026-03-17 08:13:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: stylistic improvements.

Browse Source 
* doc/bison.texinfo: Prefer "continue" to empty loop bodies.
	Add some @group/@end group to avoid poor page breaks.
This commit is contained in:
Akim Demaille
2012-02-19 18:17:19 +01:00
parent 24ec083743
commit d4fca42763
1 changed files with 107 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

125
doc/bison.texinfo
View File

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