You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by John Embretsen <Jo...@Sun.COM> on 2007/11/14 16:34:35 UTC
Searching the Derby Documentation
I know navigating the Derby manuals and finding what you are looking for can be
a gruesome experience for both users and developers.
Various tricks can be used to make this easier, e.g. searching all manuals
combined into one PDF (such as those found here:
http://dbtg.thresher.com/derby/test/DerbyDocs/index.html ), or using advanced
Google searches.
Inspired by David's blog post (and comments) at
http://weblogs.java.net/blog/davidvc/archive/2007/06/searching_the_d.html
I created my own custom (google) search engine for searching the Derby docs and
public API. It's available for everyone to use, the URL is
http://www.google.com/coop/cse?cx=013165901514945153857%3A6lvlcohwpjo
(unfortunately not so easy to remember).
I've made some refinements for searching a particular Derby version, or a
particular manual in the doc trunk. There is currently a max limit of 16
refinements.
It's possible to volunteer to contribute to this search engine for those who
feel inspired, but maybe it would be better to somehow create something similar
that is "owned" by apache, and include it on our web page?
Anyway, I hope this is useful to someone.
--
John
Re: Searching the Derby Documentation
Posted by John Embretsen <Jo...@Sun.COM>.
Lance J. Andersen 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.
A related conclusion from the blogosphere:
"Derby has a great feature list but I wonder how many users are ignorant of what
it can do because of the poor documentation?"
http://rrees.wordpress.com/2007/12/31/setting-up-a-derby-database/
--
John
> John Embretsen wrote:
>> I know navigating the Derby manuals and finding what you are looking
>> for can be
>> a gruesome experience for both users and developers.
[snip]
Re: Searching the Derby Documentation
Posted by Laura Stewart <sc...@gmail.com>.
On 11/16/07, Andrew McIntyre <mc...@gmail.com> wrote:
...
>
> DITA 1.4 appears to have fairly complete back-of-the-book index generation:
>
> http://dita-ot.sourceforge.net/SourceForgeFiles/doc/release_14.html
>
> Although I think you're referring to the old Cloudscape global index
> which was definitely very useful. I suppose it might be possible with
> XSLT and lots of time to combine the XML for each book into one
> massive XML and generate a global index with links into the specific
> books for the indexterms, at least for the HTML and HTML book formats.
I would be happy to have just a back of the book index. I don't think
that a global index is necessary if we have organized the information
into the correct books.
--
Laura Stewart
Re: Searching the Derby Documentation
Posted by Andrew McIntyre <mc...@gmail.com>.
On Nov 14, 2007 6:25 PM, Rick Hillegas <Ri...@sun.com> wrote:
>
> Laura Stewart wrote:
> >
> > 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.
DITA 1.4 appears to have fairly complete back-of-the-book index generation:
http://dita-ot.sourceforge.net/SourceForgeFiles/doc/release_14.html
Although I think you're referring to the old Cloudscape global index
which was definitely very useful. I suppose it might be possible with
XSLT and lots of time to combine the XML for each book into one
massive XML and generate a global index with links into the specific
books for the indexterms, at least for the HTML and HTML book formats.
Relative filesystem URLs might not work for PDFs, but I wouldn't rule
it out completely. At any rate, there's no built-in multi-book index
feature in the DITA toolkit as far as I'm aware, so a global index
would be something we'd have to build ourselves, once we migrated to
DITA 1.4 and got back-of-the-book indexes working correctly.
There are two problems with regular indexes, though. One is that there
hasn't been an ASL release of the DITA toolkit since 1.2.2, for
whatever reason, and the back-of-the-book index support for PDFs may
not have been implemented for PDFs generated by the old PDF / FOP
targets that were deprecated with DITA-OT 1.3.1:
http://dita-ot.sourceforge.net/SourceForgeFiles/doc/release_13.html
The current PDF2 targets rely on the Idiom FO plugin (ok, looks like a
BSD derivative although it's got a strange clause at the end) but also
on the RenderX XEP rendering engine, whose free version has a license
that is very restrictive and not open source friendly. So, we might
not get back-of-the-book indexes even if we upgraded to DITA 1.4
without some additional effort on our part.
andrew
Re: Searching the Derby Documentation
Posted by Kim Haase <Ca...@Sun.COM>.
Laura Stewart wrote:
> On 11/19/07, Kim Haase <Ca...@sun.com> wrote:
>> Michelle Caisse wrote:
>>> 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
>
> I use Arbortext. If the new files are setup to be eol independent
> (can't recall the command that you apply to the files, but it is
> probably on the Derby wiki) then that is not a problem. I use a tool
> called Search and Replace to remove the Arbortext comment line after I
> have completed my edits.
>
According to http://db.apache.org/derby/manuals/dita.html, the commands
to be put in the .subversion/config file are
*.dita = svn:eol-style=native
*.ditamap = svn:eol-style=native
*.out = svn:eol-style=native
My diff files always indicate that this property is set -- for example,
Property changes on: src/ref/rrefattribtracedirectory.dita
___________________________________________________________________
Name: svn:eol-style
+ native
But this should have no effect on the behavior of Arbortext. Maybe
Arbortext works differently on Windows and UNIX. We have a UNIX version.
Kim
Re: Searching the Derby Documentation
Posted by Laura Stewart <sc...@gmail.com>.
On 11/19/07, Kim Haase <Ca...@sun.com> wrote:
> Michelle Caisse wrote:
> > 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
>
I use Arbortext. If the new files are setup to be eol independent
(can't recall the command that you apply to the files, but it is
probably on the Derby wiki) then that is not a problem. I use a tool
called Search and Replace to remove the Arbortext comment line after I
have completed my edits.
--
Laura Stewart
Re: Searching the Derby Documentation
Posted by Kim Haase <Ca...@Sun.COM>.
Michelle Caisse wrote:
> Jørgen Løland wrote:
>
>> Rick Hillegas wrote:
>>
>>> Laura Stewart wrote:
>>>
>>>> On 11/14/07, Lance J. Andersen <La...@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
Re: Searching the Derby Documentation
Posted by Michelle Caisse <Mi...@Sun.COM>.
Jørgen Løland wrote:
> Rick Hillegas wrote:
>
>> Laura Stewart wrote:
>>
>>> On 11/14/07, Lance J. Andersen <La...@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.
Kim and Laura, I'm curious if you use an xml editor to edit the DITA, or
do you use a text editor?
-- Michelle
Re: Searching the Derby Documentation
Posted by Jørgen Løland <Jo...@Sun.COM>.
Rick Hillegas wrote:
> Laura Stewart wrote:
>> On 11/14/07, Lance J. Andersen <La...@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?
--
Jørgen Løland
Re: Searching the Derby Documentation
Posted by Rick Hillegas <Ri...@Sun.COM>.
Laura Stewart wrote:
> On 11/14/07, Lance J. Andersen <La...@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.
Re: Searching the Derby Documentation
Posted by Laura Stewart <sc...@gmail.com>.
On 11/14/07, Lance J. Andersen <La...@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...
--
Laura Stewart
Re: Searching the Derby Documentation
Posted by "Lance J. Andersen" <La...@Sun.COM>.
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
John Embretsen wrote:
> I know navigating the Derby manuals and finding what you are looking
> for can be
> a gruesome experience for both users and developers.
>
> Various tricks can be used to make this easier, e.g. searching all
> manuals
> combined into one PDF (such as those found here:
> http://dbtg.thresher.com/derby/test/DerbyDocs/index.html ), or using
> advanced
> Google searches.
>
> Inspired by David's blog post (and comments) at
> http://weblogs.java.net/blog/davidvc/archive/2007/06/searching_the_d.html
> I created my own custom (google) search engine for searching the Derby
> docs and
> public API. It's available for everyone to use, the URL is
>
> http://www.google.com/coop/cse?cx=013165901514945153857%3A6lvlcohwpjo
>
> (unfortunately not so easy to remember).
>
> I've made some refinements for searching a particular Derby version, or a
> particular manual in the doc trunk. There is currently a max limit of 16
> refinements.
>
> It's possible to volunteer to contribute to this search engine for
> those who
> feel inspired, but maybe it would be better to somehow create
> something similar
> that is "owned" by apache, and include it on our web page?
>
> Anyway, I hope this is useful to someone.
>
>