Difference between revisions of "Documentation Primer/Manual/DocBook Reference/Markup"

Latest revision as of 11:13, 9 September 2012

Other languages:

English

[edit] General KDE markup style guide

• Format for readability, and content, not for a formatted document.
  
  It is not your job or responsibility to make sure the final documentation looks good. If you use appropriate markup tags for the content of your documentation, the processing tools will ensure your document looks good. Do not substitute an inappropriate DocBook XML tag because you do not like the "look" of the correct tag.
  
  You should use white space to make the DocBook source more readable to the writer. Please do not indent unless it is absolutely necessary.

• Do what you can to ensure you turn in a valid DocBook file. The reviewers will correct any DocBook errors you create, but please try to reduce errors by checking your work before it is turned in. If you have the KDE tools installed, you can use the command checkXML index.docbook to check for syntax errors. No result from checkXML is a good result - it means there are no problems.

• Non-English words should be tagged with <foreignphrase lang="de">Wort</foreignphrase>.

• Underlining and CAPITALIZING entire words are leftovers from the days of typewriters. They are no longer appropriate for today's documents.

• Do not use quotation marks in your documentation. If you want a word to appear within quotation marks, simply enclose it between quote tags.

  This software is provided <quote>as is</quote>

• There are three different "dashes" that are commonly found in documentation.
  • The hyphen combines two or more words into one. For example, "mother-in-law". The hyphen can be entered directly from the keyboard.
  • The en-dash is used to seperate numbers/dates/etc. For example, "Sections 1–3 review basic concepts". The en-dash can be encoded using &ndash;.
  • The em-dash is used to separate sentences, or to show that something is missing. This is rarely used in technical documentation, but it can be used to show that one sentence is interrupted by another. The em-dash can be encoded using &mdash;.

• When trying to decide between an ordered and unordered list, simply ask yourself the following question: "Does the order of the listed items matter?" or "If I change the order of the listed items, does that change the meaning of the list?". If you answer "No" to either question, then an unordered list is likely the logical choice.

• All <chapter> and <sectN> tags must have an id. The id must be in all lower case, and with dashes separating words. For example, <sect1 id="how-to-obtain-kapp">.

• All elements must have a full closing tag unless they are empty elements. Empty elements must still be closed with a /.
  
  Incorrect: <para/Blah blah/ or <para>Blah blah</>
  Correct:<para>Blah blah</para>

• No attribute minimization.
  
  Incorrect: attribute=value or attribute='value'
  Correct: attribute="value"

• All entities must end with a semi-colon:
  
  Incorrect: %parameterentity or &generalentity
  Correct: %parameterentity; or &generalentity;

• Element GIs (the first word in a tag) must be written in lower case only.
  
  Incorrect: <MediaObject> or <MEDIAOBJECT>
  Correct: <mediaobject>
  
  Entities are also case sensitive, and will result in validation errors if the case is wrong.

• Specify date and application's version in the format:

    <date>2000-12-31</date>
    <releaseinfo>1.02.03 (&kde; 4.x)</releaseinfo>

  
  The <date> is the date of the last update. The <releaseinfo> always matches the version number of the application that is described in the documentation (if any). A translated version of a documentation always has the same <date> and <releaseinfo> as the English original. Please respect this, it is the only way to manage efficiently both the writing and the translation processes.

• The list of entities for applications is maintained centrally. Entity names are the application name completely in lower case. In case the name you need does not exist yet, send a mail to kde-docbook@kde.org to have it added. You may add it in the prologue for validation purposes (in case it's new), but don't forget to remove it when you submit the document, because there should not be any "extra" entities defined in the document prologue.

• For language-independent entities, use kdelibs/kdoctools/customization/entities/general.entities and for language-specific entities, use kdelibs/kdoctools/customization/lang/user.entities. Try to avoid clashes with existing KDE entities.

• The en/user.entities file should be updated keeping in mind that translation must be possible. Here is an example of how this translation can be managed:
  
  &LMB; is en entity which stands for "Left Mouse Button"
  
  When translating to French for example, do not translate only the entity contents, please also translate the entity name to &BGS; (or &bgs;), to reflect the change in the initials:

  <!ENTITY "LMB" "left mouse button"> becomes
  <!ENTITY "BGS" "bouton gauche de la souris">

  
  Languages that decline nouns like German and Russian can use something like the following:

  <!ENTITY "LMB" "linke Maustaste">
  <!ENTITY "LMBn" "linken Maustaste">

• If you feel that some elements don't make fine enough a distinction, feel free to use the attribute role (but please tell the DocBook team, as otherwise you may find your document to be suddenly invalid).

• Use <qandaset> for FAQs, not an <itemizedlist>. Please split up a FAQ into several chapters or sections if it gets big. The HTML files get too big otherwise, which the users may not like.

• Abbreviations and acronyms should be marked up as well.
  
  Use the DocBook tags <abbrev> and <acronym> respectivly.
  
  Please keep them apart: acronyms are things like GUI, KDE, GPL, while abbreviations are things like etc., i.e., e.g.
  
  There are entities for the most common ones.

• Use <glossterm> or <firstterm> each time you introduce a technically significant new word.

• Keep in mind that the "$" sign is introduced by the shell, and is not part of an environment variable's name:
  
  ls -l $KDEDIR is marked up as
  
  

  <userinput><command>ls</command>
  <option>-l</option>
  <parameter>$<envar>KDEDIR</envar></parameter>
  </userinput>

  
  export $KDEDIR=/usr/local/kde is marked up as:
  
  

  <userinput>
  <command>export</command>
  <parameter>$<envar>KDEDIR</envar>=<filename>
  /usr/local/kde</filename></parameter></userinput>

• Only use <ulink> for URL's and not for files, unlike <A> in HTML. Don't use it for email addresses either, they have their own element, <email>.

• The elements <beginpage> and <bridgehead> are disallowed and have been removed from the KDE customized DTD. (They are not meant for new technical documentation.) <revisionhistory> has been removed also: we are using SVN already.

• ← DocBook Reference
• ↑ Back to Menu ↑
• Purpose of this document →