bookinfo section is most easily prepared
by copying the KDE template.
Contains the entire document. Most important thing to remember is the
langattribute, 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.
Wraps the “meta” information – information about the document, not about the application it is documenting. Required in KDE documentation. No attributes.
Wraps the author information, and may also contain
<othercredit>information. Required in KDE documentation. No attributes.
Required element in the header section of all KDE 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.
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.
The contributor's first name.
If the author normally uses more than a first and surname, you can add further names here.
The author's surname.
An email address for the maintainer of the document is required for KDE 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 other contexts in the document,
<email>is used to contain any email address, and is not used inside the
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.
roleattribute is required, and can contain any one of the following:
othercreditelement also includes the
This is used in very specific circumstances, where an organization (e.g. “The KDE 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.
This is a wrapper for copyright information.
copyrightmust contain these elements:
yearelement for each year in which the document was changed or added to. Do not put more than one year in each tag, rather add more
yearelements, and use the 4 digit “YYYY” format.
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
copyrightsections, rather than trying to fit multiple names in the one section.
Copyright is automatically held by the author of the document, but the
copyrightelement is still required for all KDE documentation. None of the elements contained have any attributes.
Please do not add more names or years to existing
<year>elements. Add more, if they are required, or have multiple
This contains, of course, a legal notice. This is absolutely required for any KDE 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.)
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>Frameworks xx.yy</releaseinfo> for docbooks in frameworks <releaseinfo>Plasma xx.yy</releaseinfo> for docbooks in plasma workspace <releaseinfo>Applications xx.yy</releaseinfo> for docbooks released as Applications <releaseinfo>xx.yy (Applications xx.yy)</releaseinfo> for docbooks with own version released as Applications <releaseinfo>$applicationname xx.yy</releaseinfo> for applications with independent release schedule (extragear/playground)
In KDE 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.
A wrapper for a set of keywords suitable for search engines. Required for KDE Documentation, and there are no attributes. The
keywordsetshould contain several
<keywordset>for each search term. You must include at a minimum the terms “KDE”, the name of the application you are documenting, and the name of the package it is found in, for example “kdegames”. The keywords should be in order from most general first (that is, KDE) through less general, to the most specific. Add two or three more relevant words that people might search with, e.g., for the application KWrite you might add “editor” and “text”. This is required for KDE Documentation, and there are no attributes.
- <!-- TRANS:ROLES_OF_TRANSLATORS -->
This line is specific to KDE documentation. Although it is 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
othercreditsections here as appropriate.
An example you find in the template docbooks