One of the basic principles behind the use of DocBook in TDE is that content and presentation are strictly separated. DocBook files contain the content, and XSL files contain the information about presentation. This has a number of advantages, some of which are:
When writing, you don't have to worry about whether the information is well presented, just that the information you're writing is correct and readable.
All TDE 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's important
is that the DocBook source has the information
necessary to work out what is being referred to.)
Would you like to comment or contribute an update to this page?
Send feedback to the TDE Development Team