Hi John,

Am 18.02.2006 um 19:27 schrieb John R. Culleton:

I hope to offer the doc project one thing that I can do and perhaps others can't. The current pdf copy of the manual dated December 28, 2005, lacks an index. I know that this is supposed to come out of the docbook cycle somehow but it did not in this instance.

you got mail!

Further, looking at the index for the December, 2004 edition I note some areas needing improvement. For example the following three main headings occur:
Dialog
Dialogs
dialogs

yes, that's exactly why I really appreciate your offer to help. Lets see how that could work...

Obviously these headings should be consolidated and their subheads combined where appropriate. That is one reason why indexing cannot be a totally automated process. Judgment needs to be applied by a human being.

The index can of course be a byproduct of the development cycle. But there are two problems I foresee. First the development cycle has long since gone past the Dec 28th edition of the manual, but that edition is the only one currently available as a pdf.

Hmm, I don't get your point here. The GIMP development cycle is very loosely coupled to the writing of the manual. Right now we work a better manual for the stable gimp 2.2 release. So nothing to worry about being out of sync here.

An index must match the book exactly to be useful. The only way to make that match is with the text and the pagination of the pdf.

Yes it must match and no pagination is not the only way to get it. We have no pagination in the process of writing and editing. An html document neither a docbook xml file has one. (Well they do, but they are different and therefore unusable) The index is coupled to the chapters and sections instead. the numbering of the pages is done later automatically. This way we can say for each and every section which index terms should be linked to it.

Second, indexing through the cycle woould require working in each and every document to insert the appropriate indexing tags. If twenty people are writing modules of the document that won't be feasible. That process results in user-unfriendly duplications like Dialog etc. above and other anomalies.

working with different people together on one project is the only way it works in open source I guess. To avoid misspelling and the like it would help to have some rules about how to select and use index tags e.g.

first level - objects (image) second index level - verbs (open)
everything as singular (image instead of images)

... thats where I hope you can help us a lot. Best might be to have a very good index to start with and derive the tag catalog and rules from it.
This is the only way I see that helps the other languages in the manual too.

Therefore I will go through the Dec 28 pdf and create an index independent of the xml cycle. At this point there is no other way to create an index that matches that pdf. I will make that index available in pdf format for printing out as a companion document. The pagination will be correct to the Dec 28 edition which is the critical issue. When the next pdf version is made available then I will repeat the process.

Sorry this sounds a bit stupid, why doing the work for each and every release?
I'd suggest you write an index, based on a recent pdf and we transfer it afterwards into the xml files.
This way the pagination will correct itself when published the next time from the xml files.

The html help documents don't need a general index so there is no conflict.

Uhh, why not? It has one right now! And best of all: you get it for free!

If anyone see objections to this effort I would be interested in hearing them. I will prepare the index in any case for my own use. The only issue I see would be the posting of it alongside the main pdf file.

Your input is invited.

done!

Greetings, lexA