TDE-isms: entities, necessary bits (credits, translation stuff)
Entities (which are simply variables which expand to some other text) are an important part of DocBook markup, and are used particularly widely in TDE documentation. For example, there are entities defined for almost all TDE 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 TDE documentation. This means that you don't 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:
As mentioned before, all TDE
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 TDE itself: &tde;
.
For example, “that is,” is written as &ie;
and “for example,” as ⪚
. This ensures that the same markup and
capitalization are used for these abbreviations throughout TDE
documentation. Technological abbreviations such as HTTP and XML also
have entities, which are capitalized as usual (that is,, &HTTP;
and &XML;
for the previous examples).
Names of companies and their products are often trademarked. For
this reason, it is important to mark them up with the
trademark
tag, using the class="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®.
Names of contributors to TDE 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 keys on the keyboard are always marked up with either
keycap
or keysym
. Since it can be
difficult to distinguish between these two tags, entities have been
created for common keys, for example,, &Ctrl;
and &Alt;
.
The definitions of these entities can be found in the following locations in TDE 3:
tdelibs/kdoctools/customization/entities/general.entities
tdelibs/kdoctools/customization/entities/contributor.entities
tdelibs/kdoctools/customization/en/user.entities
There are several sections that appear in all TDE DocBook files, even though they are not required by DocBook itself:
<!ENTITY package "tde-module"> <!ENTITY % addindex "IGNORE"> <!ENTITY % English "INCLUDE">
This appears in the prologue immediately after the FPI. See prologue for more details about this section.
<!-- TRANS:ROLES_OF_TRANSLATORS -->
This appears after the <authorgroup>
element, and is a required
placeholder for use in translation (also known as “i18n”
from the number of letters between the first and the last of the word “internationalization”).
Would you like to comment or contribute an update to this page?
Send feedback to the TDE Development Team