Content and PresentationOne of the basic principles behind the use of DocBook in KDE is that content and presentation are strictly separated. DocBook files contain the content, and XSL files contain the information about the presentation. This has a number of advantages, some of which are:
When writing, you do not have to worry about whether the information is well presented, just that the information you're writing is correct and readable.
All KDE documentation has a similar look, so once readers are familiar with conventions in one document, they're familiar with all documents.
Documentation is future-proofed, since by providing as much information about content as possible, future formats, search engines, etc. are likely to be catered for easily.
In practice, this means that you should add markup that describes
what things are and not how they should appear. So,
in the example above, the <keycombo> (a
keyboard shortcut) tells the reader (or computer) that the keys Ctrl,
Alt and V should be pressed simultaneously, but
doesn't say anything about how that should be displayed in the final
output. (In fact, it appears as “Ctrl+Alt+V”, but it
could equally be converted to “C-M-V” à la Emacs
or even some other way of showing keyboard shortcuts. What is important
is that the DocBook source has the information
necessary to work out what is being referred to.)