EntitiesEntities (which are simply variables that expand to some other text) are an important part of DocBook markup, and are used particularly widely in KDE documentation. For example, there are entities defined for almost all KDE applications. Therefore, when referring to, for example, Konqueror in documentation, you should use:
&konqueror; is, among other things, a
web browser.
This has several advantages. Firstly, it ensures that applications are capitalized and marked-up consistently across all KDE documentation. This means that you do not have to remember whether the help center program is KHelpCenter, KHelpcenter or Khelpcenter: the entity (which is always entirely lowercase) automatically expands to the correct one.
There are entities defined for several classes of names:
- All KDE applications
As mentioned before, all KDE applications have an entity. The entity name is in entirely lowercase, and expands to the correctly capitalized version of the application name. There is also an entity for KDE itself:
&kde;.- Common English and technology abbreviations
For example, “i.e.” is written as
&ie;and “e.g.” as⪚. This ensures that the same markup and capitalization are used for these abbreviations throughout KDE documentation. Technological abbreviations such as HTTP and XML also have entities, which are capitalized as usual (i.e.,&HTTP;and&XML;for the previous examples).- Trademarks
Names of companies and their products are often trademarked. For this reason, it is important to mark them up with the
trademarktag, using theclass="registered"attribute if necessary. To reduce effort, and ensure that trademarks are given proper acknowledgment, many common technology-related trademarks have been given entities. For example, the entity&X-Window;expands to X Window System®.- Contributor Names
Names of contributors to KDE documentation have entities of the form
&Firstname.Lastname;(or&Firstname.Initial.Lastname;). Email addresses of contributors have entities of the form&Firstname.Lastname.mail;.- Names of special keys
Names of keys on the keyboard are always marked up with either
keycaporkeysym. Since it can be difficult to distinguish between these two tags, entities have been created for common keys, e.g.,&Ctrl;and&Alt;.
The definitions of these entities can be found in the following locations in KDE 3:
- Items not requiring translation (KDE application names, technology abbreviations, trademarks)
- Contributor names and email addresses
- Language-specific terms and key names