Re: maint: doc: fix documentation of YYERROR

[Hans Aberg]

On 2 Apr 2012, at 20:16, Akim Demaille wrote:

> Le 2 avr. 2012 à 18:46, Hans Aberg a écrit :
> 
>> On 2 Apr 2012, at 16:57, Akim Demaille wrote:
>> 
>>> What do you think we should do about this?
>>> - leave as is
>>> - factor the @def macros to all use no `;'
>>> - try to keep the `;' in the core of the text,
>>> but have it appear without the `;' in the Index.
>> 
>> You might use the style of the Guile 2.x manual. In the index, only the name 
>> is given. In the definition, the syntax is given, with a text body 
>> explanation.
> 
> I'm not sure I see what you mean.
...
> Unless you can point me to an example in
> http://www.gnu.org/software/guile/manual/guile.html of where
> you think they address this.


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]

In the Procedure Index, only the name would mentioned
  http://www.gnu.org/software/guile/manual/guile.html#Procedure-Index
In the PDF, it looks like:
  scm_with_fluids............................. 405
  scm_with_guile.............................. 101
  scm_with_throw_handler...................... 294

>  For instance in the documentation
> of Java, Paolo wrote this:
> 
> @deffn {Statement} {return YYABORT;}
> Return immediately from the parser, indicating failure.
> @xref{Java Parser Interface}.
> @end deffn
> 
> @deffn {Statement} {return YYACCEPT;}
> Return immediately from the parser, indicating success.
> @xref{Java Parser Interface}.
> @end deffn
> 
> @deffn {Statement} {return YYERROR;}
> Start error recovery without printing an error message.
> @xref{Error Recovery}.
> @end deffn
> 
> It makes plenty of sense when reading the generated file, but
> the index is very wrong.  In guile, AFAICS, they just specify
> the arguments, which we also know how to do.

So here, what appears in the index, I think should only be the name, YYABORT, 
etc. If there i a definition, like in the Guile manual, it might look like:
  YYABORT;     [Macro]
  Macro to pretend that an unrecoverable syntax error has occurred...

Current entry
  YYABORT .................................. 81, 157
  YYABORT;...................................... 87
would be simplified to
  YYABORT .................................. 81, 87, 157 

If one so wants, if it it is not too complicated, the page numbers might have 
different styles, suggesting type of reference, like in the TeX book, say to 
mark out main definition and examples.

Hans