Re: RFC - Admin manual index (draft)

Richard Huxton writes:

> Well, here's my first stab at indexing the admin manual.

Oh, you're working on that, too? ;-)

> Sorry about the
> delay, but it was one part lack of round tuits and two parts half-wittery on
> my part.
>
> http://www.archonet.com/pgadmin/

Comments:

I think the terms you picked are good. But I think you're confusing the
index with a table of contents. For instance, you list all the command
line tools under one index entry. I can obtain a list like that by going
to the reference manual ToC. Instead each tool should be listed under one
entry, because I want to look up pg_dump under "P". This is true for most
of your entries, AFAICS. PGDATA under "P", LD_LIBRARY_PATH under "L", an
extra entry for "shared libraries".

> I still need to go through and refactor the whole thing and also figure out
> how the "see xxx" bit works.

<indexterm>
<primary>foo</>
<see>bar</>
</indexterm>

> I'm getting 12 index entries ignored and no idea why (didn't notice until I'd
> almost finished). Any smart ideas how to figure out which 12 of the 200?

Either you're using spans, in which case the "startref" entry is ignored
(I think), or you're having duplicates, or you're messing with scopes.

> Would it be possible to use entities to add indexterms? Then we could have a
> central list of index definitions and just put &idx-backup-pgdump; in the
> actual document. Might help to keep the index structured.

I think we want to keep the index markers near the text they mark.

> Some of the links in the index have very good names, some less good. I'm
> guessing these are taken from the id attributes. Any problems with renaming a
> few of these presuming I grepped for references to the original id's?

Are you using the -p option for collateindex? Maybe you shouldn't.
Adding id attributes is okay though, as long as it doesn't get out of
hand.

> If this gets accepted for inclusion, I take it I need to do a make clean then
> a cvs diff?

When you're finished send me a diff so I can merge it with my work. I'll
commit it when we're making a branch.

Thanks!

--
Peter Eisentraut peter_e(at)gmx(dot)net http://funkturm.homeip.net/~peter