TDE Specialities
Prev
Next

TDE Specialities

TDE-isms: entities, necessary bits (credits, translation stuff)

Entities

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:

All TDE applications

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;.

Common English and technology abbreviations

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).

Trademarks

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®.

Contributor Names

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 special keys

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:

Items not requiring translation (TDE application names, technology abbreviations, trademarks)

tdelibs/kdoctools/customization/entities/general.entities

Contributor names and email addresses

tdelibs/kdoctools/customization/entities/contributor.entities

Language-specific terms and key names

tdelibs/kdoctools/customization/en/user.entities

Necessary Sections

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”).

Prev
Next
Home


Would you like to comment or contribute an update to this page?
Send feedback to the TDE Development Team