Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Derby Development" <derby-dev@db.apache.org>
Received-SPF: pass (hermes.apache.org: local policy)
Message-ID: <416AF713.6040202@wiu.edu>
Date: Mon, 11 Oct 2004 16:11:47 -0500
From: scott hutinger <s-hutinger@wiu.edu>
User-Agent: Mozilla Thunderbird 0.8 (X11/20040913)
MIME-Version: 1.0
To: Derby Development <derby-dev@db.apache.org>
Subject: Re: Derby documentation in PDF format
References: <m3pt3tqj9r.fsf@yesco.org> <4166D095.70301@bristowhill.com>
 <41670F19.3030300@Mutagen.Net>
In-Reply-To: <41670F19.3030300@Mutagen.Net>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

I just thought others might like to know that looking at some of the 
DITA information might be a bit on the verbose side, and might take a 
bit more time to get feedback on this.  I am by no means a document 
specialist, and I am a bit uncertain how many in this group really 
are?   Possibly Jeff might be the best person to get any information on 
'what might be any possible objections'?

DITA seems to look like a very good alternative to the current problems 
in my view, but I just follow this group very closely, so guess I don't 
count :-)
But I have been looking at all the DITA information since this morning, 
and thought I might be able to help a bit in this, but...a lot of 
information to look over exists.

 From what I have seen, I think it looks great!

scott

Jeff Levitt wrote:

> Jean T. Anderson wrote:
>
>> Jonas S Karlsson wrote:
>>
>>  
>>
>>> ...
>>>
>>> I'm sorry if I wasn't clear. I consider our "src"-files (the .ihtml)
>>> files to be generated, they were not written by a human:
>>>
>>>
>>>   
>>
>> oops! thanks for the clarification!
>>
>> The *.ihtml files actually are the Derby source for the manuals.
>>
>> As I understand it, the Cloudscape doc set source is stored in ArborText
>> Epic. The IBM docs person generated files for Derby from Epic as
>> multiple html files, then modified those to ihtml for forrest and to
>> reflect Derby. --Also, I made a heavy pass through the ihtml docs as
>> well before checking them into the subversion repository.
>>
>> The IBM docs person said it's easy to generate a single file per book,
>> but he doubted there was a way to reapply all the changes correctly.
>>
>> I see several options at this point:
>>
>> (1) Ask IBM docs to regenerate them as fewer files, then the Derby
>> community applies all the changes that need to be made, starting from
>> scratch.
>> (2) Derby community starts (perhaps slowly) consolidating the existing
>> ihtml files into a more desirable format.
>> (3) <==== your fine idea goes here =====>
>>
>> Incidentally a fewer number of files would have the benefit of reducing
>> the size and complexity of the forrest site.xml file.  A file gets
>> associated with the site by an entry in the site.xml file.  If an entry
>> for that file is not there, forrest generates a left-hand navigation tab
>> with the entire site contents. It made me sea sick the first time I
>> encountered it. If you want to see this effect, edit your local copy of
>> the site.xml to remove all but the "table of contents" and "index"
>> entries for the manuals, do 'forrest site', then 'forrest run', then
>> click on a page in one of the manuals.
>>
>> So, the current site.xml has an entry for every page in every manual.
>> With the exception of the "table of contents" and "index" pages, 
>> entries don't have a label so it doesn't explode that navigation bar.
>> --Imagine 700 files listed in that navigation tab. One problem remains
>> that I haven't been able to figure out. The pages without a label get
>> correctly associated with the Manuals tab (and that tab gets built
>> correctly), but you lose context for the specific manual to which the
>> page belongs.
>>
>> This problem would be solved by consolidating many files into fewer so
>> that all can be listed with a label in site.xml.
>>
>> -jean
>>
>>
>>  
>>
> I am the 'IBM docs person' that Jean and Jonas mentioned in their 
> responses earlier.  I'm very glad to see that people liked the 
> Cloudscape PDF's.  In a perfect world, I would have created a solution 
> that would allow you to generate whole PDF's of each of the docs for 
> Derby.  Unfortunately, I did not have enough time before I had to have 
> a solution in place to contribute the docs to Derby, so my quick fix 
> was to create the html for Forrest that you now find with Derby.
>
> But now that I have more time, I have been trying to come up with a 
> solution to several issues that the html presents, many of which have 
> already been brought up in this discussion.  Indeed, html is not a 
> very good source format.  Ideally, it would be nice to have XML 
> source.  This would solve several problems.  First, we could use the 
> XML to generate one PDF, or many html files, or just one large html 
> file.  In effect,  we would have a single source that would allow us 
> to output the documentation into any format we want.  In addition, the 
> conversion to XML would remove these "blank" files that Jonas mentioned.
>
> I would like to convert the Derby documentation to XML DITA.  DITA is 
> an open-source initiative for creating XML-based documentation.  You 
> can find out more about the DITA open-source standard initiative at 
> http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
>
> Converting to XML DITA solves the above problems, but also improves 
> the QUALITY of the documentation immensly.  DITA allows you to create 
> "articles" of information based on the books' contents that can stand 
> alone on their own or within the book context.  ALL of the information 
> in the 6 Derby books would be placed in articles that are classified 
> as either concepts, reference material, or tasks.  In addition, we can 
> further classify them as installation, configuration, development, 
> adminstration, any many other descriptive catergories.  Then, users 
> can sort the documentation by catergory, allowing them to look up only 
> "development reference" or "installation tasks" etc, independent of 
> the books.  And users who still want to use the book motif can use 
> provided mapping files that automatically resort the articles into the 
> proper order for each book and generate html, PDF's, etc.  DITA 
> basically solves all of our problems and improves the retrievability 
> of the documentation.
>
> The conversion to DITA will take quite a bit of time. In the meantime, 
> we could still use the current setup to modify the html files and 
> build with Forrest.  But once the conversion is done and we 
> recontribute the new doc set to Derby, I think the benefits far 
> outweigh the delay.
>
> I would be interested in what members of the community think about 
> this proposal.  If there are no objections, I could begin work on this 
> very soon.
>
> Jeff Levitt
>