[kde-doc-english]Doc for konqueror

[Frederik Fouvry]

| <rant>
| I believe that we have far too many markup tags, many of which seem to be in 
| practice equivalent; <keysym> vs. <keycap> for example. meinproc --check will 
| happily accept either <keysym>Enter</keysym> or <keycap>Enter</keycap> so 

It will accept a lot more than those two as well.  That's not
really an argument.

| there is no feedback to the author saying whether what he has entered is the 
| correct choice (which should it be?). So why not have just one tag here?

The distinction cannot be made automatically (that's why you have
to do it).  The DocBook documentation contains this example:

  <para>
  The <keycap>F1</keycap> key on an IBM PC keyboard generates the
  scan code <keycode>0x3B</keycode> when pressed.  This value
  is defined as <keysym>KEY_F1</keysym> in 
  <filename class="headerfile">keyboard.h</filename>.
  </para>

It doesn't say it all, but imho it makes clear that what you want
in most cases is keycap.  Few users care about keysyms and keycodes.
This is true for quite a few more cases.

The elements that the KDE documentation is very unlikely ever to
need have been removed from the DTD.

| There was some discussion a few months ago about the use of the <action> tag 
| in the Command Reference section of a handbook. As I understand it no one 
| could come up with a reason for using this tag.

That is a slightly different issue (I think).  These are much
more concrete than <action> which is a rather fuzzy idea.  Marking
that up did not bring that much:
- they changed often (keys don't)
- it was not clear what exactly the element should contain
  (a verb, a noun, a sentence?)
- the example for the use of markup I like is a search: suppose
  you want a list of all keys, of all system files, of all
  variables, menu items in the documentation.  It's easy when
  it's marked up.  Would anyone ever look for actions?  Unlikely
  if they're not well-defined.
- some elements can provide interesting functionality, e.g. for a
  left-handed user, the mousebutton element can generate the
  inverted text (right becomes left and vice versa), if that is
  stored in the user settings.  Names of system files might be
  linked to the files, etc.  
  OK, it's not in place yet, but it can be done.  The
  HTML/LinuxDoc SGML documentation there used to be was very poor
  in that respect.

I admit though that it would be more satisfying to see that it
made a visible/functional difference.

| I also have to say that what really confuses me as a part-time author is the 
| different markup that seems to be applied to different parts of a filename / 
| path, for no apparent good reason.
| </rant>

I'm not aware of such a thing, but if enlightened I'm happy to
provide an explanation ;-)

Frederik