book and the bookinfo section

Chapter 4. book and the bookinfo section

The bookinfo section is most easily prepared by copying the KDE 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 KDE Documentation. No attributes.

<authorgroup>

Wraps the author information, and may also contain <othercredit> information. Required in KDE documentaiton. No attributes.

<author>

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.

<firstname>

The contributors first name.

<othername>

If the author normally uses more than a first and surname, you can add further names here.

<surname>

The authors surname

<affiliation>

Used in KDE documentation to enclose the <address> and <email>

<address>

In KDE documentation, this is the only context we use address. It is found inside affiliation and contains only email.

<email>

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 address element.

<othercredit role="">

Similary to author, this is a wrapper around information describing other contributors to the document. Include here the contributors 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.

<contrib>

The role this contributor played in the document or application preparation. This could contain something like:

  • Developer

  • Deutsche Übersetzung

  • Reviewer

  • Traduction franࣧaise

<corpauthor>

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 maintainers 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, and use the 4 digit ‘YYYY’ format.

<holder>

The usual full name of the copyright holder(s). If there are more than one copyright holders (the document was previously maintained by another person, or is written collabaratively), 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 KDE documentation. None of the elements contained have any attributes.

<legalnotice>

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

<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 normal European format, with / delimiters, in the form “dd/mm/yyyy”. Please be extremely careful about this, and triple check it before you send in the document.

<releaseinfo>

This must match exactly the version of the application you are documenting. It must conform to the format X.x.xx (where X is a major version number and x are minor version numbers. This is not the version of the document. There are no attributes, and this element is required in KDE documentation.

<abstract>

In KDE Documentation, the abstract is required. It should be a short one or two sentence summary on the document. The abstract is not the place to put version or contact information, it should say something about the application and it's purpose. For example “KFoo is a small fast network enabled foo generator, suitable for both beginner and advanced foo users.”.

<keywordset>

A wrapper for a set of keywords suitable for search engines. Required for KDE Documentation, and there are no attributes. The keywordset should contain several of the <keyword>s.

<keyword>

Add one <keyword> inside the <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'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 4.1. The bookinfo section from the KDE template


<bookinfo>
<title>The Kapp Handbook</title>

<authorgroup>
<author>
<firstname>George</firstname>
<othername>N.</othername>
<surname>Ugnacious</surname>
<affiliation>
<address><email>gnu@kde.org</email></address>
</affiliation>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>1999</year>
<year>2000</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 (DD/MM/YYYY) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->

<date>03/04/1999</date>
<releaseinfo>1.01.00</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>
&kapp; 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 KDE, the KDE package it is in, the name
 of your application, and a few relevant keywords. -->

<keywordset>
<keyword>KDE</keyword>
<keyword>kdeutils</keyword>
<keyword>Kapp</keyword>
<keyword>nothing</keyword>
<keyword>nothing else</keyword>
</keywordset>

</bookinfo>
KDE Logo