[help-texinfo] Formatting parser symbols and rules

[lfinsto1]

Hello Karl et al,

I've been working on the second Texinfo manual for the IWF Metadata
Harvester (`Scantest') (http://www.nongnu.org/iwf-mdh/iwfmdh.html).  It
documents, among other things, the symbols and rules belonging to a parser
written using GNU Bison.  Texinfo doesn't support this directly, and my
solutions are somewhat more complicated than I'd like.  I doubt that
anyone has time to work on modifying Texinfo to support this, but I
thought I'd describe the problems briefly, so you could add this to a
"TODO" file, if you thought it was worthwhile.

The manual, in various formats, is available here:
http://www.nongnu.org/iwf-mdh/iwfmdh.html#Documentation

I've been working on the TeX and HTML versions;
I haven't looked at the Info version yet.

The sources are here:  http://ftp.gwdg.de/pub/gnu2/iwfmdh/scantest/
or here:
http://cvs.savannah.nongnu.org/viewcvs/iwf-mdh/scantest/DOC/TEXINFO/?root=iwf-mdh

The main file, which contains the macros and includes the other files, is
`scantest.texi'.  The file containing the Texinfo code for the parser is
`parser.texi'.  They are in the directory `Scantest-1.0/DOC/TEXINFO/'.

1.  It would be nice to have a set of address@hidden' commands for parser
symbols, or even one set for tokens and one for non-terminals.
I've used address@hidden' for the tokens and non-terminal symbols.
I like the formatting produced by the address@hidden' commands, and I thought
it would be too much work to try to simulate it using address@hidden',
address@hidden', and address@hidden'.  However, using address@hidden' does have 
the
effect that the symbols are put into the Variable Index.  I'm not sure
this is a good idea or not.  I've added two new indices, one for
tokens (address@hidden') and one for non-teminals (address@hidden') and add the
entries by hand, so the entries in the Variable Index are redundant.

2.  I've been formatting the parser rules so that they look like the
grammar rules in _The METAFONTbook_.  This is the macro I use:

@macro angles {arg}
@iftex
@tex
\\begingroup
\\catcode`\\_=13
\\let_=\\space
\\rm
$\\langle$\arg\$\\rangle$
\\endgroup
@end tex
@end iftex
@ifhtml
@html
<
@end html
\arg\
@html
>
@end html
@end ifhtml
@end macro

This works fine, except that it doesn't work for the first item in the
entries for the Parser Rule Index (address@hidden'), which disappeared in
the HTML output if I tried to use it.  It worked fine in the TeX version.
My solution (or kludge) is to duplicate the index entries, once
for TeX, once for the other formats:

@iftex
@prindex @angles{statement_list} @lra{} @t{EMPTY}
@prindex @angles{statement_list} @lra{} @angles{statement_list}
@angles{statement}
@end iftex
@c
@c **** (4) Index entries for HTML/INFO
@c
@ifnottex
@prindex statement_list @lra{} @t{EMPTY}
@prindex statement_list @lra{} statement_list statement
@end ifnottex
@c
@c **** (4) Text
@c
@noindent
@angles{statement list} @lra{} @address@hidden
@ruleor{} @angles{statement list} @address@hidden

In the HTML output, this has the effect that non-terminals are
surrounded by angle brackets in the running text and the underline
character is replaced by a space, whereas there are no angle brackets
in the index and the underline characters are unchanged.  This is
clearly not ideal, but I'm not sure what the best solution would be.
I'm also undecided about whether an index of parser rules is really
needed at all.

The next two points aren't connected with the parser.

3.    I use address@hidden' and address@hidden' for class member variables and
functions.   It's been awhile since I looked at the "object-oriented"
address@hidden' commands.  I believe I don't use them because some of them
cause "object-oriented" terminology to be printed to the manual, which
I don't want.  I find it useful to have the names of the variables and
functions duplicated in the appropriate index using the class
qualifier, e.g.,

@vindex Id_Type::name
@vindex Id_Type::value
@c
@deftypevr {Public variables} string name
@deftypevrx {}                void* value
@end deftypevr


@findex @t{Id_Type::Id_Type}
@c
@deftypefn {Constructor} void Id_Type (@code{void})
@end deftypefn

It would be nice if this could be automated, somehow.

4.  Some of the lines in my input files get quite long.  There is no
way of breaking them that works everywhere.  For example, it's not
possible to use `@ ' in an index entry.  Some of the address@hidden' lines are
also very long, and I think `makeinfo' at least will fail if they're
broken.

The manual is still very rudimentary, but any comments about it would
be welcome.

Thanks,

Laurence