Antwort: Re: [Bug 76553] New: Add Documentation Entry: Strange GUI, impossible to add documentation

[Alexander Dymo]

On Wednesday 03 March 2004 12:53, Robert Vogl wrote:
> Albeit the inconsistent GUI-Design I think the user should never be faced
> with an editor and the need to learn more or less cryptic XML just to add
> an entry in its collection of desired documentation. 
I think that feature wasn't added for user convenience. That feature IMHO
is mainly for KDevelop developers who want to provide some links to important
documentation.

> In principle it may be 
> a good idea to browse the TOC offline. But in practical it does not help
> alot if the chapters are available only online (would it really blow up the
> net-traffic to browse also the TOC online?). How to ensure that the online
> documentation fits to my locally installed libs or whatever? How to
> synchronize the XML-offline-TOC with the online-TOC, etc.? I bet, if I will
> decide next year to start e.g. a python-project, the .TOC-file that is
> delivered with KDevelop today is outdated.
Those topics aren't available online because nobody provides them.
There is no standard format for documentation and topics for UNIX.
We need to cope with man, info, html, etc... While I agree that for
online HTML docs our topics aren't that good (due to online-offline and
syncronization problems), but they are extremely usefull for local man and
info sources.
Also I'd like to see topics for W3C, OMG and other standards. You surelly
don't want to have them offline if you don't refer to them. And the topic
would direct you to the appropriate place. Also standards aren't changed
as frequently as documentation for libraries, compilers, etc.

> Most of the documentation I use either comes in PDF or HTML format and I
> prefer to use it offline. For the moment if I would like to use common
> HTML-docs than the only place to integrate is "General/Documentation
> generated by Doxygen". This works fine, but the title of that entry is
> misleading (how can the user decide if the documentation was generated by
> Doxygen or KDoc?) -> GUI-Problem.
Hey, KDevelop user is a developer ;) We don't want to hide technical details!

> If that widget is merely forseen to  
> integrate KDE-Documentation (according to the handbook ) then its right
> title would be something like "KDE API documentaion". 
KDoc was used only for generating KDE API documentation but it wasn't
restricted only for it. The fact kdoc isn't used anymore means only that
this is deprecated feature and should (and will) be removed in the next
version.

> KDevelop should be 
> smart enough to decide wether it was generated by doxygen or kdoc if that
> is really essential. Don't pinch the user with such technical details! But
> where is now the place to integrate other documentation?
The current situation is there is no good way to integrate user HTML
documentation. If you don't want the index and topic, the correct solution
would be to use bookmarks. There you can point to every kind of documentation
(html, pdf, even chm and many others). Basically everything that can be
viewed in konqueror can be added as a bookmark and viewed in KDevelop.

> My suggestions:
> 1.)
> Get rid of the browse-TOC-offline-but-chapter-online feature. I cannot
> imagine a case if that would be useful. Either I need a certain information
> or I don't need it. In the latter case I also don't need the TOC.
No, for the reasons above. It is still usefull for man and info pages, links
to standards, compiler and language bugs pages, our own KDevelop docs.

> Keep your focus to implement a proper way to integrate locally stored
> documentation and a handy (and stable!) bookmarking-system (wishlist-item:
> PDF would be nice too).
You can put everything in bookmarks (everything that can be viewed in
konqueror, of course)! Good you've pointed us at them, I've noticed
that "add bookmark" dialog asks only for html files. Actually, you can provide
it an asterisk (*) and bookmark everything!
This is now fixed in head and branch and will be in next 3.0.3 release.

About the proper way to integrate html documentation. There is no good
way to extract topic from a collection of html documents. This means that
only xml file with topic description can help ( our KDevelopTOC and DevHelp
formats ).
Maybe we need to provide a gui for building that xml file or simply use
KBookmark* stuff to get konqueror-like bookmarks.

-- 
Alexander Dymo
Ukrainian State Maritime Technical University, ICST Department