Re: maint: doc: fix documentation of YYERROR

[Akim Demaille]

Le 2 avr. 2012 à 22:10, Hans Aberg a écrit :

> I was thinking about the API, like in
>  http://www.gnu.org/software/guile/manual/guile.html#Initialization
> Actually, I was looking at the PDF, where it looks like:
>  void * scm_with_guile (void *(*func)(void *), void *data)    [C Function]

There are special commands in Texinfo to support functions,
indeed, but here the case is different.

I may "cheat" with Texinfo and let it think that "return" is
the return type, and the ";" are the arguments:

address@hidden {Statement} {return YYERROR;}
address@hidden {Statement} {return} YYERROR ;
 Start error recovery (without printing an error message).
 @xref{Error Recovery}.
address@hidden deffn
address@hidden deftypefn

The result is not as nice looking:

But at least that fixes the index:

If I use @code{;} to avoid the italic, then the PDF
looks ok (except the spurious space between YYERROR
and the semicolon).

The HTML rendering is not as nice. but I can live
with it:

Finally, in info:

 -- Statement: return YYACCEPT;
     Return immediately from the parser, indicating success.  *Note
     Java Parser Interface::.

 -- Statement: return YYERROR ;
     Start error recovery (without printing an error message).  *Note
     Error Recovery::.



I think I'll go for that.  Of course, another possibility
would be something like:

> @deffn {Constant} YYERROR
> Value to return (@samp{return YYERROR;}) to start error recovery (without
> printing an error message).  @xref{Error Recovery}.
> @end deffn


(In C for instance, we have:

> @deffn {Macro} YYERROR;
> @findex YYERROR
> Cause an immediate syntax error.  This statement initiates error
> recovery just as if the parser itself had detected an error; however, it
> does not call @code{yyerror}, and does not print any message.  If you
> want to print an error message, call @code{yyerror} explicitly before
> the @samp{YYERROR;} statement.  @xref{Error Recovery}.
> @end deffn

with a double index entry).

Any preferred solution?