Difference between revisions of "Documentation Primer/Manual/DocBook Reference/Book and Bookinfo"

Jump to: navigation, search
m (1 revision: Moving Docbook Primer from UserBase to TechBase)
Line 1: Line 1:
<languages />

Revision as of 09:06, 1 September 2012

Other languages:
These pages are being transferred from UserBase. Please don't work on them until the transfer is complete, and the old UserBase pages have been removed.

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.


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 previous versions of DocBook, <email> could not be used directly inside <author>. Since DocBook XML V 4.2 (used by KDE for documents after KDE 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.
The role this contributor played in the document or application preparation. This could contain something like:
  • Developer
  • Deutsche Übersetzung
  • Reviewer
  • Traduction française


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. copyright must contain these elements:
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.
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 KDE 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.


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.


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 KDE documentation.


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 keywordset should contain several <keyword>s.


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.


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: The bookinfo section from the KDE template
<title>The &kmyapplication; Handbook</title>

<!-- 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@kde.org</email>">
and use `&George.N.Ugnacious; &George.N.Ugnacious.mail;' in the author element.


<holder>George N. Ugnacious</holder>
<!-- 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. -->

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


<!-- Abstract about this handbook -->

&kmyapplication; is an application specially designed to do nothing you would
ever want.

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

<keyword>nothing else</keyword>