Thread: RFC - Admin manual index (draft)

Well, here's my first stab at indexing the admin manual. 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/

I've tried to concentrate on getting environment variables, config settings
etc indexed since I figure people will run a text-search on the index page to
find a specific thing.

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

It's based on CVS of a week or so ago, so I'll need to update it to match
current. Was having problems doing a cvs update - seemed to be doing something
but was sending one packet every minute or so - might just be the server was
busy.

Any comments gratefully received. Some notes/thoughts below:

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?

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.

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?

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

PS - congrats to any/all involved in the release of 7.1 - nice work.

- Richard Huxton

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@gmx.net   http://funkturm.homeip.net/~peter