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

[Frederik Fouvry]

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

The manual says (http://www.docbook.org/tdg/en/html/action.html)

  action - A response to a user event

  Description

  Actions are usually associated with GUIs. An event might be
  movement or clicking of the mouse, a change in focus, or any
  number of other occurrences.
 
Which is still not much clearer, IMHO.  (OK, it is what happens
when you click/tick/hit ... some buttons, fields, keys, etc.)

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

I would write: <action>Close down</action> this instance of &konqueror;
But then again, I haven't tried to use it hundreds of times.

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

I think that would be wrong.  IMHO, the content of action should
be fairly short (at most a few words).

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

That has been removed in a later version of the DTD (current TDG
version: 2.0.4).  (It is formatted inline, which is an indication
for that fact that it probably should not be very long.  The
limited content is an indication for the fact that not too much
text should go in there.)

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

One might do.  One use I can think of is to make a list of all
actions in the documentation, which the user can consult to find
out how something is done.  I don't know if that makes sense
given the current use of the element?

I hope this was (at least a bit) helpful,

Frederik