.toc redesign

[Bernd Gehrmann]

On Thu, 19 Jul 2001, Thomas Fromm wrote:

First, what I haven't mentioned before, I think you're mixing
up the 'table of contents' and the index. The table of contents
is for presenting a set of documentation in a systematical way.
It's shown in the documentation tree widget. The index is an 
alphabetical, searchable list of identifiers. It's currently 
available via 'find in index' in the help menu and is a separate
dialog (but that's not the only way to present it. Qt's assistant
uses a tab in the sidebar for it). In the Python and PHP tocs
and indices the difference is obvious (and it indicates that the
respective documentation is really well-structured :-) In the
KDE case, it happens that the documentation tree shows the list
of classes; but that is essentially because there is no useful
overview documentation for KDE. I think for Qt we should add
topics like 'Geometry management' and 'Internationalization' to
the documentation tree. Anyway, I think it's important to dis-
tinguish these different concepts.

Some other thoughts...

I don't think it's feasible to expect all authors of extensions
to distribute fine-grained symbol information in a standard format,
at least not in the forseeable future. Maybe that works for PHP,
but e.g. the Perl community is so widespread and has so many
manpage and vi purists that it just won't happen. But that's not
an insurmountable problem: this information can be found completely
dynamically. Type in 'pydoc:Tkinter' or 'perldoc:functions/grep' as 
url in Konqueror for examples :-) Unfortunately this can be very
slow. Maybe one can use a (binary?) cache for this and either let
the user regenerate the cache from time to time or use timestamps
of the directories where extensions are stored
(like /usr/lib/perl5/5.00503).

For other languages (maybe PHP, but certainly C, C++) your xml 
idea is certainly a good one. That's why I suggested to take a
look at doxygen's tag files. IIRC they contain a lot of the infor-
mation of your example. It's actively developed and its author
is very responsive, so maybe you could reuse this format or dis-
cuss any needed extensions with him. Last year it was proposed
that kdelibs switch to doxygen, but somehow this attempt got
stuck :-( 

So far for some thoughts on this topic. Sorry, I'm being a bit
troubled personally currently and can't think rational enough
for anything further :-(

Bernd.


-
to unsubscribe from this list send an email to kdevelop-devel-request at kdevelop.org with the following body:
unsubscribe »your-email-address«