[kde-doc-english]<action>Questions</action>

[Pam R]

I've been wondering about the use and application of the <action> tag. 
According to template.docbook, it is only used in the Command Reference 
section, where the examples show it surrounding a short description of the 
command, for example the entry in template.docbook for File->Quit is;
<listitem><para><action>Quits</action> &kapp;</para></listitem>

Now this example is especially terse and doesn't convey any information that 
can't be gained by just reading the menu item name, so in practice the 
docbook writer is tempted to put some flesh onto it by making it something 
like <action>Close down this instance of &konqueror;</action>

Some menu items deserve an even fuller description in the Command Reference 
section, particularly where there is no obvious place to add it in the main 
body of the document, and in these cases the author may wish to use more than 
one para between the <listitem> tags, should all of these <para></para> 
sections have <action></action> embedded?

On the other hand, there is often the case where a link to a fuller 
description of the menu item's function would be appropriate, but it seems 
that meinproc objects when you try to include <link>..</link> within an 
<action> section, (even though V1.0.3 of 'Docbook: The Definitive Guide' says 
that you can do this).

I suppose that what I am asking is for a precise definition of why and where 
the <action> tag should be used in KDE documentation, or maybe I am asking if 
there are any advantages to using it at all?. 

Please excuse me for not posting this to the docbook list, which might have 
been more appropriate, but I am  not subscribed to it.

Pam