Re: Keel documentation

Shash Chatterjee wrote:

> 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.

Yes, I think that the underlying files (chapter.xml, etc) should be 
renamed too.

> 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.

Yeah, but that would mean that new targets would have to be added: if we 
want to do a build of the manual (with translations), they'd manually 
have to be added (not optimal, IMHO).

> 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 think we should simply put all images in the images/ directory, and at 
the most prefix them to indicate chapter. This would make sharing of 
images much easier; also build and managing of images would be MUCH 
simpler. It's not like we're going to localize images or something ;-)

>>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".

Well, I certainly agree we shouldn't attempt it for now. BTW, I've 
really got to admire the new build system: it's FANTASTIC!! It beats the 
pants off any other system (including Maven). It's so good that I'll be 
stealing ideas off it for my project here ;-)

I just wish we had one feature from Maven: the JAR repository. A few 
weeks ago, I just did a calculation of duplicate JARs on the full CVS 
checkout, and it would have shaved off ~18MB off. Maybe we should look 
into that sometime later...


BTW, I've updated the Keel Manual page to contain links to the various 
chapters.
http://66.105.113.115/vqwiki-2.3.5/jsp/Wiki?KeelManual

I feel that we should produce points on the wiki, discuss them and then 
finally make the transition to the actual DocBook XML. I have no idea if 
the "ATTACH" functionality of the wiki works, but maybe we could upload 
drafts there (for those of us who don't have commit access).

Regarding the chapter outline, I'd like to see the following as a template:

[Goal: What this chapter is supposed to do]

[ ... ]

[Summary: A quick summary of the commands/concepts/etc learnt]

That should be more than enough for most chapters.


Regards,
Ashish



-- 


"This e-mail message may contain confidential, proprietary or legally privileged information. It 
should not be used by anyone who is not the original intended recipient. If you have erroneously 
received this message, please delete it immediately and notify the sender. The recipient 
acknowledges that ICICI Bank or its subsidiaries and associated companies,  (collectively "ICICI 
Group"), are unable to exercise control or ensure or guarantee the integrity of/over the contents of the information contained in e-mail transmissions and further acknowledges that any views 
expressed in this message are those of the individual sender and no binding nature of the message shall be implied or assumed unless the sender does so expressly with due authority of ICICI Group.Before opening any attachments please check them for viruses and defects."