Re: RFC: doc: use only @example, not @smallexample

[Akim Demaille]

Le 15 mars 2012 à 18:59, Paul Eggert a écrit :

> On 03/15/2012 09:20 AM, Akim Demaille wrote:
> 
>> I don't see why we have both @example and @smallexample.
> 
> The "@smallexample"s are there for when
> the Bison manual is printed in @smallbook format,
> which the GNU Press does (see
> <http://shop.fsf.org/product/bison-manual/>).

Ah!  Ok, thanks for the pointer!  I only saw that we
had examples in two different sizes in the regular PDF.

> Another possibility would be to use @smallexample
> conditionally, only when @smallbook is in effect.
> We'd need to check that the examples fit in ordinary
> large printed format if we do that.
> 
> Another possibility, and perhaps the best one,
> is to redo the examples so their lines are not so
> long that they cause problems with smallbook format.
> Then we could just use @example everywhere.
> Those long lines make the examples hard to read
> anyway....

Well, actually none is larger that usual coding style.
When an @example looks ok in Texinfo source, it basically
looks ok in PDF (more or less).

But I do agree with your point.

Actually, I'm not fond of the style used for the grammars
in the documentation:

input:    /* empty */
        | input line
;

line:     '\n'
        | exp '\n'      @{ printf ("%.10g\n", $1); @}
;

exp:      NUM           @{ $$ = $1;           @}
        | exp exp '+'   @{ $$ = $1 + $2;      @}
        | exp exp '-'   @{ $$ = $1 - $2;      @}
        | exp exp '*'   @{ $$ = $1 * $2;      @}
        | exp exp '/'   @{ $$ = $1 / $2;      @}
        | exp exp '^'   @{ $$ = pow ($1, $2); @}  /* Exponentiation */
        | exp 'n'       @{ $$ = -$1;          @}  /* Unary minus    */
;

It does not work too well when the symbols have longer
names, and I don't think this "Makefile" style really
provides better readability (besides, depending on
the example, the semicolon is sometimes in the first col,
sometimes aligned with the colon and pipes).

I prefer the following style (which does help to stay
within a more reasonable width).  Would people be ok
if I change the documentation style as follows? In my
experience it scales much better to real world grammars.

input:
  /* empty */
| input line
;

line:
  '\n'
| exp '\n'  @{ printf ("%.10g\n", $1); @}
;

exp:
  NUM           @{ $$ = $1; @}
| exp exp '+'   @{ $$ = $1 + $2; @}
| exp exp '-'   @{ $$ = $1 - $2; @}
| exp exp '*'   @{ $$ = $1 * $2; @}
| exp exp '/'   @{ $$ = $1 / $2; @}
| exp exp '^'   @{ $$ = pow ($1, $2); @}  /* Exponentiation */
| exp 'n'       @{ $$ = -$1; @}           /* Unary minus    */
;

(Note that opening braces are aligned in a group of
rules, but not between groups).