Re: Subject: GDP: index entries for snippets

[Graham Percival]

On Sat, 9 Feb 2008 12:55:06 +0100
"Kess Vargavind" <address@hidden> wrote:

> First, I love indeces (indexes?) and use them everywhere.

Would you be willing to maintain the indeces/indexes?  Some of the
doc writers (including myself) either aren't good, or aren't
interested, in trying to think of potential terms.  I'd rather
have those people work on the actual documentation text.

The idea is this: once we've finished a section of the docs (for
example, NR 1.1 Pitches), you take the file and add whatever index
entries wherever you want.  I won't complain about having too many
or too few or if they're in the wrong place or whatever... but in
exchange, if anybody complains about the index (too much info,
links in the wrong places, whatever), I send those complaints to
you.  :)


Just as a reminder, a few weeks ago I offered a challenge: tell me
exactly what index text to add, and I can do so in less than 30
seconds.  As a result of that challenge, 1 person offered 1 index
entry.  Nobody else did anything.



> Explanations about the indeces. I always look for a paragraph or two
> just before the index itself, that (which?!) explains the
> conventions. Especially needed in the html version, if I may say so.
> (See below.) Not so important, but might help the user finding what
> they want.

Easily added.  Just send me whatever text you suggest.  Ideally
something that makes sense for all output formats, but if
necessary we could insert HTML-only text.

I added examples of this intro text to the GDP site.


> Different indeces. This is good and important. At the moment there's
> two, though spontaneously I think them to be good choices (a general
> one versus one for the commands) they would really further the
> indeces' purpose if they truly split up. I mean this, the command
> index' coverage is great (but as always, can be tweaked further) but
> needs some loving in the formatting and sorting department, while the
> general index really needs a work-through.

This is easily done -- actually, it was a technical challenge to
get them combined in the first place.  But when the question first
arose two years ago, the general concensus was that the general
index should include commands as well.

I'm quite open to changing this, but I'd want a fair amount of
discussion first.


> The command index. A few suggestions:
> ___ Sort alphabetically (after usage rather than literally), that is,
> do not sort under a leading interpunction symbol. Example order:
> ___ Sort under the letters A to Z and one or two others. For instance
> that !, /+, ~ & c. are sorted under one heading, e. g. "Symbols".
> ___ Always use main head words (although they in
> some cases may be contrived and hypothetical, they really help the
> 
> The aboe points hold true in general, but specifically so for the pdf

All those things would be nice, but we cannot do this for
technical reasons.  If you're interested in more information,
please see the texinfo manual  (ie google for it) and look at
their info about indices.  Sorry.

> The html version's indeces. See above for general pointers, there
> really is just one main thing that/which (aargh! you've made me
> realise I have no idea how to use that/which now...) give my skin
> rashes. Namely, how does it work? (You don't have to answer here as I
> already have figured most of it out, but it really would help if
> someone explains it in the docs themselves.)

Sorry, I don't understand -- you look for the term you want, then
click on the link.  I know this sounds like a completely stupid
and useless answer, but I really don't understand the question
"how does it work".

Cheers,
- Graham