db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kim Haase <Camilla.Ha...@Sun.COM>
Subject Re: Searching the Derby Documentation
Date Mon, 19 Nov 2007 18:22:12 GMT
Michelle Caisse wrote:
> Jørgen Løland wrote:
> 
>> Rick Hillegas wrote:
>>
>>> Laura Stewart wrote:
>>>
>>>> On 11/14/07, Lance J. Andersen <Lance.Andersen@sun.com> wrote:
>>>>  
>>>>
>>>>> Perhaps this is an indication that we need to revisit the layout of 
>>>>> the
>>>>> manuals to make them easier to use and put this as a high priority for
>>>>> things to address going forward.  If the documentation is difficult to
>>>>> navigate, this can be a turnoff to users.
>>>>>
>>>>> Regards
>>>>> lance
>>>>>
>>>>>     
>>>>
>>>>
>>>> I think that what we really need to invest in is changes to the code
>>>> that generates the docs, so that an index can be created with the
>>>> output.  Many index entries are already in the DITA files for the
>>>> documentation and are not exposed because the code that generates the
>>>> output is not setup to support index generation...
>>>>
>>>>
>>>>   
>>>
>>> +1 to the idea of generating an index. The old Cloudscape index used 
>>> to be very helpful and I think that a lot of that work has been 
>>> preserved in the existing index entry markers.
>>
>>
>> This may be a silly question, but why are we using dita when there are 
>> good tools for this? Why aren't we using LaTeX?
>>
> We definitely need a tool that can generate an index, but the UI for 
> creating docs in LaTeX is very cumbersome, awkward, and inefficient. Of 
> the mark-up languages I've used (nroff, html, and LaTeX), it is the most 
> difficult to work with.

Agreed -- I used TeX (not LaTeX, I think) for a bit 10-11 years ago. I 
felt fortunate that I was only making minor changes to existing docs 
rather than producing new text.

> 
> Kim and Laura, I'm curious if you use an xml editor to edit the DITA, or 
> do you use a text editor?

I use a text editor. I tried to use ArborText, which accommodates the 
DTD just fine, but found that it changed the line endings in the files, 
making the diffs invalid -- that is, the diffs file showed changes in 
addition to the actual content changes. It also sticks an Arbortext 
comment into each file.

Kim

> 
> -- Michelle

Mime
View raw message