Re: [help-texinfo] Formatting parser symbols and rules

[lfinsto1]

>> That wouldn't work, because there are many other variables that need to
>> go
>> in the variable index.   I'd like to keep the parser symbols separate to
>> reduce clutter.
>
> You can always do that by adding context to index entry's text.  For
> example:
>
>   @vindex address@hidden, parser symbol}
>

Thanks, but the problem is the entries that are automatically created by
the address@hidden' commands.

>> > I highly recommend redirecting all indexes into one in the end,
>> anyway.
>> >
>>
>> Oh, well we obviously disagree on this point.
>
> I agree with Karl, FWIW: indices are primarily for finding information
> easily.  WHile in the on-line Info file this normally doesn't matter
> (since the info-searching commands of Info readers look in all
> indices), it does matter in the printed output and in HTML, since
> there the reader will have too look up stuff in several disjoint
> lists.  That's a pain, IMO.
>

I'm not saying that you and Karl are wrong; there are just different
approaches to indexing.  I'm not sure whether an alphabetical listing of
parser rules is really useful.  Even if I decide that it is, I think an
appendix would be more useful than an index.  I do know how to get this to
work using `\write' commands, an auxiliary program, and a second pass, but
just using the index feature is much simpler.

> Can you tell why you prefer separate indices?

I think it's easier for people to find the information they want if it's
sorted into categories.  In German books, for example, it's common for a
book to have two indices; one for names of persons, and the other for
names of things.  A (fairly) recent change to the GNU Coding Standards
specifies that function names should not be formatted as, e.g., `foo()'
but rather as `foo'.  I'm happy to go along with this, but it does make it
hard to distinguish functions from variables.  One could have a single
index with entries like `foo (function), bar (variable)' or separate ones
for variables and functions.  However, the formatting in the former case
isn't done automatically by the address@hidden' commands, and many people 
probably
wouldn't want this.  If a combined index were useful, it would possible to
create one by duplicating all of the entries "by hand".  I don't find it
to be that much trouble to add address@hidden' commands, although they do
clutter up the input files.


>
>> address@hidden' puts the text in a slanted font in the TeX output, except for
>> `[]'
>> in address@hidden', as I've determined.  I suppose it wasn't meant to be
>> used this way
>
> @var is not meant to be used for literal symbol names, only for
> metasyntactical variables, i.e. for symbols that stand for something
> else.

Answered in previous email, which crossed yours.

>
> If you just want slanted font, use @i or @emph instead.
>
>> Declarations like `char c[]' are awkward to format, anyway, since
>> address@hidden @var{c[]}' would seem to make the brackets part of the
>> variable rather than the type.
>
> Why on Earth would you want to use something like address@hidden @var{c[]}'?
>

Only in the case of function declarations.  I have determined that an
ordinary declaration like this fails inside a function, and causes a
warning to be issued outside of a function, when using GCC under Windows:
"ttemp.c:4: warning: array 'c' assumed to have one element"

>> In addition, address@hidden' causes `makeinfo' without `--html' to issue
>> the following (annoying) warnings:
>>
>> c:\Scantest\DOC\TEXINFO//glblfncs.texi:41: warning: unlikely character [
>> in @var.
>> c:\Scantest\DOC\TEXINFO//glblfncs.texi:41: warning: unlikely character ]
>> in @var
>
> See above: you are using @var for a situation it wasn't supposed to
> handle.
>

It is meant to be used for arguments in function declarations.  It is, of
course, arguable, that the brackets properly belong to the type rather
than the name, but that's perhaps being too pedantic.  My guess is that
math mode is used for the brackets, anyway, since neither address@hidden' nor
address@hidden' causes slanted brackets to be used.  If I get ambitious, I 
might try
to do something about this problem.  Otherwise, my inclination is to file
it under "slightly annoying, but not worth bothering about".

Thanks,

Laurence