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

[Robert Vogl]

Hi Bernd,

thanks for your response.

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. 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.

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. 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". 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?

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.

2.)
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).

Have a nice day,

--
Robert Vogl
robert.vogl at esg.de


                                                                                                                                          
                      Bernd Pol                                                                                                           
                      <bernd.pol at online        An:       kdevelop-devel at kdevelop.org                                                      
                      .de>                     Kopie:    robert.vogl at esg.de                                                               
                                               Thema:    Re: [Bug 76553] New: Add Documentation Entry: Strange GUI, impossible to add     
                      02.03.2004 22:27          documentation                                                                             
                                                                                                                                          
                                                                                                                                          




Am Dienstag, 02. März 2004 10:06 (UTC) schrieb Robert Vogl:
> The dialog to integrate external documentation (Configure
> KDevelop/Documentation Tree/KDevelop TOC Documentation) is not
> intuitive to handle. If I like to add external documentation I have
> to specifiy a location prior to the title. I expect the reverse
> order. The title-widget is greyed out. Why is the user prevented from
> specifying the desired title? The location dialog asks for a *.toc
> file. How to get or create that??? It is impossible simply to specify
> a local directory that holds an index.html-file for documentation
> that was delivered as HTML (and not generated by Doxygen).
>
> The table shows three columns named "Name", "Title" and "URL".
> Therefore if I click on "Edit" I expect to edit name, title and URL
> of an entry of that table. But I'm asked to change a "Documentation
> Path" (I guess same as URL) instead. The widget for "Library name"
> and "Library source path"(?) are grayed out and cannot be changed (am
> I really in the edit-dialog!?). And why is the Edit-Dialog completely
> different from the Add-Dialog? This is not intuitive.
>
> A confusing GUI is a bug. Nevertheless my integrated documentation
> never shows up in the "Documentation" window.

It is a bit tricky. And, yes, it does not behave as one assumes at first
sight. But help is underway... ;-)

I did just commit a new section of the User Manual to CVS HEAD. This
will show up online tomorrow at
http://docs.kde.org/en/HEAD/kdevelop/kdevelop/

Look at chapter 6, "Standard Contents of the Documentation List"
section.
--
Have a good day,
Bernd