I also miss global index, as francois said it was my main
tool to finding what I was interested in. I can never guess
which book what I want is in.
Of course google search is an alternative, but indexes just
help me more sometimes. My favorite question is something
like:
There is a derby property, not quite sure how it is spelled, let's
look in the index under derby.x and quickly scan and find the one
I want and where it is documented.
Jeff Levitt wrote:
> --- Francois Orsini <[EMAIL PROTECTED]> wrote:
>
>
>>Looks good Jeff.
>>
>>The original Cloudscape documentation had a
>>fantastic master/global
>>index file - it was my main front-door to me for any
>>type of
>>documentation searching - I could locate anything
>>real fast and
>>documents (HTML) were linked as well. I know this
>>global index file
>>took a lot of time to build but it did save so much
>>time when looking
>>for something in the documentation...
>>
>>The MySQL online documentation also lets users add
>>comments to the
>>documentation - I have to admit it has been useful
>>when I tried to get
>>my way around MySQL....
>>
>>Cheers,
>>
>>--francois
>>
>>On 7/26/05, David Van Couvering
>><[EMAIL PROTECTED]> wrote:
>>
>>>Ooh, yes, very nice. This is something I have
>>
>>struggled with in the
>>
>>>past -- I click on a topic, and then to go to
>>
>>sub-topics I have to
>>
>>>I also very much like the related topics feature.
>>>
>>>It would be great if those of us who use the
>>
>>manuals could "add" related
>>
>>>topics as it becomes clear they are related. It
>>
>>would be even *nicer*
>>
>>>if this could be done right there online without
>>
>>having to edit DITA files.
>>
>>>If you look at the PGP documentation you will see
>>
>>what I mean:
>>
>>>http://www.php.net/manual/en/install.unix.php
>>>
>>>at the bottom of the page there is the "add a
>>
>>note" link. Users can add
>>
>>>notes to the page to provide more details, helpful
>>
>>hints, or
>>
>>>complaints. There are quite a few helpful notes
>>
>>added to this page.
>>
>>>Wouldn't it be possible to modify the DITA
>>
>>template to allow users to
>>
>>>add notes? We could then incorporate useful notes
>>
>>into the next rev of
>>
>>>the docs.
>>>
>>>David
>
>
> So I've actually been doing quite a bit of research
> into doing something like inline comments to the
> documentation, and I've run into several issues:
> 1. Both PHP and MySQL use the same engine for their
> inline comments. They use PHP scripting (of course).
> The problem is whether we can do that or something
> similar on an Apache web site server. I mean this not
> in a technical sense (obviously we have the "ability"
> to do it), but in a legal sense (whether Apache will
> allow it).
> 2. PHP and MySQL documentation aren't updated nightly
> as ours is. If we re-generate all of our
> documentation nightly, wouldn't we lose that day's
> comments from outsiders? The solution would be to have
> the commenting engine store the comments in separate
> files outside the content files themselves. But then
> what happens if we delete a topic or change it's name?
> Lots of infrastructure problems with this solution to
> be worked out.
> 3. Again, if we use outside files to store the
> comments, we return to the Apache legality issue. Can
> we do things like add and modify files on the Apache
> servers? I didn't think we could.
>
> Now related links as we currently use them is another
> story. I would define our related links as strictly
> links from one topic in a manual to another. As David
> requested, I think some sort of web page could be
> created that has tables showing the relationships
> between topics, and simple check boxes could enable or
> disable related links between one topic and another.
> I think on a technical level, we would need to have
> the engine behind this generate the relationship
> tables for each book into separate files, then modify
> the ant nightly build to merge the relationship tables
> with the ditamap for each book before creating the
> output. The issue I see with this is who gets to
> modify the tables? Committers? How would one request
> a change? Just through a JIRA entry, and then a
> committer checks and unchecks the boxes on the web
> page?
>
> As for the global index, I think it is possible.
> First we have to get individual indexes working for
> each manual, which we don't have yet either! Scott
> Hutinger and I did some research earlier this year
> into implementing indexes but we were never able to
> get it completed. If and when we do that, then Global
> indexing wouldn't be too far behind. We already have
> index entries defined within each topic dita file, but
> they are just sitting there for now not implemented
> anywhere. Going back to the idea for a web page that
> allows for creating and deleting our related links, I
> think it could also be possible to create a section
> where we can enter, modify, and delete index entries
> for each topic.
>
