diff options
Diffstat (limited to 'doc/tutorials/markup')
| -rw-r--r-- | doc/tutorials/markup/CMakeLists.txt | 9 | ||||
| -rw-r--r-- | doc/tutorials/markup/Makefile.am | 3 | ||||
| -rw-r--r-- | doc/tutorials/markup/index.docbook | 5317 |
3 files changed, 5329 insertions, 0 deletions
diff --git a/doc/tutorials/markup/CMakeLists.txt b/doc/tutorials/markup/CMakeLists.txt new file mode 100644 index 0000000..cebfe1b --- /dev/null +++ b/doc/tutorials/markup/CMakeLists.txt @@ -0,0 +1,9 @@ +################################################# +# +# Improvements and feedback are welcome +# +# This file is released under GPL >= 2 +# +################################################# + +tde_create_handbook( DESTINATION khelpcenter/markup ) diff --git a/doc/tutorials/markup/Makefile.am b/doc/tutorials/markup/Makefile.am new file mode 100644 index 0000000..4169155 --- /dev/null +++ b/doc/tutorials/markup/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/tutorials/markup/index.docbook b/doc/tutorials/markup/index.docbook new file mode 100644 index 0000000..fa84114 --- /dev/null +++ b/doc/tutorials/markup/index.docbook @@ -0,0 +1,5317 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"><!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &tde; DocBook Markup Guide</title> + +<authorgroup> +<author> +<personname><firstname>Lauri</firstname><surname>Watts</surname></personname> +<email>lauri@kde.org</email> +</author> +<author>&tde-authors;</author> +</authorgroup> + +<copyright> +<year>2000</year><year>2001</year><year>2002</year><year>2003</year> +<holder>Lauri Watts</holder> +</copyright> +<copyright> +<year>&tde-copyright-date;</year> +<holder>&tde-team;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>&tde-release-date;</date> +<releaseinfo>&tde-release-version;</releaseinfo> + +<abstract> +<para> +A reference guide to &tde; DocBook markup standards. +Please report any errors or omissions to +<email>trinity-devel@lists.pearsoncomputing.net</email>. +</para> +</abstract> + +<keywordset> +<keyword>TDE</keyword> +<keyword>Docbook</keyword> +<keyword>Documentation</keyword> +<keyword>Authors</keyword> +</keywordset> + +</bookinfo> + +<chapter id="markup-guide"> +<title>General &tde; markup style guide</title> + +<itemizedlist> +<listitem> +<para> +Format for readability, and content, not for a formatted document. +</para> +<para> +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 <quote>look</quote> of the correct tag. +</para> +<para> +You should use white space to make the DocBook source more readable to +the writer. Please do not indent unless it is absolutely necessary. +</para> +</listitem> + +<listitem> +<para> +Do what you can to ensure you turn in a <emphasis>valid</emphasis> +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 &tde; tools installed, you can use the +command <userinput><command>checkXML</command> +<filename>index.docbook</filename></userinput> to check for syntax +errors. No result from <command>checkXML</command> is a good result - +it means there are no problems. +</para> +</listitem> + +<listitem> +<para> +Non-English words should be tagged with <markup><foreignphrase +lang="de">Wort</foreignphrase></markup>. +</para> +</listitem> + +<listitem> +<para> +Underlining and CAPITALIZING entire words are leftovers from the days of +typewriters. They are no longer appropriate for today's documents. +</para> +</listitem> + +<listitem> +<para> +Do not use quotation marks in your documentation. If you want a word to +appear within quotation marks, simply enclose it between <sgmltag +class="element">quote</sgmltag> tags. +</para> +<informalexample> +<para> +This software is provided <markup><quote>as +is</quote>.</markup> +</para> +</informalexample> +</listitem> + +<listitem> +<para> +There are three different <quote>dashes</quote> that are commonly found +in documentation. +</para> +<itemizedlist> +<listitem> +<para> +The hyphen combines two or more words into one. For example, +<quote>mother-in-law</quote>. The hyphen can be entered directly from +the keyboard. +</para> +</listitem> +<listitem> +<para> +The en-dash is used to seperate numbers/dates/&etc;. For example, +<quote>Sections 1–3 review basic concepts</quote>. The en-dash +can be encoded using <sgmltag class="genentity">ndash</sgmltag>. +</para> +</listitem> +<listitem> +<para> +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 <sgmltag class="genentity">mdash</sgmltag>. +</para> +</listitem> +</itemizedlist> +</listitem> + +<listitem> +<para> +When trying to decide between an ordered and unordered list, simply ask +yourself the following question: <quote>Does the order of the listed +items matter?</quote> or <quote>If I change the order of the listed +items, does that change the meaning of the list?</quote>. If you answer +<quote>No</quote> to either question, then an unordered list is likely +the logical choice. +</para> +</listitem> + +<listitem> +<para> +All <sgmltag class="starttag">chapter</sgmltag> and <sgmltag +class="starttag">sect<replaceable>N</replaceable></sgmltag> tags must +have an <sgmltag class="attribute">id</sgmltag>. The <sgmltag +class="attribute">id</sgmltag> must be in all lower case, and with +dashes separating words. For example, <markup><sect1 +id="how-to-obtain-kapp"></markup>. +</para> +</listitem> + +<listitem> +<para> +All elements must have a full closing tag unless they are empty +elements. Empty elements must still be closed with a /. +</para> +<segmentedlist> +<segtitle>Incorrect</segtitle> +<segtitle>Correct</segtitle> +<seglistitem> +<seg><markup><para/Blah blah/ or <para>Blah +blah</></markup></seg> +<seg><markup><para>Blah blah</para></markup></seg> +</seglistitem> +</segmentedlist> +</listitem> + +<listitem> +<para> +No attribute minimization. +</para> +<segmentedlist> +<segtitle>Incorrect</segtitle> +<segtitle>Correct</segtitle> +<seglistitem> +<seg><markup>attribute=value</markup> or +<markup>attribute='value'</markup></seg> +<seg><markup>attribute="value"</markup></seg> +</seglistitem> +</segmentedlist> +</listitem> + +<listitem> +<para> +All entities must end with a semi-colon: +</para> + +<segmentedlist> +<segtitle>Incorrect</segtitle> +<segtitle>Correct</segtitle> +<seglistitem> +<seg><markup>%parameterentity</markup> or +<markup>&generalentity</markup></seg> +<seg><markup>%parameterentity;</markup> or +<markup>&generalentity;</markup></seg> +</seglistitem> +</segmentedlist> +</listitem> + +<listitem> +<para> +Element GIs (the first word in a tag) must be written in lower case +only. +</para> +<segmentedlist> +<segtitle>Incorrect</segtitle> +<segtitle>Correct</segtitle> +<seglistitem> +<seg><markup><MediaObject></markup> or +<markup><MEDIAOBJECT></markup></seg> +<seg><markup><mediaobject></markup></seg> +</seglistitem> +</segmentedlist> +<para> +Entities are also case sensitive, and will result in validation errors +if the case is wrong. +</para> +</listitem> + +<listitem> +<para> +Specify date and application's version in the format: +</para> + +<screen> + <markup><date>2000-12-31</date></markup> + <markup><releaseinfo>1.02.03</releaseinfo></markup> +</screen> + +<para> +The <sgmltag class="starttag">date</sgmltag> is the date of the last +update. The <sgmltag class="starttag">releaseinfo</sgmltag> 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 <sgmltag class="starttag">date</sgmltag> and <sgmltag +class="starttag">releaseinfo</sgmltag> as the English original. Please +respect this, it is the only way to manage efficiently both the writing +and the translation processes. +</para> +</listitem> + +<listitem> +<para> +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 +<email>kde-docbook@kde.org</email> 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 <quote>extra</quote> entities defined in the document +prologue. +</para> +</listitem> + +<listitem> +<para> +For language-independent entities, use +<filename>kdelibs/kdoctools/customization/entities/general.entities</filename> +and for language-specific entities, use +<filename>kdelibs/kdoctools/customization/<replaceable>lang</replaceable>/user.entities</filename>. Try +to avoid clashes with existing &tde; entities. +</para> +</listitem> + +<listitem> +<para> +The <filename>en/user.entities</filename> file should be updated +keeping in mind that translation must be possible. Here is an example of +how this translation can be managed: +</para> + +<example> +<title>Managing translatable entities</title> + +<para> +<sgmltag class="genentity">LMB</sgmltag> is en entity which stands for +<quote>Left Mouse Button</quote> +</para> + +<para> +When translating to French for example, do not translate only the entity +contents, please also translate the entity name to <sgmltag +class="genentity">BGS</sgmltag> (or <sgmltag +class="genentity">bgs</sgmltag>), to reflect the change in the +initials: +</para> + +<screen> <markup><!ENTITY "LMB" "left mouse button"></markup> <lineannotation>becomes</lineannotation> + <markup><!ENTITY "BGS" "bouton gauche de la souris"></markup></screen> + +<para> +Languages that decline nouns like German and Russian can use something +like the following: +</para> + +<screen><markup> + <!ENTITY "LMB" "linke Maustaste"> + <!ENTITY "LMBn" "linken Maustaste"> +</markup></screen> +</example> +</listitem> + +<listitem> +<para> +If you feel that some elements don't make fine enough a distinction, +feel free to use the attribute <sgmltag class="attribute">role</sgmltag> +(but please tell the DocBook team, as otherwise you may find your +document to be suddenly invalid). +</para> +</listitem> + +<listitem> +<para> +Use <sgmltag class="starttag">qandaset</sgmltag> for +&FAQ;s, not an <sgmltag +class="starttag">itemizedlist</sgmltag>. 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. +</para> +</listitem> + +<listitem> +<para> +Abbreviations and acronyms should be marked up as well. +</para> + +<para> +Use the DocBook tags <sgmltag class="starttag">abbrev</sgmltag> and +<sgmltag class="starttag">acronym</sgmltag> respectivly. +</para> + +<para> +Please keep them apart: acronyms are things like &GUI;, &tde;, +<acronym>GPL</acronym>, while abbreviations are things like &etc;, &ie;, +⪚. +</para> + +<para> +There are entities for the most common ones. +</para> +</listitem> + +<listitem> +<para> +Use <sgmltag class="starttag">glossterm</sgmltag> or <sgmltag +class="starttag">firstterm</sgmltag> each time you introduce a +technically significant new word. +</para> +</listitem> + +<listitem> +<para> +Keep in mind that the <quote>$</quote> sign is introduced by the shell, +and is not part of an environment variable's name: +</para> + +<informalexample> +<para> +<userinput><command>ls</command> <option>-l</option> +<parameter>$<envar>TDEDIR</envar></parameter></userinput> is marked up +as</para> +<screen><markup><userinput><command>ls</command> +<option>-l</option> +<parameter>$<envar>TDEDIR</envar></parameter> +</userinput></markup></screen> +<para><userinput><command>export</command> +<parameter>$<envar>TDEDIR</envar>=<replaceable>/usr/local/tde</replaceable></parameter></userinput> +is marked up as:</para> +<screen><markup><userinput> +<command>export</command> +<parameter>$<envar>TDEDIR</envar>=<filename> +/usr/local/tde</filename></parameter></userinput></markup></screen> +</informalexample> +</listitem> + +<listitem> +<para> +Only use <sgmltag class="starttag">ulink</sgmltag> for &URL;'s and not +for files, unlike <sgmltag class="starttag">A</sgmltag> in +<acronym>HTML</acronym>. Don't use it for email addresses either, they +have their own element, <sgmltag class="starttag">email</sgmltag>. +</para> +</listitem> + +<listitem> +<para> +The elements <sgmltag class="starttag">beginpage</sgmltag> and <sgmltag +class="starttag">bridgehead</sgmltag> are disallowed and have been +removed from the &tde; customized <acronym>DTD</acronym>. (They are not +meant for new technical documentation.) <sgmltag +class="starttag">revisionhistory</sgmltag> has been removed also: we are +using <acronym>SVN</acronym> already. +</para> +</listitem> + +</itemizedlist> + +</chapter> + +<chapter id="purpose"> +<title>Purpose of this document</title> + +<para> +The purpose of this document is to describe how markup has been standardized within +&tde; documentation only. +</para> + +<para> +This document is <emphasis>not</emphasis> to be considered more +authoritative than the DocBook documentation, including the O'Reilly +Duck book. However, there are places where the &tde; +<acronym>DTD</acronym> is more restrictive than, or just differs from, +the <acronym>OASIS</acronym> <acronym>DTD</acronym>, and these are noted +in this document. In these cases, follow the instructions here. +</para> + +<para> +Please read and make use of the other documentation available to you, +which is much more comprehensive. This document is not intended to be +more than a quick reference for &tde; authors, to clarify how the +DocBook &XML; elements are used within the &tde; Documentation. +</para> + +<sect1> +<title>Other reference material</title> + +<para> +Please take a look at the following reference material, rather than +relying on this document to answer all your questions. +</para> + +<variablelist> +<varlistentry> +<term><ulink url="http://www.docbook.org/">The Duck book</ulink></term> +<listitem> +<para> +The complete DocBook <acronym>SGML</acronym> (and now +&XML;) reference. Available as a download in several +formats, so you can keep a copy on your hard drive for reference. Also +available for sale in hard copy - if you see yourself doing a lot of +DocBook Authoring, you definitely ought to consider buying it. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><ulink +url="http://opensource.bureau-cornavin.com/crash-course/">The Crash +Course to Docbook</ulink></term> +<listitem> +<para> +A non-&tde; specific crash course to marking up documentation. This is the +starting point for all &tde; documents, including the markup issues discussed +here. Note that the current version is written for +<acronym>SGML</acronym>, but the concepts are still correct for &XML;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The &tde; Documentation Template</term> +<listitem> +<para> +Covers many things not mentioned here, including required and optional +chapters, the preferred way to mark up the prologue and bookinfo +sections, and how to deal with licensing and credits. It can be found +in <filename>kdelibs/kdoctools/template.docbook</filename> in <acronym>CVS</acronym>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://www.millin.de/linux_docbook_xmlbuch.html">DocBook-XML</ulink> (in German)</term> +<listitem> +<para>A very nice book, in German only unfortunately, but comes highly recommended.</para> +</listitem> +</varlistentry> + + +</variablelist> + +</sect1> +</chapter> + +<chapter id="prologue"> +<title>The Prologue</title> + +<screen><markup> +<?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 <replaceable>kmyapplication</replaceable> "<application>KMyApp</application>"> + <!ENTITY kappname "<replaceable>&kmyapplication;</replaceable>"><!-- replace kmyapplication here + do *not* replace kappname--> + <!ENTITY package "<replaceable>tde-module</replaceable>"><!-- 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 --> +]></markup></screen> + + +<para> +In general, this needs minimal changing from the template. The items +you <emphasis>must</emphasis> change are the entities +<quote>kappname</quote>, <quote>package</quote>, and <quote>English</quote>. +</para> + +<para> +The entity <quote>kappname</quote> 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 +(<quote>&kmyapplication;</quote>) as follow: +</para> + +<example> +<title>Setting up the global <quote>kappname</quote> entity</title> + +<screen> +From: +<markup> +<!ENTITY kappname "&kmyapplication;" -- this only *seems* redundant --> +</markup> +To: +<markup> +<!ENTITY kappname "&kate;" -- this only *seems* redundant --> +</markup> +</screen> +</example> + +<para>In short: change any occurrence of <quote>kmyapplication</quote> +to the real name of your application. Do <emphasis>not</emphasis> use +<quote>kappname</quote> or <quote>kapp</quote> directly in a document +yourself.</para> + +<para>The entity <quote>package</quote> is used similarly. It allows +us to insert a single piece of <quote>boilerplate</quote> text into +every document, and have the correct package name inserted when the +document is compiled. Use the cvs module name, in lower case, ⪚ +<quote>tdeedu</quote> or <quote>tdebase</quote>.</para> + +<para>The entity <sgmltag class="paramentity">addindex</sgmltag> is a toggle. If +set to <quote>INCLUDE</quote> a document index will be automatically +generated. It is normally set instead to <quote>IGNORE</quote>, and should +not be changed unless you really do want to generate an index. You can find +out more about indexes in <xref linkend="references-indexes-glossary"/>.</para> + +<example> +<title>A &tde; User Manual Prolog</title> + +<para>Here is an example of a completely set up prolog, as it normally +looks. This is the prolog from the &amor; documentation</para> + +<screen><markup><?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"> +]></markup></screen> +</example> + +<note> +<para> +The entity <quote>English</quote> 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: +</para> + +<itemizedlist> +<listitem> +<para> +Afrikaans +</para> +</listitem> +<listitem> +<para> +British-English +</para> +</listitem> +<listitem> +<para> +Bulgarian +</para> +</listitem> +<listitem> +<para> +Catalan +</para> +</listitem> +<listitem> +<para> +Czech +</para> +</listitem> +<listitem> +<para> +Danish +</para> +</listitem> +<listitem> +<para> +German +</para> +</listitem> +<listitem> +<para> +Greek +</para> +</listitem> +<listitem> +<para> +English +</para> +</listitem> +<listitem> +<para> +Spanish +</para> +</listitem> +<listitem> +<para> +Estonian +</para> +</listitem> +<listitem> +<para> +Finnish +</para> +</listitem> +<listitem> +<para> +Faroese +</para> +</listitem> +<listitem> +<para> +French +</para> +</listitem> +<listitem> +<para> +Hebrew +</para> +</listitem> +<listitem> +<para> +Hungarian +</para> +</listitem> +<listitem> +<para> +Indonesian +</para> +</listitem> +<listitem> +<para> +Italian +</para> +</listitem> +<listitem> +<para> +Japanese +</para> +</listitem> +<listitem> +<para> +Dutch +</para> +</listitem> +<listitem> +<para> +Norwegian (Note, this is only for compatibility, either Norwegian-Bokmal or +Norwegian-Nynorsk should be used in preference.) +</para> +</listitem> +<listitem> +<para> +Norwegian-Bokmal +</para> +</listitem> +<listitem> +<para> +Norwegian-Nynorsk +</para> +</listitem> +<listitem> +<para> +Polish +</para> +</listitem> +<listitem> +<para> +Portuguese +</para> +</listitem> +<listitem> +<para> +Brasilian-Portuguese +</para> +</listitem> +<listitem> +<para> +Romanian +</para> +</listitem> +<listitem> +<para> +Russian +</para> +</listitem> +<listitem> +<para> +Slovak +</para> +</listitem> +<listitem> +<para> +Slovenian +</para> +</listitem> +<listitem> +<para> +Serbian +</para> +</listitem> +<listitem> +<para> +Swedish +</para> +</listitem> +<listitem> +<para> +Turkish +</para> +</listitem> +<listitem> +<para> +Ukrainian +</para> +</listitem> +<listitem> +<para> +Walloon +</para> +</listitem> +<listitem> +<para> +Xhosa +</para> +</listitem> +<listitem> +<para> +Continental-Chinese +</para> +</listitem> +<listitem> +<para> +Traditional-Chinese +</para> +</listitem> +</itemizedlist> +</note> + +<sect1 id="book-and-bookinfo"> +<title><sgmltag class="element">book</sgmltag> and the <sgmltag +class="element">bookinfo</sgmltag> section</title> + +<para> +The <sgmltag class="element">bookinfo</sgmltag> section is most easily prepared +by copying the &tde; template. +</para> + +<variablelist> +<varlistentry> +<term><sgmltag class="starttag">book lang="&language"</sgmltag> +<anchor id="book"/> +</term> +<listitem> +<para> +Contains the entire document. Most important thing to remember is the <sgmltag +class="attribute">lang</sgmltag> attribute, which must contain exactly <sgmltag +class="attvalue">&language;</sgmltag>, and must not be changed. To set the +language for the document, change the entity as described in the <link +linkend="prologue">prologue</link> section. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">bookinfo</sgmltag> +<anchor id="bookinfo"/> +</term> +<listitem> +<para> +Wraps the <quote>meta</quote> information – information about +the document, not about the application it is documenting. Required in +&tde; documentation. No attributes. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">authorgroup</sgmltag> +<anchor id="authorgroup"/> +</term> +<listitem> +<para> +Wraps the author information, and may also contain <sgmltag +class="starttag">othercredit</sgmltag> information. Required in &tde; +documentation. No attributes. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">author</sgmltag> +<anchor id="author"/> +</term> +<listitem> +<para> +Required element in the header section of all &tde; documentation. Use this +element <emphasis>only</emphasis> for the author(s) of the document. Other +contributers (developers, translators, and so on) should be credited in the +<link linkend="othercredit"><sgmltag +class="starttag">othercredit</sgmltag></link> section. No attributes. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">personname</sgmltag><anchor id="personname"/></term> +<listitem> +<para>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.</para></listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">firstname</sgmltag><anchor id="firstname"/></term> +<listitem> +<para> +The contributor's first name. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">othername</sgmltag><anchor +id="othername"/></term> +<listitem> +<para> +If the author normally uses more than a first and surname, you can add +further names here. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">surname</sgmltag><anchor +id="surname"/></term> +<listitem> +<para> +The author's surname. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">email</sgmltag></term> +<listitem> +<para> +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. +</para> + +<note><para>In previous versions of DocBook, <sgmltag +class="starttag">email</sgmltag> could not be used directly inside +<sgmltag class="starttag">author</sgmltag>. Since DocBook XML V 4.2 +(used by &tde; for documents after &tde; 3.1.x), this is possible, +which simplifies this markup considerably.</para></note> + +<para> +In other contexts in the document, <sgmltag +class="starttag">email</sgmltag> is used to contain any email address, +and is not used inside the <sgmltag class="element">address</sgmltag> +element. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">othercredit role=""</sgmltag> +<anchor id="othercredit"/></term> +<listitem> +<para> +Similary to <sgmltag class="element">author</sgmltag>, 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. +</para> + +<para> +The <sgmltag class="attribute">role</sgmltag> attribute is required, and can +contain any one of the following: +</para> + +<itemizedlist> +<listitem> +<para>Translator</para> +</listitem> +<listitem> +<para>Developer</para> +</listitem> +<listitem> +<para>Reviewer</para> +</listitem> +<listitem> +<para>Graphist</para> +</listitem> +<listitem> +<para>Musician</para> +</listitem> +</itemizedlist> + +<para> +The <sgmltag class="element">othercredit</sgmltag> element also includes the +<sgmltag class="element">contrib</sgmltag> element. +</para> + +<variablelist> +<varlistentry> +<term><sgmltag class="starttag">contrib</sgmltag> +<anchor id="contrib"/></term> +<listitem> +<para> +The role this contributor played in the document or application preparation. +This could contain something like: +</para> + +<itemizedlist> +<listitem> +<para>Developer</para> +</listitem> +<listitem> +<para><foreignphrase lang="de">Deutsche Übersetzung</foreignphrase></para> +</listitem> +<listitem> +<para>Reviewer</para> +</listitem> +<listitem> +<para><foreignphrase lang="fr">Traduction française</foreignphrase></para> +</listitem> +</itemizedlist> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">corpauthor</sgmltag> +<anchor id="corpauthor"/></term> +<listitem> +<para> +This is used in very specific circumstances, where an organization +(⪚ <quote>The TDE Team</quote>) 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. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">copyright</sgmltag> +<anchor id="copyright"/></term> +<listitem> +<para> +This is a wrapper for copyright information. <sgmltag +class="element">copyright</sgmltag> must contain these elements: +</para> + +<variablelist> +<varlistentry> +<term><sgmltag class="starttag">year</sgmltag><anchor id="year"/></term> +<listitem> +<para> +Add one <sgmltag class="element">year</sgmltag> 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 <sgmltag +class="element">year</sgmltag> elements, and use the 4 digit +<quote>YYYY</quote> format. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">holder</sgmltag><anchor id="holder"/></term> +<listitem> +<para> +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 <sgmltag +class="element">copyright</sgmltag> sections, rather than trying to +fit multiple names in the one section. +</para> +</listitem> +</varlistentry> +</variablelist> + +<para> +Copyright is automatically held by the author of the document, but the +<sgmltag class="element">copyright</sgmltag> element is still required +for all &tde; documentation. None of the elements contained have any +attributes. +</para> +<para>Please do <emphasis>not</emphasis> add more names or years to +existing <sgmltag class="starttag">holder</sgmltag> or <sgmltag +class="starttag">year</sgmltag> elements. Add more, if they are +required, or have multiple <sgmltag +class="element">copyright</sgmltag> sections.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">legalnotice</sgmltag><anchor +id="legalnotice"/></term> +<listitem> +<para> +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 +<sgmltag>&FDLNotice;</sgmltag> entity, which inserts some information into +the document about the document's license (and <emphasis>not</emphasis> the +license of the application you are describing.) +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="date"><sgmltag class="starttag">date</sgmltag></term> +<listitem> +<para> +<emphasis>The date is very important.</emphasis> 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 <emphasis>original</emphasis> document, +and you must <emphasis>not</emphasis> change the date if you are a +translator. The format of the date is very important. It +<emphasis>must</emphasis> be in the <acronym>ISO</acronym>, with +<quote>literal</quote> delimiters, in the form +<quote>yyyy-mm-dd</quote>. Please be extremely careful about this, +and triple check it before you send in the document. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="releaseinfo"><sgmltag class="starttag">releaseinfo</sgmltag></term> +<listitem> +<para> +This should match exactly the version of the +<emphasis>application</emphasis> 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 <quote>1.4</quote>, you may write +<markup><releaseinfo>1.4</releaseinfo></markup>, and you +do not need to make it +<markup><releaseinfo>1.04.00</releaseinfo></markup></para> +<para>This is <emphasis>not</emphasis> the version of the document. +There are no attributes, and this element is required in &tde; +documentation.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="abstract"><sgmltag class="starttag">abstract</sgmltag></term> +<listitem> +<para> +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 <quote>KFoo is a +small fast network enabled foo generator, suitable for both beginner and +advanced foo users.</quote>. +</para> +<para>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, +<quote>This is the KFoo handbook and describes KFoo 1.2.</quote> on +its own, is not.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="keywordset"><sgmltag class="starttag">keywordset</sgmltag></term> +<listitem> +<para> +A wrapper for a set of keywords suitable for search engines. Required +for &tde; Documentation, and there are no attributes. The <sgmltag +class="element">keywordset</sgmltag> should contain several +<sgmltag class="starttag">keyword</sgmltag>s. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="keyword"><sgmltag class="starttag">keyword</sgmltag></term> +<listitem> +<para> +Add one <sgmltag class="starttag">keyword</sgmltag> inside the <sgmltag +class="starttag">keywordset</sgmltag> for each search term. You must +include at a minimum the terms <quote>TDE</quote>, the name of the +application you are documenting, and the name of the package it is found +in, for example <quote>tdegames</quote>. The keywords should be in +order from most general first (that is, <acronym>TDE</acronym>) through +less general, to the most specific. Add two or three more relevant words +that people might search with, ⪚, for the application &kwrite; you +might add <quote>editor</quote> and <quote>text</quote>. This is +required for &tde; Documentation, and there are no attributes. +</para></listitem> +</varlistentry> + +<varlistentry> +<term id="translator-hooks"><markup><!-- TRANS:ROLES_OF_TRANSLATORS +--></markup></term> +<listitem> +<para> +This line is specific to &tde; documentation. Although it's a comment, +it is <emphasis>absolutely</emphasis> 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 <sgmltag +class="element">othercredit</sgmltag> sections here as appropriate. +</para> +</listitem> +</varlistentry> +</variablelist> + +<example> +<title>The bookinfo section from the &tde; template</title> +<screen width="40"><markup> +<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> +</markup></screen> +</example> +</sect1> +</chapter> + +<chapter id="section-tags"> +<title>Chapters and Sections</title> + +<variablelist> +<varlistentry> +<term id="chapter"><sgmltag class="starttag">chapter +id=""</sgmltag></term> +<listitem> +<para> +Use chapters to break up the document into smaller chunks. A chapter +break should occur when a major subject change happens. Use sections +within the chapter when the subject changes, but you are still +discussing a particular aspect of a larger subject. +</para> + +<para> +For example, going from discussing how to use the application, to how to +configure the application would be worthy of a new chapter. Moving from +discussing how to specifically configure the application on SuSE, to how +to specifically configure the application on &RedHat;, would be a new +section in a larger <quote>Configuration</quote> chapter. +</para> + +<para> +Chapters must have an <sgmltag class="attribute">id</sgmltag>. This is +the only attribute used in &tde; documentation. For &tde; Documents, +this id must be in lower case, and with a hyphen (-) to separate words. +Please don't use spaces, underscores, or run the words together. For +<acronym>HTML</acronym> generation, the chapter id and most <sgmltag +class="starttag">sect1</sgmltag> id's are used to name the separate +<abbrev>HTML</abbrev> pages, so take care to make them sensible and +descriptive. For translators, these id's should be translated, but you +will need to take care to also translate references to the id's in +<sgmltag class="starttag">link</sgmltag> and <sgmltag +class="starttag">xref</sgmltag> elements in other parts of the document. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="title"> +<sgmltag class="starttag">title</sgmltag></term> +<listitem> +<para> +Titles are used in many places, but the most common is the Chapter and +Section headings. Make sure to use sensible titles, as these will also +be that chapter's (or section's) entry in the table of contents, so people +will rely on these to find the part of the document they are interested +in. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="sect1"><sgmltag class="starttag">sect1 id=""</sgmltag>, +<sgmltag class="starttag">sect2</sgmltag>, <sgmltag +class="starttag">sect3</sgmltag>, <sgmltag +class="starttag">sect4</sgmltag>, <sgmltag +class="starttag">sect5</sgmltag></term> +<listitem> +<anchor id="sect2"/><anchor id="sect3"/><anchor id="sect4"/><anchor +id="sect5"/> +<para> +Use sections to break chapters up into smaller pieces. Use similar +criteria on where to divide them as you would for chapters. +</para> + +<para> +Sections require a <sgmltag class="starttag">title</sgmltag>. Sections +are nested according to the number - a <sgmltag +class="starttag">sect2</sgmltag> can contain any number of <sgmltag +class="starttag">sect3</sgmltag>, which can contain <sgmltag +class="starttag">sect4</sgmltag>, but a <sgmltag +class="starttag">sect2</sgmltag> can't directly contain a <sgmltag +class="starttag">sect4</sgmltag>. +</para> + +<para> +<sgmltag class="starttag">sect1</sgmltag> requires an id attribute, and +you can use id's on the other section tags if you want to later link +directly to them from other parts of the document. <sgmltag +class="attribute">id</sgmltag> is the only attribute used in &tde; +Documentation. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="sect1info"><sgmltag class="starttag">sect1info</sgmltag>, +<sgmltag class="starttag">sect2info</sgmltag>, <sgmltag +class="starttag">sect3info</sgmltag>, <sgmltag +class="starttag">sect4info</sgmltag>, <sgmltag +class="starttag">sect5info</sgmltag></term> <listitem><anchor +id="sect2info"/><anchor id="sect3info"/><anchor id="sect4info"/><anchor +id="sect5info"/> +<para> +The section info elements are rarely used in &tde; Documentation. +They are appropriate for documents where some smaller sections are +contributed by third parties, or where the document covers multiple +applications. The contents are more or less the same as those of the +<sgmltag class="starttag">bookinfo</sgmltag> section, although they +tend to be briefer.</para> +<para>Please ensure if you use these elements that you add the +translation placeholder comments as you do in the prolog.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="appendix"> +<sgmltag class="starttag">appendix</sgmltag></term> +<listitem> +<para> +The standard installation instructions for all applications are +contained in an <sgmltag class="starttag">appendix</sgmltag>, and are +normally required for &tde; documents. Although the installation +instructions as found in the template are reasonably complete, and +need no customization for most applications, authors are very strongly +encouraged to expand on them. For example, links to web pages, where +to find libraries, plugins, screenshots of the application in a +particular configuration, or any other information you can think of. +</para> + +<para>If the application is only distributed with &tde;, there is +little use in repeating the same installation instructions for every +manual. You may leave it out entirely, unless you have further +information to add.</para> + +<para> +For other purposes, appendices are used infrequently in &tde; +Documentation. An appendix can be found, for example, in the &kppp; +document, containing such things as Hayes Modem commands. Only use an +appendix if you think it's very necessary. In most cases, the +information it would contain would be better moved to the main document. +In the example of &kppp;, this information is vital to a few people, but +extremely uninteresting to the majority, so it was placed in an +appendix. +</para> +</listitem> +</varlistentry> + +</variablelist> +</chapter> + +<chapter id="links"> +<title>The linking elements</title> + +<variablelist> +<varlistentry> +<term id="link"><sgmltag class="starttag">link +linkend=""</sgmltag></term> + +<listitem> +<para> +The most common link. Use this to turn a word or phrase into a link to +another part of the document. <sgmltag +class="attribute">linkend</sgmltag> is the only attribute we use. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="ulink"><sgmltag class="starttag">ulink url=""</sgmltag></term> +<listitem> +<para>A link that refers to a document using it's +<acronym>URI</acronym>. Use this for websites and ftp sites, but not +for <link linkend="email">email addresses</link>, which have their own +specific tag. Please do <emphasis>not</emphasis> use this to link to +other documents on the local system. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="anchor"> +<sgmltag class="starttag">anchor id=""/</sgmltag></term> +<listitem> +<para> +Marks a place in the document, which you can use to link to. Note that +the <sgmltag class="attribute">id</sgmltag> attribute on any other +element where it is valid, will automatically generate an +<acronym>HTML</acronym> anchor in generated <acronym>HTML</acronym>, so +you do not need to duplicate these. Use anchors only when you need to +jump into the middle of a longer page, for example, to a particular menu +item, or to a particular option in a preference dialog. +</para> +<note> +<para> +<sgmltag class="emptytag">anchor</sgmltag> is an empty element, and must +be closed with a /. +</para> +</note> +</listitem> +</varlistentry> + +<varlistentry> +<term id="xref"><sgmltag class="emptytag">xref +linkend=""</sgmltag></term> +<listitem> +<para> +A cross reference to another part of the document. Use this when you +want to refer to the section without the name. This is one of very few +unclosed elements allowed. <sgmltag class="attribute">linkend</sgmltag> +is the only attribute we currently use. +</para> +<note> +<para> +<sgmltag class="emptytag">xref</sgmltag> is an empty element, and must +be closed with a /. +</para> +</note> +</listitem> +</varlistentry> + +<varlistentry> +<term id="email"> +<sgmltag class="starttag">email</sgmltag></term> +<listitem> +<para> +Use this to enclose an email address. Don't add <quote>mailto:</quote> +to the email address, and don't use <sgmltag class="starttag">ulink +url=""</sgmltag> for email addresses. No attributes required. +</para> +</listitem> +</varlistentry> + +</variablelist> + +</chapter> + +<chapter id="lists"> +<title>Lists</title> + +<variablelist> +<varlistentry> +<term id="listitem"><sgmltag class="starttag">listitem</sgmltag></term> +<listitem> +<para> +<sgmltag class="starttag">listitem</sgmltag> is the main building block +of almost all the lists. It should always contain some other markup, +usually a <sgmltag class="starttag">para</sgmltag> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="orderedlist"><sgmltag +class="starttag">orderedlist</sgmltag></term> +<listitem> +<para> +Use this type of list when the order of the items matters, but they are +not a set of steps that are carried out to achieve something. A good +example is a list of things in order of importance. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="itemizedlist"><sgmltag +class="starttag">itemizedlist</sgmltag></term> +<listitem> +<para> +Use an itemized list when the order of the items is not +important. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="variablelist"><sgmltag +class="starttag">variablelist</sgmltag></term> +<listitem> +<para> +A list that has two sections for each entry. Examples: A menu item, and +what the menu item does, An action, and its result, or a term and its +definition. This is a very common type of list. (Almost this entire +document is composed of variable lists.) +</para> +<para> +<sgmltag class="starttag">variablelist</sgmltag> contains the following +elements: +</para> + +<variablelist> +<varlistentry> +<term id="varlistentry"><sgmltag +class="starttag">varlistentry</sgmltag></term> +<listitem> +<para> +A <sgmltag class="starttag">varlistentry</sgmltag> is a wrapper around +each pair in the variable list. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="term"><sgmltag class="starttag">term</sgmltag></term> +<listitem> +<para> +To reuse the above examples, the <sgmltag +class="starttag">term</sgmltag> for each pair would be the menu item you +are describing, the action, or the term you are defining. You can use +the <sgmltag class="attribute">id</sgmltag> attribute for this element, +which is quite convenient in long lists such as a menu reference, +enabling you to link directly to a particular menu item from another +part of the document. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><sgmltag class="starttag">listitem</sgmltag></term> +<listitem> +<para> +As described above the <sgmltag class="starttag">listitem</sgmltag> is +used inside a <sgmltag class="starttag">varlistentry</sgmltag> to hold +the second part of the pair: The result of choosing that menu item, for +example, the consequences of an action, or the definition of the term. +</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term id="procedure"><sgmltag +class="starttag">procedure</sgmltag></term> +<listitem> +<para> +Use a procedure list when you are listing a sequence of steps which are +performed in a particular order. +</para> +<para> +A procedure contains only one tag: +</para> + +<variablelist> +<varlistentry><term id="step"><sgmltag +class="starttag">step</sgmltag></term> +<listitem> +<para> +A step is one of the sequence of events that make up a +procedure. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="substeps"><sgmltag class="starttag">substeps</sgmltag></term> +<listitem> +<para>A step can contain substeps</para> +</listitem> +</varlistentry> + +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term id="simplelist"><sgmltag +class="starttag">simplelist</sgmltag></term> +<listitem> +<para> +A simple list is just that - a simple list, with no formatting +required. A simple list can contain only one type of element: +</para> + +<variablelist> +<varlistentry><term id="member"><sgmltag +class="starttag">member</sgmltag></term> +<listitem> +<para> +Members of a simple list. +</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term id="segmentedlist"> +<sgmltag class="starttag">segmentedlist</sgmltag></term> +<listitem> +<para> +A Segmented list is a very particular type of list. Use +sparingly, as it's very difficult to get these right, and most content +appropriate for a segmented list could just as well fit the table model. +</para> + +<example> +<title>A Segmented List</title> + +<screen><markup> +<segmentedlist> +<segtitle>Name</segtitle> +<segtitle>Occupation</segtitle> +<segtitle>Favorite Food</segtitle> +<seglistitem> +<seg>Tux</seg> +<seg>Linux Mascot</seg> +<seg>Herring</seg> +</seglistitem> +<seglistitem> +<seg>Konqui</seg> +<seg>The TDE Dragon</seg> +<seg>Gnomes</seg> +</seglistitem> +</segmentedlist></markup></screen> + +<segmentedlist><segtitle>Name</segtitle> +<segtitle>Occupation</segtitle> +<segtitle>Favorite Food</segtitle> + +<seglistitem><seg>Tux</seg> +<seg>Linux Mascot</seg> +<seg>Herring</seg></seglistitem> + +<seglistitem><seg>Konqui</seg> +<seg>The TDE Dragon</seg> +<seg>Gnomes</seg></seglistitem></segmentedlist> +</example> + +<para>The segmented list contains the following elements:</para> + +<variablelist> + +<varlistentry> +<term id="segtitle"><sgmltag class="starttag">segtitle</sgmltag></term> +<listitem> +<para> +The title each segment will have +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="seglistitem"><sgmltag +class="starttag">seglistitem</sgmltag></term> +<listitem> +<para> +A set of entries in the list +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="seg"><sgmltag class="starttag">seg</sgmltag></term> +<listitem> +<para> +The contents of the entries in the list. In each +<sgmltag class="starttag">seglistitem</sgmltag> there is one +<sgmltag class="starttag">seg</sgmltag> for each +<sgmltag class="starttag">segtitle</sgmltag>. +</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +</variablelist> +</chapter> + +<chapter id="tables"> +<title>Tables</title> + +<variablelist> + +<varlistentry> +<term id="informaltable"><sgmltag +class="starttag">informaltable</sgmltag></term> +<listitem> +<para> +This is the table type used most in &tde; Documentation. Please be very +sure that what you are marking up as a table, is actually tabular data, +as in many cases a <sgmltag class="starttag">variablelist</sgmltag> is +more appropriate. Please do not use any of the presentation attributes +to make tables <quote>look nice</quote>. The only attribute currently +allowed in &tde; Documents is <sgmltag class="attribute">pgwide</sgmltag>. +</para> + +<para> +An <sgmltag class="starttag">informaltable</sgmltag> must contain a +<sgmltag class="starttag">tgroup cols=""</sgmltag> entry. Informal +tables have no specific title, if you wish the table to be titled and to +have an entry in the table of contents, you should use <link +linkend="table"><sgmltag class="starttag">table</sgmltag></link>. Do +not use any attributes other than <sgmltag +class="attribute">pgwide</sgmltag> on tables or informal tables for +&tde; documentation. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="table"><sgmltag class="starttag">table</sgmltag></term> +<listitem> +<para> +A formal table with a title. Tables will have their own separate entry +in the table of contents. Other than the addition of a title, they are +marked up the same as an <sgmltag +class="starttag">informaltable</sgmltag>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="tgroup"><sgmltag class="starttag">tgroup +cols=""</sgmltag></term> +<listitem> +<para> +A <sgmltag class="starttag">tgroup</sgmltag> is a required element in a +table. The <sgmltag class="attribute">cols</sgmltag> attribute is +required, and should be completed with the number of columns the table +is to hold. No other attributes used in &tde; Documentation. +</para> + +<para> +A <sgmltag class="element">tgroup</sgmltag> must contain a <sgmltag +class="element">tbody</sgmltag> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="tbody"><sgmltag class="starttag">tbody</sgmltag></term> +<listitem> +<para> +A <sgmltag class="element">tbody</sgmltag> is a required element in a +table. There are no attributes. The <sgmltag +class="element">tbody</sgmltag> contains rows. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="row"><sgmltag class="starttag">row</sgmltag></term> +<listitem> +<para> +A <sgmltag class="element">row</sgmltag> corresponds directly with the +rows of the table. Rows contain <sgmltag +class="starttag">entry</sgmltag> tags, one for each column in the table, +as specified by the <sgmltag class="attribute">cols</sgmltag> attribute +on the <link linkend="tgroup"><sgmltag +class="starttag">tgroup</sgmltag></link> tag. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="entry"><sgmltag class="starttag">entry</sgmltag></term> +<listitem> +<para> +The entry is the basic building block of a table. Each entry corresponds +to one <quote>data cell</quote> in the table. There must be as many +<sgmltag class="starttag">entry</sgmltag> tags in each row as the +<sgmltag class="attribute">cols</sgmltag> attribute on the <link +linkend="tgroup"><sgmltag class="starttag">tgroup</sgmltag></link> tag. +There are no attributes used in &tde; Documentation. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="thead"><sgmltag class="starttag">thead</sgmltag></term> +<listitem> +<para> +<sgmltag class="starttag">thead</sgmltag> can be used to create a +heading row for the table. It must appear before the <sgmltag +class="element">tbody</sgmltag> element, and should normally contain one +<sgmltag class="element">row</sgmltag> and as many <sgmltag +class="element">entry</sgmltag> elements as the rest of the table. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="tfoot"><sgmltag class="starttag">tfoot</sgmltag></term> +<listitem> +<para><sgmltag class="starttag">tfoot</sgmltag> is not currently used in +&tde; Documentation. If you want to use it, please see the Duck book +for information. +</para> +</listitem> +</varlistentry> +</variablelist> + +<example> +<title>An <sgmltag class="starttag">informaltable</sgmltag> +template</title> +<screen width="40"> +<markup> +<informaltable> +<tgroup cols="2"> +<tbody> +<row> +<entry></entry> +<entry></entry> +</row> +</tbody> +</tgroup> +</informaltable> +</markup> +</screen> +</example> + +<example> +<title>A <sgmltag class="starttag">table</sgmltag> template</title> +<screen width="40"> +<markup> +<table> +<title></title> +<tgroup cols="2"> +<tbody> +<row> +<entry></entry> +<entry></entry> +</row> +</tbody> +</tgroup> +</table> +</markup> +</screen> +</example> + +</chapter> + +<chapter id="gui"> +<title>The &GUI; elements, menus, toolbars and +shortcuts.</title> + +<variablelist> + +<varlistentry> +<term id="action"><sgmltag class="starttag">action</sgmltag></term> +<listitem> +<para> +The result of a user action. This does not need to be a complete +sentence, or even more than a single word. For example, <quote>This +button <action>closes the dialog</action>.</quote> The main +place you will find this in &tde; Documentation is in the Menu and +Command reference chapters of the manuals. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="guibutton"><sgmltag +class="starttag">guibutton</sgmltag></term> +<listitem> +<para> +The text on a button that you click on. Icons, Radio buttons and check +boxes are not considered buttons in this sense. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="guiicon"><sgmltag class="starttag">guiicon</sgmltag></term> +<listitem> +<para> +The name or description of an icon. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="guilabel"><sgmltag class="starttag">guilabel</sgmltag></term> +<listitem> +<para> +The text of anything that is labelled on screen, and isn't a button, +icon, menu, or menu item. For example, the name of a dialog box, the +name of a tab in that dialog box, and the name of a label by a checkbox. +</para> +<para>Take care that the text exactly matches the label on screen. If +it has a <literal>:</literal> on the dialog box, put the +<literal>:</literal> into your documentation. Match the +capitalization. There is a script in the tde-i18n module called +<filename>check-gui-texts</filename> which you can use to help check +that your text matches exactly what is in the application. During +translation, the translators can use this script to generate +translations from their translations of the &GUI; itself, but this +will only work if the English text matches precisely.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="guimenu"><sgmltag class="starttag">guimenu</sgmltag></term> +<listitem> +<para> +The top level name of a menu (that is, the name you can see on the menu +bar when the menu isn't open). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="guimenuitem"><sgmltag +class="starttag">guimenuitem</sgmltag></term> +<listitem> +<para> +The final item you select on the menu, that actually performs an action. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="guisubmenu"><sgmltag +class="starttag">guisubmenu</sgmltag></term> +<listitem> +<para> +A submenu. That is, a menu which has items both above and below it in +the hierarchy. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="keycap"><sgmltag class="starttag">keycap</sgmltag></term> +<listitem> +<para> +A keycap is a key as it is labelled on your keyboard. +<keycap>Home</keycap> is a keycap on a standard English keyboard. +<keycap>Alt Gr</keycap> is a standard key on many European keyboards. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="keycode"><sgmltag class="starttag">keycode</sgmltag></term> +<listitem> +<para> +The internal identifier for a key on the keyboard. Used very +infrequently, but you may find need for it, for example when describing +entries in rc files. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="keysym"><sgmltag class="starttag">keysym</sgmltag></term> +<listitem> +<para> +Right arrow is the <sgmltag class="starttag">keysym</sgmltag> for the +<sgmltag class="starttag">keycap</sgmltag> that looks like +<keycap>-></keycap>. Please note this is a &tde; specific use of +<sgmltag class="starttag">keysym</sgmltag>, and does not precisely +follow the examples in the Duck Book. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="menuchoice"><sgmltag +class="starttag">menuchoice</sgmltag></term> +<listitem> +<para> +A menuchoice describes a menu entry. You should use <sgmltag +class="starttag">menuchoice</sgmltag> anywhere you are describing how +to reach a menu item. In normal text, there are no particular +requirements. In a menu reference, the <sgmltag +class="starttag">menuchoice</sgmltag> should also contain a <sgmltag +class="starttag">shortcut</sgmltag> element describing the keyboard +shortcut, and the contents should also be marked up with <sgmltag +class="starttag">accel</sgmltag> as appropriate. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="shortcut"><sgmltag class="starttag">shortcut</sgmltag></term> +<listitem> +<para> +A key combination that is a shortcut for a menu item. This is +<emphasis>only</emphasis> used inside <sgmltag +class="starttag">menuchoice</sgmltag> and contains <sgmltag +class="starttag">keycombo</sgmltag> or <sgmltag +class="starttag">keycap</sgmltag> that is defined as the keyboard +shortcut in the menu. In the markup, it appears before the actual menu +entries inside the <sgmltag class="starttag">menuchoice</sgmltag> You do +not need to describe the shortcut every time the menu item is mentioned +in the text, although it may be appropriate to do so on some occasions. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="mousebutton"><sgmltag +class="starttag">mousebutton</sgmltag></term> +<listitem> +<para> +The normal name of a mouse button. It will be normally be one +of:</para> + +<itemizedlist> +<listitem> +<para><markup><mousebutton>left</mousebutton></markup> or +the entity <sgmltag class="genentity">LMB</sgmltag> +</para> +</listitem> + +<listitem> +<para><markup><mousebutton>middle</mousebutton></markup> or +the entity <sgmltag class="genentity">MMB</sgmltag> +</para> +</listitem> + +<listitem> +<para><markup><mousebutton>right</mousebutton></markup> or +the entity <sgmltag class="genentity">RMB</sgmltag>. +</para> +</listitem> + +<listitem> +<para><markup><mousebutton>wheel</mousebutton></markup> +</para> +</listitem> +</itemizedlist> + +<para>Wheel is used only in specific instructions for applications that +support it, of course.</para> + +<para> +Use the entities where possible, they are a lot less typing and +are simple to remember (which is why we have provided them.) If you are +translating, check with your team leader, as the entities above are +<emphasis>not</emphasis> translated, but you may have your own language +specific ones to use in their place. +</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term id="keycombo"><sgmltag class="starttag">keycombo +action=""</sgmltag></term> +<listitem> +<para> +A keycombo is a sequence or combination of keypresses that are performed +together. A keycombo can contain <sgmltag +class="starttag">keycap</sgmltag>, <sgmltag class="starttag">keysym</sgmltag> or <sgmltag class="starttag">mousebutton</sgmltag>, or +any combination of these, in any order.</para> <para>It is normal to +have them in the order <literal>modifier</literal>, +<literal>Alpha-numeric</literal>, <literal>Mouse</literal>. That is, +<keycombo>&Ctrl;<keycap>A</keycap></keycombo>, not +<keycombo><keycap>A</keycap>&Ctrl;</keycombo>, unless pressing +<keycap>A</keycap> then &Ctrl; actually is the shortcut. +</para> + +<para> +Keycombo requires an <sgmltag class="attribute">action</sgmltag> +attribute, describing exactly how the keys (or mouse buttons) are +combined. The choices are: +</para> + +<itemizedlist> +<listitem> +<para> +<sgmltag class="attvalue">Click</sgmltag> +</para> +</listitem> + +<listitem> +<para> +<sgmltag class="attvalue">Double-Click</sgmltag> +</para> +</listitem> + +<listitem> +<para><sgmltag class="attvalue">Other</sgmltag> +</para> +</listitem> + +<listitem> +<para><sgmltag class="attvalue">Press</sgmltag> +</para> +</listitem> + +<listitem> +<para><sgmltag class="attvalue">Seq</sgmltag> +</para> +</listitem> + +<listitem> +<para><sgmltag class="attvalue">Simul</sgmltag> +</para> +</listitem> +</itemizedlist> + +<para> +You will most likely need to use <sgmltag class="attvalue">Seq</sgmltag> +(for a sequence of keys that are pressed one after the other), or +<sgmltag class="attvalue">Simul</sgmltag> for a combination of keys that +are pressed at the same time. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="accel"><sgmltag class="starttag">accel</sgmltag></term> +<listitem> +<para> +The accelerator key that can be used to access a <acronym>GUI</acronym> +menu without a mouse. This is indicated in the menu by an underlined +letter. Although we previously used this in the menu references, we +have since decided not to, the maintenance is too high, and it causes +an enormous amount of work during translation. +</para> +</listitem> +</varlistentry> + +</variablelist> + +<example> +<title>An example from a menu reference entry</title> + +<screen width="40"> +<markup> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl; +<keycap>C</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Copy</guimenuitem> +</menuchoice></term> +<listitem><para><action>Copy the selected text</action> to the +clipboard</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo action="simul">&Ctrl; +<keycap>V</keycap> +</keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Paste</guimenuitem> +</menuchoice></term> +<listitem><para><action>Paste</action> the contents of +the clipboard at the cursor.</para></listitem> +</varlistentry> +</markup> +</screen> + +<para> +Please note, this is very complicated markup, and until you have +written a few it's very hard to follow, but it does get much easier with +practise! Although indenting is discouraged in general, this is one +place where you might want to use some indenting and white space to make +it clearer while writing, at least when you are beginning. There are +also no rules as to when you must start a new line for a new element, so +format the markup to suit your own taste while you are writing, if that +makes it easier for you to follow. +</para> +</example> + +</chapter> + +<chapter id="actions-and-commands"> +<title>Describing actions and commands</title> + +<variablelist> + +<varlistentry> +<term id="replaceable"><sgmltag +class="starttag">replaceable</sgmltag></term> +<listitem> +<para> +Use this for placeholder or sample text, that a user would not +actually type, but would instead replace with the correct text for +their environment. For example, <markup>Edit the file +<filename><replaceable>/usr/local/foo/bar</replaceable></filename></markup>, +because it may already be established that <filename +class="directory">/usr/local</filename> is only the default location +of this file, and the user may have it installed to ⪚ <filename +class="directory">/opt/</filename> instead. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="application"><sgmltag +class="starttag">application</sgmltag></term> +<listitem> +<para> +Use this to mark up the name of any software program mentioned in the +text. Don't use this to mark up the actual command issued to execute +the application. For example, <sgmltag +class="starttag">application>Kate</application</sgmltag> is the +name of the editor, but <sgmltag +class="starttag">command>kate</command</sgmltag> is the name of +the command that starts the <application>Kate</application> +application.</para> +<note> +<para> +All &tde; applications, and several non-&tde; but very common +applications, are provided as entities. +</para> +</note> + +<para> +For the &tde; applications, using the entities will save you much +typing, and will ensure that applications are always referred to with +their correct name across all documentation. The entity is always the +application's executable name, in lower case, ⪚ <sgmltag +class="genentity">kcontrol</sgmltag>, <sgmltag +class="genentity">konqueror</sgmltag> or <sgmltag +class="genentity">kmail</sgmltag>. +</para> + +<para> +For non-&tde; applications, one of the major reasons to use the entities +is that there are legal implications, so far as we are required to +acknowledge trademarks and copyrights held by others outside our +organisation. You will find in <xref linkend="appendix-entities"/> a +list containing a list of the more common non-&tde; application +entities. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="interface"><sgmltag +class="starttag">interface</sgmltag></term> +<listitem> +<para> +Catch all element for gui interface items that do not have a more +specific tag. You can use this to markup things like the <quote>View +pane</quote> in &khelpcenter;, or the <quote>Board</quote> in +&kjumpingcube;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="userinput"><sgmltag +class="starttag">userinput</sgmltag></term> +<listitem> +<para> +<emphasis>Any</emphasis> text that the user must type, including +commands and data entry. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="screen"><sgmltag class="starttag">screen</sgmltag></term> +<listitem> +<para> +Used to represent the computer screen (usually to represent a terminal +or console.) Text contained in <sgmltag +class="starttag">screen</sgmltag> is considered to be literal text — +line breaks and white space are honored and it will be rendered with a +mono-spaced font. Don't use screen when what you really want is an +example, or an informal example. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="command"><sgmltag class="starttag">command</sgmltag></term> +<listitem> +<para> +Text the user enters to instruct the computer or an application +to do something. <userinput><command>ls +<option>-al</option></command></userinput> is a command (it's also userinput, +and has options.) <userinput><command>/join #tde</command></userinput> +in an <acronym>irc</acronym> client is a command (and again, is +userinput.) +</para> + +<para> +Commands are not <sgmltag class="element">userinput</sgmltag> when you +are not expecting the user to actually type them, for example in the +sentence <quote>The output from the <command>ls</command> command should +show you...</quote>, the text <quote>ls</quote> is a command, but is not +<sgmltag class="element">userinput</sgmltag> in this context. +</para> + +<para> +Applications not marked up with the <sgmltag +class="starttag">application</sgmltag> tag are also considered commands, +for example, <command>gcc</command>, <command>automake</command> and +<command>autoconf</command>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="prompt"><sgmltag class="starttag">prompt</sgmltag></term> +<listitem> +<para> +The prompt at which a user types input. For most &tde; +Documentation, this has been standardised as +<sgmltag +class="starttag">prompt</sgmltag><sgmltag class="genentity">percnt</sgmltag><sgmltag +class="endtag">prompt</sgmltag> (which is the % character). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option"><sgmltag class="starttag">option</sgmltag></term> +<listitem> +<para>An optional parameter to a command. Since we write about &UNIX; +platforms, an option on the commandline is almost always indicated by a +<quote>-</quote>, but there are exceptions (⪚, +<userinput><command>tar</command> <option>zxvf</option> +<replaceable>filename.tar.gz</replaceable></userinput> or +<userinput><command>ps</command> <option>ax</option></userinput>, which +are marked up as +<markup><userinput><command>tar</command> +<option>zxvf</option> +<replaceable>filename.tar.gz</replaceable></userinput></markup> +and <markup><userinput><command>ps</command> +<option>ax</option></userinput></markup> respectively. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="envar"><sgmltag class="starttag">envar</sgmltag></term> +<listitem> +<para> +An environment variable. Note that the variable indicator (usually $ +for &UNIX;) is not part of the name of the environment variable, so it +is correct to do this: +<markup>$<envar>TDEDIR</envar></markup>. There are no +attributes in use in &tde; Documentation. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="errorcode"><sgmltag class="starttag">errorcode</sgmltag></term> +<listitem> +<para> +A (usually numeric, but not always) error +code. <errorcode>SIGSEGV</errorcode> is an errorcode, as is +<errorcode>404</errorcode> as you might receive when you are web +browsing. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="errorname"><sgmltag class="starttag">errorname</sgmltag></term> +<listitem> +<para> +The actual text of an error message - to reuse the +<errorcode>404</errorcode> example, the <sgmltag +class="starttag">errorname</sgmltag> might be <errorname>Page not +found</errorname>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="errortype"><sgmltag class="starttag">errortype</sgmltag></term> +<listitem> +<para> +The type of error, ⪚ <errortype>fatal</errortype> +or <errortype>recoverable</errortype>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="filename"><sgmltag class="starttag">filename</sgmltag></term> +<listitem> +<para> +Use <sgmltag class="starttag">filename</sgmltag> for all occurrences of +file names including: +</para> +<itemizedlist> +<listitem> +<para> +Directory names — with the attribute <markup>class="directory"</markup> +</para> +</listitem> +<listitem> +<para> +Paths +</para> +</listitem> +<listitem> +<para> +File names +</para> +</listitem> +<listitem> +<para> +File name placeholders (which should also be tagged with +<sgmltag class="starttag">replaceable</sgmltag> +</para> +</listitem> +</itemizedlist> + +<para> +Do not use <sgmltag class="starttag">filename</sgmltag> for file +fragments or extensions (&ie; <literal role="extension">*.tgz</literal> +which should instead be marked up as <link linkend="literal"><sgmltag +class="starttag">literal role="extension"</sgmltag></link>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="symbol"><sgmltag class="starttag">symbol</sgmltag></term> +<listitem> +<para> +Symbols are things that are replaced by the computer when they are +processed. It's difficult to say when things are a symbol and when they +are not - if there is a more specific element to use (⪚ <sgmltag +class="starttag">envar</sgmltag> or <sgmltag +class="starttag">constant</sgmltag> then you should use that instead. +</para> +</listitem> +</varlistentry> + +</variablelist> + +</chapter> + +<chapter id="questions-and-answers"> +<title>Questions and Answers</title> + +<variablelist> +<varlistentry> +<term id="qandaset"><sgmltag class="starttag">qandaset</sgmltag></term> +<listitem> +<para> +A set of questions and answers, suitable for a +&FAQ;. <sgmltag class="starttag">qandaset</sgmltag> must +contain <sgmltag class="starttag">qandaentry</sgmltag>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="qandaentry"><sgmltag class="starttag">qandaentry</sgmltag></term> +<listitem> +<para> +Each question and answer pair is a <sgmltag +class="starttag">qandaentry</sgmltag>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="question"><sgmltag class="starttag">question</sgmltag></term> +<listitem> +<para> +The question being asked. It must be inside a qandaentry, and +it must have a matching answer. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="answer"><sgmltag class="starttag">answer</sgmltag></term> +<listitem> +<para> +The answer to the matching question in the same qandaset. +</para> +</listitem> +</varlistentry> + +</variablelist> + +<example> +<title><sgmltag class="starttag">qandaset</sgmltag> Template</title> +<screen width="40"><markup> +<qandaset> +<qandaentry> +<question> +</question> +<answer> +</answer> +</qandaentry> +</qandaset> +</markup></screen> +</example> + +</chapter> + +<chapter id="screenshots-and-examples"> +<title>Images and Examples</title> + +<variablelist> + +<varlistentry> +<term id="screenshot"><sgmltag class="starttag">screenshot</sgmltag></term> +<listitem> +<para> +Wrapper around screenshots. Use this when you are including a +screenshot in your document. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="screeninfo"> +<sgmltag class="starttag">screeninfo</sgmltag></term> +<listitem> +<para> +Screeninfo is a description of the screenshot. It's common (but not +required) to reuse this text in the textobject element, as it saves +translation time. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="mediaobject"><anchor id="inlinemediaobject"/><sgmltag +class="starttag">mediaobject</sgmltag> and <sgmltag +class="starttag">inlinemediaobject</sgmltag></term> +<listitem> +<para> +Use <sgmltag class="element">inlinemediaobject</sgmltag> to insert an +inline image (that is, one that is inside a paragraph of text, or is the +only item in a table entry. Use <sgmltag +class="element">mediaobject</sgmltag> for all other images. If the +image is a screenshot, the <sgmltag +class="element">mediaobject</sgmltag> should be wrapped with a +<sgmltag class="element">screenshot</sgmltag> element. mediaobjects +contain the following items: +</para> + +<variablelist> +<varlistentry><term id="imageobject"><sgmltag class="starttag">imageobject</sgmltag></term> +<listitem> +<para> +Imageobject contains information about one specific image. DocBook +allows you to add more than one imageobject, in order to provide +alternatives if the user is unable to see the preferred image. We don't +currently use this functionality in &tde; Documentation, but may do at +some time in the future. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="imagedata"><sgmltag class="emptytag">imagedata fileref="" +format=""</sgmltag></term> +<listitem> +<para> +This element holds the actual image reference. The fileref +indicates the location of the image. You should always keep images in the same +directory as the document itself, so you need only put the filename into the +fileref attribute. The format indicates the type of image you are including. +For &tde; this should be <sgmltag class="attvalue">PNG</sgmltag>. Do +<emphasis>not</emphasis> use gif format images for &tde; documents. +</para> +<para> +This is one of few <quote>empty</quote> elements in use in &tde; +Documentation. This means there is no </imagedata>, but you +should <emphasis>always</emphasis> close the element as shown above, +with a final <quote>/</quote>. +</para> +<para> +Keep the images in the same directory as your +<filename>index.docbook</filename>, don't create a separate directory to +store them in. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="textobject"><sgmltag +class="starttag">textobject</sgmltag></term> +<listitem> +<para> +Encloses the text part of a screenshot, which for &tde; Documentation +means it contains a <sgmltag class="starttag">phrase</sgmltag> element. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="phrase"><sgmltag class="starttag">phrase</sgmltag></term> +<listitem> +<para> +A short descriptive phrase about the image contents, this element is +contained in the <sgmltag class="starttag">textobject</sgmltag> element. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="caption"><sgmltag class="starttag">caption</sgmltag></term> +<listitem> +<para> +If you want the image to have a caption when displayed, you can add +this. It's not required for &tde; documents, but recommended, +especially if there are several images near each other and there could +be confusion as to which you are referring in the text. +</para> +</listitem> +</varlistentry> + +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term id="informalexample"><sgmltag +class="starttag">informalexample</sgmltag></term> +<listitem> +<para> +Use this element to enclose any informal examples you use in your +document. There are no attributes. An informal example can contain +almost any markup, so feel free to use them liberally. They should +generally not be part of a paragraph. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="example"><sgmltag class="starttag">example</sgmltag></term> +<listitem> +<para> +An example is a more formal example, which has a title and an entry in +the table of contents. Use sparingly, because having a hundred examples +listed in the contents of a 5 page document lessens their usefulness. +However, don't hesitate to use when you think it's necessary. +</para> +<para> +I've used them in this document to make it easy to quickly go to the +small <quote>template</quote> examples for complex markup, because you +can find them directly from the table of contents. Less difficult +examples in this document have <sgmltag +class="starttag">informalexample</sgmltag> instead. Use your best +judgement. As with <sgmltag class="starttag">informalexample</sgmltag>, +they can contain almost any markup. +</para> +</listitem> +</varlistentry> + +</variablelist> + +<example> +<title>A screenshot example</title> + +<screen width="40"> +<markup> +<screenshot> +<screeninfo>An example image</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="example.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>An example image</phrase> +</textobject> +</mediaobject> +</screenshot> +</markup> +</screen> +</example> +</chapter> + +<chapter id="other-markup"> +<title>General markup (not covered elsewhere)</title> + +<variablelist> +<varlistentry> +<term id="abbrev"><sgmltag class="starttag">abbrev</sgmltag></term> +<listitem> +<para> +Abbreviations are shortened forms of longer words. +</para> + +<para> +Abbreviations are not normally pronounced in speech. Examples are ⪚ +and &ie;. This is a &tde; specific distinction, please stick to +it. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="acronym"><sgmltag class="starttag">acronym</sgmltag></term> +<listitem> +<para> +Acronyms are shortened forms of words or phrases, often made up of the +initials of the words in a phrase. Acronyms are normally pronounced in +speech as well as written. Examples are &GUI; and +&tde;. As with <sgmltag class="starttag">abbrev</sgmltag>, this is a +&tde; specific distinction. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="attribution"> +<sgmltag class="starttag">attribution</sgmltag></term> +<listitem> +<para> +If you use <sgmltag class="starttag">quote</sgmltag> or <sgmltag +class="starttag">blockquote</sgmltag>, the source of the quote (that is, +<emphasis>who</emphasis> you are quoting) should be cited with this tag. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="blockquote"><sgmltag +class="starttag">blockquote</sgmltag></term> +<listitem> +<para> +Use this when you want to quote a passage of text that should be set off +from the main text, for example, an entire paragraph from a book or +other source. Use <sgmltag class="starttag">quote</sgmltag> to quote a +passage of text that is not to be set off, for example a short sentence +or comment from another person. Use both of them as little as you can, +there are copyright issues to quoting from other works inside &tde; +Documentation. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="emphasis"><sgmltag class="starttag">emphasis</sgmltag></term> +<listitem> +<para> +Use this to emphasise text. Don't use it to mark up file names, +commands, or anything else. Use it where you might type in all caps in +an email, for emphasis of one word or short phrase, and try not to use +it too much. Emphasis loses it's power when over used. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="computeroutput"><sgmltag +class="starttag">computerouput</sgmltag></term> +<listitem> +<para> +Text the user can see on the computer screen. For example, a +listing of a directory as produced after the command +<command>ls</command> would be <sgmltag +class="element">computeroutput</sgmltag>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="epigraph"><sgmltag class="starttag">epigraph</sgmltag></term> +<listitem> +<para> +A short quote or saying at, sometimes used at the beginning of a chapter +as an introduction. Use sparingly, no attributes used by &tde;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="equation"><sgmltag class="starttag">equation</sgmltag></term> +<listitem> +<para> +Equation is used if you need to mark up a mathematical equation. You +are unlikely to need to use this in &tde; Documents. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="hardware"><sgmltag class="starttag">hardware</sgmltag></term> +<listitem> +<para> +Used when referring to a piece of computer hardware, ⪚ +<hardware>Floppy Drive</hardware> or <hardware>Monitor</hardware>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="lineannotation"><sgmltag +class="starttag">lineannotation</sgmltag></term> +<listitem> +<para> +A comment, for example in a <sgmltag +class="starttag">programlisting</sgmltag>. This is +<emphasis>not</emphasis> for comments contained in the text, it is for +comments by the author (you) <emphasis>about</emphasis> the text. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="literal"><sgmltag class="starttag">literal</sgmltag></term> +<listitem> +<para> +In &tde; Documentation, this is markup of last resort (or <quote>the +least of all evils</quote>) Use it only for things that must be marked +up, but have no appropriate tag, and preferably only for the following +things (already decided on:) +</para> +<itemizedlist> +<listitem> +<para> +<sgmltag class="starttag">literal +role="extension">*.tar.gz</literal</sgmltag> +</para> +</listitem> +</itemizedlist> +</listitem> +</varlistentry> + +<varlistentry> +<term id="literallayout"><sgmltag +class="starttag">literallayout</sgmltag></term> +<listitem> +<para> +Use very sparingly, when it is absolutely vital that some text is +presented exactly as it appears, including white space and line breaks. +There is almost always a better tag to use than this (screen and +computeroutput together, or even a screenshot). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="markup"><sgmltag class="starttag">markup</sgmltag></term> +<listitem> +<para> +Use to wrap markup examples, for text that should be represented +literally. Examples are this document, and documents that have +<abbrev>HTML</abbrev> markup included literally in them. Other than +meta-documentation like this, you probably won't have much need for +<sgmltag class="element">markup</sgmltag>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="optional"><sgmltag class="starttag">optional</sgmltag></term> +<listitem> +<para> +Optional information, usually in user input. Not used to date in &tde; +Documentation, but it may be appropriate in some circumstances. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="para"><sgmltag class="starttag">para</sgmltag></term> +<listitem> +<para> +A paragraph. This is the most common tag. You do not need to enclose +lists, tables, or other markup with <sgmltag +class="starttag">para</sgmltag>. Sometimes however, you might want to do +so, especially with <sgmltag class="starttag">screen</sgmltag> and some +types of lists, when they actually are still part of the current +paragraph. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="quote"><sgmltag class="starttag">quote</sgmltag></term> +<listitem> +<para> +Use when you are quoting something or someone, inside a sentence. Also +use if you want a word or phrase to be <quote>enclosed in quotes</quote> +like this. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="trademark"><sgmltag class="starttag">trademark +class=""</sgmltag></term> +<listitem> +<para> +Used to denote that a word is a trademark. There is the optional +attribute <sgmltag class="attribute">class</sgmltag> which should +contain one of the following, if appropriate: +</para> +<itemizedlist> +<listitem><para>copyright</para></listitem> +<listitem><para>registered</para></listitem> +<listitem><para>service</para></listitem> +<listitem><para>trade</para></listitem> +</itemizedlist> +<para> +If there is no <sgmltag class="attribute">class=""</sgmltag> attribute, +<quote>trade</quote> is assumed. +</para> +<para> +We have provided entities, marked up appropriately, for very commonly +met trademarks, including &Qt; (<sgmltag +class="genentity">Qt</sgmltag>), &UNIX; (<sgmltag +class="genentity">UNIX</sgmltag>), &Linux; (<sgmltag +class="genentity">Linux</sgmltag>) and many more. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="sgmltag"><sgmltag class="starttag">sgmltag</sgmltag></term> +<listitem> +<para> +An <acronym>SGML</acronym> tag. This includes &XML; and &XHTML; tags. +Use this for marking up individual components, but use <sgmltag +class="starttag">markup</sgmltag> when you need to display a block of +markup. +</para> +<para> +<sgmltag class="element">sgmltag</sgmltag> will generate the correct +markup characters for you, based on the <sgmltag +class="attribute">class</sgmltag> attribute. +</para> + +<para> +Attribute values available: +</para> + +<itemizedlist> +<listitem> +<para> +<sgmltag class="attvalue">attvalue</sgmltag>, for the contents of +an attribute. +</para> +</listitem> +<listitem> +<para> +<sgmltag class="attvalue">attribute</sgmltag>, for attributes. +</para> +</listitem> +<listitem> +<para> +<sgmltag class="attvalue">element</sgmltag>, for element names. +</para> +</listitem> +<listitem> +<para> +<sgmltag class="attvalue">endtag</sgmltag>, for closing tags (⪚ +<sgmltag class="endtag">para</sgmltag>. +</para> +</listitem> +<listitem> +<para> +<sgmltag class="attvalue">emptytag</sgmltag>, for tags which are +<quote>empty</quote>, such as <sgmltag class="emptytag">br</sgmltag> in +&XHTML;. +</para> +</listitem> +<listitem> +<para> +<sgmltag class="attvalue">genentity</sgmltag>, for markup up general +entities. For example, <sgmltag class="genentity">nbsp</sgmltag> in +&XHTML;. +</para> +</listitem> +<listitem> +<para> +<sgmltag class="attvalue">numcharref</sgmltag>, to mark up a numbered +character reference. <sgmltag class="genentity">nbsp</sgmltag>, for +example, could also be referred to as <sgmltag +class="numcharref">160</sgmltag>. +</para> +</listitem> +<listitem> +<para> +<sgmltag class="attvalue">paramentity</sgmltag> <!-- TODO find a very --> +<!-- short description to put here -->. You are unlikely to need this +for any &tde; documentation. +</para> +</listitem> +<listitem> +<para> +<sgmltag class="attvalue">pi</sgmltag> <!-- TODO find a very --> +<!-- short description to put here -->. Note this is an +<acronym>SGML</acronym> <acronym>PI</acronym>, not an &XML; one. You +are very unlikely to need this for any &tde; documentation. +</para> +</listitem> +<listitem> +<para> +<sgmltag class="attvalue">xmlpi</sgmltag>. An &XML; processing +instruction, such as <!-- TODO find an example that is common --> +</para> +</listitem> +<listitem> +<para> +<sgmltag class="attvalue">starttag</sgmltag>. An opening tag, such as +<sgmltag class="starttag">para</sgmltag>. Most of this document is +marked up this way. +</para> +</listitem> +<listitem> +<para> +<sgmltag class="attvalue">sgmlcomment</sgmltag>. +</para> +</listitem> +</itemizedlist> +</listitem> +</varlistentry> + +<varlistentry> +<term id="superscript"><sgmltag +class="starttag">superscript</sgmltag></term> +<listitem> +<para> +Superscript as in x<superscript>2</superscript>. Unlikely to be +required in most &tde; Documentation. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="msgtext"><sgmltag class="starttag">msgtext</sgmltag></term> +<listitem> +<para> +The actual text of an informational message. Use <sgmltag +class="starttag">errorname</sgmltag> for error +messages. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="subscript"><sgmltag +class="starttag">subscript</sgmltag></term> +<listitem><para>Used to create things like H<subscript>2</subscript>O. +Unlikely to be found in most &tde; Documents. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="foreignphrase"><sgmltag class="starttag">foreignphrase +lang=""</sgmltag></term> +<listitem> +<para> +Use this any time you need to use text in a language different than the +main language of the document. This should be rare, but may occur +especially in credits information. The <sgmltag +class="attribute">lang</sgmltag> attribute should contain the normal two +letter designation of the language. Please be careful with these, the +<emphasis>Country</emphasis> and <emphasis>Language</emphasis> codes are +sometimes different, ⪚ <quote>se</quote> is the country code for +Sweden, but the language code is <quote>sv</quote>. Using +<quote>uk</quote> for British English would give you possibly unexpected +results, as this is actually the language code for Ukrainian. +</para> +</listitem> +</varlistentry> +</variablelist> + +</chapter> + +<chapter id="tips-hints-etc"> +<title>Admonitions: Tips, hints, and Warnings.</title> + +<para> +Admonitions are set off from the main body of the text. Use these +sparingly, as they disturb the flow of the writing, but don't be afraid +to use them where necessary. Just make sure they +<emphasis>are</emphasis> necessary when you do use them. +</para> + +<para> +We have settled on a preliminary order of importance for these elements, +which differs from that explained in the Duck Book. Note that this +particular order is for &tde; Documentation only, and use your own +judgement which is the most appropriate element if your situation +differs from those outlined. +</para> + +<variablelist> + +<varlistentry> +<term id="warning"><sgmltag class="starttag">warning</sgmltag></term> +<listitem> +<para> +Use warning when data loss could occur if you follow the procedure being +described. +</para> +</listitem> +</varlistentry> + +<varlistentry><term id="caution"><sgmltag +class="starttag">caution</sgmltag></term> +<listitem> +<para> +A note of caution. Use this for example when the reader may lose easily +recovered or replaceable information (⪚ user settings), or when they +could cause data loss if they don't correctly follow the procedure being +outlined. +</para> +</listitem> +</varlistentry> + +<varlistentry><term id="important"><sgmltag +class="starttag">important</sgmltag></term> +<listitem> +<para> +When there is no danger of data loss, but you wish to make clear to the +reader a consequence that isn't immediately obvious (⪚ when changing +the font for one instance of a program also changes the default setting, +and this isn't clear from the &GUI;.) +</para> +</listitem> +</varlistentry> + +<varlistentry><term id="note"><sgmltag +class="starttag">note</sgmltag></term> +<listitem> +<para> +Information the user should be aware of, but is peripheral to the actual +task being described. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="tip"><sgmltag class="starttag">tip</sgmltag></term> +<listitem> +<para> +When you're giving a hint to make things easier or more productive for +the reader. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="footnote"><sgmltag class="starttag">footnote +id=""</sgmltag></term> +<listitem> +<para> +Use very sparingly for things that really are footnotes. An example +might be to note that the situation being described will be changing at +some currently unknown future time. Most footnotes would better be +marked up as notes, or tips. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="footnoteref"><sgmltag class="starttag">footnoteref +linkend=""</sgmltag></term> +<listitem> +<para> +You can refer to a footnote more than once, by using this element to +refer to it's unique id. The footnote does not need to be in the same +chapter. Use this very sparingly. +</para> +</listitem> +</varlistentry> +</variablelist> +</chapter> + +<chapter id="synopsis"> +<title>The synopsis elements</title> + +<variablelist> + +<varlistentry> +<term id="cmdsynopsis"><sgmltag +class="starttag">cmdsynopsis</sgmltag></term> +<listitem> + +<para> + +</para> + +<example> +<title>How to markup a command synopsis</title> +<screen width="40"> + +<cmdsynopsis> +<command>more</command> +<group choice="opt"><option>-d</option> +<option>l</option><option>f</option> +<option>p</option><option>c</option> +<option>s</option><option>u</option> +</group> +<arg>-num</arg> +<arg>+/ pattern</arg> +<arg>+ linenum</arg> +<arg rep="repeat"><replaceable>file</replaceable></arg> +</cmdsynopsis> +</screen> + +<para>This should generate: + +<cmdsynopsis> +<command>more</command> +<group +choice="opt"><option>-d</option> +<option>l</option><option>f</option> +<option>p</option><option>c</option> +<option>s</option><option>u</option></group> +<arg>-num</arg> +<arg>+/ pattern</arg> +<arg>+ linenum</arg> +<arg rep="repeat"><replaceable>file</replaceable></arg> +</cmdsynopsis> +</para> + +<para> +There are several very nice examples in the Duck book at <ulink +url="http://www.docbook.org">www.docbook.org</ulink> +</para> +</example> + +</listitem> +</varlistentry> + +<varlistentry> +<term id="funcsynopsis"><sgmltag class="starttag">funcsynopsis</sgmltag></term> +<listitem> + +<example> +<title>How to markup a function synopsis</title> + +<screen> +<markup> +<funcsynopsis> +<funcprototype> +<funcdef>void <function>setFile</function></funcdef> +<paramdef>QString <parameter>file</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<funcsynopsis> +<funcprototype> +<funcdef>void <function>setAutoResize</function></funcdef> +<paramdef>bool <parameter><replaceable>val</replaceable></parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<funcsynopsis> +<funcprototype> +<funcdef>QString <function>getVideoCodec</function></funcdef><void/> +</funcprototype> +</funcsynopsis> +</markup> +</screen> + +<para> +These would generate the following, respectively. +</para> + +<funcsynopsis> +<funcprototype> +<funcdef>void <function>setFile</function></funcdef><paramdef>QString <parameter>file</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<funcsynopsis> +<funcprototype> +<funcdef>void <function>setAutoResize</function></funcdef><paramdef>bool <parameter><replaceable>val</replaceable></parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<funcsynopsis> +<funcprototype> +<funcdef>QString <function>getVideoCodec</function></funcdef><void/> +</funcprototype> +</funcsynopsis> + +</example> + +<para>A function synopsis can contain the following:</para> +<variablelist> + +<varlistentry> +<term id="funcprototype"><sgmltag +class="starttag">funcprototype</sgmltag></term> <listitem><para>Contains +a prototype of the function. It can contain <sgmltag +class="starttag">void</sgmltag>, <sgmltag +class="starttag">varargs</sgmltag>, <sgmltag +class="starttag">paramdef</sgmltag> or most commonly, a <sgmltag +class="starttag">funcdef</sgmltag> which actually defines the +function.</para></listitem> +</varlistentry> + +<varlistentry> +<term id="funcdef"><sgmltag class="starttag">funcdef</sgmltag></term> +<listitem><para>A function and it's return type. </para></listitem> +</varlistentry> + +<varlistentry> +<term id="funcparams"><sgmltag class="starttag">funcparams</sgmltag></term> +<listitem><para>Contains the list of parameters for the +function.</para></listitem> +</varlistentry> + +<varlistentry><term id="paramdef"><sgmltag class="starttag">paramdef</sgmltag></term> +<listitem><para>Information about the parameters of a +function.</para></listitem> +</varlistentry> + +<varlistentry> +<term id="void"><sgmltag class="starttag">void</sgmltag></term> +<listitem><para>An empty element in a function indicating there are no +arguments.</para></listitem> +</varlistentry> + +<varlistentry><term id="varargs"><sgmltag class="starttag">varargs</sgmltag></term> +<listitem><para>An empty element in a function indicating there are multiple +arguments, without specifically listing them. This is generally represented +with an ellipsis (...). For example <function>int +max(...);</function></para></listitem> +</varlistentry> + +<varlistentry> +<term id="funcsynopsisinfo"><sgmltag class="starttag">funcsynopsisinfo</sgmltag></term> +<listitem><para>Not used in &tde; documentation.</para></listitem> +</varlistentry> +</variablelist> + +</listitem> +</varlistentry> + +<varlistentry> +<term id="arg"><sgmltag class="starttag">arg</sgmltag></term> +<listitem><para>Used inside <link linkend="cmdsynopsis"><sgmltag +class="starttag">cmdsynopsis</sgmltag></link>. Since most &tde; +applications are &GUI; only, you won't see this very often. See the entry +for <link linkend="cmdsynopsis"><sgmltag +class="starttag">cmdsynopsis</sgmltag></link> for a full explanation and +example.</para></listitem></varlistentry> + +<varlistentry><term id="group"><sgmltag class="starttag">group</sgmltag></term> +<listitem><para>Group</para></listitem></varlistentry> +<varlistentry><term id="sbr"><sgmltag class="starttag">sbr</sgmltag></term> +<listitem><para>sbr</para></listitem></varlistentry> +<varlistentry><term id="synopfragment"><sgmltag class="starttag">synopfragment</sgmltag></term> +<listitem><para>synopfragment</para></listitem> +</varlistentry> + +<varlistentry> +<term id="modifier"><sgmltag class="starttag">modifier</sgmltag></term> +<listitem><para>A modifier modifies a class, field, or method synopsis. +Examples are the words <quote>public</quote>, <quote>private</quote> or +<quote>virtual</quote></para></listitem> +</varlistentry> + +<varlistentry> +<term id="fieldsynopsis"><sgmltag class="starttag">fieldsynopsis</sgmltag></term> +<listitem><para>A field synopsis.</para></listitem> +</varlistentry> + +<!-- + +<varlistentry> +<term id="classsynopsisinfo"><sgmltag +class="starttag">classynopsisinfo</sgmltag></term> +<listitem><para>A class synopsis</para></listitem> +</varlistentry> + + + +<varlistentry> +<term id="methodsynopsis"><sgmltag +class="starttag">methodsynopsis</sgmltag></term> +<listitem><para>A method synopsis</para> + + +<classsynopsis language="cpp"> +<ooclass> +<classname>QWidget</classname> +</ooclass> +<methodsynopsis> + +<methodname>QWidget::QWidget</methodname> +<methodparam choice="opt"> +<funcparams> +<parameter>QWidget* parent = 0</parameter></funcparams> +</methodparam> +<methodparam choice="opt"> +<type>const char*</type> <parameter>name = 0</parameter> +</methodparam> +</methodsynopsis> +</classsynopsis> + + + +<methodsynopsis> + <methodname>QWidget::QWidget</methodname> + <methodparam choice="opt"> + <funcparams> + <parameter>QWidget* parent = 0</parameter></funcparams> + </methodparam> + <methodparam choice="opt"> + <parameter>const char* name = 0</parameter> + </methodparam> + </methodsynopsis> + +<classsynopsis language="cpp"> +<ooclass> +<classname></classname> +</ooclass> + +<destructorsynopsis> +<void/> +</destructorsynopsis> + +<fieldsynopsis> +<varname></varname> +</fieldsynopsis> + +<methodsynopsis> +<methodname></methodname> +<methodparam> +<modifier></modifier> +<type></type> +<parameter></parameter> +</methodparam> +</methodsynopsis> +<methodsynopsis> +<methodname></methodname> +<methodparam> +<modifier></modifier> +<type></type> +<funcparams></funcparams> +</methodparam> +</methodsynopsis> + +<constructorsynopsis> +<methodparam> +<modifier></modifier> +<type></type> +<parameter></parameter> +</methodparam> +</methodsynopsis> +<methodsynopsis> +<methodname></methodname> +<methodparam> +<modifier></modifier> +<type></type> +<funcparams></funcparams> +</methodparam> +</constructorsynopsis> + +</classsynopsis> + + +</listitem> +</varlistentry> + +<varlistentry> +<term id="destructorsynopsis"><sgmltag +class="starttag">destructorsynopsis</sgmltag></term> +<listitem><para>A destructor synopsis</para></listitem> +</varlistentry> + +<varlistentry> +<term id="constructorsynopsis"><sgmltag class="starttag"> +constructorsynopsis</sgmltag></term> +<listitem><para>A constructor synopsis + +<constructorsynopsis> +<methodname>QWidget::QWidget</methodname> +<methodparam choice="opt"> +<funcparams><type>QWidget*</type> <parameter>parent = 0</parameter></funcparams> +</methodparam> +<methodparam choice="opt"> +<funcparams> +<type>const char*</type> <parameter>name = 0</parameter></funcparams> +</methodparam> +</constructorsynopsis> + +<constructorsynopsis> + <methodname>QWidget::QWidget</methodname> + <methodparam choice="opt"> + <funcparams> + <parameter>QWidget* parent = 0</parameter></funcparams> + </methodparam> +<methodparam choice="opt"> + <parameter>const char* name = 0</parameter> +</methodparam> + </constructorsynopsis> + +</para></listitem> +</varlistentry> + +<varlistentry> +<term id="methodparam"><sgmltag class="starttag"> +methodparam</sgmltag></term> +<listitem><para>A parameter to a method, used inside a <sgmltag +class="element">methodsynopsis</sgmltag></para></listitem> +</varlistentry> +--> +</variablelist> +</chapter> + +<chapter id="programming"> +<title>Markup for programming</title> + +<para> +For formally marking up code examples or making a synopsis, you should +study the Duck Book and the <link linkend="synopsis">Synopsis</link> +chapter. The elements described below are mainly for marking up of +pieces of source code that appear in the running text. Remember that +&tde; and &tde; applications are written almost exclusively in C++, so +our useage may differ in places from the examples in the Duck book, +which may be describing other programming languages. +</para> + +<para> +To Developers reading this, remember most of the authors who may be +documenting your work are unfamiliar with source code, and many of them +like it that way. Therefore, the explanations here are more concerned +with how to tell things apart than what they are for, and may make you +cringe. +</para> + +<para>To everyone reading this, this section is very much under +construction so to speak. If you already need to use this markup, you +can ask questions on the tde-docbook mailing list, which is the most +likely place to get correct and up to date answers.</para> + +<variablelist> +<varlistentry> +<term id="classname"><sgmltag +class="starttag">classname</sgmltag></term> +<listitem> +<para> +Used to identify the name of a class in a programming language. In +&tde; Documentation, you won't see this much in the user documentation, +except for those applications which contain an <acronym>API</acronym> reference +chapter, and occasionally in others. You will find it used a lot in the +<application>TDevelop</application> documentation. +</para> + +<para> +For non-programmers, as we're almost exclusively discussing &tde; +applications written in C++ and using &Qt;, classnames are fairly easy +to distinguish: They start with a capital Q or K, and are usually one +word only, in the form of <classname>KApplication</classname> or +<classname>QListBox</classname>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="function"><sgmltag class="starttag">function</sgmltag>, +<sgmltag class="starttag">methodname</sgmltag></term> +<listitem><anchor id="methodname"/> +<para> +A function or <quote>subroutine</quote>. In C++, a function generally +looks something like this: <function>foo();</function>. The semi-colon +may not always be present and there may or may not be content inside the +braces. +</para> + +<para> +If you see things that have the form +<methodname>Kfoo::bar()</methodname> these are not just functions, but +also methods, so you would use the <sgmltag +class="starttag">methodname</sgmltag> for these. +</para> + +<para> +Constructors are methods where the parts before and after the :: are the +same, ⪚ <methodname>KFoo::Kfoo()</methodname>.Destructors look like +Constructors, but have a <literal>~</literal> after the :: ⪚ +<methodname>Kfoo::~Kfoo()</methodname>. The same things apply as with +functions and methods: there may or may not be a ; at the end, and there +may or may not be content inside the braces of a constructor (there is +never content for a destructor). +</para> + +<para> +These are normally marked up as <sgmltag +class="starttag">methodname</sgmltag>, but if you need to make a +synopsis of a method, there are specific elements available: <link +linkend="constructorsynopsis"><sgmltag +class="starttag">constructorsynopsis</sgmltag></link> and <link +linkend="destructorsynopsis"><sgmltag +class="starttag">destructorsynopsis</sgmltag></link> +</para> + +<para>To recap: </para> + +<variablelist> +<varlistentry> +<term>Function</term> +<listitem> +<para> +<function>foo()</function> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Methodname</term> +<listitem> +<para><methodname>Kfoo::bar()</methodname> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Constructor</term> +<listitem> +<para> +<methodname>Kfoo::Kfoo()</methodname> These are methods in ordinary +text, but when making a synopsis, have a more specific tag to use. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Destructor</term> +<listitem> +<para><methodname>Kfoo::~Kfoo()</methodname> These are methods in +ordinary text, but when making a synopsis, have a more specific tag to +use. +</para> +</listitem> +</varlistentry> +</variablelist> + +<para> +Sometimes you really can't tell the difference, especially when they are +being mentioned in passing in the text. Also, programmers tend to +shorten and make shortcuts when referring to snippets of source. If +it's very unclear what something is, mark it up with <sgmltag +class="starttag">function</sgmltag> and ask the developer. +</para> + +<tip> +<para> +Asking a developer <quote>What is foo?</quote> will likely result in a +two page explanation of a finer point of C++ programming, which, if you +could understand it, you wouldn't have needed to ask the question in the +first place. It saves everyone a lot of time and frustration if you +word the question <quote>Out of function, method, constructor and +destructor, which is the best fit for foo?</quote>. +</para> +</tip> + +</listitem> +</varlistentry> + +<varlistentry> +<term id="varname"><sgmltag class="starttag">varname</sgmltag></term> +<listitem> +<para> +The name of a variable. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="returnvalue"><sgmltag +class="starttag">returnvalue</sgmltag></term> +<listitem> +<para> +The value returned by a function. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="token"><sgmltag class="starttag">token</sgmltag></term> +<listitem> +<para> +A token is a placeholder, something that is replaced by an actual value +during processing. (I need to come up with a useful example for a token) +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="constant"><sgmltag class="starttag">constant</sgmltag></term> +<listitem> +<para> +A constant. In the snippet: +</para> +<programlisting>enum MyType { Red = 0, Green, Blue, Yellow };</programlisting> +<para><constant>Red</constant>, <constant>Green</constant>, +<constant>Blue</constant> and <constant>Yellow</constant> should be +marked up as <sgmltag class="starttag">constant</sgmltag></para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="type"><sgmltag class="starttag">type</sgmltag></term> +<listitem> +<para> +Used to classify a value. In the snippet: +</para> +<programlisting>enum MyType { Red = 0, Green, Blue, Yellow };</programlisting> +<para><type>MyType</type> is a <sgmltag +class="starttag">type</sgmltag></para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="programlisting"><sgmltag +class="starttag">programlisting</sgmltag></term> +<listitem> +<para> +Use this to wrap any source code examples in your document. You don't +need to use this for short snippets that are inline in the text, but you +should use it for any examples longer than a line or two, or that are a +separate block of text. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="structname"><sgmltag +class="starttag">structname</sgmltag>,<sgmltag +class="starttag">structfield</sgmltag></term> +<listitem><anchor id="structfield"/> +<para> +Not used in &tde; Documentation, primarily because they are rare +in &tde; source code, and are almost certainly never going to require +marking up. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="parameter"><sgmltag +class="starttag">parameter</sgmltag></term> +<listitem> +<para> +Parameters can be used for commandlines as well as for code samples. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="classsynopsis"><sgmltag +class="starttag">classsynopsis</sgmltag></term> +<listitem> +<para> +A class synopsis +</para> + +<classsynopsis class="class" language="cpp"> +<ooclass> +<classname>DCOPStub</classname> +</ooclass> +<classsynopsisinfo>? not sure about what goes here ?</classsynopsisinfo> +<methodsynopsis><type>enum</type> <methodname>Status</methodname> +<methodparam> +<parameter>CallSucceeded</parameter> +</methodparam> +<methodparam> +<parameter>CallFailed</parameter> +</methodparam> +</methodsynopsis> +</classsynopsis> + +</listitem> +</varlistentry> + +<varlistentry> +<term id="initializer"><sgmltag +class="starttag">initializer</sgmltag></term> +<listitem> +<para> +An initializer +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="exceptionname"><sgmltag +class="starttag">exceptionname</sgmltag></term> +<listitem> +<para> +An exception name +</para> +</listitem> +</varlistentry> + +</variablelist> + +<anchor id="constructorsynopsis"/> +<anchor id="destructorsynopsis"/> +<anchor id="classsynopsisinfo"/> +<anchor id="methodparam"/> +<anchor id="methodsynopsis"/> + +</chapter> + +<chapter id="callouts"> +<title>Making Callouts</title> + +<para> +Callouts are difficult, so they have their own chapter. Use callouts +when you want to refer from text to specific parts of an image, +programlisting, or synopsis. Using callouts with graphics is currently +unused, and is somewhat problematic, so they will not (yet) be described +here. +</para> + +<variablelist> + +<varlistentry> +<term id="calloutlist"><sgmltag +class="starttag">calloutlist</sgmltag></term> +<listitem> +<para> +A list element that contains the callouts themselves. That is, a list +of the explanations that belong to the indicated areas in the item being +explained. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="callout"><sgmltag class="starttag">callout +arearefs=""</sgmltag></term> +<listitem> +<para> +The actual explanation or description of the called out area or line. +The <sgmltag class="attribute">arearefs</sgmltag> attribute should +contain the id of the appropriate callout you are referring to. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="programlistingco"><sgmltag +class="starttag">programlistingco</sgmltag> +and <sgmltag class="starttag">screenco</sgmltag></term> +<listitem> +<para><anchor id="screenco"/> +Callouts applied to a programlisting or a screen element. Although they +look more difficult than just embedding the callouts directly in the +text, they really aren't too hard. The programlistingco contains one +areaspec, and one programlisting. The screenco contains one areaspec +and one screen element. The programlisting and screen elements are +exactly as you would normally have. +</para> +<variablelist> + +<varlistentry> +<term id="areaspec"><sgmltag class="starttag">areaspec</sgmltag></term> +<listitem> +<para> +The areaspec contains a list of area elements, each of which describes +one single callout. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="area"><sgmltag class="emptytag">area coords="" +id=""</sgmltag></term> +<listitem> +<para> +The area is another of the very few empty elements, so there is no +<sgmltag class="endtag">area</sgmltag>. The <sgmltag +class="attribute">id</sgmltag> attribute should contain a unique name +for the item. The <sgmltag class="attribute">coords</sgmltag> contains +a pair of numbers which indicate first the line and then the column +where the co should appear. The line and column refer to the position +in relation to the container element, <emphasis>not the entire +document!</emphasis>. That is, in a screenco, the line and column +numbers refer to the line <emphasis>within the <sgmltag +class="element">screen</sgmltag> element</emphasis>. +</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> +</variablelist> + +<example> +<title>Marking up callouts with <sgmltag +class="starttag">screenco</sgmltag>.</title> +<screen> +<markup> +<screenco> + <areaspec> + <area coords="2 65" id="currentdir"/> + <area coords="3 65" id="updir"/> + <area coords="4 75" id="hiddenfile"/> + <area coords="10 75" id="backupfile"/> + <area coords="13 70" id="hiddendir"/> + +<screen> +total 864 +drwx------ 8 vampyr vampyr 4096 Oct 2 18:01 ./ +drwxr-xr-x 13 root root 4096 Oct 1 16:32 ../ +-rw------- 1 vampyr vampyr 32 Sep 2 14:21 .MCOP-random-seed +-rw------- 1 vampyr vampyr 0 Sep 2 14:42 .Xauthority +-rw-r--r-- 1 vampyr vampyr 1899 Aug 6 19:32 .Xdefaults +-rw------- 1 vampyr vampyr 261 Sep 29 22:59 .bash_history +-rw-r--r-- 1 vampyr vampyr 24 Aug 6 19:32 .bash_logout +-rw-r--r-- 1 vampyr vampyr 285 Aug 6 19:34 .bash_profile +-rw-r--r-- 1 root root 230 Aug 6 19:32 .bash_profile~ +-rw-r--r-- 1 vampyr vampyr 559 Aug 6 19:32 .bashrc +-rw-r--r-- 1 vampyr vampyr 4044 Aug 6 19:32 .emacs +drwxr-xr-x 7 vampyr vampyr 4096 Sep 29 17:31 .trinity/ +</screen> +</screenco> +<calloutlist> +<callout arearefs="currentdir1"><para>The current directory.</para> +</callout> +<callout arearefs="updir1"> +<para>One directory up in the tree.</para> +</callout> +<callout arearefs="hiddenfile1"> +<para>A hidden file, indicated by the . beginning the name.</para> +</callout> +<callout arearefs="backupfile1"> +<para>A backup or temporary file, indicated by the ~ ending the name.</para> +</callout> +<callout arearefs="hiddendir1"> +<para>A hidden directory, which, like a hidden file, is indicated by the . at +the start of the name.</para> +</callout> +</calloutlist> +</markup> +</screen> + +<para> +All this markup above, while it looks complicated is really quite simple +if you study it closely. It would generate the following: +</para> + +<screenco> + <areaspec> + <area coords="2 65" id="currentdir1"/> + <area coords="3 65" id="updir1"/> + <area coords="4 75" id="hiddenfile1"/> + <area coords="10 75" id="backupfile1"/> + <area coords="13 70" id="hiddendir1"/> + </areaspec> + +<screen> +total 864 +drwx------ 8 vampyr vampyr 4096 Oct 2 18:01 ./ +drwxr-xr-x 13 root root 4096 Oct 1 16:32 ../ +-rw------- 1 vampyr vampyr 32 Sep 2 14:21 .MCOP-random-seed +-rw------- 1 vampyr vampyr 0 Sep 2 14:42 .Xauthority +-rw-r--r-- 1 vampyr vampyr 1899 Aug 6 19:32 .Xdefaults +-rw------- 1 vampyr vampyr 261 Sep 29 22:59 .bash_history +-rw-r--r-- 1 vampyr vampyr 24 Aug 6 19:32 .bash_logout +-rw-r--r-- 1 vampyr vampyr 285 Aug 6 19:34 .bash_profile +-rw-r--r-- 1 root root 230 Aug 6 19:32 .bash_profile~ +-rw-r--r-- 1 vampyr vampyr 559 Aug 6 19:32 .bashrc +-rw-r--r-- 1 vampyr vampyr 4044 Aug 6 19:32 .emacs +drwxr-xr-x 7 vampyr vampyr 4096 Sep 29 17:31 .trinity/ +</screen> +</screenco> +<calloutlist> +<callout arearefs="currentdir1"><para>The current directory.</para> +</callout> +<callout arearefs="updir1"> +<para>One directory up in the tree.</para> +</callout> +<callout arearefs="hiddenfile1"> +<para>A hidden file, indicated by the . beginning the name.</para> +</callout> +<callout arearefs="backupfile1"> +<para>A backup or temporary file, indicated by the ~ ending the name.</para> +</callout> +<callout arearefs="hiddendir1"> +<para>A hidden directory, which, like a hidden file, is indicated by the . at +the start of the name.</para> +</callout> +</calloutlist> +</example> + +<variablelist> +<varlistentry><term id="co"><sgmltag class="starttag">co</sgmltag></term> +<listitem> +<para> +Indicates where a callout is. For &tde; <acronym>HTML</acronym> +documentation, a small numbered graphic will be placed here, and also at +the location of the explanation. These numbered graphics are links +between the two places. It is entirely possible to embed the callout +elements directly in the text you are describing, and this is perhaps +the easiest way to do it. It isn't the most specific, but working out +the line coordinates to use the more precise elements is difficult, so +this way is acceptable for now. +</para> +</listitem> +</varlistentry> +</variablelist> + +<example> +<title>Marking up callouts by embedding directly in text</title> + +<screen> +<screen> +drwxr-xr-x 3 vampyr vampyr 4096 Aug 6 19:32 .triniity/ +lrwxrwxrwx 1 vampyr vampyr 15 Sep 3 19:46 +.tdeinit-whiterabbit.magicians.org-:0 -> /tmp/.kinV4m2iI= <co id="symlink"/> +-rw-r--r-- 1 vampyr vampyr 2096 Aug 6 19:32 .tderc +-r-------- 1 vampyr vampyr 21 Sep 2 14:21 .kxmlrpcd +-rw-r--r-- 1 vampyr vampyr 185 Aug 6 19:32 .mailcap +-rw------- 1 vampyr vampyr 31 Sep 2 14:21 .mcoprc +drwxr-xr-x 4 vampyr vampyr 4096 Aug 6 19:32 .netscape/ +-rw------- 1 vampyr vampyr 777947 Sep 2 14:42 .xsession-errors +drwxr-xr-x 5 vampyr vampyr 4096 Sep 2 14:42 Desktop/ <co id="dir"/> +drwx------ 2 vampyr vampyr 4096 Aug 6 19:32 tmp/ +-rw-r--r-- 1 vampyr vampyr 3836 Oct 13 16:44 notes.txt <co id="file"/> +</screen> + +<calloutlist> +<callout arearefs="symlink"> +<para>A symbolic link, indicated by the ->, and showing the location it is +linked to.</para> +</callout> +<callout arearefs="dir"> +<para>An ordinary directory.</para> +</callout> +<callout arearefs="file"> +<para>An ordinary file.</para> +</callout> +</calloutlist> +</screen> + +<para> +Again it's really not as hard as it looks on first glance. This markup +would generate the following: +</para> + +<screen> +drwxr-xr-x 3 vampyr vampyr 4096 Aug 6 19:32 .trinity/ +lrwxrwxrwx 1 vampyr vampyr 15 Sep 3 19:46 +.tdeinit-whiterabbit.magicians.org-:0 -> /tmp/.kinV4m2iI= <co id="symlink"/> +-rw-r--r-- 1 vampyr vampyr 2096 Aug 6 19:32 .tderc +-r-------- 1 vampyr vampyr 21 Sep 2 14:21 .kxmlrpcd +-rw-r--r-- 1 vampyr vampyr 185 Aug 6 19:32 .mailcap +-rw------- 1 vampyr vampyr 31 Sep 2 14:21 .mcoprc +drwxr-xr-x 4 vampyr vampyr 4096 Aug 6 19:32 .netscape/ +-rw------- 1 vampyr vampyr 777947 Sep 2 14:42 .xsession-errors +drwxr-xr-x 5 vampyr vampyr 4096 Sep 2 14:42 Desktop/ <co id="dir"/> +drwx------ 2 vampyr vampyr 4096 Aug 6 19:32 tmp/ +-rw-r--r-- 1 vampyr vampyr 3836 Oct 13 16:44 notes.txt <co id="file"/> +</screen> + +<calloutlist> +<callout arearefs="symlink"> +<para>A symbolic link, indicated by the ->, and showing the location it is +linked to.</para> +</callout> +<callout arearefs="dir"> +<para>An ordinary directory.</para> +</callout> +<callout arearefs="file"> +<para>An ordinary file.</para> +</callout> +</calloutlist> +</example> + +<variablelist> +<varlistentry> +<term id="imageobjectco"><sgmltag +class="starttag">imageobjectco</sgmltag></term> +<listitem> +<para> +Currently unused in &tde; Documentation. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="mediaobjectco"><sgmltag +class="starttag">mediaobjectco</sgmltag></term> +<listitem> +<para> +Currently unused in &tde; Documentation. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="areaset"> +<sgmltag class="starttag">areaset</sgmltag></term> +<listitem> +<para> +Currently unused in &tde; Documentation. This and the +above two elements will be used eventually (just as soon as I figure out +how they work). +</para> +</listitem> + +</varlistentry> + +<varlistentry> +<term id="graphicco"><sgmltag class="starttag">graphicco</sgmltag></term> +<listitem> +<para> +Not to be used in &tde; Documentation at all. +</para> +</listitem> + +</varlistentry> +</variablelist> + +</chapter> + +<chapter id="references-indexes-glossary"> +<title>References, indexes, and glossaries</title> + +<para> +These elements are very underused in &tde; Documentation up to this point, +and we will probably make an effort to implement them more fully at some +point. In the meantime, you may use them if you wish, so they are +explained here. +</para> + +<sect1 id="glossaries"> +<title>Making a glossary</title> + +<variablelist> +<varlistentry> +<term id="glossterm"><sgmltag +class="starttag">glossterm</sgmltag></term> +<listitem> +<para> +Use this inline to identify words in the text that are explained further +in a <link linkend="glossary"><sgmltag +class="starttag">glossary</sgmltag></link> or <link +linkend="glosslist"><sgmltag +class="starttag">glosslist</sgmltag></link>. When it's placed inside a +<sgmltag class="starttag">glossentry</sgmltag> it contains the term that +glossary entry is defining (see the example below to see this in +action.) +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="glossary"><sgmltag class="starttag">glossary</sgmltag></term> +<listitem> +<para> +Put this where you have the glossary appearing. This is usually +at the end of the document, perhaps last before the credits section, or before +an index. A glossary will become a separate section in the book. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="glosslist"><sgmltag class="starttag">glosslist</sgmltag></term> +<listitem> +<para> +Use this if the glossary is fairly short and simple. It can +appear anywhere a normal list could appear. For &tde; Documentation, a proper +glossary is preferred, so keep use of <sgmltag +class="starttag">glosslist</sgmltag> to a minimum, where your glossary +would only contain a small handful of entries. Use your own judgement +which is most appropriate. You might use a glosslist for example, to +explain a list of terms which only appear in one section, but are very +important to understanding that section and occur several times there, +so you want the explanations to appear close to the text. +</para> +</listitem> +</varlistentry> + +<varlistentry><term id="glossdiv"><sgmltag +class="starttag">glossdiv</sgmltag></term> +<listitem> +<para> +Divides a glossary into several smaller sections. A good use of this in +a very large glossary could be to break it up into separate sections for +each letter in the alphabet. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="glossentry"><sgmltag class="starttag">glossentry +id=""</sgmltag></term> +<listitem> +<para> +Contains the actual entries in the glossary or glosslist, where you +explain the terms you have marked up with glossterm in the text. You +should give these an <sgmltag class="attribute">id</sgmltag>, so they +can be linked to from the text, and crossreferenced between glossary +entries. +</para> + +<para> +A <sgmltag class="element">glossentry</sgmltag> always contains one +<link linkend="glossterm"><sgmltag +class="starttag">glossterm</sgmltag></link>. It also contains one <link +linkend="glossdef"><sgmltag class="starttag">glossdef</sgmltag></link>, +or one <link linkend="glosssee"><sgmltag +class="starttag">glosssee</sgmltag></link>, or a <link +linkend="glossdef"><sgmltag class="starttag">glossdef</sgmltag></link> +and a <link linkend="glossseealso"><sgmltag +class="starttag">glossseealso</sgmltag></link>. +</para> + +<tip> +<para> +I would suggest a consistent naming scheme, so glossary entries are easy +to reference without having to go look them up all the time. For +example, I use the form <sgmltag +class="attribute">id="gloss-<replaceable>word</replaceable>"</sgmltag>, +where <replaceable>word</replaceable> is the term that is being +explained. +</para> +</tip> +</listitem> +</varlistentry> + +<varlistentry><term id="glossdef"><sgmltag +class="starttag">glossdef</sgmltag></term> +<listitem> +<para> +Contains the actual definitions of the terms +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="glosssee"><sgmltag class="starttag">glosssee +otherterm=""</sgmltag></term> +<listitem> +<para> +You can use this to save duplicating entries in the glossary. Instead +of a <sgmltag class="starttag">glossdef</sgmltag> you can put <sgmltag +class="starttag">glosssee</sgmltag> with the <acronym>id</acronym> of +another <sgmltag class="starttag">glossentry</sgmltag>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="glossseealso"><sgmltag class="starttag">glossseealso +otherterm=""</sgmltag></term> +<listitem> +<para> +This is very similar to <sgmltag class="starttag">glosssee</sgmltag>, +but instead of replacing the <sgmltag +class="starttag">glossdef</sgmltag> it is in addition to +it. +</para> +</listitem> +</varlistentry> +</variablelist> + +<para> +If you compare a glossary entry to a variable list entry, you'll see the +structure is quite similar, with a <sgmltag +class="element">glossterm</sgmltag> taking the place of the <sgmltag +class="element">term</sgmltag>, and a <sgmltag +class="element">glossdef</sgmltag> taking the place of the <sgmltag +class="element">listitem</sgmltag>. Since variable lists get heavy use +in &tde; Documents, it shouldn't take you long to pick up how to do a +glossary. +</para> + +<example> +<title>How to markup a glossary</title> + +<para> +Say you have in the text of the document the following sentence: +</para> + +<blockquote> +<para> +KWord is a graphical, wysiwyg word processor, and is part of KOffice. +</para> +</blockquote> + +<para> +You want to have the words KWord and koffice in the index, and KWord, +wysiwyg, <quote>word processor</quote> and KOffice explained in a +glossary. +</para> + +<para> +Many of these terms also need to be marked up with other tags, such as +application, and acronym. +</para> + +<para>The eventual markup would look like this:</para> + +<screen> +<markup> +<para><glossterm linkend="gloss-kword">KWord</glossterm> +<indexterm><primary>KWord</primary></indexterm> is a +graphical <glossterm linkend +="gloss-wysiwyg"><acronym>WYSIWYG</acronym></glossterm> +<glossterm linkend="gloss-word-processor">word +processor</glossterm>, and is part of <glossterm +linkend="gloss-koffice">KOffice</glossterm>. +<indexterm><primary>KOffice</primary></indexterm></para> +</markup> +</screen> + +<para> +The next part is shown here as a <sgmltag +class="starttag">glosslist</sgmltag>, and if there were really only this +many entries in it, that could be entirely appropriate. In reality, if +you are going to make a glossary, it would have many more entries and so +would warrant it's own <sgmltag class="starttag">glossary</sgmltag> +section. The syntax inside <sgmltag class="starttag">glossary</sgmltag> +and <sgmltag class="starttag">glosslist</sgmltag> are otherwise the +same. +</para> + +<screen> +<markup> +<glosslist> +<glossentry id="gloss-kword"> +<glossterm>KWord</glossterm> +<glossdef><para>The name of the TDE word +processor</para></glossdef> +</glossentry> + +<glossentry id="gloss-koffice"> +<glossterm>KOffice</glossterm> +<glossdef><para>A collection of office productivity tools, designed +by and for <acronym>TDE</acronym>, including presentation software, +a word processor, a spreadsheet, a <acronym>PIM</acronym>, and a +vector illustration application.</para></glossdef> +</glossentry> + +<glossentry id="gloss-word-processor"> +<glossterm>word processor</glossterm> +<glossdef><para>An application for handling text, typically more +concerned with formatting visually than a plain text +editor.</para></glossdef> +</glossentry> + +<glossentry id="gloss-wysiwyg"> +<glossterm>WYSIWYG</glossterm> +<glossdef><para>Stands for <quote>What You See Is What You +Get</quote>, indicating that you can visually format the presentation of +your data onscreen, and when you print the document, it will look exactly as you +see on the screen.</para></glossdef> +</glossentry> +</glosslist> +</markup> +</screen> + +<para> +And the result of all this would be as follows: +</para> + +<para> +<glossterm linkend="gloss-kword">KWord</glossterm> +<indexterm><primary>KWord</primary></indexterm> is a graphical +<glossterm linkend +="gloss-wysiwyg"><acronym>WYSIWYG</acronym></glossterm> <glossterm +linkend="gloss-word-processor">word processor</glossterm>, and is part +of <glossterm +linkend="gloss-koffice">KOffice</glossterm>.<indexterm><primary>KOffice</primary></indexterm>. +</para> + +<glosslist> +<glossentry id="gloss-kword"> +<glossterm>KWord</glossterm> +<glossdef><para>The name of the TDE word processor</para></glossdef> +</glossentry> + +<glossentry id="gloss-koffice"> +<glossterm>KOffice</glossterm> +<glossdef><para>A collection of office productivity tools, designed by and for +<acronym>TDE</acronym>, including presentation software, a word processor, a +spreadsheet, a <acronym>PIM</acronym>, and a vector illustration +application.</para></glossdef> +</glossentry> + +<glossentry id="gloss-word-processor"> +<glossterm>word processor</glossterm> +<glossdef><para>An application for handling text, typically more concerned with +formatting visually than a plain text editor.</para></glossdef> +</glossentry> + +<glossentry id="gloss-wysiwyg"> +<glossterm>WYSIWYG</glossterm> +<glossdef><para>Stands for <quote>What You See Is What You Get</quote>, +indicating that you can visually format the presentation of your data onscreen, +and when you print the document, it will look exactly as you see on the +screen.</para></glossdef></glossentry> +</glosslist> + +</example> + +</sect1> + +<sect1 id="indexes"> +<title>Making an Index</title> + +<para> +For &tde; Documentation, indexes will in the future be generated +automatically, so many of these elements are not to be used directly +when authoring. At this stage, indexes are not generated, but if you +want to you can mark up words that should be indexed with the <sgmltag +class="starttag">indexterm</sgmltag> element, to save work for later. +</para> + +<variablelist> +<varlistentry> +<term id="indexterm"><sgmltag +class="starttag">indexterm</sgmltag></term> +<listitem> +<anchor id="primary"/> +<para> +Use this to note places in the main text of the document that should +have an entry in the index. Don't over use it - not every single +occurrence of a word needs to be noted in the index, but every +occurrence where that term is significant should be. +</para> + +<para> +<sgmltag class="element">indexterm</sgmltag> should contain a <sgmltag +class="starttag">primary</sgmltag>, which contains the text that the +entry will appear under in the index. +</para> + +<para> +Place the <sgmltag class="element">indexterm</sgmltag> directly before +the word you want to index, and place the word itself inside the primary +element. If the word should also be listed under a secondary heading, +place that term inside a secondary element. +</para> + +<example> +<title>Index</title> + +<para>Say the document contains the following sentence:</para> + +<blockquote><para>KWord is a graphical, wysiwyg word processor, and is part of +KOffice. </para></blockquote> + +<para>You want KWord to have an index entry of it's own, and to also be noted +under KOffice in the index.</para> + +<screen> +<markup> +<para><application>KWord</application> +<indexterm><primary>KWord</primary><secondary>KOffice</secondary></indexterm> +is a graphical, <acronym>WYSIWYG</acronym> word processor, and is part of +KOffice.</para> +</markup> +</screen> + +<para>The fact that an index entry exists is not normally indicated by a change +in appearance.</para> +</example> + +<para>If you think it should also be added under a third heading in the index, +you can use tertiary to indicate this. Most terms you would find in &tde; +Documentation will only need a primary index heading, so use the others +sparingly, if at all. +</para> +</listitem> +</varlistentry> + +<varlistentry><term id="tertiary"><sgmltag class="starttag">tertiary</sgmltag></term> +<listitem><para>tertiary</para></listitem></varlistentry> + +<varlistentry><term id="seealso"><sgmltag class="starttag">seealso</sgmltag></term> +<listitem><para>seealso</para></listitem></varlistentry> + +</variablelist> + +<para> +The following elements are used to create the actual index, but they are +automatically generated, if required. You should not use them when +authoring documents. +</para> + +<itemizedlist> +<listitem id="index"> +<para> +<sgmltag class="starttag">index</sgmltag> +</para> +</listitem> +<listitem id="indexdiv"> +<para> +<sgmltag class="starttag">indexdiv</sgmltag> +</para> +</listitem> +<listitem id="indexentry"> +<para> +<sgmltag class="starttag">indexentry</sgmltag> +</para> +</listitem> +<listitem id="primaryie"> +<para> +<sgmltag class="starttag">primaryie</sgmltag> +</para> +</listitem> +<listitem id="secondaryie"> +<para> +<sgmltag class="starttag">secondaryie</sgmltag> +</para> +</listitem> +<listitem id="see"> +<para> +<sgmltag class="starttag">see</sgmltag> +</para> +</listitem> +<listitem id="seealsoie"> +<para> +<sgmltag class="starttag">seealsoie</sgmltag> +</para> +</listitem> +<listitem id="seeie"> +<para> +<sgmltag class="starttag">seeie</sgmltag> +</para> +</listitem> +<listitem id="tertiaryie"> +<para> +<sgmltag class="starttag">tertiaryie</sgmltag> +</para> +</listitem> +</itemizedlist> +</sect1> + +<sect1 id="other-reference-sections"> +<title>Other Reference Sections</title> + +<variablelist> + +<varlistentry> +<term id="firstterm"><sgmltag +class="starttag">firstterm</sgmltag></term> +<listitem> +<para> +Mark up the first occurence of a technically significant term with this +element. If you are creating a glossary or an index, the first occurence +of a term will probably also warrant being an entry in one or both. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="refsynopsisdivinfo"><sgmltag +class="starttag">refsynopsisdivinfo</sgmltag></term> +<listitem> +<para> +refsynopsisdivinfo +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="refnamediv"><sgmltag +class="starttag">refnamediv</sgmltag></term> +<listitem> +<para>refnamediv +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="refclass"><sgmltag +class="starttag">refclass</sgmltag></term> +<listitem> +<para> +refclass +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="refmeta"><sgmltag +class="starttag">refmeta</sgmltag></term> +<listitem> +<para> +refmeta +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="refsect1"><sgmltag +class="starttag">refsect1</sgmltag>,<sgmltag +class="starttag">refsect2</sgmltag> +and <sgmltag class="starttag">refsect3</sgmltag></term> +<listitem> +<anchor id="refsect2"/><anchor id="refsect3"/> +<para> +refsect1, refsect2 and refsect3 +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="refmiscinfo"><sgmltag +class="starttag">refmiscinfo</sgmltag></term> +<listitem> +<para> +refmiscinfo +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="refsect1info"><sgmltag +class="starttag">refsect1info</sgmltag>,<sgmltag +class="starttag">refsect2info</sgmltag> and <sgmltag +class="starttag">refsect3info</sgmltag></term> +<listitem><anchor id="refsect2info"/><anchor id="refsect3info"/> +<para> +refsect1info, refsect2info and refsect3info +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="refdescriptor"><sgmltag +class="starttag">refdescriptor</sgmltag></term> +<listitem> +<para> +refdescriptor +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="setindex"><sgmltag class="starttag">setindex</sgmltag></term> +<listitem> +<para> +Not Used in &tde; Documentation +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="refpurpose"><sgmltag +class="starttag">refpurpose</sgmltag></term> +<listitem> +<para> +refpurpose +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="reference"><sgmltag class="starttag">reference</sgmltag></term> +<listitem> +<para> +reference +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="refentrytitle"><sgmltag +class="starttag">refentrytitle</sgmltag></term> +<listitem> +<para> +refentrytitle +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="refname"><sgmltag class="starttag">refname</sgmltag></term> +<listitem> +<para> +refname +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="refentry"><sgmltag class="starttag">refentry</sgmltag></term> +<listitem> +<para> +refentry +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="refsynopsisdiv"><sgmltag +class="starttag">refsynopsisdiv</sgmltag></term> +<listitem> +<para> +refsynpsisdiv +</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> +</chapter> + +<chapter id="tags-we-dont-use"> +<title>Tags we do not use</title> + +<para> +These are tags that are available for DocBook &XML;, but we have decided +they will not (at this time) be used for &tde; Documentation. They are +included here for completeness, and so nobody can say <quote>I didn't +know I wasn't supposed to use that!</quote> +</para> + +<para> +They fall into two categories: Tags we have definitely decided to not +use, in which case we have made a decision to use another tag instead, +and tags that are just irrelevant to the documentation we are doing, +which you hopefully will never want. Should we write new documentation +that can sensibly be marked up with any of these elements, this list +will be revised. +</para> + +<para> +If you think you have a use for one of these elements, please, check +with the DocBook team first, and be prepared to justify your case. +</para> + +<itemizedlist> +<listitem id="ackno"><para><sgmltag class="starttag">ackno</sgmltag></para></listitem> +<listitem id="alt"><para><sgmltag class="starttag">alt</sgmltag></para></listitem> +<listitem id="appendixinfo"><para><sgmltag class="starttag">appendixinfo</sgmltag></para></listitem> +<listitem id="artheader"><para><sgmltag class="starttag">artheader</sgmltag></para></listitem> +<listitem id="article"><para><sgmltag class="starttag">article</sgmltag></para></listitem> +<listitem id="articleinfo"><para><sgmltag class="starttag">articleinfo</sgmltag></para></listitem> +<listitem id="artpagenums"><para><sgmltag class="starttag">artpagenums</sgmltag></para></listitem> +<listitem id="audiodata"><para><sgmltag class="starttag">audiodata</sgmltag></para></listitem> +<listitem id="audioobject"><para><sgmltag class="starttag">audioobject</sgmltag></para></listitem> +<listitem id="authorblurb"><para><sgmltag class="starttag">authorblurb</sgmltag></para></listitem> +<listitem id="authorinitials"><para><sgmltag class="starttag">authorinitials</sgmltag></para></listitem> +<listitem id="beginpage"><para><sgmltag class="starttag">beginpage</sgmltag></para></listitem> +<listitem id="bibliodiv"><para><sgmltag class="starttag">bibliodiv</sgmltag></para></listitem> +<listitem id="biblioentry"><para><sgmltag class="starttag">biblioentry</sgmltag></para></listitem> +<listitem id="bibliography"><para><sgmltag class="starttag">bibliography</sgmltag></para></listitem> +<listitem id="bibliographyinfo"><para><sgmltag class="starttag">bibliographyinfo</sgmltag></para></listitem> +<listitem id="bibliomisc"><para><sgmltag class="starttag">bibliomisc</sgmltag></para></listitem> +<listitem id="bibliomixed"><para><sgmltag class="starttag">bibliomixed</sgmltag></para></listitem> +<listitem id="bibliomset"><para><sgmltag class="starttag">bibliomset</sgmltag></para></listitem> +<listitem id="biblioset"><para><sgmltag class="starttag">biblioset</sgmltag></para></listitem> +<listitem id="bookbiblio"><para><sgmltag class="starttag">bookbiblio</sgmltag></para></listitem> +<listitem id="bridgehead"><para><sgmltag class="starttag">bridgehead</sgmltag></para></listitem> +<listitem id="chapterinfo"><para><sgmltag class="starttag">chapterinfo</sgmltag></para></listitem> +<listitem id="citation"><para><sgmltag class="starttag">citation</sgmltag></para></listitem> +<listitem id="citerefentry"><para><sgmltag class="starttag">citerefentry</sgmltag></para></listitem> +<listitem id="citetitle"><para><sgmltag class="starttag">citetitle</sgmltag></para></listitem> +<listitem id="city"><para><sgmltag class="starttag">city</sgmltag></para></listitem> +<listitem id="collab"><para><sgmltag class="starttag">collab</sgmltag></para></listitem> +<listitem id="collabname"><para><sgmltag class="starttag">collabname</sgmltag></para></listitem> +<listitem id="colophon"><para><sgmltag class="starttag">colophon</sgmltag></para></listitem> +<listitem id="colspec"><para><sgmltag class="starttag">colspect</sgmltag></para></listitem> +<listitem id="comment"><para><sgmltag class="starttag">comment</sgmltag></para></listitem> +<listitem id="confdates"><para><sgmltag class="starttag">confdates</sgmltag></para></listitem> +<listitem id="confgroup"><para><sgmltag class="starttag">confgroup</sgmltag></para></listitem> +<listitem id="confnum"><para><sgmltag class="starttag">confnum</sgmltag></para></listitem> +<listitem id="confsponsor"><para><sgmltag class="starttag">confsponsor</sgmltag></para></listitem> +<listitem id="conftitle"><para><sgmltag class="starttag">conftitle</sgmltag></para></listitem> +<listitem id="contractnum"><para><sgmltag class="starttag">contractnum</sgmltag></para></listitem> +<listitem id="contractsponsor"><para><sgmltag class="starttag">contractsponsor</sgmltag></para></listitem> +<listitem id="corpname"><para><sgmltag class="starttag">corpname</sgmltag></para></listitem> +<listitem id="country"><para><sgmltag class="starttag">country</sgmltag></para></listitem> +<listitem id="database"><para><sgmltag class="starttag">database</sgmltag></para></listitem> +<listitem id="dedication"><para><sgmltag class="starttag">dedication</sgmltag></para></listitem> +<listitem id="docinfo"><para><sgmltag class="starttag">docinfo</sgmltag></para></listitem> +<listitem id="edition"><para><sgmltag class="starttag">edition</sgmltag></para></listitem> +<listitem id="editor"><para><sgmltag class="starttag">editor</sgmltag></para></listitem> +<listitem id="entrytbl"><para><sgmltag class="starttag">entrytbl</sgmltag></para></listitem> +<listitem id="fax"><para><sgmltag class="starttag">fax</sgmltag></para></listitem> +<listitem id="figure"><para><sgmltag class="starttag">figure</sgmltag></para></listitem> +<listitem id="formalpara"><para><sgmltag class="starttag">formalpara</sgmltag></para></listitem> +<listitem id="glossaryinfo"><para><sgmltag class="starttag">sgmltag</sgmltag></para></listitem> +<listitem id="graphic"><para><sgmltag class="starttag">graphic</sgmltag></para></listitem> +<listitem id="highlights"><para><sgmltag class="starttag">highlights</sgmltag></para></listitem> +<listitem id="honorific"><para><sgmltag class="starttag">honorific</sgmltag></para></listitem> +<listitem id="indexinfo"><para><sgmltag class="starttag">indexinfo</sgmltag></para></listitem> +<listitem id="informalequation"><para><sgmltag class="starttag">informalequation</sgmltag></para></listitem> +<listitem id="informalfigure"><para><sgmltag class="starttag">informalfigure</sgmltag></para></listitem> +<listitem id="inlineequation"><para><sgmltag class="starttag">inlineequation</sgmltag></para></listitem> +<listitem id="inlinegraphic"><para><sgmltag class="starttag">inlinegraphic</sgmltag></para></listitem> +<listitem id="interfacedefinition"><para><sgmltag class="starttag">interfacedefinition</sgmltag></para></listitem> +<listitem id="interfacename"><para><sgmltag class="starttag">interfacename</sgmltag></para></listitem> +<listitem id="invpartnumber"><para><sgmltag class="starttag">invpartnumber</sgmltag></para></listitem> +<listitem id="isbn"><para><sgmltag class="starttag">isbn</sgmltag></para></listitem> +<listitem id="issn"><para><sgmltag class="starttag">issn</sgmltag></para></listitem> +<listitem id="issuenum"><para><sgmltag class="starttag">issuenum</sgmltag></para></listitem> +<listitem id="itermset"><para><sgmltag class="starttag">itermset</sgmltag></para></listitem> +<listitem id="jobtitle"><para><sgmltag class="starttag">jobtitle</sgmltag></para></listitem> +<listitem id="lineage"><para><sgmltag class="starttag">lineage</sgmltag></para></listitem> +<listitem id="lot"><para><sgmltag class="starttag">lot</sgmltag></para></listitem> +<listitem id="lotentry"><para><sgmltag class="starttag">lotentry</sgmltag></para></listitem> +<listitem id="manvolnum"><para><sgmltag class="starttag">manvolnum</sgmltag></para></listitem> +<listitem id="medialabel"><para><sgmltag class="starttag">medialabel</sgmltag></para></listitem> +<listitem id="modespec"><para><sgmltag class="starttag">modespec</sgmltag></para></listitem> +<listitem id="msg"><para><sgmltag class="starttag">msg</sgmltag></para></listitem> +<listitem id="msgaud"><para><sgmltag class="starttag">msgaud</sgmltag></para></listitem> +<listitem id="msgentry"><para><sgmltag class="starttag">msgentry</sgmltag></para></listitem> +<listitem id="msgexplan"><para><sgmltag class="starttag">msgexplan</sgmltag></para></listitem> +<listitem id="msginfo"><para><sgmltag class="starttag">msginfo</sgmltag></para></listitem> +<listitem id="msglevel"><para><sgmltag class="starttag">msglevel</sgmltag></para></listitem> +<listitem id="msgmain"><para><sgmltag class="starttag">msgmain</sgmltag></para></listitem> +<listitem id="msgorig"><para><sgmltag class="starttag">msgorig</sgmltag></para></listitem> +<listitem id="msgrel"><para><sgmltag class="starttag">msgrel</sgmltag></para></listitem> +<listitem id="msgset"><para><sgmltag class="starttag">msgset</sgmltag></para></listitem> +<listitem id="msgsub"><para><sgmltag class="starttag">msgsub</sgmltag></para></listitem> +<listitem id="objectinfo"><para><sgmltag class="starttag">objectinfo</sgmltag></para></listitem> +<listitem id="olink"><para><sgmltag class="starttag">olink</sgmltag></para></listitem> +<listitem id="orgdiv"><para><sgmltag class="starttag">orgdiv</sgmltag></para></listitem> +<listitem id="orgname"><para><sgmltag class="starttag">orgname</sgmltag></para></listitem> +<listitem id="otheraddr"><para><sgmltag class="starttag">otheraddr</sgmltag></para></listitem> +<listitem id="pagenums"><para><sgmltag class="starttag">pagenums</sgmltag></para></listitem> +<listitem id="part"><para><sgmltag class="starttag">part</sgmltag></para></listitem> +<listitem id="partintro"><para><sgmltag class="starttag">partintro</sgmltag></para></listitem> +<listitem id="phone"><para><sgmltag class="starttag">phone</sgmltag></para></listitem> +<listitem id="pob"><para><sgmltag class="starttag">pob</sgmltag></para></listitem> +<listitem id="postcode"><para><sgmltag class="starttag">postcode</sgmltag></para></listitem> +<listitem id="preface"><para><sgmltag class="starttag">preface</sgmltag></para></listitem> +<listitem id="prefaceinfo"><para><sgmltag class="starttag">prefaceinfo</sgmltag></para></listitem> +<listitem id="printhistory"><para><sgmltag class="starttag">printhistory</sgmltag></para></listitem> +<listitem id="productname"><para><sgmltag class="starttag">productname</sgmltag></para></listitem> +<listitem id="productnumber"><para><sgmltag class="starttag">productnumber</sgmltag></para></listitem> +<listitem id="property"><para><sgmltag class="starttag">property</sgmltag></para></listitem> +<listitem id="pubdate"><para><sgmltag class="starttag">pubdate</sgmltag></para></listitem> +<listitem id="publisher"><para><sgmltag class="starttag">publisher</sgmltag></para></listitem> +<listitem id="publishername"><para><sgmltag class="starttag">publishername</sgmltag></para></listitem> +<listitem id="pubsnumber"><para><sgmltag class="starttag">pubsnumber</sgmltag></para></listitem> +<listitem id="qandadiv"><para><sgmltag class="starttag">qandadiv</sgmltag></para></listitem> +<listitem id="refentryinfo"><para><sgmltag class="starttag">refentryinfo</sgmltag></para></listitem> +<listitem id="referenceinfo"><para><sgmltag class="starttag">referenceinfo</sgmltag></para></listitem> +<listitem id="remark"><para><sgmltag class="starttag">remark</sgmltag></para></listitem> +<listitem id="revdescription"><para><sgmltag class="starttag">revdescription</sgmltag></para></listitem> +<listitem id="revhistory"><para><sgmltag class="starttag">revhistory</sgmltag></para></listitem> +<listitem id="revision"><para><sgmltag class="starttag">revision</sgmltag></para></listitem> +<listitem id="revnumber"><para><sgmltag class="starttag">revnumber</sgmltag></para></listitem> +<listitem id="revremark"><para><sgmltag class="starttag">revremark</sgmltag></para></listitem> +<listitem id="secondary"><para><sgmltag class="starttag">secondary</sgmltag></para></listitem> +<listitem id="section"><para><sgmltag class="starttag">section</sgmltag></para></listitem> +<listitem id="sectioninfo"><para><sgmltag class="starttag">sectioninfo</sgmltag></para></listitem> +<listitem id="seriesinfo"><para><sgmltag class="starttag">seriesinfo</sgmltag></para></listitem> +<listitem id="seriesvolnums"><para><sgmltag class="starttag">seriesvolnums</sgmltag></para></listitem> +<listitem id="set"><para><sgmltag class="starttag">set</sgmltag></para></listitem> +<listitem id="setindexinfo"><para><sgmltag class="starttag">setindexinfo</sgmltag></para></listitem> +<listitem id="setinfo"><para><sgmltag class="starttag">setinfo</sgmltag></para></listitem> +<listitem id="shortaffil"><para><sgmltag class="starttag">shortaffil</sgmltag></para></listitem> +<listitem id="sidebar"><para><sgmltag class="starttag">sidebar</sgmltag></para></listitem> +<listitem id="sidebarinfo"><para><sgmltag class="starttag">sidebarinfo</sgmltag></para></listitem> +<listitem id="simpara"><para><sgmltag class="starttag">simpara</sgmltag></para></listitem> +<listitem id="simplemsgentry"><para><sgmltag class="starttag">simplemsgentry</sgmltag></para></listitem> +<listitem id="simplesect"><para><sgmltag class="starttag">simplesect</sgmltag></para></listitem> +<listitem id="spanspec"><para><sgmltag class="starttag">spanspec</sgmltag></para></listitem> +<listitem id="state"><para><sgmltag class="starttag">state</sgmltag></para></listitem> +<listitem id="street"><para><sgmltag class="starttag">street</sgmltag></para></listitem> +<listitem id="subject"><para><sgmltag class="starttag">subject</sgmltag></para></listitem> +<listitem id="subjectset"><para><sgmltag class="starttag">subjectset</sgmltag></para></listitem> +<listitem id="subjectterm"><para><sgmltag class="starttag">subjectterm</sgmltag></para></listitem> +<listitem id="subtitle"><para><sgmltag class="starttag">subtitle</sgmltag></para></listitem> +<listitem id="systemitem"><para><sgmltag class="starttag">systemitem</sgmltag></para></listitem> +<listitem id="titleabbrev"><para><sgmltag class="starttag">titleabbrev</sgmltag></para></listitem> +<listitem id="toc"><para><sgmltag class="starttag">toc</sgmltag></para></listitem> +<listitem id="tocback"><para><sgmltag class="starttag">tocback</sgmltag></para></listitem> +<listitem id="tocchap"><para><sgmltag class="starttag">tocchap</sgmltag></para></listitem> +<listitem id="tocentry"><para><sgmltag class="starttag">tocentry</sgmltag></para></listitem> +<listitem id="tocfront"><para><sgmltag class="starttag">tocfront</sgmltag></para></listitem> +<listitem id="toclevel1"><para><sgmltag class="starttag">toclevel1</sgmltag></para></listitem> +<listitem id="toclevel2"><para><sgmltag class="starttag">toclevel2</sgmltag></para></listitem> +<listitem id="toclevel3"><para><sgmltag class="starttag">toclevel3</sgmltag></para></listitem> +<listitem id="toclevel4"><para><sgmltag class="starttag">toclevel4</sgmltag></para></listitem> +<listitem id="toclevel5"><para><sgmltag class="starttag">toclevel5</sgmltag></para></listitem> +<listitem id="tocpart"><para><sgmltag class="starttag">tocpart</sgmltag></para></listitem> +<listitem id="videodata"><para><sgmltag class="starttag">videodata</sgmltag></para></listitem> +<listitem id="videoobject"><para><sgmltag class="starttag">videoobject</sgmltag></para></listitem> +<listitem id="volumenum"><para><sgmltag class="starttag">volumenum</sgmltag></para></listitem> +<listitem id="wordasword"><para><sgmltag class="starttag">wordasword</sgmltag></para></listitem> +</itemizedlist> +</chapter> + +<chapter id="alphabetical-list"> +<title>Alphabetical List of all elements</title> + +<para> +This is a list of all the markup elements contained in DocBook XML +4.1.2. Choose the element you are interested in to go directly to the +section of this document which describes it. +</para> + +<note> +<para> +We don't use all these elements in &tde; Documentation - they are here +for completeness. Elements we don't use are listed in <xref +linkend="tags-we-dont-use"/>. +</para> +</note> + +<itemizedlist> +<listitem><para><link linkend="authorinitials"><sgmltag +class="starttag">authorinitials</sgmltag></link></para></listitem> + +<listitem><para><link linkend="beginpage"><sgmltag class="starttag">beginpage</sgmltag></link></para></listitem> +<listitem><para><link linkend="bibliodiv"><sgmltag class="starttag">bibliodiv</sgmltag></link></para></listitem> +<listitem><para><link linkend="biblioentry"><sgmltag class="starttag">biblioentry</sgmltag></link></para></listitem> +<listitem><para><link linkend="bibliographyinfo"><sgmltag class="starttag">bibliographyinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="bibliomset"><sgmltag class="starttag">bibliomset</sgmltag></link></para></listitem> +<listitem><para><link linkend="bibliomisc"><sgmltag class="starttag">bibliomisc</sgmltag></link></para></listitem> +<listitem><para><link linkend="bibliomixed"><sgmltag class="starttag">bibliomixed</sgmltag></link></para></listitem> +<listitem><para><link linkend="biblioset"><sgmltag class="starttag">biblioset</sgmltag></link></para></listitem> +<listitem><para><link linkend="bibliography"><sgmltag class="starttag">bibliography</sgmltag></link></para></listitem> +<listitem><para><link linkend="blockquote"><sgmltag class="starttag">blockquote</sgmltag></link></para></listitem> +<listitem><para><link linkend="book"><sgmltag class="starttag">book</sgmltag></link></para></listitem> +<listitem><para><link linkend="bookbiblio"><sgmltag class="starttag">bookbiblio</sgmltag></link></para></listitem> +<listitem><para><link linkend="bookinfo"><sgmltag class="starttag">bookinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="bridgehead"><sgmltag class="starttag">bridgehead</sgmltag></link></para></listitem> +<listitem><para><link linkend="co"><sgmltag class="starttag">co</sgmltag></link></para></listitem> +<listitem><para><link linkend="callout"><sgmltag class="starttag">callout</sgmltag></link></para></listitem> +<listitem><para><link linkend="calloutlist"><sgmltag class="starttag">calloutlist</sgmltag></link></para></listitem> +<listitem><para><link linkend="caption"><sgmltag class="starttag">caption</sgmltag></link></para></listitem> +<listitem><para><link linkend="caution"><sgmltag class="starttag">caution</sgmltag></link></para></listitem> +<listitem><para><link linkend="chapter"><sgmltag class="starttag">chapter</sgmltag></link></para></listitem> +<listitem><para><link linkend="chapterinfo"><sgmltag class="starttag">chapterinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="citation"><sgmltag class="starttag">citation</sgmltag></link></para></listitem> +<listitem><para><link linkend="citerefentry"><sgmltag class="starttag">citerefentry</sgmltag></link></para></listitem> +<listitem><para><link linkend="citetitle"><sgmltag class="starttag">citetitle</sgmltag></link></para></listitem> +<listitem><para><link linkend="city"><sgmltag class="starttag">city</sgmltag></link></para></listitem> +<listitem><para><link linkend="classname"><sgmltag class="starttag">classname</sgmltag></link></para></listitem> +<listitem><para><link linkend="classsynopsis"><sgmltag class="starttag">classsynopsis</sgmltag></link></para></listitem> +<listitem><para><link linkend="classsynopsisinfo"><sgmltag class="starttag">classsynopsisinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="cmdsynopsis"><sgmltag class="starttag">cmdsynopsis</sgmltag></link></para></listitem> +<listitem><para><link linkend="colspec"><sgmltag class="starttag">colspec</sgmltag></link></para></listitem> +<listitem><para><link linkend="collab"><sgmltag class="starttag">collab</sgmltag></link></para></listitem> +<listitem><para><link linkend="collabname"><sgmltag class="starttag">collabname</sgmltag></link></para></listitem> +<listitem><para><link linkend="colophon"><sgmltag class="starttag">colophon</sgmltag></link></para></listitem> +<listitem><para><link linkend="command"><sgmltag class="starttag">command</sgmltag></link></para></listitem> +<listitem><para><link linkend="comment"><sgmltag class="starttag">comment</sgmltag></link></para></listitem> +<listitem><para><link linkend="computeroutput"><sgmltag class="starttag">computeroutput</sgmltag></link></para></listitem> +<listitem><para><link linkend="confdates"><sgmltag class="starttag">confdates</sgmltag></link></para></listitem> +<listitem><para><link linkend="confgroup"><sgmltag class="starttag">confgroup</sgmltag></link></para></listitem> +<listitem><para><link linkend="confnum"><sgmltag class="starttag">confnum</sgmltag></link></para></listitem> +<listitem><para><link linkend="confsponsor"><sgmltag class="starttag">confsponsor</sgmltag></link></para></listitem> +<listitem><para><link linkend="conftitle"><sgmltag class="starttag">conftitle</sgmltag></link></para></listitem> +<listitem><para><link linkend="constant"><sgmltag class="starttag">constant</sgmltag></link></para></listitem> +<listitem><para><link linkend="constructorsynopsis"><sgmltag class="starttag">constructorsynopsis</sgmltag></link></para></listitem> +<listitem><para><link linkend="contractnum"><sgmltag class="starttag">contractnum</sgmltag></link></para></listitem> +<listitem><para><link linkend="contractsponsor"><sgmltag class="starttag">contractspnosor</sgmltag></link></para></listitem> +<listitem><para><link linkend="contrib"><sgmltag class="starttag">contrib</sgmltag></link></para></listitem> +<listitem><para><link linkend="copyright"><sgmltag class="starttag">copyright</sgmltag></link></para></listitem> +<listitem><para><link linkend="corpauthor"><sgmltag class="starttag">corpauthor</sgmltag></link></para></listitem> +<listitem><para><link linkend="corpname"><sgmltag class="starttag">corpname</sgmltag></link></para></listitem> +<listitem><para><link linkend="country"><sgmltag class="starttag">country</sgmltag></link></para></listitem> +<listitem><para><link linkend="database"><sgmltag class="starttag">database</sgmltag></link></para></listitem> +<listitem><para><link linkend="date"><sgmltag class="starttag">date</sgmltag></link></para></listitem> +<listitem><para><link linkend="dedication"><sgmltag class="starttag">dedication</sgmltag></link></para></listitem> +<listitem><para><link linkend="destructorsynopsis"><sgmltag class="starttag">destructorsynopsis</sgmltag></link></para></listitem> +<listitem><para><link linkend="docinfo"><sgmltag class="starttag">docinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="edition"><sgmltag class="starttag">edition</sgmltag></link></para></listitem> +<listitem><para><link linkend="editor"><sgmltag class="starttag">editor</sgmltag></link></para></listitem> +<listitem><para><link linkend="email"><sgmltag class="starttag">email</sgmltag></link></para></listitem> +<listitem><para><link linkend="emphasis"><sgmltag class="starttag">emphasis</sgmltag></link></para></listitem> +<listitem><para><link linkend="envar"><sgmltag class="starttag">envar</sgmltag></link></para></listitem> +<listitem><para><link linkend="entry"><sgmltag class="starttag">entry</sgmltag></link></para></listitem> +<listitem><para><link linkend="entrytbl"><sgmltag class="starttag">entrytbl</sgmltag></link></para></listitem> +<listitem><para><link linkend="epigraph"><sgmltag class="starttag">epigraph</sgmltag></link></para></listitem> +<listitem><para><link linkend="equation"><sgmltag class="starttag">equation</sgmltag></link></para></listitem> +<listitem><para><link linkend="errorcode"><sgmltag class="starttag">errorcode</sgmltag></link></para></listitem> +<listitem><para><link linkend="errorname"><sgmltag class="starttag">errorname</sgmltag></link></para></listitem> +<listitem><para><link linkend="errortype"><sgmltag class="starttag">errortype</sgmltag></link></para></listitem> +<listitem><para><link linkend="example"><sgmltag class="starttag">example</sgmltag></link></para></listitem> +<listitem><para><link linkend="exceptionname"><sgmltag class="starttag">exceptionname</sgmltag></link></para></listitem> +<listitem><para><link linkend="fax"><sgmltag class="starttag">fax</sgmltag></link></para></listitem> +<listitem><para><link linkend="figure"><sgmltag class="starttag">figure</sgmltag></link></para></listitem> +<listitem><para><link linkend="fieldsynopsis"><sgmltag class="starttag">fieldsynopsis</sgmltag></link></para></listitem> +<listitem><para><link linkend="filename"><sgmltag class="starttag">filename</sgmltag></link></para></listitem> +<listitem><para><link linkend="firstterm"><sgmltag class="starttag">firstterm</sgmltag></link></para></listitem> +<listitem><para><link linkend="footnote"><sgmltag class="starttag">footnote</sgmltag></link></para></listitem> +<listitem><para><link linkend="footnoteref"><sgmltag class="starttag">footnoteref</sgmltag></link></para></listitem> +<listitem><para><link linkend="foreignphrase"><sgmltag class="starttag">foreignphrase</sgmltag></link></para></listitem> +<listitem><para><link linkend="formalpara"><sgmltag class="starttag">formalpara</sgmltag></link></para></listitem> +<listitem><para><link linkend="funcdef"><sgmltag class="starttag">funcdef</sgmltag></link></para></listitem> +<listitem><para><link linkend="funcparams"><sgmltag class="starttag">funcparams</sgmltag></link></para></listitem> +<listitem><para><link linkend="funcprototype"><sgmltag class="starttag">funcprototype</sgmltag></link></para></listitem> +<listitem><para><link linkend="funcsynopsis"><sgmltag class="starttag">funcsynopsis</sgmltag></link></para></listitem> +<listitem><para><link linkend="funcsynopsisinfo"><sgmltag class="starttag">funcsynopsisinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="function"><sgmltag class="starttag">function</sgmltag></link></para></listitem> +<listitem><para><link linkend="guibutton"><sgmltag class="starttag">guibutton</sgmltag></link></para></listitem> +<listitem><para><link linkend="guiicon"><sgmltag class="starttag">guiicon</sgmltag></link></para></listitem> +<listitem><para><link linkend="guilabel"><sgmltag class="starttag">guilabel</sgmltag></link></para></listitem> +<listitem><para><link linkend="guimenu"><sgmltag class="starttag">guimenu</sgmltag></link></para></listitem> +<listitem><para><link linkend="guimenuitem"><sgmltag class="starttag">guimenuitem</sgmltag></link></para></listitem> +<listitem><para><link linkend="guisubmenu"><sgmltag class="starttag">guisubmenu</sgmltag></link></para></listitem> +<listitem><para><link linkend="glossdef"><sgmltag class="starttag">glossdef</sgmltag></link></para></listitem> +<listitem><para><link linkend="glossdiv"><sgmltag class="starttag">glossdiv</sgmltag></link></para></listitem> +<listitem><para><link linkend="glossentry"><sgmltag class="starttag">glossentry</sgmltag></link></para></listitem> +<listitem><para><link linkend="glosslist"><sgmltag class="starttag">glosslist</sgmltag></link></para></listitem> +<listitem><para><link linkend="glosssee"><sgmltag class="starttag">glosssee</sgmltag></link></para></listitem> +<listitem><para><link linkend="glossseealso"><sgmltag class="starttag">glossseealso</sgmltag></link></para></listitem> +<listitem><para><link linkend="glossterm"><sgmltag class="starttag">glossterm</sgmltag></link></para></listitem> +<listitem><para><link linkend="glossary"><sgmltag class="starttag">glossary</sgmltag></link></para></listitem> +<listitem><para><link linkend="glossaryinfo"><sgmltag class="starttag">glossaryinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="graphic"><sgmltag class="starttag">graphic</sgmltag></link></para></listitem> +<listitem><para><link linkend="graphicco"><sgmltag class="starttag">graphicco</sgmltag></link></para></listitem> +<listitem><para><link linkend="group"><sgmltag class="starttag">group</sgmltag></link></para></listitem> +<listitem><para><link linkend="hardware"><sgmltag class="starttag">hardware</sgmltag></link></para></listitem> +<listitem><para><link linkend="highlights"><sgmltag class="starttag">highlights</sgmltag></link></para></listitem> +<listitem><para><link linkend="holder"><sgmltag class="starttag">holder</sgmltag></link></para></listitem> +<listitem><para><link linkend="honorific"><sgmltag class="starttag">honorific</sgmltag></link></para></listitem> +<listitem><para><link linkend="isbn"><sgmltag class="starttag">isbn</sgmltag></link></para></listitem> +<listitem><para><link linkend="issn"><sgmltag class="starttag">issn</sgmltag></link></para></listitem> +<listitem><para><link linkend="itermset"><sgmltag class="starttag">itermset</sgmltag></link></para></listitem> +<listitem><para><link linkend="imagedata"><sgmltag class="starttag">imagedata</sgmltag></link></para></listitem> +<listitem><para><link linkend="imageobject"><sgmltag class="starttag">imageobject</sgmltag></link></para></listitem> +<listitem><para><link linkend="imageobjectco"><sgmltag class="starttag">imabeobjectco</sgmltag></link></para></listitem> +<listitem><para><link linkend="important"><sgmltag class="starttag">important</sgmltag></link></para></listitem> +<listitem><para><link linkend="index"><sgmltag class="starttag">index</sgmltag></link></para></listitem> +<listitem><para><link linkend="indexdiv"><sgmltag class="starttag">indexdiv</sgmltag></link></para></listitem> +<listitem><para><link linkend="indexentry"><sgmltag class="starttag">indexentry</sgmltag></link></para></listitem> +<listitem><para><link linkend="indexinfo"><sgmltag class="starttag">indexinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="indexterm"><sgmltag class="starttag">indexterm</sgmltag></link></para></listitem> +<listitem><para><link linkend="informalequation"><sgmltag class="starttag">informalequation</sgmltag></link></para></listitem> +<listitem><para><link linkend="informalexample"><sgmltag class="starttag">informalexample</sgmltag></link></para></listitem> +<listitem><para><link linkend="informalfigure"><sgmltag class="starttag">informalfigure</sgmltag></link></para></listitem> +<listitem><para><link linkend="informaltable"><sgmltag class="starttag">informaltable</sgmltag></link></para></listitem> +<listitem><para><link linkend="initializer"><sgmltag class="starttag">initializer</sgmltag></link></para></listitem> +<listitem><para><link linkend="inlineequation"><sgmltag class="starttag">inlineequation</sgmltag></link></para></listitem> +<listitem><para><link linkend="inlinegraphic"><sgmltag class="starttag">inlinegraphic</sgmltag></link></para></listitem> +<listitem><para><link linkend="inlinemediaobject"><sgmltag class="starttag">inlinemediaobject</sgmltag></link></para></listitem> +<listitem><para><link linkend="interface"><sgmltag class="starttag">interface</sgmltag></link></para></listitem> +<listitem><para><link linkend="interfacedefinition"><sgmltag class="starttag">interfacedefinition</sgmltag></link></para></listitem> +<listitem><para><link linkend="interfacename"><sgmltag class="starttag">interfacename</sgmltag></link></para></listitem> +<listitem><para><link linkend="invpartnumber"><sgmltag class="starttag">invpartnumber</sgmltag></link></para></listitem> +<listitem><para><link linkend="issuenum"><sgmltag class="starttag">issuenum</sgmltag></link></para></listitem> +<listitem><para><link linkend="itemizedlist"><sgmltag class="starttag">itemizedlist</sgmltag></link></para></listitem> +<listitem><para><link linkend="jobtitle"><sgmltag class="starttag">jobtitle</sgmltag></link></para></listitem> +<listitem><para><link linkend="keycap"><sgmltag class="starttag">keycap</sgmltag></link></para></listitem> +<listitem><para><link linkend="keycode"><sgmltag class="starttag">keycode</sgmltag></link></para></listitem> +<listitem><para><link linkend="keycombo"><sgmltag class="starttag">keycombo</sgmltag></link></para></listitem> +<listitem><para><link linkend="keysym"><sgmltag class="starttag">keysym</sgmltag></link></para></listitem> +<listitem><para><link linkend="keyword"><sgmltag class="starttag">keyword</sgmltag></link></para></listitem> +<listitem><para><link linkend="keywordset"><sgmltag class="starttag">keywordset</sgmltag></link></para></listitem> +<listitem><para><link linkend="legalnotice"><sgmltag class="starttag">legalnotice</sgmltag></link></para></listitem> +<listitem><para><link linkend="lineannotation"><sgmltag class="starttag">lineannotation</sgmltag></link></para></listitem> +<listitem><para><link linkend="lineage"><sgmltag class="starttag">lineage</sgmltag></link></para></listitem> +<listitem><para><link linkend="link"><sgmltag class="starttag">link</sgmltag></link></para></listitem> +<listitem><para><link linkend="listitem"><sgmltag class="starttag">listitem</sgmltag></link></para></listitem> +<listitem><para><link linkend="literal"><sgmltag class="starttag">literal</sgmltag></link></para></listitem> +<listitem><para><link linkend="literallayout"><sgmltag class="starttag">literallayout</sgmltag></link></para></listitem> +<listitem><para><link linkend="lot"><sgmltag class="starttag">lot</sgmltag></link></para></listitem> +<listitem><para><link linkend="lotentry"><sgmltag class="starttag">lotentry</sgmltag></link></para></listitem> +<listitem><para><link linkend="manvolnum"><sgmltag class="starttag">manvolnum</sgmltag></link></para></listitem> +<listitem><para><link linkend="markup"><sgmltag class="starttag">markup</sgmltag></link></para></listitem> +<listitem><para><link linkend="medialabel"><sgmltag class="starttag">medialabel</sgmltag></link></para></listitem> +<listitem><para><link linkend="mediaobject"><sgmltag class="starttag">mediaobject</sgmltag></link></para></listitem> +<listitem><para><link linkend="mediaobjectco"><sgmltag class="starttag">mediaobjectco</sgmltag></link></para></listitem> +<listitem><para><link linkend="member"><sgmltag class="starttag">member</sgmltag></link></para></listitem> +<listitem><para><link linkend="menuchoice"><sgmltag class="starttag">menuchoice</sgmltag></link></para></listitem> +<listitem><para><link linkend="methodname"><sgmltag class="starttag">methodname</sgmltag></link></para></listitem> +<listitem><para><link linkend="methodparam"><sgmltag class="starttag">methodparam</sgmltag></link></para></listitem> +<listitem><para><link linkend="methodsynopsis"><sgmltag class="starttag">methodsynopsis</sgmltag></link></para></listitem> +<listitem><para><link linkend="modespec"><sgmltag class="starttag">modespec</sgmltag></link></para></listitem> +<listitem><para><link linkend="modifier"><sgmltag class="starttag">modifier</sgmltag></link></para></listitem> +<listitem><para><link linkend="mousebutton"><sgmltag class="starttag">mousebutton</sgmltag></link></para></listitem> +<listitem><para><link linkend="msg"><sgmltag class="starttag">msg</sgmltag></link></para></listitem> +<listitem><para><link linkend="msgaud"><sgmltag class="starttag">nmsgaud</sgmltag></link></para></listitem> +<listitem><para><link linkend="msgentry"><sgmltag class="starttag">msgentry</sgmltag></link></para></listitem> +<listitem><para><link linkend="msgexplan"><sgmltag class="starttag">msgexplan</sgmltag></link></para></listitem> +<listitem><para><link linkend="msginfo"><sgmltag class="starttag">msginfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="msglevel"><sgmltag class="starttag">msglevel</sgmltag></link></para></listitem> +<listitem><para><link linkend="msgmain"><sgmltag class="starttag">msgmain</sgmltag></link></para></listitem> +<listitem><para><link linkend="msgorig"><sgmltag class="starttag">msgorig</sgmltag></link></para></listitem> +<listitem><para><link linkend="msgrel"><sgmltag class="starttag">msgrel</sgmltag></link></para></listitem> +<listitem><para><link linkend="msgset"><sgmltag class="starttag">msgset</sgmltag></link></para></listitem> +<listitem><para><link linkend="msgsub"><sgmltag class="starttag">msgsub</sgmltag></link></para></listitem> +<listitem><para><link linkend="msgtext"><sgmltag class="starttag">msgtext</sgmltag></link></para></listitem> +<listitem><para><link linkend="note"><sgmltag class="starttag">note</sgmltag></link></para></listitem> +<listitem><para><link linkend="olink"><sgmltag class="starttag">olink</sgmltag></link></para></listitem> +<listitem><para><link linkend="objectinfo"><sgmltag class="starttag">objectinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="option"><sgmltag class="starttag">option</sgmltag></link></para></listitem> +<listitem><para><link linkend="optional"><sgmltag class="starttag">optional</sgmltag></link></para></listitem> +<listitem><para><link linkend="orderedlist"><sgmltag class="starttag">orderedlist</sgmltag></link></para></listitem> +<listitem><para><link linkend="orgdiv"><sgmltag class="starttag">orgdiv</sgmltag></link></para></listitem> +<listitem><para><link linkend="orgname"><sgmltag class="starttag">orgname</sgmltag></link></para></listitem> +<listitem><para><link linkend="otheraddr"><sgmltag class="starttag">otheraddr</sgmltag></link></para></listitem> +<listitem><para><link linkend="othercredit"><sgmltag class="starttag">othercredit</sgmltag></link></para></listitem> +<listitem><para><link linkend="othername"><sgmltag class="starttag">othername</sgmltag></link></para></listitem> +<listitem><para><link linkend="pob"><sgmltag class="starttag">pob</sgmltag></link></para></listitem> +<listitem><para><link linkend="pagenums"><sgmltag class="starttag">pagenums</sgmltag></link></para></listitem> +<listitem><para><link linkend="para"><sgmltag class="starttag">para</sgmltag></link></para></listitem> +<listitem><para><link linkend="paramdef"><sgmltag class="starttag">paramdef</sgmltag></link></para></listitem> +<listitem><para><link linkend="parameter"><sgmltag class="starttag">parameter</sgmltag></link></para></listitem> +<listitem><para><link linkend="part"><sgmltag class="starttag">part</sgmltag></link></para></listitem> +<listitem><para><link linkend="partintro"><sgmltag class="starttag">partintro</sgmltag></link></para></listitem> +<listitem><para><link linkend="phone"><sgmltag class="starttag">phone</sgmltag></link></para></listitem> +<listitem><para><link linkend="phrase"><sgmltag class="starttag">phrase</sgmltag></link></para></listitem> +<listitem><para><link linkend="postcode"><sgmltag class="starttag">postcode</sgmltag></link></para></listitem> +<listitem><para><link linkend="preface"><sgmltag class="starttag">preface</sgmltag></link></para></listitem> +<listitem><para><link linkend="prefaceinfo"><sgmltag class="starttag">prefaceinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="primary"><sgmltag class="starttag">primary</sgmltag></link></para></listitem> +<listitem><para><link linkend="primaryie"><sgmltag class="starttag">primaryie</sgmltag></link></para></listitem> +<listitem><para><link linkend="printhistory"><sgmltag class="starttag">printhistory</sgmltag></link></para></listitem> +<listitem><para><link linkend="procedure"><sgmltag class="starttag">procedure</sgmltag></link></para></listitem> +<listitem><para><link linkend="productname"><sgmltag class="starttag">productname</sgmltag></link></para></listitem> +<listitem><para><link linkend="productnumber"><sgmltag class="starttag">productnumber</sgmltag></link></para></listitem> +<listitem><para><link linkend="programlisting"><sgmltag class="starttag">programlistingco</sgmltag></link></para></listitem> +<listitem><para><link linkend="prompt"><sgmltag class="starttag">prompt</sgmltag></link></para></listitem> +<listitem><para><link linkend="property"><sgmltag class="starttag">property</sgmltag></link></para></listitem> +<listitem><para><link linkend="pubdate"><sgmltag class="starttag">pubdate</sgmltag></link></para></listitem> +<listitem><para><link linkend="publisher"><sgmltag class="starttag">publisher</sgmltag></link></para></listitem> +<listitem><para><link linkend="publishername"><sgmltag class="starttag">publishername</sgmltag></link></para></listitem> +<listitem><para><link linkend="pubsnumber"><sgmltag class="starttag">pubsnumber</sgmltag></link></para></listitem> +<listitem><para><link linkend="qandadiv"><sgmltag class="starttag">qandadiv</sgmltag></link></para></listitem> +<listitem><para><link linkend="qandaentry"><sgmltag class="starttag">qandaentry</sgmltag></link></para></listitem> +<listitem><para><link linkend="qandaset"><sgmltag class="starttag">qandaset</sgmltag></link></para></listitem> +<listitem><para><link linkend="question"><sgmltag class="starttag">question</sgmltag></link></para></listitem> +<listitem><para><link linkend="quote"><sgmltag class="starttag">quote</sgmltag></link></para></listitem> +<listitem><para><link linkend="refclass"><sgmltag class="starttag">refclass</sgmltag></link></para></listitem> +<listitem><para><link linkend="refdescriptor"><sgmltag class="starttag">refdescriptor</sgmltag></link></para></listitem> +<listitem><para><link linkend="refentry"><sgmltag class="starttag">refentry</sgmltag></link></para></listitem> +<listitem><para><link linkend="refentryinfo"><sgmltag class="starttag">refentryinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="refentrytitle"><sgmltag class="starttag">refentrytitle</sgmltag></link></para></listitem> +<listitem><para><link linkend="referenceinfo"><sgmltag class="starttag">referenceinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="refmeta"><sgmltag class="starttag">refmeta</sgmltag></link></para></listitem> +<listitem><para><link linkend="refmiscinfo"><sgmltag class="starttag">refmiscinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="refname"><sgmltag class="starttag">refname</sgmltag></link></para></listitem> +<listitem><para><link linkend="refnamediv"><sgmltag class="starttag">refnamediv</sgmltag></link></para></listitem> +<listitem><para><link linkend="refpurpose"><sgmltag class="starttag">refpurpose</sgmltag></link></para></listitem> +<listitem><para><link linkend="refsect1"><sgmltag class="starttag">refsect1</sgmltag></link></para></listitem> +<listitem><para><link linkend="refsect1info"><sgmltag class="starttag">refsect1info</sgmltag></link></para></listitem> +<listitem><para><link linkend="refsect2"><sgmltag class="starttag">refsect2</sgmltag></link></para></listitem> +<listitem><para><link linkend="refsect2info"><sgmltag class="starttag">refsect2info</sgmltag></link></para></listitem> +<listitem><para><link linkend="refsect3"><sgmltag class="starttag">refsect3info</sgmltag></link></para></listitem> +<listitem><para><link linkend="refsect3info"><sgmltag class="starttag">refsect3info</sgmltag></link></para></listitem> +<listitem><para><link linkend="refsynopsisdiv"><sgmltag class="starttag">refsynopsisdiv</sgmltag></link></para></listitem> +<listitem><para><link linkend="refsynopsisdivinfo"><sgmltag class="starttag">refsynopsisdivinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="reference"><sgmltag class="starttag">reference</sgmltag></link></para></listitem> +<listitem><para><link linkend="releaseinfo"><sgmltag class="starttag">releaseinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="remark"><sgmltag class="starttag">remark</sgmltag></link></para></listitem> +<listitem><para><link linkend="replaceable"><sgmltag class="starttag">replaceable</sgmltag></link></para></listitem> +<listitem><para><link linkend="returnvalue"><sgmltag class="starttag">returnvalue</sgmltag></link></para></listitem> +<listitem><para><link linkend="revdescription"><sgmltag class="starttag">revdescription</sgmltag></link></para></listitem> +<listitem><para><link linkend="revhistory"><sgmltag class="starttag">revhistory</sgmltag></link></para></listitem> +<listitem><para><link linkend="revnumber"><sgmltag class="starttag">revnumber</sgmltag></link></para></listitem> +<listitem><para><link linkend="revremark"><sgmltag class="starttag">revremark</sgmltag></link></para></listitem> +<listitem><para><link linkend="revision"><sgmltag class="starttag">revision</sgmltag></link></para></listitem> +<listitem><para><link linkend="row"><sgmltag class="starttag">row</sgmltag></link></para></listitem> +<listitem><para><link linkend="sbr"><sgmltag class="starttag">sbr</sgmltag></link></para></listitem> +<listitem><para><link linkend="sgmltag"><sgmltag class="starttag">sgmltag</sgmltag></link></para></listitem> +<listitem><para><link linkend="screen"><sgmltag class="starttag">screen</sgmltag></link></para></listitem> +<listitem><para><link linkend="screenco"><sgmltag class="starttag">screenco</sgmltag></link></para></listitem> +<listitem><para><link linkend="screeninfo"><sgmltag class="starttag">screeninfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="screenshot"><sgmltag class="starttag">screenshot</sgmltag></link></para></listitem> +<listitem><para><link linkend="secondary"><sgmltag class="starttag">secondary</sgmltag></link></para></listitem> +<listitem><para><link linkend="secondaryie"><sgmltag class="starttag">secondaryie</sgmltag></link></para></listitem> +<listitem><para><link linkend="sect1"><sgmltag class="starttag">sect1</sgmltag></link></para></listitem> +<listitem><para><link linkend="sect1info"><sgmltag class="starttag">sect1info</sgmltag></link></para></listitem> +<listitem><para><link linkend="sect2"><sgmltag class="starttag">sect2</sgmltag></link></para></listitem> +<listitem><para><link linkend="sect2info"><sgmltag class="starttag">sect2info</sgmltag></link></para></listitem> +<listitem><para><link linkend="sect3"><sgmltag class="starttag">sect3</sgmltag></link></para></listitem> +<listitem><para><link linkend="sect3info"><sgmltag class="starttag">sect3info</sgmltag></link></para></listitem> +<listitem><para><link linkend="sect4"><sgmltag class="starttag">sect4</sgmltag></link></para></listitem> +<listitem><para><link linkend="sect4info"><sgmltag class="starttag">sect4info</sgmltag></link></para></listitem> +<listitem><para><link linkend="sect5"><sgmltag class="starttag">sect5</sgmltag></link></para></listitem> +<listitem><para><link linkend="sect5info"><sgmltag class="starttag">sect5info</sgmltag></link></para></listitem> +<listitem><para><link linkend="section"><sgmltag class="starttag">section</sgmltag></link></para></listitem> +<listitem><para><link linkend="sectioninfo"><sgmltag class="starttag">sectioninfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="see"><sgmltag class="starttag">see</sgmltag></link></para></listitem> +<listitem><para><link linkend="seealso"><sgmltag class="starttag">seealso</sgmltag></link></para></listitem> +<listitem><para><link linkend="seealsoie"><sgmltag class="starttag">seealsoie</sgmltag></link></para></listitem> +<listitem><para><link linkend="seeie"><sgmltag class="starttag">seeie</sgmltag></link></para></listitem> +<listitem><para><link linkend="seg"><sgmltag class="starttag">seg</sgmltag></link></para></listitem> +<listitem><para><link linkend="seglistitem"><sgmltag class="starttag">seglistitem</sgmltag></link></para></listitem> +<listitem><para><link linkend="segmentedlist"><sgmltag class="starttag">segmentedlist</sgmltag></link></para></listitem> +<listitem><para><link linkend="seriesinfo"><sgmltag class="starttag">seriesinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="seriesvolnums"><sgmltag class="starttag">seriesvolnums</sgmltag></link></para></listitem> +<listitem><para><link linkend="set"><sgmltag class="starttag">set</sgmltag></link></para></listitem> +<listitem><para><link linkend="setindex"><sgmltag class="starttag">setindex</sgmltag></link></para></listitem> +<listitem><para><link linkend="setindexinfo"><sgmltag class="starttag">setindexinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="setinfo"><sgmltag class="starttag">setinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="shortaffil"><sgmltag class="starttag">shortaffil</sgmltag></link></para></listitem> +<listitem><para><link linkend="shortcut"><sgmltag class="starttag">shortcut</sgmltag></link></para></listitem> +<listitem><para><link linkend="sidebar"><sgmltag class="starttag">sidebar</sgmltag></link></para></listitem> +<listitem><para><link linkend="sidebarinfo"><sgmltag class="starttag">sidebarinfo</sgmltag></link></para></listitem> +<listitem><para><link linkend="simpara"><sgmltag class="starttag">simpara</sgmltag></link></para></listitem> +<listitem><para><link linkend="simplelist"><sgmltag class="starttag">simplelist</sgmltag></link></para></listitem> +<listitem><para><link linkend="simplemsgentry"><sgmltag class="starttag">simplemsgentry</sgmltag></link></para></listitem> +<listitem><para><link linkend="simplesect"><sgmltag class="starttag">simplesect</sgmltag></link></para></listitem> +<listitem><para><link linkend="spanspec"><sgmltag class="starttag">spanspec</sgmltag></link></para></listitem> +<listitem><para><link linkend="state"><sgmltag class="starttag">state</sgmltag></link></para></listitem> +<listitem><para><link linkend="step"><sgmltag class="starttag">step</sgmltag></link></para></listitem> +<listitem><para><link linkend="street"><sgmltag class="starttag">street</sgmltag></link></para></listitem> +<listitem><para><link linkend="structfield"><sgmltag class="starttag">structfield</sgmltag></link></para></listitem> +<listitem><para><link linkend="structname"><sgmltag class="starttag">structname</sgmltag></link></para></listitem> +<listitem><para><link linkend="substeps"><sgmltag class="starttag">substeps</sgmltag></link></para></listitem> +<listitem><para><link linkend="subject"><sgmltag class="starttag">subject</sgmltag></link></para></listitem> +<listitem><para><link linkend="subjectset"><sgmltag class="starttag">subjectset</sgmltag></link></para></listitem> +<listitem><para><link linkend="subjectterm"><sgmltag class="starttag">subjectterm</sgmltag></link></para></listitem> +<listitem><para><link linkend="subscript"><sgmltag class="starttag">subscript</sgmltag></link></para></listitem> +<listitem><para><link linkend="subtitle"><sgmltag class="starttag">subtitle</sgmltag></link></para></listitem> +<listitem><para><link linkend="superscript"><sgmltag class="starttag">superscript</sgmltag></link></para></listitem> +<listitem><para><link linkend="surname"><sgmltag class="starttag">surname</sgmltag></link></para></listitem> +<listitem><para><link linkend="symbol"><sgmltag class="starttag">symbol</sgmltag></link></para></listitem> +<listitem><para><link linkend="synopfragment"><sgmltag class="starttag">synopfragment</sgmltag></link></para></listitem> +<listitem><para><link linkend="synopsis"><sgmltag class="starttag">synopsis</sgmltag></link></para></listitem> +<listitem><para><link linkend="systemitem"><sgmltag class="starttag">systemitem</sgmltag></link></para></listitem> +<listitem><para><link linkend="tbody"><sgmltag class="starttag">tbody</sgmltag></link></para></listitem> +<listitem><para><link linkend="tfoot"><sgmltag class="starttag">tfoot</sgmltag></link></para></listitem> +<listitem><para><link linkend="tgroup"><sgmltag class="starttag">tgroup</sgmltag></link></para></listitem> +<listitem><para><link linkend="thead"><sgmltag class="starttag">thead</sgmltag></link></para></listitem> +<listitem><para><link linkend="table"><sgmltag class="starttag">table</sgmltag></link></para></listitem> +<listitem><para><link linkend="term"><sgmltag class="starttag">term</sgmltag></link></para></listitem> +<listitem><para><link linkend="tertiary"><sgmltag class="starttag">tertiary</sgmltag></link></para></listitem> +<listitem><para><link linkend="tertiaryie"><sgmltag class="starttag">tertiaryie</sgmltag></link></para></listitem> +<listitem><para><link linkend="textobject"><sgmltag class="starttag">textobject</sgmltag></link></para></listitem> +<listitem><para><link linkend="tip"><sgmltag class="starttag">tip</sgmltag></link></para></listitem> +<listitem><para><link linkend="title"><sgmltag class="starttag">title</sgmltag></link></para></listitem> +<listitem><para><link linkend="titleabbrev"><sgmltag class="starttag">titleabbrev</sgmltag></link></para></listitem> +<listitem><para><link linkend="toc"><sgmltag class="starttag">toc</sgmltag></link></para></listitem> +<listitem><para><link linkend="tocback"><sgmltag class="starttag">tocback</sgmltag></link></para></listitem> +<listitem><para><link linkend="tocchap"><sgmltag class="starttag">tocchap</sgmltag></link></para></listitem> +<listitem><para><link linkend="tocentry"><sgmltag class="starttag">tocentry</sgmltag></link></para></listitem> +<listitem><para><link linkend="tocfront"><sgmltag class="starttag">tocfront</sgmltag></link></para></listitem> +<listitem><para><link linkend="toclevel1"><sgmltag class="starttag">toclevel1</sgmltag></link></para></listitem> +<listitem><para><link linkend="toclevel2"><sgmltag class="starttag">toclevel2</sgmltag></link></para></listitem> +<listitem><para><link linkend="toclevel3"><sgmltag class="starttag">toclevel3</sgmltag></link></para></listitem> +<listitem><para><link linkend="toclevel4"><sgmltag class="starttag">toclevel4</sgmltag></link></para></listitem> +<listitem><para><link linkend="toclevel5"><sgmltag class="starttag">toclevel5</sgmltag></link></para></listitem> +<listitem><para><link linkend="tocpart"><sgmltag class="starttag">tocpart</sgmltag></link></para></listitem> +<listitem><para><link linkend="token"><sgmltag class="starttag">token</sgmltag></link></para></listitem> +<listitem><para><link linkend="trademark"><sgmltag class="starttag">trademark</sgmltag></link></para></listitem> +<listitem><para><link linkend="type"><sgmltag class="starttag">type</sgmltag></link></para></listitem> +<listitem><para><link linkend="ulink"><sgmltag class="starttag">ulink</sgmltag></link></para></listitem> +<listitem><para><link linkend="userinput"><sgmltag class="starttag">userinput</sgmltag></link></para></listitem> +<listitem><para><link linkend="varargs"><sgmltag class="starttag">varargs</sgmltag></link></para></listitem> +<listitem><para><link linkend="varlistentry"><sgmltag class="starttag">varlistentry</sgmltag></link></para></listitem> +<listitem><para><link linkend="varname"><sgmltag class="starttag">varname</sgmltag></link></para></listitem> +<listitem><para><link linkend="variablelist"><sgmltag class="starttag">variablelist</sgmltag></link></para></listitem> +<listitem><para><link linkend="videodata"><sgmltag class="starttag">videodata</sgmltag></link></para></listitem> +<listitem><para><link linkend="videoobject"><sgmltag class="starttag">videoobject</sgmltag></link></para></listitem> +<listitem><para><link linkend="void"><sgmltag class="starttag">void</sgmltag></link></para></listitem> +<listitem><para><link linkend="volumenum"><sgmltag class="starttag">volumenum</sgmltag></link></para></listitem> +<listitem><para><link linkend="warning"><sgmltag class="starttag">warning</sgmltag></link></para></listitem> +<listitem><para><link linkend="wordasword"><sgmltag class="starttag">wordasword</sgmltag></link></para></listitem> +<listitem><para><link linkend="xref"><sgmltag class="starttag">xref</sgmltag></link></para></listitem> +<listitem><para><link linkend="year"><sgmltag class="starttag">year</sgmltag></link></para></listitem> +</itemizedlist> + +</chapter> + +<chapter id="credits-and-license"> +<title>Credits and License</title> +<para>Document copyright 2000, 2001 Lauri Watts +<email>lauri@kde.org</email></para> + +<para> +This reference was written with substantial help and input from the +following people who definitely deserve credit: +</para> + +<itemizedlist> +<listitem><para>Frederik Fouvry</para></listitem> +<listitem><para>Eric Bischoff</para></listitem> +<listitem><para>Michael McBride</para></listitem> +<listitem><para>Lee Wee Tiong</para></listitem> +<listitem><para>Philip Rodrigues</para></listitem> +<listitem><para>Eyal Lotem +<email>GNUPeaker@yahoo.com</email></para></listitem> +<listitem><para>Malte Starostik +<email>malte.starostik@t-online.de</email></para></listitem> +<listitem><para>Antonio Larossa Jiminez</para></listitem> +</itemizedlist> + +&underFDL; +</chapter> + +<appendix id="appendix-entities"> +<title>Entities</title> + +<para>TODO</para> +</appendix> + +</book> +<!-- +Local Variables: +mode: sgml +sgml-indent-step:0 +sgml-indent-data:nil +End: +--> |