kdeaddons documentation

[Lauri Watts]

On Saturday 20 April 2002 22.17, Charles Samuels wrote:

Redirecting to kde-doc-english, where this is on topic.

> In the kdeaddons module, the documentation is arranged like so:
>
> doc/kate-plugins/openheader.docbook
> doc/kate-plugins/projectmanager.docbook
> doc/kate-plugins/textfilter.docbook
> doc/kate-plugins/xmltools.docbook

That listing is a little misleading.  Note that these are not valid documents 
on their own, and weren't intended to be, they are simply chapters for 
inclusion into index.docbook.  See kdebase/doc/kate/ or koffice/doc/kword/ 
for other examples.  The only reason any documentation is broken up into more 
than one file is ease of translation and multiple authorship.

> I propose that we change it to:
>
> doc/kate-plugins/openheader/index.docbook
> doc/kate-plugins/projectmanager/index.docbook
> doc/kate-plugins/textfilter/index.docbook
> doc/kate-plugins/xmltools/index.docbook
>
> First of all, it's consistent with every other module, 

Not really, the only one that has documentation this deep is kdebase, and not 
for any of the application manuals even in there.  The kdeaddons module 
currently works the same as any other, with a single index.docbook per 
directory, based on the top level directories in the module itself.  kdebase 
is a little special, but subdirectories are in general deprecated (for 
example, we ask writers not to use them for screenshots either.)

The right solution would be doc/textfilter/index.docbook and so on, but then 
how to install the right manual with the right place.  Also, making each of 
these a valid standalone document, will at least double the file size of each 
one, they're quite minimal at present.

> and secondly, and
> most importantly, it allows installing only one of the docbook files, the
> one that you actually want.

The real proble is, how do you propose the users access these manuals from 
within Kate (or any other app)?  At present, the setup allows a "Help --> 
Plugins" menu entry, where you will get the contents page, from which to 
choose the plugin you're interested in. 

A menu entry per installed plugin is not very efficient, especially as more 
and more plugins get added.  If you have a solution to this, I'd be 
interested to hear it, Daniel and I couldn't figure out anything more 
user-friendly than this though.   

Regards,
-- 
Lauri Watts