Re: Keel documentation

Ashish,

> 1. Translations of the manual
> 	Rename book.xml to book-en_US.xml (and so on) so that it clearly 
> shows the manual is for English. 

I will change the name.  All the entity references are defined in book.xml, I
wonder whether all the chapter.xml, service.xml, etc. in the udnerlying doc
structure should be renamed as well?  Now's the time to do it, before we
actually start working with the docs.
 
> With the new directory structure, 
> it should be very easy to do a translation: drop a translated 
> version as book-ja_JA.xml in the same place as the corresponding 
> english file. 	Also, the build system would probably need to be 
> updated to take care of multiple languages..?
>
The build system doesn't really care about the underlying structure, so all we
need to do is to add three lines to the top-level build.xml for book-ja_JA.xml.
 
> 2. Standardization of image formats
> 	I think we should standardize on PNG as the image format, as it 
> saves space, can do true-color, and is better than GIF. We have a 
> number of formats in the old manual (GIF, SVG, etc) and having a 
> standard image format and naming convention/directory structure 
> (since all images will be in a seperate hierarchy).
> 
I agree....and definitely for any new graphics generated.  For the existing
images, though, we might need to start with what we have now, and over time
regenerate to PNG.  I was thinking under images, we would mimic the chapter
hierarchy, so it was immediately obvious which image went with what text.  I
was also thinking that instead of copying all files/dirs under images, I could
change to copy *.png, *.gif, *.svg, *.jpg from the chapters hierarchy (so we
didn;t need to create a image hierarchy under images).  What do you think?

> I'd also love it if we could somehow modify the build system so that 
> by adding chapter.xml in doc/manual of a app/service/client resulted 
> in that being added to the manual. Dunno if it's a good idea, though.

If you look at the doc structure, that is exactly what I was getting prepared
for, and used the same names as we have for app/service/client directories.
Also, this is the reason I picked a generic "service.xml", "client.xml",
"app.xml" for each service so we could automate the doc generation from some
source.  It would be nice if we could extract and collate the doc from each
service, client, etc.  For now, with Mike trying to make the build process
simpler, and the rush to get everything organized, I'd say lets just do it
manually under keel-doc.  In a future release, we'll adapt the build system to
make this a "distributed doc system".

Good suggestions.

Shash