<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
<!-- Define an entity for your application if it is not part of TDE
CVS -->
<!ENTITY kmyapplication
"<application>KMyApp</application>">
<!ENTITY kappname "&kmyapplication;
"><!-- replace kmyapplication here
do *not* replace kappname-->
<!ENTITY package "tde-module
"><!-- tdebase, tdeadmin, etc. Leave
this unchanged if your
application is not maintained in TDE GIT -->
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE"> <!-- ONLY If you are writing non-English
original documentation, change
the language here -->
]>
In general, this needs minimal changing from the template. The items you must change are the entities “kappname”, “package”, and “English”.
The entity “kappname” looks like it's redundant (as the comment in the template notes), but it is important. This allows us to use one global text in all documents, and still refer to the specific application by its correct name. So it should be changed to refer to this new entity, but this time you should only change the part in quotes (“&kmyapplication;”) as follow:
Example 3.1. Setting up the global “kappname” entity
From: <!ENTITY kappname "&kmyapplication;" -- this only *seems* redundant --> To: <!ENTITY kappname "&kate;" -- this only *seems* redundant -->
In short: change any occurrence of “kmyapplication” to the real name of your application. Do not use “kappname” or “kapp” directly in a document yourself.
The entity “package” is used similarly. It allows us to insert a single piece of “boilerplate” text into every document, and have the correct package name inserted when the document is compiled. Use the cvs module name, in lower case, for example, “tdeedu” or “tdebase”.
The entity %addindex;
is a toggle. If
set to “INCLUDE” a document index will be automatically
generated. It is normally set instead to “IGNORE”, and should
not be changed unless you really do want to generate an index. You can find
out more about indexes in Chapter 17, References, indexes, and glossaries.
Example 3.2. A TDE User Manual Prolog
Here is an example of a completely set up prolog, as it normally looks. This is the prolog from the AMOR documentation
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
<!ENTITY kappname "&amor;">
<!ENTITY package "tdetoys">
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE">
]>
The entity “English” should be changed to reflect your language, if you are either writing original documentation in another language, or you are translating a document. For TDE the original documentation should always be in English, so you should not need to change this when writing. For informational purposes, the currently supported languages are:
Afrikaans
British-English
Bulgarian
Catalan
Czech
Danish
German
Greek
English
Spanish
Estonian
Finnish
Faroese
French
Hebrew
Hungarian
Indonesian
Italian
Japanese
Dutch
Norwegian (Note, this is only for compatibility, either Norwegian-Bokmal or Norwegian-Nynorsk should be used in preference.)
Norwegian-Bokmal
Norwegian-Nynorsk
Polish
Portuguese
Brasilian-Portuguese
Romanian
Russian
Slovak
Slovenian
Serbian
Swedish
Turkish
Ukrainian
Walloon
Xhosa
Continental-Chinese
Traditional-Chinese
The bookinfo
section is most easily prepared
by copying the TDE template.
<book lang="&language">
Contains the entire document. Most important thing to remember is the lang
attribute, which must contain exactly &language;
, and must not be changed. To set the
language for the document, change the entity as described in the prologue section.
<bookinfo>
Wraps the “meta” information – information about the document, not about the application it is documenting. Required in TDE documentation. No attributes.
<authorgroup>
Wraps the author information, and may also contain <othercredit>
information. Required in TDE
documentation. No attributes.
<author>
Required element in the header section of all TDE documentation. Use this
element only for the author(s) of the document. Other
contributers (developers, translators, and so on) should be credited in the
<othercredit>
section. No attributes.
<personname>
Used to wrap a person's name. You can use this directly in the text as well, but here it should be used to contain each author or contributor name.
<firstname>
The contributor's first name.
<othername>
If the author normally uses more than a first and surname, you can add further names here.
<surname>
The author's surname.
<email>
An email address for the maintainer of the document is required for TDE documentation. You do not have to use your primary private address, and you may be able to arrange for someone else (the developer perhaps) to receive the email regarding the document. In any case, there must be an address for users and translators to contact regarding errors and document bugs.
In previous versions of DocBook, <email>
could not be used directly inside
<author>
. Since DocBook XML V 4.2
(used by TDE for documents after TDE 3.1.x), this is possible,
which simplifies this markup considerably.
In other contexts in the document, <email>
is used to contain any email address,
and is not used inside the address
element.
<othercredit role="">
Similary to author
, this is a wrapper around
information describing other contributors to the document. Include here the
contributor's name and email address as you do for the author. See the template
for more details.
The role
attribute is required, and can
contain any one of the following:
Translator
Developer
Reviewer
Graphist
Musician
The othercredit
element also includes the
contrib
element.
<corpauthor>
This is used in very specific circumstances, where an organization (for example, “The TDE Team”) is being credited with authorship of a document. Authors writing about applications should not use this and should credit themselves. If you do find a need to use this, please be sure to include a maintainer's name and email address in the credits chapter of the document.
<copyright>
This is a wrapper for copyright information. copyright
must contain these elements:
<year>
Add one year
element for each year
in which the document was changed or added to. Don't put more than
one year in each tag, rather add more year
elements, and use the 4 digit
“YYYY” format.
<holder>
The usual full name of the copyright holder(s). If there is more
than one copyright holder (the document was previously maintained by
another person, or is written collaboratively), then add more copyright
sections, rather than trying to
fit multiple names in the one section.
Copyright is automatically held by the author of the document, but the
copyright
element is still required
for all TDE documentation. None of the elements contained have any
attributes.
Please do not add more names or years to
existing <holder>
or <year>
elements. Add more, if they are
required, or have multiple copyright
sections.
<legalnotice>
This contains, of course, a legal notice. This is absolutely required for any
TDE document. In the context of this section, it should contain the
&FDLNotice;
entity, which inserts some information into
the document about the document's license (and not the
license of the application you are describing.)
<date>
The date is very important. It is used not only by scripts for automatic processing of documentation, but is also central to revision control and co-ordination of translations. You must change the date if you have changed the original document, and you must not change the date if you are a translator. The format of the date is very important. It must be in the ISO, with “literal” delimiters, in the form “yyyy-mm-dd”. Please be extremely careful about this, and triple check it before you send in the document.
<releaseinfo>
This should match exactly the version of the application you are documenting. It should normally conform to the format X.x.xx (where X is a major version number and x are minor version numbers, however, you no longer have to pad the content to this length. That is to say, if the application has released version “1.4”, you may write <releaseinfo>1.4</releaseinfo>, and you do not need to make it <releaseinfo>1.04.00</releaseinfo>
This is not the version of the document. There are no attributes, and this element is required in TDE documentation.
<abstract>
In TDE Documentation, the abstract is required. It should be a short one- or two-sentence summary of the document. The abstract is not the place to put version or contact information, but it should say something about the application and its purpose. For example “KFoo is a small fast network enabled foo generator, suitable for both beginner and advanced foo users.”.
The abstract is your chance to sum up the application in a small paragraph — in KHelpCenter it shows up on the first page as your document is selected, and the abstract frequently shows up in the summary of your document in web searches. A short overview of the application you are writing about is very valuable in this situation, “This is the KFoo handbook and describes KFoo 1.2.” on its own, is not.
<keywordset>
A wrapper for a set of keywords suitable for search engines. Required
for TDE Documentation, and there are no attributes. The keywordset
should contain several
<keyword>
s.
<keyword>
Add one <keyword>
inside the <keywordset>
for each search term. You must
include at a minimum the terms “TDE”, the name of the
application you are documenting, and the name of the package it is found
in, for example “tdegames”. The keywords should be in
order from most general first (that is, TDE) through
less general, to the most specific. Add two or three more relevant words
that people might search with, for example,, for the application KWrite you
might add “editor” and “text”. This is
required for TDE Documentation, and there are no attributes.
This line is specific to TDE documentation. Although it's a comment,
it is absolutely required in documents. It is
used by the translation system as a placeholder for the translation
teams to add their own role info. Translators should add more othercredit
sections here as appropriate.
Example 3.3. The bookinfo section from the TDE template
<bookinfo>
<title>The &kmyapplication; Handbook</title>
<authorgroup>
<author>
<!-- This is just put in as an example. For real documentation, please
define a general entity in entities/contributor.entities, e.g.
<!ENTITY George.N.Ugnacious "<personname><firstname>George</firstname><othername>N.</othername><surname>Ugnacious</surname></personname>">
<!ENTITY George.N.Ugnacious.mail "<email>gnu@tde.org</email>">
and use `&George.N.Ugnacious; &George.N.Ugnacious.mail;' in the author element.
-->
<personname>
<firstname>George</firstname>
<othername>N.</othername>
<surname>Ugnacious</surname>
</personname>
<email>gnu@tde.org</email>
</author>
</authorgroup>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
<copyright>
<year>2002</year>
<holder>George N. Ugnacious</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice. Read the explanation in fdl-notice.docbook
and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>
<!-- Date and version information of the documentation
Don't forget to include this last date and this last revision number, we
need them for translation coordination !
Please respect the format of the date (YYYY-MM-DD) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->
<date>2003-01-10</date>
<releaseinfo>1.1.</releaseinfo>
<!-- Abstract about this handbook -->
<abstract>
<para>
&kmyapplication; is an application specially designed to do nothing you would
ever want.
</para>
</abstract>
<!-- This is a set of Keywords for indexing by search engines.
Please at least include TDE, the TDE package it is in, the name
of your application, and a few relevant keywords. -->
<keywordset>
<keyword>TDE</keyword>
<keyword>tdeutils</keyword>
<keyword>Kapp</keyword>
<keyword>nothing</keyword>
<keyword>nothing else</keyword>
</keywordset>
</bookinfo>
Would you like to comment or contribute an update to this page?
Send feedback to the TDE Development Team