diff options
Diffstat (limited to 'doc/tutorials')
21 files changed, 7992 insertions, 0 deletions
diff --git a/doc/tutorials/CMakeLists.txt b/doc/tutorials/CMakeLists.txt new file mode 100644 index 0000000..6bc5f18 --- /dev/null +++ b/doc/tutorials/CMakeLists.txt @@ -0,0 +1,9 @@ +################################################# +# +# Improvements and feedback are welcome +# +# This file is released under GPL >= 2 +# +################################################# + +tde_auto_add_subdirectories() diff --git a/doc/tutorials/Makefile.am b/doc/tutorials/Makefile.am new file mode 100644 index 0000000..85c6cde --- /dev/null +++ b/doc/tutorials/Makefile.am @@ -0,0 +1,4 @@ +KDE_LANG = en +KDE_DOCS = AUTO +SUBDIRS = $(AUTODIRS) + diff --git a/doc/tutorials/docprimer/CMakeLists.txt b/doc/tutorials/docprimer/CMakeLists.txt new file mode 100644 index 0000000..a4e5cd9 --- /dev/null +++ b/doc/tutorials/docprimer/CMakeLists.txt @@ -0,0 +1,9 @@ +################################################# +# +# Improvements and feedback are welcome +# +# This file is released under GPL >= 2 +# +################################################# + +tde_create_handbook( DESTINATION khelpcenter/docprimer ) diff --git a/doc/tutorials/docprimer/Makefile.am b/doc/tutorials/docprimer/Makefile.am new file mode 100644 index 0000000..4169155 --- /dev/null +++ b/doc/tutorials/docprimer/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/tutorials/docprimer/index.docbook b/doc/tutorials/docprimer/index.docbook new file mode 100644 index 0000000..28792b1 --- /dev/null +++ b/doc/tutorials/docprimer/index.docbook @@ -0,0 +1,2160 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kde-authors '<personname><surname>The &kde; Documentation Team</surname></personname>'> + <!ENTITY meinproc "<command>meinproc</command>"> + <!ENTITY checkxml "<command>checkXML</command>"> + <!ENTITY svn "<application>Subversion</application>"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"><!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &tde; Documentation Primer</title> + +<authorgroup> +<author>&kde-authors;</author> +<author> +<firstname>Carlos</firstname><surname>Woelz</surname> +</author> +<author>&tde-authors;</author> +</authorgroup> + +<copyright> +<year>2004</year> +<holder>The KDE Documentation Team</holder> +</copyright> +<copyright> +<year>2004</year> +<holder>Carlos Woelz</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> +This document provides information to start writing documentation for &tde;. +Please report any errors or omissions to +<email>trinity-devel@lists.pearsoncomputing.net</email>. +</para> +</abstract> + +<keywordset> +<keyword>TDE</keyword> +<keyword>Writing</keyword> +<keyword>Documentation</keyword> +</keywordset> + +</bookinfo> + +<chapter id="intro"> +<title>Introduction</title> + +<para> +The objective of this guide is to present all information required to make the +experience of writing &tde; documentation as easy as possible. +The next chapter gives some information about what skills you'll need for the task. +It is important to note that this guide is a joint effort of the &tde; +English Documentation Team and the &tde; Quality Team. You can ask for support +from both teams at any time.</para> + +<para>The <emphasis>&tde; English Documentation Team</emphasis> exists to +provide end-user documentation for the whole of &tde;. It's a big task, but an +important one. Although &tde; aims to be easy to use, not everything is obvious +without some help, and, in a project this big, even an experienced user +can't know every corner of &tde;.</para> +<para>The team is made up of people doing several different tasks: +<itemizedlist> +<listitem><para>Writing documentation for individual applications</para> +</listitem> +<listitem><para>Writing wider documentation for the whole of &tde; (like +the User Guide, or this document).</para> +</listitem> +<listitem><para>Proofreading and/or updating documentation to ensure +that it is correct and up-to-date.</para> +</listitem> +</itemizedlist> +Contributors to all of these areas are always welcome. You can +choose the area you would like to contribute to, based on your skills +and what you enjoy doing. If you need any help with documentation issues, +do not hesitate to ask at the &tde; Documentation mailing list, +<email>kde-doc-english@kde.org</email>, or on <acronym>IRC</acronym> in the channel #kde-docs on +<systemitem class="domainname">irc.freenode.net</systemitem>.</para> + + +<para> +The <emphasis>&tde; Quality Team</emphasis> provides support for +new contributors, and to coordinates the efforts of the volunteers. +The <ulink url="http://quality.kde.org">&tde; Quality Team Website</ulink> +provides guides to help you with some general development tasks, +such as getting the sources, +<ulink url="http://quality.kde.org/develop/cvsguide/">Building +&tde; From Source Step By Step</ulink>, and +<ulink url="http://quality.kde.org/develop/cvsguide/managestep.php"> +Working with Subversion</ulink>, &etc;. If these guides are not sufficient, and you +are having problems with &tde; development, we provide support for new contributors +at the &tde; Quality mailing list, <email>kde-quality@kde.org</email>, or on IRC +in the channel #kde-quality on +<filename class="directory">irc.freenode.net</filename>. +</para> + +</chapter> + + +<chapter id="getting-started"> +<title>Getting Started</title> + +<para>If you got this far reading this document, you're probably interested in +helping with &tde; documentation. If so, welcome aboard! We're always +happy to have new contributors, and whatever your skills, you can help +make &tde; even better. +<!-- Where to find us - mailing list, IRC, i18n.kde.org/doc --></para> + + +<sect1 id="requirements"> +<title>Things You'll Need</title> + +<para>To write documentation, there are only three things that are absolutely +necessary: some English knowledge, knowing what you want to document, and +access to a relatively recent version of the application you want to +document.</para> + +<note><para>Notice that the list of requirements does +<emphasis>not</emphasis> contain a requirement that you learn DocBook, +or any of the other tools we use. We're very happy to receive +documentation written in plain text. We would much rather have the +content and have to add formatting than have no content at all.</para> +</note> + +<sect2 id="requirements-english"> +<title>English Knowledge</title> + +<para>All &tde; documentation is originally written in English, so you +have to be able to write English to a reasonable level. That said, you +<emphasis>don't</emphasis> need to be a native speaker, and you don't +need to write word-perfect English. There are native English-speaking +proofreaders on the documentation team, and we would much rather have +<emphasis>some</emphasis> documentation that needs a little tweaking, +than no documentation at all. If you don't feel comfortable writing in +English, you might like to contribute to one of the &tde; translation +teams. You can find more information about translation on <ulink +url="http://i18n.kde.org">http://i18n.kde.org</ulink>.</para> + +<para>If you're a fluent English speaker with an eye for detail, you +might be interested in joining the proofreading +team. Just drop an email to <email>kde-doc-english@kde.org</email> if +you'd like to help the proofreaders.</para> +<!-- What about moving this to the other task section in the end? --> + + +</sect2> +<sect2 id="requirements-what-to-write"> +<title>Deciding What to Write About</title> +<para>&tde; is a very large project, with many different parts and +programs. Because of this, it can be hard to know where to start if you +want to contribute. There are a few rules of thumb that can help you +decide what to write about: +<itemizedlist> +<listitem><para>Find a topic that you'll enjoy writing about; It will +increase your motivation and help you to produce better documentation.</para> +</listitem> +<listitem><para>Write about an application you know well. You'll be able +to spend more time on writing and less time trying to work out how the +application works. On the other hand, documenting an application can be +a good way to learn about how it works, especially if you like a challenge!</para> +</listitem> +</itemizedlist> +</para> + +<para> +If you are looking for an application to document, or just checking the status +of the application you want to work with, the +<ulink url="http://wiki.kde.org/tiki-index.php?page=KDE+Quality+Team"> +&tde; Quality Team Wiki</ulink> contains lists of applications, organized +by modules, and their general status, including documentation status, and who +is working on it. Not all modules and applications are included or up to date, +but it is certainly worth checking.</para> + +<para>If you start documenting one of the listed applications, please add your +name to the wiki pages as well. But If you just can't find an application to +work with, write to <email>kde-doc-english@kde.org</email> and ask for +suggestions. There's always something available to do, but there's no obligation +to work on a particular application. Also, contributing to a document doesn't +force you into keeping that document up-to-date (although if you can do that, +it's very welcome!). +</para> + +<para>Another place to check is the &tde; bug list at <ulink +url="http://bugs.kde.org">http://bugs.kde.org</ulink>. This is usually +more detailed than the wiki, and provides a place to list specific small +changes that are needed to documents. These are often nice small jobs +to get you started contributing. A set of quick links to ready made +queries are available from the Documentation Project's <ulink +url="http://i18n.kde.org/doc/current.php"> +http://i18n.kde.org/doc/current.php</ulink> page.</para> + +<para>It is also helpful to the team to file more bugs like these +above. You will need a bugzilla account, and a recent copy of &tde;. +Simply open an application, choose +<menuchoice><guimenu>Help</guimenu><guimenuitem><replaceable>appname</replaceable> +Handbook</guimenuitem></menuchoice>. Then just read through the document, +following along in the application. &tde; applications are a moving +target to document, and sometimes the documentation has not yet caught +up with a change to the interface or behavior of an application. Feel +free to file bugs for any of these issues you find, in order of urgency:</para> + +<itemizedlist> +<listitem><para>Inaccurate information about how an application +works</para><para>For instance, if you previously needed to save +changes to a file before they take effect in the &GUI;, and this now +happens automatically, text referring to manual saving should be +removed, or it will confuse readers.</para> +<!-- This example is terrible, can someone find a better one? --> +</listitem> +<listitem><para>GUI options or menu items (or sometimes, entire +dialogs)</para><para>This often happens in configuration dialogs, when +new items are added, a new grouping of existing options may be +created.</para> +</listitem> +<listitem><para>New Features that are available and are not yet +documented.</para></listitem> +</itemizedlist> + +</sect2> + +<sect2 id="requirements-access"> +<title>Access to a Recent Version</title> + +<para>To make sure that the documentation you write is up-to-date, +you'll need to run a recent version of the application you are working with. +This normally means a recent beta version, a version of your application +compiled from sources or a version of &tde; compiled from sources in the &svn; +repository. If you think that compiling from sources is too burdensome, and you +cannot get some recent beta packages, there are still some interesting +possibilities to work around this requirement:</para> + +<itemizedlist> +<listitem><para> +Write about a stable application: there are many apps with a stable interface +which are still lacking good documentation. In this case, the last stable version +provided by your distribution will be sufficient to write about it, no +compiling required. +</para></listitem> + +<listitem><para> +Using a remote desktop connection to preview the development version is +an ideal solution to this problem. The FreeNX terminal server technology +enables decent desktop performance even with dial up Internet +connections. We are planning to offer this service to &tde; documenters, but +the infrastructure is not yet in place (as of May +2005). You may ask the <email>kde-quality@kde.org</email> mailing list +about it, if you think this is the way to go. +<!-- Also, Kurt's NX stuff will hopefully make this unnecessary Real --> +<!-- Soon Now. Once that happens, write about it here --> +</para></listitem> + +</itemizedlist> + +<para>If you want to try out building &tde; from sources, the &tde; Quality +website provides +<ulink url="http://quality.kde.org/develop/cvsguide/buildstep.php">a detailed, +step by step building guide</ulink>. You can find even more information at the +<ulink url="http://developer.kde.org/build">&tde; Developers Website</ulink>. +If you face any problems in the +compiling process you can't solve by reading the building guide, don't hesitate +to as for help on <email>kde-quality@kde.org</email>.</para> +</sect2> + +</sect1> + +</chapter> + +<chapter id="guidelines"> +<title>&tde; Writing Recommendations and Guidelines</title> + +<para>To maintain a uniform documentation set, there are some consistency rules +to be followed, that you should know before starting. In this chapter you will +find guidelines about targeting your audience, English usage, and what to cover +when you are documenting an application.</para> + +<para>We also offer some general writing tips to help you to +get started, provided by experienced &tde; documenters.</para> + +<sect1 id="guidelines-audience"> +<title>Writing for your Audience</title> + +<para>Since &tde; is used by people with a wide range of abilities, from +completely new users to long-time gurus, the documentation should be +appropriate to this audience. Therefore, in general, documentation +shouldn't assume too much about the knowledge of the reader, without +being patronizing. There are no hard-and-fast rules, but here are some +tips that should help:</para> +<itemizedlist> +<listitem><para>Remember that the audience varies with the application: for +example, a server control module has a very different user base than a user of a +game, and the manuals should reflect this. Don't insult the administrator +intelligence, and don't assume knowledge for the gamer that might not be +there.</para> +</listitem> +<listitem> +<para>Keep a logical progression of difficulty: Keep the first few pages +of the document simple, and accessible to users who have never seen the +application before. More technical information should appear towards the +end of the document.</para> +</listitem> +</itemizedlist> + +<para>Remember also that different types of documentation have different +purposes:</para> + +<variablelist> +<varlistentry> +<term>Application Handbooks</term> +<listitem> +<para>These may go into great depths on the configuration, behavior and +sometimes the philosophy of an application. There is scope to cover +corner cases of configuration, commonly asked questions, and advanced +troubleshooting techniques.</para> <para>They should also always contain +a complete reference to all the available menu functions and +configuration options for the application (but while these are required, +they should be certainly be considered a minimum of information to +provide.)</para> +<para>The Application Handbook should be answering the question: +<quote>What are all the things I can do with this application?</quote></para> +</listitem> +</varlistentry> +<varlistentry> +<term>User Guide</term> +<listitem> +<para>A much higher level overview of &tde; and its applications. This +aims to be the first stop for users to look for information, and should +be task based.</para> +<para>When writing for the User Guide, you should assume a working +default installation of &tde;, and you do not need to cover all cases of +unusual configurations, only the very common variations, nor should you +cover in-depth troubleshooting. You might provide answers to some very +common configuration errors (or not, as appropriate) and refer to the +Application Manual, the Application's Website, mailing list, and any +appropriate man pages for more detailed information.</para> +<para>Most people reading this guide do not have an actual problem, they +simply want to achieve a goal, and don't yet know how, or where to find +that information.</para> +<para>The User Guide should be answering the question: <quote>How do I +do <replaceable>this common task, ⪚ send an email, play a +movie</replaceable>?</quote>.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>What's This Help</term> +<listitem> +<para>A very focused and specific type of assistance, about a single +configuration or interface item. Again you should not really attempt to +cover all cases here, only common ones, and explain what the option +does, not why it is there. Refer users to the Application Handbook if +appropriate, for more information.</para> +<para>Provide an example of the expected input, if that is not clear +from the context.</para> +<para>The What's This Help is most often answering the question: <quote>Do I +need to fill in this box? If so, what do I put in it?</quote></para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + + +<sect1 id="guidelines-english-usage"> +<title>English Usage Guidelines and Recommendations</title> + +<para>&tde; documentation is written in +standard US English (rather than any other regional variety of +English). We have a set of standard forms of certain words (such as +<quote>email</quote> instead of <quote>e-mail</quote>) to improve +consistency across all documentation. Work is underway to expand and +formalize this list, but for the moment, it is located at <ulink +url="http://www.kde.me.uk/index.php?page=Consistency+rules">http://www.kde.me.uk/index.php?page=Consistency+rules</ulink>. +There are also standard names for &tde; widgets, which are listed in +<xref linkend="widget-names" /></para> + +<para>A good way to catch simple errors +is to read the text out loud, or have someone else read it to +you. Passages that don't flow easily or have obviously awkward construction +of the type you may miss on the screen, will usually become blindingly +obvious when you hear them. This is especially the case with detecting +really long sentences, as you will run out of breath and turn +blue.</para> + +<para>Some tips about writing readable sentences: +<itemizedlist> +<listitem><para>Use complete sentences. Not fragments. Like these ones.</para> +</listitem> +<listitem> +<para>Avoid run-on sentences, sentences that cover several different +subjects, or sentences that could be broken up into several sentences; +avoid sentences that can fill a whole paragraph all by themselves and +that are really long, like this one, which is all of the above.</para> +</listitem> +<listitem> +<para> +Use a comma before <quote>and</quote> in compound sentences, ⪚ +<quote>Use the left mouse button to select and copy text, and the +middle mouse button to paste it.</quote></para> +</listitem> +<listitem> +<para>Keep to logical sentence order.</para> +<para>For example, <quote>&konqueror; is a web browser with the +ability to browse file systems and it includes a javascript +interpreter.</quote> (Do you see why this is awkward?)</para> +</listitem> +<listitem> +<para>Try not to use the same word several times in the same sentence. +An exception to this, is an application command or technical word, +where this repetition is necessary, and improves clarity.</para> +</listitem> +<listitem> +<para>Do not start sentences with any of <quote>and,</quote> +<quote>so,</quote> <quote>but,</quote> <quote>because,</quote> or +<quote>however.</quote></para> +</listitem> +<listitem> +<para>Try to avoid contractions, rather spell out both words; ⪚, +<quote>it is</quote> rather than <quote>it's</quote>; <quote>can +not</quote> rather than <quote>can't</quote></para> +</listitem> +<listitem> +<para>There is no need to worry about simple text formatting such as +leaving two spaces after punctuation or indenting paragraphs. This is +all handled by DocBook &XML; and the <acronym>XSLT</acronym> +stylesheets in use.</para> +</listitem> +</itemizedlist> +</para> + +<para>Remember, we have also an active proofreading team, and there is +always someone to help you with grammar, so just +write and have fun!</para> + + +</sect1> + +<sect1 id="guidelines-include"> +<title>What to Include</title> +<para>For most applications, a structure something like this would be +appropriate: +<orderedlist> +<listitem> +<para>Introduction: A basic description of what the application does and +any noteworthy features, &etc;.</para> +</listitem> +<listitem> +<para>Using <replaceable>KApp</replaceable>: Task-based description of +the most common uses of the application.</para> +</listitem> +<listitem> +<para>Program reference: Description of all of the features of the +application. This would usually include a menu reference, but might also +include command line options, syntax description, &etc;, if they are +appropriate to the application.</para> +<para>This is required for all &tde; applications that you at a minimum +cover any application specific menu entries, and strongly recommended +that you cover all the standard ones too (in case users are reading the +manual outside of &tde;, or yours happens to be the first one they read, +and it provides consistency. Cut and paste is your friend here.)</para> +<para>Note that although this is a required section, and for some +applications it is the only section, it should be considered a +minimum.</para> +</listitem> +<listitem> +<para>Frequently Asked Questions: List the most common questions and +problems that users have with the application, and their +solutions. <quote>How do I ...?</quote>-type questions are especially +appropriate.</para> +</listitem> +<listitem> +<para>Credits and License: A list of those who contributed to the +documentation, and a link to the &GNU; Free Documentation License, under +which all &tde; documentation is licensed.</para> +<para>This chapter is required for all &tde; documents, and must have +<emphasis>at least</emphasis> the two license links (one for the +document, and one for the application)</para> +</listitem> +<listitem> +<para>Installation: This chapter can be automatically generated, +provided that the application follows the usual &tde; compilation +procedure (&ie; <command>./configure</command>, <command>make && make +install</command>). If you need to add extra information about compiling +or installing the application, it can go here.</para> +</listitem> +</orderedlist> +</para> + +<para>You will find a template document with these sections in +<filename>trunk/KDE/kdelibs/kdoctools/template.docbook</filename> file in &tde; +&svn; repository.</para> +</sect1> + +</chapter> + +<chapter id="writing-docs"> +<title>Writing Documentation: Procedures and Tools</title> + +<para>If you're worried about having to learn a lot of new tools and +procedures in order to write documentation, you don't need to, +because the information we've covered so far is everything you need to +know to be able to contribute. Although we <emphasis>do</emphasis> have +some tools we use and procedures we follow, it's not vital that everyone +knows them in detail, especially when starting out.</para> + +<para>For example, all +&tde; documentation is written in DocBook &XML;, but we're very happy to +receive documentation written in plain text. There are people on the +documentation team who are very familiar with DocBook, and can easily +add the markup if the content is there.</para> + +<para>Another example: if you are starting to document an application from +scratch, you don't need to get the sources of the current documentation. But +if you are starting from existing documentation, you don't need to know +about how to get the sources, there are other means to do that.</para> + +<para>Of course, if you want to learn about DocBook, you can. After a +little practice, you will probably find that it's not as hard as it +looks. And if you learn about dealing with a &svn; repository, you will +be able to integrate yourself to the regular &tde; development process +(upload your changes, work together with other developers, &etc;) +</para> + + +<sect1 id="getting-the-sources"> +<title>Getting the Documentation Sources</title> + + +<note><para>If you are starting your document from scratch, you probably do not +need to read this section, and may start working right now. +</para></note> + +<para> +You are welcome to use plain text to contribute to &tde; documentation. +It is a great way to start, and we strongly encourage it. +If you will miss the power of the DocBook format as +you improve your documentation skills, then you can learn it. In the mean +time, someone will manually edit the plain text to add the DocBook +markup and commit it to &tde; &svn; repository, removing the burden of doing most of the +more complex stuff covered in this very guide. We'll take a look at writing in +DocBook and using &svn; later in this document, so if you're interested, read on, +but if you want to use plain text, you can go directly to +<xref linkend="getting-plain-text" />. +</para> + +<para>Documentation for &tde;, like the rest of the source code, is kept +in a &svn; repository. &svn; provides a way for +many developers to work on the same source code (or in our case, the +same documentation), and has many useful features to help with this. For +example, previous versions of every file are saved so that any mistakes +can be quickly backed out, if they can't be easily corrected.</para> + +<para>The basic principle behind &svn; is simple: one server stores a +definitive copy of the files making up a project. This is known as the +<firstterm>repository</firstterm>. Each developer can download the files to make +their own private copy, named <firstterm>working copy</firstterm> or +<firstterm>sandbox</firstterm>. Using &svn;, the developers can upload their +modifications to the main repository (a process called "committing") +or update their own copy to reflect recent changes made by others. +</para> + +<para>There are two main ways edit the contents of a &tde; document you +want to improve: using plain text or DocBook.</para> + + +<sect2 id="getting-plain-text"> +<title>Working with plain text sources</title> + +<para> +The <ulink url="http://docs.kde.org/index_head.html">docs.kde.org +website</ulink> displays most of the &tde; documentation in &HTML; format, updated +daily from the &svn; repository. There are two versions available in the website: the +<ulink url="http://docs.kde.org/">stable version</ulink> and the +<ulink url="http://docs.kde.org/index_head.html">&tde; from &svn; version</ulink>. +You will always use the latest version of the documentation, &ie; the +<ulink url="http://docs.kde.org/index_head.html">&tde; from &svn; version</ulink>. +</para> +<para> +The <ulink url="http://docs.kde.org/index_head.html">docs.kde.org +website</ulink> presents a quick and easy method of retrieving +the latest version of the &tde; documentation. Clicking the name of the +application you want to document in the list will open the documentation in +your web browser. Simply copy the text from the website to your favorite +text editor, edit it , and submit the results in +plain text to the &tde; Documentation mailing list, +<email>kde-doc-english@kde.org</email>. Please note that not all &tde; +applications are listed there. If you cannot find the documentation of +the application you want to work with, then you can request it by sending a +message to the &tde; Documentation mailing list. +</para> + +<para> +Now you know everything you need to start working. When you are +finished writing, you may want to read <xref linkend="other-tasks" />. Have fun! +</para> + +</sect2> + +<sect2 id="getting-docbook"> +<title>Retrieving the DocBook sources</title> + +<para> +The latest DocBook sources are located inside the &tde; repository. +Now you need to find and retrieve them. +</para> +<para> +The software inside the &tde; repository is divided into +<firstterm>modules</firstterm>, which are used to organize the different +software projects inside the repository. Modules are the top-level folders in the +&svn; repository folder tree, and each one contains a group of related +applications. These modules are sometimes released in binary +form as <firstterm>packages</firstterm>. If you know the name of the package +your application belongs to, you probably know the module name as well, as +they are frequently the same. You need to know in which module your application +is, to retrieve its DocBook sources. For instance, &kmail; is in the +tdepim module, &quanta; in the tdewebdev module, &cervisia; in the tdesdk module +and so on. If you need any help in this process, don't hesitate to ask. Each +module contains a folder named "doc", and inside it, you can find the +DocBook sources. +</para> + +<para> +To access the repository, you can use the <command>svn</command> command line application<!--, +the &cervisia; application--> or browse the <ulink url="http://websvn.kde.org">&tde; WebSVN website (websvn.kde.org)</ulink>. +</para> + +<para>The <ulink url="http://websvn.kde.org">websvn.kde.org</ulink> is a +web +based representation of the contents of the &svn; repository. It is easy +to download files using <ulink url="http://websvn.kde.org">websvn.kde.org</ulink>, +the operating system or desktop you use does not matter. +</para> + +<para> +Retrieving your own working copy of the repository has many advantages. You +will be able to use your working copy to create files containing the changes you +made, to update your copy with changes made by other documenters, and if you get +a &tde; &svn; account, to upload your changes directly to the repository. +But this is out of the scope of this section. Here we will show you simply +how to retrieve the sources using &svn;<!-- or &cervisia,;--> the easiest way we can. +You can get more information about these tools (they are really useful) +by reading the <xref linkend="managing-svn" />.</para> + +<procedure> +<title>Retrieving documentation sources using WebSVN</title> + +<step><para> +Go to <ulink url="http://websvn.kde.org">http://websvn.kde.org</ulink> +using your favorite web browser. Let's suppose you are looking for +&cervisia;'s documentation sources. +</para></step> + +<step><para> The &tde; repository is divided into <quote>trunk</quote> +(also known as HEAD, where development is going on, +<quote>branches</quote>, where both stable and working branches live, +and <quote>tags</quote>, where you can retrieve snapshots of sources at +a release. Most work for documentation goes on in <quote>trunk</quote>, +so click there.</para></step> + +<step><para>The main &tde; modules are in the <quote>TDE</quote> folder, +so click on that. +</para></step> + +<step><para> +Click the "trunk" link to get the main branch listing. Click on "TDE" +to get the list of modules from a &tde; release. +</para></step> + +<step><para> +&cervisia; is part of the tdesdk module (&tde; software +development kit module). Therefore, click the <quote>tdesdk</quote> item on the +list. The contents of the tdesdk module will be displayed. +</para></step> + +<step><para> Click the <quote>doc</quote> item on the list, to see the +contents of the documentation folder of the module. The contents of the +doc (documentation) folder will be displayed. </para></step> + +<step><para> +Select the application you want to work with from +the list (in our case, <quote>cervisia</quote>). All &cervisia;'s +documentation source files will be displayed, being images or DocBook files. +</para></step> + +<step><para> +Now you reached the list of files that are part of +&cervisia;'s documentation, including +images and DocBook sources. The DocBook sources are files in the format +<filename class="extension">*.docbook</filename>. In this case, there is only +one file file in this format: <filename>index.docbook</filename>. Click this +file on the list. A list of <firstterm>revisions</firstterm> (versions) +of that file will be displayed. +</para></step> + +<step><para> +Click the <quote>download</quote> link from the revision on the top of +the list. It is the most recent one. Save the file. Repeat this process +with all the files you want to download. +</para></step> +</procedure> + +<para> +We use &kmail;'s documentation sources as example in the +following procedures. +</para> + +<procedure> +<title>Retrieving documentation sources using &svn;</title> + +<step><para> +Check if you have the &svn; client installed (hint: enter <command>svn</command> in the +terminal screen). If not, install the &svn; package using the tools provided by +your distribution. +</para></step> + +<step><para> +Now it is time to download, or <firstterm>checkout</firstterm> the sources. +Using &svn;, type in the terminal: +<programlisting>mkdir <replaceable>path/to/working/folder</replaceable> +cd <replaceable>path/to/working/folder</replaceable> +svn checkout svn://anonsvn.kde.org/home/kde/<replaceable>trunk/KDE/module</replaceable>/doc/<replaceable>application</replaceable> +</programlisting> +where <replaceable>path/to/working/folder</replaceable> is the folder you want +to install the sources in your system, <replaceable>trunk/KDE/module</replaceable> is the +application's module location in the repository and <replaceable>application</replaceable> is the +application name. Remember to use small caps to type the application and +module names. In our example, &kmail; is in the tdepim module, so you would +enter: +<programlisting>svn checkout svn://anonsvn.kde.org/home/kde/trunk/KDE/kdepim/doc/kmail +</programlisting> +Note that only applications which are part of a regular &tde; release are under +<replaceable>trunk/KDE/</replaceable>. <application>Amarok</application> docs, for instance, is in the +multimedia module of extragear. Extragear is contains mature applications which are +not part of a &tde; release. To get <application>Amarok</application> docs, type in the terminal: + +<programlisting>svn checkout svn://anonsvn.kde.org/home/kde/trunk/extragear/multimedia/doc/amarok +</programlisting> +</para></step> +</procedure> + +<!--FIXME: update this section when Cervisia has svn support + +<procedure> +<title>Retrieving documentation sources using &cervisia;</title> + +<step><para> +Check if you have the &svn; and tdesdk &cervisia; +applications installed. If not, install the &svn; and tdesdk packages using the +tools provided by your distribution. +</para></step> + +<step><para> +It is not really necessary to set up cervisia to download the sources, but you +may want to do that if you want to do more. For more information about setting +up &cervisia;, see <xref linkend="managing-svn" />. +</para></step> + +<step><para> +To store the repository location using &cervisia;, choose the +<menuchoice><guimenu>Repository</guimenu> +<guimenuitem>Repositories...</guimenuitem></menuchoice> menu item. Click the +<guilabel>Add...</guilabel> button. Enter <quote><replaceable>:pserver:anonymous@anoncvs.kde.org:/home/kde</replaceable><quote> +in the <guilabel>Repository:</guilabel> edit box. Press <guibutton>OK</guibutton>. +You will see the repository you just entered on the repositories list. + +<figure id="screenshot-repositories" float="1"> +<title>A screenshot of &cervisia;'s Configure Access to Repositories dialog</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="cervisia-repository.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s Configure Access to +Repositories dialog</phrase></textobject> +</mediaobject> +</figure> +</para> + +<para>Now you need to login. Select the repository on the list and press the +<guilabel>Login...</guilabel> button. A pop-up dialog will appear. Just press +<keycap>enter</keycap>.</para> + +<para>If the <guilabel>Status</guilabel> column entry shows +<guilabel>Logged in</guilabel> instead of <guilabel>Not logged in</guilabel>, +it means you successfully configured the &tde; repository location in &cervisia;. +</para></step> + +<step><para> +Now it is time to download, or <firstterm>checkout</firstterm> the sources. +Choose the <menuchoice><guimenu>Repository</guimenu> +<guimenuitem>Checkout...</guimenuitem></menuchoice> menu item. + +<figure id="screenshot-checkout" float="1"> +<title>A screenshot of &cervisia;'s Checkout dialog</title> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="cervisia-checkout.png"/></imageobject> +<textobject><phrase>A screenshot of &cervisia;'s Checkout dialog</phrase></textobject> +</mediaobject> +</figure> +</para> + +<para> +Select the &tde; repository location in the <guilabel>Repository:</guilabel> +drop down box. Enter in the <guilabel>Module:</guilabel> edit box the location +of the documentation sources, in the form <quote><replaceable>module</replaceable>/doc/<replaceable>application</replaceable><quote>, +where <replaceable>module</replaceable> is the +application's module name and <replaceable>application</replaceable> is the +application name. In our example, since &kmail; is in the tdepim module, you +should enter <quote><replaceable>tdepim</replaceable>/doc/<replaceable>kmail</replaceable><quote>. +Enter in the <guilabel>Working folder:</guilabel> edit box +the folder under which the sources should be downloaded. Press +<guilabel>OK</guilabel>. +</para></step> +</procedure>--> + +</sect2> +</sect1> + +<sect1 id="quanta"> +<title>&quanta;</title> + +<para> +&quanta; is a friendly editor for <acronym>SGML</acronym> and &XML; +documents. &quanta; features syntax highlighting, autocompletion, autoclosing +and code folding for DocBook tags, easy access for the &tde; documentation +tools, <link linkend="using-meinproc">&meinproc;</link> and +<link linkend="using-checkxml">&checkxml;</link>. +</para> + +<screenshot id="screenshot-quanta"> +<screeninfo>A screenshot of &quanta;'s main window</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="quanta.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &quanta;'s main window</phrase></textobject> +<caption><para>A screenshot of &quanta;'s main window</para></caption> +</mediaobject> +</screenshot> + +<para> +Some of the tools available for DocBook editing are the document +structure sidebar, tag editor sidebar and, starting with &quanta; 3.4 (which +is part of &tde; 3.4), &quanta; offers a DocBook toolbar, complete with table +and list wizards, ui elements, admonitions, &tde; tools and other standard +tags. While &quanta; offers a visual page editor for html and xhtml +pages, there is no support yet for DocBook visual editing. We highlight here +some of these features. +</para> + + +<variablelist> + + +<varlistentry> +<term>DocBook Toolbars</term> + +<listitem><para> +The DocBook toobars offer easy access to the most common DocBook tags, +plus the list, table and image wizards. You can check your DocBook document +using the <inlinemediaobject><imageobject> +<imagedata fileref="xmlval.png" format="PNG"/></imageobject> +</inlinemediaobject><guibutton>checkXML</guibutton> button from the +<guilabel>Tools</guilabel> toolbar: the output of the script will be displayed +in he <guilabel>Messages</guilabel> sidebar, in the bottom of &quanta;'s main +window. If there is no output, that usually means no errors. +To process the DocBook into html files, use the +<inlinemediaobject><imageobject> +<imagedata fileref="" format="PNG"/></imageobject> +</inlinemediaobject><guibutton>meinproc</guibutton> button on the same toolbar. +</para> + +<note><para> +Depending on the version of some XML utilities used by &quanta;, the +<inlinemediaobject><imageobject> +<imagedata fileref="xmlval.png" format="PNG"/></imageobject> +</inlinemediaobject><guibutton>checkXML</guibutton> and <inlinemediaobject> +<imageobject><imagedata fileref="xsltproc.png" format="PNG"/></imageobject> +</inlinemediaobject><guibutton>meinproc</guibutton> scripts +can present bugs. Starting from the upcoming &tde; 3.4.2 release, these bugs +will not exist anymore. But until there, if you experience these bugs, (in +special if &konqueror; is not starting up when using the +<guibutton>meinproc</guibutton> script or there is no output when using the +<guibutton>checkXML</guibutton> script, you can get and install the +<ulink url="http://kde-files.org/content/show.php?content=26654">updated docbook +scripts from kde-files.org</ulink> to solve these issues. +</para></note> + +<para><screenshot id="screenshot-quanta-toolbars"> +<screeninfo>A screenshot of &quanta;'s DocBook toolbar</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="quanta-toolbars.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &quanta;'s DocBook toolbar</phrase></textobject> +<caption><para>A screenshot of &quanta;'s DocBook toolbar</para></caption> +</mediaobject> +</screenshot> +</para> +</listitem> + +</varlistentry> + + +<varlistentry> + +<term>Tag Editor</term> + +<listitem><para> +The tag or attributes editor is located on the right sidebar, and it shows +the available attributes for the tag which is currently being edited. +The tag editor helps you to edit the attributes for the current tag: just click +on the <guilabel>Value</guilabel> column of any attribute to edit it. +</para> + +<para><screenshot id="screenshot-quanta-tag"> +<screeninfo>A screenshot of &quanta;'s attribute editor sidebar</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="quanta-tag.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &quanta;'s attribute editor sidebar</phrase></textobject> +<caption><para>A screenshot of &quanta;'s attribute editor sidebar</para></caption> +</mediaobject> +</screenshot> + +</para></listitem> + +</varlistentry> + +<varlistentry> + +<term>Documentation Sidebar</term> + +<listitem><para> +Another useful feature is the documentation sidebar, which allows you to +download and use documentation packages as offline reference. This guide is +also available offline, using &quanta;'s documentation +sidebar. Just grab and install the +<ulink url="http://kde-files.org/content/show.php?content=26176">&tde; Doc +Primer documentation package</ulink>. The documentation sidebar is on the right +side of the main window. +</para> + +<para><screenshot id="screenshot-quanta-doc-primer"> +<screeninfo>A screenshot of &quanta;'s documentation sidebar</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="quanta-doc-primer.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &quanta;'s documentation sidebar</phrase></textobject> +<caption><para>A screenshot of &quanta;'s documentation sidebar, showing the +&tde; Doc Primer</para></caption> +</mediaobject> +</screenshot> + +</para></listitem> +</varlistentry> + +<varlistentry> + +<term>Entities Autocompletion</term> + +<listitem><para> +&quanta; offers autocompletion for entities. However, this feature is +hardly useful without the &tde; entities definitions. To generate the entities +list for the &tde;, follow the procedure below: +</para> + +<note><para> +The autocompletion feature still has some bugs in the 3.4.1 release. +These bugs are fixed, and will be available starting from the 3.4.2 release. +</para></note> + +<procedure> +<title>Generating and installing the <filename>entities.tag</filename> file</title> + +<step><para> +Open &quanta;. Choose the <menuchoice><guimenu>DTD</guimenu> +<guimenuitem>Load & Convert DTD</guimenuitem></menuchoice> menu item. +</para></step> + +<step><para> +Now, we have to select the right dtd file to convert. +On the dialog, select the &tde; installation folder (usually +<filename class="directory">/usr</filename> or +<filename class="directory">/opt/trinity</filename>. If you cannot find it, type +<screen><prompt>$</prompt><userinput>tde-config --prefix</userinput></screen> +on a terminal application. The dtd file we want is named +<filename>kdex.dtd</filename> under +<filename class="directory">share/apps/ksgmltools2/customization/dtd/</filename>. +Select it and press <guibutton>OK</guibutton>. A new Document Type Editing +Package (DTEP) for kdex will be created. +</para></step> + +<step><para> +Now that you have converted the dtd, you can either use it directly, +by choosing the <menuchoice><guimenu>DTD</guimenu> +<guimenuitem>Change the DTD...</guimenuitem></menuchoice> and selecting the +kdex dtd. But the best solution is to install the +<filename>entities.tag</filename> file for automatic use with the &tde; +docbook dtds. +</para></step> +<step><para> +Now, let's copy the file from the kdex dtep to the kde-docbook +dtep. You can use a console application or a file manager to perform this action. +These locations are under the <filename class="directory">TDEHOME</filename> +folder, the folder that contains your &tde; settings and application data, +usually, <filename class="directory">~/.trinity</filename>. If you cannot find it, type +<screen><prompt>$</prompt><userinput>tde-config --localprefix</userinput></screen> +on a terminal application. The dtep folder is under +<filename class="directory">TDEHOME/share/apps/quanta/dtep</filename>. +The simplest way to do copy it is using a terminal application (⪚ &konsole;). +</para></step> + +<step><para> +Start a console application and enter the command: +<screen><prompt>$</prompt><command>cp `tde-config --localprefix`/share/apps/quanta/dtep/kdex/entities.tag `tde-config \ +--localprefix`/share/apps/quanta/dtep/kde-docbook-4.1.2/entities.tag</command></screen> +</para></step> + +<step><para>Restart &quanta;.</para></step> + +</procedure> + +<para> +<screenshot id="screenshot-quanta-entities"> +<screeninfo>A screenshot of &quanta;'s entities auto-completion feature</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="quanta-entities.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &quanta;'s entities auto-completion feature</phrase></textobject> +<caption><para>A screenshot of &quanta;'s entities auto-completion feature</para></caption> +</mediaobject> +</screenshot> +</para></listitem> + +</varlistentry> + +<varlistentry> + +<term>Document Structure</term> + +<listitem><para> +finally, the document structure displays the logical representation of your +document. By left mouse button clicking on an element, your cursor will taken +to the element's position in the document. By right mouse button clicking on an +element, you are presented with a number of actions that deal with navigating +and updating the tree. +</para> + +<para><screenshot id="screenshot-quanta-structure"> +<screeninfo>A screenshot of &quanta;'s document structure sidebar</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="quanta-doc-structure.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &quanta;'s document structure sidebar</phrase></textobject> +<caption><para>A screenshot of &quanta;'s document structure sidebar</para></caption> +</mediaobject> +</screenshot> +</para></listitem> +</varlistentry> + +</variablelist> + +<para> +&quanta; is part of the tdewebdev module, which is released as part +of &tde;. Binary packages are available for the majority of the +distributions. Quanta can be easily extended to support custom scripts, +toolbars and documentation sidebars. For more information, check the +application handbook. +</para> + +</sect1> + +<sect1 id="kate"> +<title>&kate;</title> + +<para> +&kate; is an extensible and powerful text editor which is part of the +tdebase module. &kate; can syntax highlight DocBook documents out of the box, +and is generally a very powerful editor, but you can get even more +XML specific functionality installing the XML plugin for &kate;. +</para> + +<procedure> +<title>Installing the XML plugin for &kate;</title> + +<step><para> +The XML plugin for &kate; is available as part of the tdeaddons module, which +is released as part of &tde;. Binary packages are available for the majority of +the distributions. Install the binary package using your distribution tools or +compile tdeaddons to install the plugin. +</para></step> + +<step><para> +Open the <guilabel>Configure &kate;</guilabel> +dialog by choosing the +<menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Configure &kate;...</guimenuitem></menuchoice> menu item. +</para></step> + +<step><para> +Select the <guilabel>Plugins</guilabel> item from the +<guilabel>Application</guilabel> tree. Check the <guilabel>&kate; XML +Completion</guilabel> and the <guilabel>&kate; XML Validation</guilabel> boxes. +</para> + +<screenshot id="screenshot-kate-plugin-config"> +<screeninfo>A screenshot of &kate;'s Plugin Manager Configure +Dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kate-plugin.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &kate;'s Plugin Manager Configure +Dialog</phrase></textobject> +<caption><para>A screenshot of &kate;'s Plugin Manager Configure +Dialog</para></caption> +</mediaobject> +</screenshot> +</step> + +<step><para> +Press <guibutton>OK</guibutton>. +</para></step> + +</procedure> + +<para> +With the XML plugin for &kate; installed, you will have autocompletion, +autoclosing for DocBook tags and entities. Since &tde; documentation uses +entities widely, this is a very welcome feature. Additional XML tools will be +available trough the <guimenu>XML</guimenu> menu (in special, trough the +<guimenuitem>Validate XML</guimenuitem> menu item, which will allow you to +check your DocBook documents). The output of this action will appear in the +<guibutton>XML Checker Output</guibutton> button in the side bar located in +the lower part of &kate;'s main window. +</para> + +<screenshot id="screenshot-kate-validate-xml"> +<screeninfo>A screenshot of &kate;'s Main Window showing the XML Checker +Output</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="kate-validate-xml.png" +format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &kate;'s Main Window showing the XML Checker +Output</phrase></textobject> +<caption><para>A screenshot of &kate;'s Main Window showing the XML Checker +Output</para></caption> +</mediaobject> +</screenshot> + +</sect1> + + +<sect1 id="emacs-and-psgml"> +<title>Emacs and Psgml</title> +<para>The venerable &Emacs; editor has a powerful +<acronym>SGML</acronym> and &XML; editing mode called psgml. The price +of this power is a steeper learning curve than the other editors, so if +you haven't used &Emacs; before, you will probably want to try the other +editors first. If, on the other hand, you're already familiar with +&Emacs;, then psgml is your best choice.</para> + +<para>Installation of psgml is beyond the scope of this document, but it +should simply be a case of installing appropriate packages for your +distribution. The relevant configuration for &tde;-related documentation +is simple. Just tell psgml where the &tde; catalog files are located +with the following line in your <filename>.emacs</filename> file: +<programlisting> +(setq sgml-catalog-files + (list "CATALOG" "<replaceable>TDEDIR</replaceable>/share/apps/ksgmltools2/customization/catalog")) +</programlisting> +where you should replace <replaceable>TDEDIR</replaceable> with the path +to your &tde; installation. You might also want to use the following +line to instruct &Emacs; to use psgml to open all <literal +role="extension">.docbook</literal> files: +<programlisting> +(setq auto-mode-alist + (cons '("\\.docbook$" . sgml-mode) auto-mode-alist)) +</programlisting> +</para> + +<para>There are of course plenty of other settings in psgml mode which +you can change to your taste: see the psgml <command>info</command> +documentation for more details. A sample <filename>.emacs</filename> +file, with some customizations useful for writing &tde; documentation, +can be found at <ulink +url="http://people.fruitsalad.org/phil/kde/dot-emacs-psgml">http://people.fruitsalad.org/phil/kde/dot-emacs-psgml</ulink>.</para> + +<para>Some basic keystrokes in psgml are: + +<variablelist> + +<varlistentry> +<term><keycombo action="seq"><keycombo action="simul">&Ctrl;<keycap>C</keycap> +</keycombo><keycap>/</keycap></keycombo></term> +<listitem><para>End current element. This inserts an end tag for the +currently open element.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><keycombo action="simul"><keycap>Meta</keycap><keysym>Tab</keysym> +</keycombo></term> +<listitem><para>Completes the current tag or entity, +context-sensitively. This will only complete on tags that are allowed at +the current point in the document. Note that, because indentation is +rarely used in &tde; documentation, it is generally safe to remap this +function to just the <keysym>Tab</keysym> key.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><keycombo action="seq"> +<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo> +<keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo> +<keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo> +</keycombo></term> +<listitem><para>Fold current element. This compresses the current +element so that only the starting tag appears. One use of this is to +fold all the <sgmltag>chapter</sgmltag> elements in a document, to get +an overview of the document on one screen, and make navigation around a +long document easier. You can unfold elements with the shortcut <keycombo action="seq"> +<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo> +<keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo> +<keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo> +</keycombo>.</para> +</listitem> +</varlistentry> + +</variablelist> +</para> + +<para>One particularly useful psgml feature that isn't well documented +is the sgml-parent-document variable. Setting this variable +appropriately tells psgml that this file is part of a larger +document. This enables the full range of psgml features for this file, +such as context-sensitive element completion. To use this feature, place +the following in a comment at the end of the child file (with the +arguments adjusted appropriately): +<programlisting> +Local Variables: +sgml-parent-document:("index.docbook" "book" "chapter") +End: +</programlisting> +The first argument is the name of the parent file (which will almost +always be <filename>index.docbook</filename> in &tde; +documentation). The second argument is the top-level (or +<quote>root</quote>) element of the whole document (&ie;, in the parent +file). The third argument is the top-level element in this file.</para> + +</sect1> + + + +<sect1 id="check-docs"> +<title>Checking and Viewing the Documents</title> +<para>There are a couple of &tde;-specific tools for manipulating +DocBook files, namely &meinproc; and +&checkxml;. &checkxml; (as the name +suggests) is used to check that documents are valid, well-formed +&XML;, and &meinproc; converts DocBook files to +&HTML;. Here's some hints on using each of them:</para> + +<sect2 id="using-checkxml"> +<title>Using &checkxml;</title> + +<para>&checkxml; is a simple command with only one argument: the file to +check. However, the output can be a bit daunting, since one small +mistake can cause a cascade of errors. The trick is to look at the first +error, fix that error, save the file, and run &checkxml; again. Often, +fixing that one error will get rid of all the other error messages. When +running &meinproc;, the same procedure applies.</para> +<!-- TODO: Some common errors and how to fix them --> + +<para>Most errors in DocBook sources fall into one of a few +categories. Here are descriptions of some of the most common errors and +their solutions:</para> + +<variablelist> + +<varlistentry> +<term>Opening and ending tag mismatch</term> +<listitem> +<screen> +<computeroutput> +index.docbook:880: parser error : Opening and ending tag mismatch: para +line 879 and sect2 +</sect2> + ^ +</computeroutput> +</screen> + +<para>This is possibly the most common type of error. It's +caused either by an element that hasn't been closed, or by tags that +overlap. The error above was generated by the following markup: +<programlisting> +<markup> +<![CDATA[ +<sect2> +... +878: running &meinproc;, the same procedure applies.</para> +879: <para>&checkxml; is a simple command with +880: </sect2> +...]]> +</markup> +</programlisting> + +</para> + +<para>The <sgmltag class="starttag">para</sgmltag> tag on line 879 has +not been closed before the <sgmltag class="endtag">sect2</sgmltag> on +line 880, causing the error. The simple fix in this case is to add a <sgmltag +class="endtag">para</sgmltag> before the closing <sgmltag +class="endtag">sect2</sgmltag>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Element does not follow the DTD</term> + +<listitem> +<screen width="80"> +<computeroutput> +index.docbook:932: element qandaentry: validity error : Element qandaentry content +does not follow the DTD, expecting (blockinfo? , revhistory? , question , answer*), got (answer) +</para></answer></qandaentry> + ^ +</computeroutput> +</screen> + +<para>This error is caused by an element in the document not matching +the requirements of the DocBook <acronym>DTD</acronym> (Document Type +Definition). The <acronym>DTD</acronym> specifies what each element must +contain. This list is shown after <errortext>expecting</errortext> in +the error message. This so-called <quote>content model</quote> is quite +difficult to understand at first: refer to the Duck Book and the section +<quote>Understanding Content Models</quote> for full information.</para> + +<para>The text after <errortext>got</errortext> shows the content +actually found in the document.</para> + +<para>In the example above, we have a <sgmltag>qandaentry</sgmltag> +which is missing the required <sgmltag>question</sgmltag> element. This +was generated by the following input: +<programlisting> +<markup> +<![CDATA[ +<qandaset> +<qandaentry><answer><para>An answer +</para></answer></qandaentry> +</qandaset> +]]> +</markup> +</programlisting> +</para> + +<para>Adding a <sgmltag>question</sgmltag> element before the +<sgmltag>answer</sgmltag> fixes the problem.</para> + +<para>An easy mistake to make is to forget to put a +<sgmltag>para</sgmltag> element around text in, for example, a +<sgmltag>listitem</sgmltag> or a +<sgmltag>sect<replaceable>n</replaceable></sgmltag>. This will be shown +as <errortext>CDATA</errortext> in the <errortext>got</errortext> +section of the error.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="using-meinproc"> +<title>Using &meinproc;</title> + +<para>The most common way to run &meinproc; is simply as + +<screen><userinput>&meinproc; <filename><replaceable>docbook-file</replaceable></filename></userinput></screen> where + +<filename><replaceable>docbook-file</replaceable></filename> is usually +<filename>index.docbook</filename>. This command creates &HTML; pages +from the DocBook file. Note that these pages are only viewable in +&tde;-based browsers (like &konqueror;). If you need to view the &HTML; +output in another browser (for example, if you're placing it on line), +use + +<screen><userinput>&meinproc; <option>--stylesheet</option> <filename><replaceable>stylesheet-name</replaceable></filename> <filename><replaceable>docbook-file</replaceable></filename> +</userinput></screen> + +where +<filename><replaceable>stylesheet-name</replaceable></filename> is the +full path to one of the &XSL; stylesheets in <filename +class="directory">$<envar>TDEDIR</envar>/share/apps/ksgmltools/customization</filename>. +To produce output suitable for the web, you can use +<filename>tde-web.xsl</filename> or +<filename>tde-chunk-online.xsl</filename>. See the +<filename>README</filename> file in that directory for more details. +</para> +</sect2> + +</sect1> + +</chapter> + + +<chapter id="docbook-intro"> +<title>DocBook Introduction</title> + +<para>All &tde; documentation is produced in DocBook &XML; format, and +writers are encouraged to learn it (although it's by no means necessary, +and we're very happy to receive documentation written in plain +text). Although DocBook can look somewhat intimidating to beginners, the +markup is extremely self-descriptive, and many people find it easier +than &HTML; to learn.</para> + +<para>In this chapter, we'll just take a basic overview of the ideas +behind DocBook. For detailed information about individual tags and so +on, please see <ulink url="help:/khelpcenter/markup/index.html"> +The TDE DocBook Markup Guide</ulink>.</para> + +<sect1 id="docbook-overview"> +<title>Overview</title> +<para>DocBook is just an application of &XML;, so if you're familiar +with &XML;, then you'll feel right at home. If not, don't worry, as most +of the gory details aren't required knowledge for simply writing and +updating documentation. A DocBook file (and, indeed, any &XML; file) +consists of plain text, with tags surrounding some text to tell you (or +a computer) what that text represents. So, a snippet from a DocBook file +might look like: + +<!-- Gah, this needs wordwrapping to look vaguely sensible, but --> +<!-- fill-mode doesn't love me, and is making it difficult --> +<programlisting> +<sgmltag class="starttag">para</sgmltag>To display the clipboard history, click on the <sgmltag class="genentity">klipper</sgmltag> icon + in the <sgmltag class="genentity">tde</sgmltag> panel, or press <sgmltag class="starttag">keycombo +action="simul"</sgmltag><sgmltag + class="genentity">Ctrl</sgmltag><sgmltag + class="genentity">Alt</sgmltag><sgmltag + class="starttag">keycap</sgmltag>V<sgmltag + class="endtag">keycap</sgmltag><sgmltag + class="endtag">keycombo</sgmltag>. Previous +clipboard entries are shown + at the top of the pop-up menu which +appears.<sgmltag + class="endtag">para</sgmltag> +</programlisting> +The <sgmltag class="starttag">para</sgmltag> and <sgmltag +class="endtag">para</sgmltag> show the start and end, respectively, of a +paragraph. These delimiting marks are called <quote>tags</quote>, and +the content they contain (along with the tags) is called an +<quote>element</quote>. The <sgmltag class="starttag">keycombo</sgmltag> +tag has an extra piece of information specified: <sgmltag +class="attribute">action="simul"</sgmltag>. This is called an +<quote>attribute,</quote> and makes the tag more specific. The words +surrounded by & and ; are <quote>entities</quote>. They're simply +variables that expand to some other text, and are widely used in &tde; +documentation. See <xref linkend="kde-specialities"/> for more +information about entities. Tags, entities, comments and other parts of +&XML; that aren't simple text are referred to as <quote>markup.</quote> +</para> +</sect1> + +<sect1 id="content-and-presentation"> +<title>Content and Presentation</title> + +<para>One of the basic principles behind the use of DocBook in &tde; is +that content and presentation are strictly separated. DocBook files +contain the content, and &XSL; files contain the information about +presentation. This has a number of advantages, some of which are: +<itemizedlist> +<listitem> +<para>When writing, you don't have to worry about whether the +information is well presented, just that the information you're writing +is correct and readable.</para> +</listitem> +<listitem> +<para>All &tde; documentation has a similar look, so once readers are +familiar with conventions in one document, they're familiar with all documents.</para> +</listitem> +<listitem> +<para>Documentation is future-proofed, since by providing as much +information about content as possible, future formats, search engines, +&etc; are likely to be catered for easily.</para> +</listitem> +</itemizedlist> +</para> + +<para>In practice, this means that you should add markup that describes +what things <emphasis>are</emphasis> and not how they should appear. So, +in the example above, the <sgmltag class="starttag">keycombo</sgmltag> (a +keyboard shortcut) tells the reader (or computer) that the keys &Ctrl;, +&Alt; and <keycap>V</keycap> should be pressed simultaneously, but +doesn't say anything about how that should be displayed in the final +output. (In fact, it appears as <quote><keycombo +action="simul">&Ctrl;&Alt;<keycap>V</keycap></keycombo></quote>, but it +could equally be converted to <quote>C-M-V</quote> à la &Emacs; +or even some other way of showing keyboard shortcuts. What's important +is that the DocBook source has the <emphasis>information</emphasis> +necessary to work out what is being referred to.) +</para> +</sect1> + +<!-- I'm not sure how necessary this is, since most of the stuff I was --> +<!-- going to write is alread covered in Chapter 5 of the DocBook --> +<!-- reference (Phil)--> +<sect1 id="docbook-structure"> +<title>Structure</title> +<para> (<book> <chapter> <sectn> +<para>)</para> +</sect1> + +<sect1 id="kde-specialities"> +<title>&tde; Specialities</title> +<para>TDE-isms: entities, necessary bits (credits, translation + stuff)</para> + +<sect2 id="entities"> +<title>Entities</title> +<para>Entities (which are simply variables which expand to some other +text) are an important part of DocBook markup, and are used particularly +widely in &tde; documentation. For example, there are entities defined +for almost all &tde; applications. Therefore, when referring to, for +example, &konqueror; in documentation, you should use: +<programlisting> +<sgmltag class="genentity">konqueror</sgmltag> is, among other things, a +web browser. +</programlisting> +</para> +<para>This has several advantages. Firstly, it ensures that applications +are capitalized and marked-up consistently across all &tde; +documentation. This means that you don't have to remember whether the +help center program is KHelpCenter, KHelpcenter or Khelpcenter: the +entity (which is always entirely lowercase) automatically expands to the +correct one. +<!-- FIXME: there are probably some i18n advantages too, but I don't --> +<!-- know them offhand --></para> + +<para>There are entities defined for several classes of names: +<variablelist> + +<varlistentry> +<term>All &tde; applications</term> +<listitem> +<para>As mentioned before, all &tde; +applications have an entity. The entity name is in entirely lowercase, +and expands to the correctly capitalized version of the application +name. There is also an entity for &tde; itself: <sgmltag +class="genentity">tde</sgmltag>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Common English and technology abbreviations</term> +<listitem> +<para>For example, <quote>&ie;</quote> is written as <sgmltag +class="genentity">ie</sgmltag> and <quote>⪚</quote> as <sgmltag +class="genentity">eg</sgmltag>. This ensures that the same markup and +capitalization are used for these abbreviations throughout &tde; +documentation. Technological abbreviations such as &HTTP; and &XML; also +have entities, which are capitalized as usual (&ie;, <sgmltag +class="genentity">HTTP</sgmltag> and <sgmltag +class="genentity">XML</sgmltag> for the previous examples).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Trademarks</term> +<listitem> +<para>Names of companies and their products are often trademarked. For +this reason, it is important to mark them up with the +<sgmltag>trademark</sgmltag> tag, using the <sgmltag +class="attribute">class="registered"</sgmltag> attribute if +necessary. To reduce effort, and ensure that trademarks are given proper +acknowledgment, many common technology-related trademarks have been +given entities. For example, the entity <sgmltag +class="genentity">X-Window</sgmltag> expands to &X-Window;.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Contributor Names</term> +<listitem> +<para>Names of contributors to &tde; documentation have entities of the +form <sgmltag class="genentity">Firstname.Lastname</sgmltag> (or +<sgmltag class="genentity">Firstname.Initial.Lastname</sgmltag>). Email +addresses of contributors have entities of the form <sgmltag +class="genentity">Firstname.Lastname.mail</sgmltag>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Names of special keys</term> +<listitem> +<para>Names of keys on the keyboard are always marked up with either +<sgmltag>keycap</sgmltag> or <sgmltag>keysym</sgmltag>. Since it can be +difficult to distinguish between these two tags, entities have been +created for common keys, ⪚, <sgmltag class="genentity">Ctrl</sgmltag> +and <sgmltag class="genentity">Alt</sgmltag>.</para> +</listitem> +</varlistentry> + +</variablelist> +</para> + +<para>The definitions of these entities can be found in the following +locations in &tde; <acronym>3</acronym>: +<variablelist> + +<varlistentry> +<term>Items not requiring translation (&tde; application names, +technology abbreviations, trademarks)</term> +<listitem> +<para><filename>tdelibs/kdoctools/customization/entities/general.entities</filename></para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Contributor names and email addresses</term> +<listitem> +<para><filename>tdelibs/kdoctools/customization/entities/contributor.entities</filename></para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Language-specific terms and key names</term> +<listitem> +<para><filename>tdelibs/kdoctools/customization/en/user.entities</filename></para> +</listitem> +</varlistentry> + +</variablelist> +</para> + +</sect2> + +<sect2 id="necessary-sections"> +<title>Necessary Sections</title> +<para>There are several sections that appear in all &tde; DocBook files, +even though they are not required by DocBook itself: +<itemizedlist> +<listitem> +<para> +<programlisting> +<!ENTITY package "tde-module"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +</programlisting> +</para> +<para>This appears in the prologue immediately after the +<acronym>FPI</acronym>. See <ulink url="help:/khelpcenter/markup.html/#prologue">prologue</ulink> +for more details about this section.</para> +</listitem> +<listitem> +<para><programlisting><!-- TRANS:ROLES_OF_TRANSLATORS --></programlisting></para> +<para>This appears after the <sgmltag +class="starttag">authorgroup</sgmltag> element, and is a required +placeholder for use in translation (also known as <quote>i18n</quote> +from the number of letters between the first and the last of the word <quote>internationalization</quote>).</para> +</listitem> +</itemizedlist> + + +</para> +</sect2> +</sect1> + +</chapter> + +<chapter id="managing-documentation"> +<title>Sending the New Documents and Changes to &tde;</title> + +<para>As part of the wider &tde; project, there are some things that +documentation writers need to be aware of. There are a large number of +other developers working on &tde;, and working together with all of them +is an important part of what we do.</para> + +<sect1 id="release-schedule"> +<title>Respecting the Release Schedule</title> +<para>String freezes, when we write, etc</para> + +<warning> +<para>This needs reviewing by someone who pays more attention to +releases than I do.</para> +<!-- TODO cwoelz: OK, I'll do it. --> +</warning> + +<para>The &tde; release process, in which we go from the fast-moving and +sometimes unstable world of the &tde; &svn; repository, to a stable, polished product, is never +exactly the same twice, but there are some common features:</para> + +<para>A schedule for the next release of &tde; is published at <ulink +url="http://developer.kde.org">developer.kde.org</ulink>, with the +definitive guide to what will be happening and when. There will be two +or more <quote>freezes</quote>, when changes of a certain type are not +allowed in the &tde; &svn; repository: +<variablelist> +<varlistentry> +<term>Feature Freeze</term> +<listitem> +<para>When feature freeze is active, developers are not allowed to +commit new features to the repository. This is a good time to start writing, since +the features available in the application during this period are the +same as the ones which will be available in the released version.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>String Freeze</term> +<listitem> +<para>Text strings appearing in the &tde; user interface and in the +documentation are not allowed to be changed. This is to allow +translators to provide thorough translations which will match the +release. We are still considering how to work during this period of +freeze. One method which we have tried is to continue writing, but hold +back all changes to be committed in one go, immediately before the +release.</para> +</listitem> +</varlistentry> +</variablelist> +</para> +</sect1> + +<sect1 id="managing-svn"> +<title>Managing the Sources with &svn;</title> + +<para>You can find detailed information about how to use &svn; in conjunction +with &tde; in the <ulink url="http://quality.kde.org/develop/cvsguide/managestep.php"> +Managing &tde; Sources with Subversion guide</ulink></para> + +</sect1> + +<!-- FIXME: Thinking better, we must decide if we remove this and simply +link to the quality site, or keep it. Better remove it. + +<sect2 id="svn-checking-out"> +<title><quote>Checking Out:</quote> Getting a copy of the &tde; +sources</title> +<para>The first stage in using &svn; is to make your own copy of the &tde; +source. This is known as <quote>checking out.</quote> To do this, make +sure the &svn; client is installed on your system, and follow these steps (from +<ulink url="http://developer.kde.org">developer.kde.org</ulink>): +<orderedlist> +<listitem><para>Install the following file as <filename>~/.cvsrc</filename>: +<programlisting>cvs -z4 -q +diff -u3 -p +update -dP +checkout -P +</programlisting> +</para> +<para>Please don't use a higher value than -z4. It just creates + unnecessary high load on the server which slows down the access for + everybody while it certainly does not increase throughput. + +<important><para>The <userinput>update -dP</userinput> is essential. Without this it won't work.</para> +</important></para> +</listitem> + +<listitem><para>Execute the following commands (if you are not using the +<application>bash</application> shell, substitute the appropriate +command for <command>export</command>): +<screen> +<userinput><command>export +#ROOT=:pserver:anonymous@anoncvs.kde.org:/home/kde</command></userinput> +<userinput><command>cvs login</command></userinput> +</screen> +</para> + +<para>Just press &Enter; if there is a question about a password. If you + don't have a <filename>.cvspass</filename> file in your home directory + create one (using <userinput><command>touch + ~/.cvspass</command></userinput> - note the dot in + <filename>.cvspass</filename>) and run <userinput><command>cvs + login</command></userinput> again. +</para> +</listitem> + +<listitem> +<para>Run <userinput><command>cvs co arts tdelibs tdebase +<replaceable>other modules</replaceable></command></userinput> where +<replaceable>other modules</replaceable> is a list of the other modules +you need. <filename>arts</filename>, <filename>tdelibs</filename> and +<filename>tdebase</filename> are the minimum you will need to run a +&tde; desktop. If you are writing documentation for applications which +live in any other modules, you will need to add them to +<replaceable>other modules</replaceable> in the command above.</para> +</listitem> +</orderedlist> +</para> +</sect2> + +<sect2 id="svn-updating"> +<title>Updating Your Sources</title> +<para>Keeping your copy of the sources up-to-date with the repository is +as simple as entering the directory of a module you want to update, and +entering <userinput><command>cvs up</command></userinput>. Only the differences +between your copy and the repository are downloaded, so this takes less +bandwidth than running <userinput><command>cvs co</command></userinput>, +as you did before.</para> + +<para>It's a good idea to run <userinput><command>cvs +up</command></userinput> before modifying files, since this helps +prevent conflicts (see below).</para> + +<para>Running <userinput><command>cvs up</command></userinput> produces a lot of +output. Most of it consists of a letter followed by a filename. The +meanings of the most common letters are: +<variablelist> + +<varlistentry> +<term><computeroutput>P</computeroutput></term> +<listitem><para>The file has been updated to the latest version in the +repository. Only the difference between your last copy and the latest +version (a patch) was sent.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><computeroutput>U</computeroutput></term> +<listitem><para>The file has been updated to the latest version in the +repository, but a patch wasn't available, so the whole file was +sent. This usually means that the file is new since your last update.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><computeroutput>M</computeroutput></term> +<listitem><para>The file is modified in your private copy. This means +you have made changes that haven't yet been committed to the repository.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><computeroutput>C</computeroutput></term> +<listitem><para>There were changes in both your private copy and the +repository, and they conflicted with one another. See <xref +linkend="svn-managing-conflicts" /> for more information.</para> +</listitem> +</varlistentry> +</variablelist> + +There are other letters which might appear: for more information, see +the CVS <command>info</command> page.</para> +</sect2> + +<sect2 id="svn-committing"> +<title><command>cvs commit</command>: Making your changes +available</title> +<para>Once you have made changes to your private copy of the +documentation, you can add these changes to the repository with the +<command>cvs commit</command> command. Run <userinput><command>cvs +commit <replaceable>file...</replaceable></command></userinput> where +<replaceable>file...</replaceable> is a list of all the files that you +have modified. You will be presented with an editor (the one set in your +<envar>EDITOR</envar> environment variable) in which you should enter a +brief log message describing the changes you've made.</para> +<para>In the log file you can use <userinput>CCMAIL:<replaceable>email +address</replaceable></userinput> to automatically send a copy of the +log message to <replaceable>email address</replaceable>. If the change +is a small one (for example, correcting a small number of typos), you +can add CVS_SILENT to the log message. This will allow easier filtering +for those who read the mailing list to which log messages are sent.</para> + +<para>Write something about binary files.</para> +<para>Mention adding new files.</para> + +</sect2> + +<sect2 id="svn-managing-conflicts"> +<title>Managing Conflicts and Other Problems</title> +<para>CVS will try to automatically handle merging two sets of changes +to a file. For example, take this situation: +<orderedlist> +<listitem><para>You and another writer are both working on a file, <filename>index.docbook</filename>.</para> +</listitem> +<listitem> +<para>The other writer makes changes to the first half of the file and +commits them to the CVS repository.</para> +</listitem> +<listitem> +<para>You make changes to the <emphasis>second</emphasis> half of the +file, but do not commit them (yet).</para> +</listitem> +</orderedlist> +</para> + +<para>Now, if you run <userinput><command>cvs up</command></userinput>, +<command>cvs</command> will add the changes from the other writer to +your private copy, while leaving your changes in the file.</para> + +<para>This works fine if two writers have made changes to different +parts of the file, but if you make changes to the same part of the file, +<command>cvs</command> cannot tell which changes should take +precedence. It will therefore mark your file as having conflicts (shown +with a <computeroutput>C</computeroutput> in the output of +<userinput><command>cvs up</command></userinput>), and place markers in +the file showing both your version and the version of the other +writer. You must then read through the file and edit it to contain only +the more appropriate of the two versions.</para> + +<para>Another common problem is that you get errors about <quote>sticky +tags</quote> when trying to commit a file. If this happens, run +<userinput><command>cvs up -A</command></userinput> and commit again.</para> +</sect2> + + +</sect1> + +--> + +<sect1 id="working-with-others"> +<title>Working With Other Documenters and Developers</title> + +<para>One important and fun part of working on &tde; is the community of +other developers who you work with. The people you'll work with most +often as a documentation writer are the documentation team, the quality +team (if you're a new contributor) and the maintainer of the application +that you're working on.</para> + +<para>The documentation team is your main resource for help with doc +writing and a central point of contact to ensure that everyone's work is +co-ordinated. The main ways to contact the documentation team are via +the <email>kde-doc-english@kde.org</email> mailing list and on +<acronym>IRC</acronym> in the fkde-docs channel on the server +<systemitem class="domainname">irc.freenode.net</systemitem>. If you +plan to work on a particular application, please tell us, so that we can +ensure that no-one else is working on it simultaneously, so that effort +would be duplicated. Also, feel free to contact us with any problems or +questions you might have about writing documentation. You don't need to +feel like you're working entirely on your own – there are plenty +of people who are able to help.</para> + +<para>The &tde; Quality Team provides more broad support. If you have +any general questions about &tde; development, or how documentation fits +into the wider &tde; environment, the Quality Team mailing list is a +good place to ask: <email>kde-quality@kde.org</email>. If you're not +sure whether to ask a question on the kde-quality or kde-doc-english +list, just pick one and ask. Many people who read one list read the +other, and you'll be pointed to the appropriate list if +necessary.</para> + +<para>Working with programmers is a little less formal. The usual reason +to contact a programmer is to ask about a feature or behavior of an +application that you're documenting. To find the appropriate person to +contact for a particular application, look in the +<menuchoice><guimenu>Help</guimenu> <guimenuitem>About +<replaceable>KApp</replaceable></guimenuitem></menuchoice> menu item for +the maintainer. If you can't find a maintainer, ask on +<email>kde-doc-english@kde.org</email> or +<email>kde-devel@kde.org</email>. If asking on the kde-devel list, +mention that you're writing the documentation for that application +– it helps to identify you to those reading a busy list. In +general, programmers and other developers are happy to help, and willing +to work with you, so don't feel afraid of asking them for information, +and building up a working relationship.</para> + +</sect1> + +<sect1 id="updating-documentation"> +<title>Updating Documentation</title> + +<para>With the pace of change of &tde; applications, documentation can +rapidly become out-of-sync with the application it is describing. To +keep its value, documentation needs to be updated. Often this is simply +a case of reading the existing documentation, and checking each +description of an item against the latest version of the +application. For example, are there new items in the menus that are not +described in the documentation?</para> + +<para>Sometimes, more extensive updates are needed. If new features of +the application significantly change the way it works, then new sections +of the documentation may be needed, or reorganization of the existing +content might be necessary. In particularly severe cases, an entire +rewrite might be necessary.</para> + +</sect1> + +<sect1 id="licenses"> +<title>Licenses for &tde; Documentation</title> + +<para>&tde; uses the <acronym>FDL</acronym> (Free Documentation License) for +all documentation. This license has several variants, some of which place +restrictions on how content is used in other contexts.</para> + +<para>The specific terms we use are:</para> + +<literallayout>Permission is granted to copy, distribute and/or modify this +document under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts.</literallayout> + +<para>This is the only version of the license that is safe to use for +documentation that is to be distributed with &tde;.</para> + +<para>The items that may differ in other uses of the <acronym>FDL</acronym> +are as follows:</para> + +<variablelist> +<varlistentry> +<term>with no Invariant Sections</term> +<listitem> +<para>Invariant sections are, as you might expect, sections that +<emphasis>must not</emphasis> be altered in any reproduction of the content. +The reasoning behind this, is so nobody can make a subjective claim, and +attribute it to you, by altering your words.</para> + +<para>For instance, if you say <quote>Foo is a terrible piece of +software</quote> and the section is marked invariant, the developers of +<quote>Foo</quote> can not take your writing, change it to say <quote>Foo is +a great piece of software</quote> and still attribute that opinion to +you.</para> + +<para>For many people, this restriction is incompatible with the +<acronym>GPL</acronym> and therefore some distributions choose not to +include any user manuals that contain <quote>Invariant Sections</quote>. +Since they must be reproduced verbatim, this also means we are not able +to reuse such content in our own manuals, without including this +statement.</para> + +<para>For this reason, <quote>Invariant Sections</quote> are not permitted +in documentation that is to be distributed with &tde;, nor can we safely +reuse content from other sources, if they include Invariant Sections.</para> + +<para>It is not normally appropriate to write opinion pieces in &tde; +documentation. Such content should be restricted to your own website, or +documentation that is not distributed with &tde;, so the fact we outlaw +<quote>Invariant Sections</quote> in &tde; documentation is not normally a +problem. If you think you have a special case, please raise it with the +documentation team, and understand that including such sections may prevent +some distributions adding your manual (or the software itself) to their +distribution.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>with Front-Cover Texts <replaceable>names of +sections</replaceable></term><term>with Back-Cover Texts <replaceable>names +of sections</replaceable></term> +<listitem> +<para>As with <quote>Invariant Sections</quote>, these are texts that may +not be altered, and must be included in any reuse of any of the content. It +also means we would have to alter our license to match that of the content +we have reused. This leads to similar problems as that of the +<quote>Invariant Sections</quote>.</para> + +<para>This one mainly comes up if we want to use <acronym>FDL</acronym> +content found from other sources (for instance, books or websites.) In +these cases, the best approach is to ask the authors to permit relicensing, +and offer to include their front/back cover texts anyway, but without having +to change our license terms.</para> +</listitem> +</varlistentry> +</variablelist> + +<warning> +<para>The terms of the <acronym>FDL</acronym> as used by &tde; +documentation, are entirely <acronym>GPL</acronym> compatible, and do +not restrict the reuse of the content. Any deviation from these terms, +or any change in license could restrict distribution of your software or +documentation, and should only be undertaken with full knowledge of the +consequences, and with written permission of all copyright +holders.</para> +</warning> + +</sect1> + +<sect1 id="bugs-kde-org"> +<title>Using bugs.kde.org</title> +<para>Note how we use b.k.o (general to-do items). Also point to Carlos' +guide on quality.k.o</para> + +<para>The &tde; bug tracking system, located at <ulink +url="http://bugs.kde.org">http://bugs.kde.org</ulink>, is now part of +the documentation team's toolkit. Issues with the &tde; documentation +can be filed in the <quote>docs</quote> +product of the bug tracker. Incorrect or outdated content, missing +content, outdated screenshots and typos are all appropriate reasons to +file bugs.</para> + +<para>When filing bugs, especially for incorrect or outdated content, be +specific about what's wrong. For example, if a certain page of a +configuration dialog is incorrectly documented, say which page it is in +the bug report. That way, someone fixing the bug can quickly find the +appropriate part of the application and the documentation, and make the +necessary changes with a minimum of effort.</para> + +<para>For more information on using the &tde; bug tracking system, see +<ulink +url="http://quality.kde.org/develop/howto/howtobugs.php">http://quality.kde.org/develop/howto/howtobugs.php</ulink>.</para> + +</sect1> + +</chapter> + +<chapter id="other-tasks"> +<title>Leveraging your Newly Acquired Knowledge</title> + +<para> After finishing documenting an application, +you can leverage the knowledge you gained in the process and improve +the application's level of quality in other areas. The Quality Team provide +guides on how to perform many of these tasks.</para> + +<para><itemizedlist> +<listitem><para><ulink url="http://quality.kde.org/develop/howto/howtodocs.php"> +Writing context help and configuration descriptions</ulink>: the handbook +is not the only source of help available for &tde; applications. Context help, +or <emphasis>whatsthis</emphasis> provides invaluable support for users, and +you will find it easy to write, especially after writing the handbook. +Documenting configuration options available through the KConfig framework may +require additional research, but configuration descriptions are often the only +documentation available for configuration options. +<!-- FIXME: Improve wording --> +</para> +</listitem> +<listitem><para><ulink url="http://quality.kde.org/develop/howto/howtoui.php"> +Performing usability analysis and tests</ulink>: to document your applications, +you probably tested most of the application functionality in a systematic way. +Please take the time read the guide and report the usability issues and +suggestions that appeared in the process.</para> +</listitem> +<listitem><para><ulink url="http://quality.kde.org/develop/howto/howtopromo.php"> +Writing guides and articles about the application</ulink>: promotion is the key +for a successful open source project, as widespread use means +usually more probability of attracting prospect contributors, developers, +documenters, translators, &etc;. +</para></listitem> +</itemizedlist> +</para> + +</chapter> + +<chapter id="credits"> +<title>Credits and License</title> +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +</chapter> + +<appendix id="widget-names"> +<title>Widget Names</title> +<para>Steal from (and extend) the <quote>Visual Guide to +&tde;</quote>.</para> + +</appendix> + + + + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: xml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +fill-column:72 +End: + +vim:tabstop=2:shiftwidth=2:expandtab +--> diff --git a/doc/tutorials/docprimer/kate-plugin.png b/doc/tutorials/docprimer/kate-plugin.png Binary files differnew file mode 100644 index 0000000..8633ffe --- /dev/null +++ b/doc/tutorials/docprimer/kate-plugin.png diff --git a/doc/tutorials/docprimer/kate-validate-xml.png b/doc/tutorials/docprimer/kate-validate-xml.png Binary files differnew file mode 100644 index 0000000..5d4e17b --- /dev/null +++ b/doc/tutorials/docprimer/kate-validate-xml.png diff --git a/doc/tutorials/docprimer/quanta-doc-primer.png b/doc/tutorials/docprimer/quanta-doc-primer.png Binary files differnew file mode 100644 index 0000000..b30f874 --- /dev/null +++ b/doc/tutorials/docprimer/quanta-doc-primer.png diff --git a/doc/tutorials/docprimer/quanta-doc-structure.png b/doc/tutorials/docprimer/quanta-doc-structure.png Binary files differnew file mode 100644 index 0000000..c8bd3bb --- /dev/null +++ b/doc/tutorials/docprimer/quanta-doc-structure.png diff --git a/doc/tutorials/docprimer/quanta-entities.png b/doc/tutorials/docprimer/quanta-entities.png Binary files differnew file mode 100644 index 0000000..dc2a4a9 --- /dev/null +++ b/doc/tutorials/docprimer/quanta-entities.png diff --git a/doc/tutorials/docprimer/quanta-tag.png b/doc/tutorials/docprimer/quanta-tag.png Binary files differnew file mode 100644 index 0000000..436692e --- /dev/null +++ b/doc/tutorials/docprimer/quanta-tag.png diff --git a/doc/tutorials/docprimer/quanta-toolbars.png b/doc/tutorials/docprimer/quanta-toolbars.png Binary files differnew file mode 100644 index 0000000..d34a759 --- /dev/null +++ b/doc/tutorials/docprimer/quanta-toolbars.png diff --git a/doc/tutorials/docprimer/quanta.png b/doc/tutorials/docprimer/quanta.png Binary files differnew file mode 100644 index 0000000..6dfb9aa --- /dev/null +++ b/doc/tutorials/docprimer/quanta.png diff --git a/doc/tutorials/docprimer/xmlval.png b/doc/tutorials/docprimer/xmlval.png Binary files differnew file mode 100644 index 0000000..180729f --- /dev/null +++ b/doc/tutorials/docprimer/xmlval.png diff --git a/doc/tutorials/docprimer/xsltproc.png b/doc/tutorials/docprimer/xsltproc.png Binary files differnew file mode 100644 index 0000000..54de744 --- /dev/null +++ b/doc/tutorials/docprimer/xsltproc.png 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: +--> diff --git a/doc/tutorials/styleguide/CMakeLists.txt b/doc/tutorials/styleguide/CMakeLists.txt new file mode 100644 index 0000000..396682f --- /dev/null +++ b/doc/tutorials/styleguide/CMakeLists.txt @@ -0,0 +1,9 @@ +################################################# +# +# Improvements and feedback are welcome +# +# This file is released under GPL >= 2 +# +################################################# + +tde_create_handbook( DESTINATION khelpcenter/styleguide ) diff --git a/doc/tutorials/styleguide/Makefile.am b/doc/tutorials/styleguide/Makefile.am new file mode 100644 index 0000000..4169155 --- /dev/null +++ b/doc/tutorials/styleguide/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/tutorials/styleguide/index.docbook b/doc/tutorials/styleguide/index.docbook new file mode 100644 index 0000000..8c94356 --- /dev/null +++ b/doc/tutorials/styleguide/index.docbook @@ -0,0 +1,466 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kde-authors '<personname><surname>The &kde; Documentation Team</surname></personname>'> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"><!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &tde; Style Guide</title> + +<authorgroup> +<author>&kde-authors;</author> +<author>&tde-authors;</author> +</authorgroup> + +<copyright> +<year>2002</year> +<holder>The KDE e.V.</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; style standards for writing documentation. +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="introduction"> +<title>Introduction</title> + +<para>The purpose of writing documentation for the &tde; Project, is +to create for all the users, a complete, well organized set of +documentation for each and every component of the &tde; project. In +order to achieve this goal, we have drafted the following guide to +help.</para> + +<para>This document is very new, and at the moment, very +sparse.</para> + +<para>If you have comments or additions, please do not hesitate to +suggest them on the kde-doc-english@kde.org mailing list.</para> + +<para>In the meantime, here are some short notes based on content that +was previously on the <ulink url="http://i18n.kde.org/">&tde; +i18n</ulink> website.</para> + +</chapter> + +<chapter id="consistency"> +<title>Consistency</title> + +<sect1 id="dates-and-revisions"> +<title>Dates and Revision Numbers</title> + +<para>While it may seem like a minor issue, and a minor part of your +document, it is very important that the following guidelines are +adhered to:</para> + +<itemizedlist> +<listitem> +<para>All dates which are part of the text of your document +should be spelled out &ie; <quote>March 2, 2000</quote></para> +<para>This is the only way to be sure that <quote>03/02/2000</quote> +is interpreted correctly in all languages, and by all readers.</para> +<important><para>Exception: in the <sgmltag>date</sgmltag> tag, dates +should be in the <quote>YYYY-MM-DD</quote> format.</para> +</important> +</listitem> +<listitem> +<para>All information included between the <sgmltag +class="starttag">releaseinfo</sgmltag> and <sgmltag +class="endtag">releaseinfo</sgmltag> should match the release number +of the application.</para> +</listitem> +</itemizedlist> +</sect1> + +<sect1 id="screenshots"> +<title>Screenshot Consistency</title> + +<para>To create consistent screenshots, use an environment where all requirements can +be configured without interfering with your normal production environment. One option +is a virtual machine. Another option is creating at least two themes. One theme is the +normal everyday theme for production. The other theme is for handbook screenshots. +Toggle between the two themes as necessary. A third option is a separate user +account configured as required.</para> + +<para>To strive for a look of consistency with screenshots, please abide by the +following requirements.</para> + +<itemizedlist> + +<listitem> +<para>No personal information. That includes login names. Be careful when including +window decorations because the title bar could include such information. Use a testing +account or a virtual machine when such information cannot be avoided.</para> +</listitem> +<listitem> +<para>Use &ksnapshot;. Normally use the <guilabel>Window Under Cursor</guilabel> option. Use the +<ulink url="help:/ksnapshot"> &ksnapshot; Handbook</ulink> to learn more.</para> +</listitem> +<listitem> +<para>Using the &ksnapshot; <guilabel>Include window decorations</guilabel> option is not +required and not forbidden. Just ensure the decorations to do not interfere with the +purpose of the screenshot.</para> +</listitem> +<listitem> +<para>PNG images only.</para> +</listitem> +<listitem> +<para>Window decorations: KDE2, Keramik, or Plastik.</para> +</listitem> +<listitem> +<para>Widget style: KDE Classic, Keramik, or Plastik.</para> +</listitem> +<listitem> +<para>In &kcontrol;->Style, enable <guilabel>Show icons on buttons</guilabel>.</para> +</listitem> +<listitem> +<para>Colors: TDE defaults.</para> +</listitem> +<listitem> +<para>Background: No wallpaper, no gradients.</para> +</listitem> + +</itemizedlist> + +</sect1> + +<sect1 id="other-consistency-issues"> +<title>Other Consistency Issues</title> + +<itemizedlist> +<listitem> +<para>Please submit only plain <acronym>ASCII</acronym> text, or +Docbook &XML;. Anything else will be returned to you. (Docbook &XML; is +preferred.)</para> +</listitem> +<listitem> +<para>Make sure you first read, and follow, the documentation template +provided. You can find this in the source folder for &tde;. Simply +point a browser to <filename +class="directory">tdelibs/doc/kdoctools/template.docbook</filename></para> +<note><para>If there is existing documentation (from the developer, or +from &tde; 1.x or 2.x), then use that as a base to work from, but it +needs to conform to the layout from the documentation +template.</para></note> +</listitem> +<listitem> +<para>Spell things according to Standard American spelling, except for +proper names, places, &etc;</para> +</listitem> +<listitem> +<para>Make sure to set your spell checker to US English. Make sure you +<emphasis>use</emphasis> your spell checker.</para> +</listitem> +<listitem> +<para>If there is a non-English word, which is used in an English +sentence, be sure to spell this correctly, using appropriate accent +marks, and any special characters. Use the &kcharselect; application +if you don't have the correct keys on your keyboard.</para> +</listitem> +<listitem> +<para>Abbreviations should be capitalized, unless they are +specifically intended to not be capitalized. (&ie; is a good +example).</para> +</listitem> +<listitem> +<para>Punctuation within numbers should be Americanized: +10,000.00</para> +</listitem> +<listitem> +<para>It is more legible to use written numbers where the number has +no technical value, ⪚ <quote>There are three buttons on the +dialog</quote>. In this context <quote>3</quote> is not technically +significant. Numbers with technical significance should be written as +figures. (&ie; <quote>a 10 MB file</quote>, not <quote>a ten MB +file</quote>.)</para> +</listitem> +<listitem> +<para>Spell check and proofread your work before you send it in. Or +even better, have someone else read it over. Spell checking programs +won't catch incorrect words such as using <quote>their</quote> for +<quote>there</quote>.</para> +</listitem> +</itemizedlist> +</sect1> + +</chapter> + +<chapter id="writing-well"> +<title>Writing Well</title> + +<para>Some things to think about when writing documentation</para> + +<para>How many times have you attempted to read a man page, and given +up in frustration — all the facts are there, but the writing is +too dry and technical for you to make sense of them? We want to avoid +this with the documentation you're writing. </para> + +<para>It's difficult to avoid the very dry, choppy style we're all too +familiar with, but do try to make the writing flow and keep it +<emphasis>user-friendly</emphasis>. Try to be as friendly as you can +manage without being patronizing, and without sacrificing clarity or +detail.</para> + +<para> Things you should consider: </para> + +<itemizedlist> + +<listitem> +<para>Make sure you explain all aspects of the interface, and that you +don't leave out any command line options available. </para> +</listitem> + +<listitem> +<para>It's important to keep a logical progression of difficulty. Keep +the first few pages of the document simple, and accessible to users +who have never seen the application before. More technical information +should appear towards the end of the document. </para> +</listitem> + +<listitem> +<para>Be sure to write to the level of the intended reader. By this we +mean, a Samba control module has a very different user base than a +user of a game, and the manuals should reflect this. Don't insult the +Samba networker's intelligence, and don't assume knowledge for the +gamer that might not be there.</para> +</listitem> + +<listitem> +<para>It is highly encouraged to use screenshots, pictures of action +buttons, &etc; These are &GUI; applications, and a picture can be worth a +thousand words. </para> +</listitem> + +<listitem> +<para>Please define computer abbreviations, unless they are well +understood by all computer users (There's no need to define +<acronym>RAM</acronym>, <acronym>PC</acronym>, &etc;).</para> + +<para>For example, <quote>If you are going to use +<acronym>PPP</acronym> (Point to Point Protocol), +then.....</quote>. Define it only once though, in this example you +could now use <acronym>PPP</acronym> without explanation for the rest +of the document.</para> + +<para>The first time you introduce the word you should use <sgmltag +class="starttag">firstterm</sgmltag> or consider setting up a glossary +and using <sgmltag class="starttag">glossentry</sgmltag>.</para> +</listitem> + +<listitem> +<para>Remember the small things: If it's dockable, explain how to do +that. Don't forget to mention where it installs itself in the K +menu. If there are any environment settings required, and if they must +be set manually, explain how to do that - if they're set +automatically, they still need to be documented.</para> +</listitem> + +<listitem> +<para>Write something you would be happy to read as a user who doesn't +know how the application works. Perhaps if you have a friend or family +member who isn't familiar with the application you're writing about, +have them work through using it, with your documentation as a +guide. </para> +</listitem> +</itemizedlist> + +</chapter> + +<chapter id="more-hints"> +<title>Other general tips and hints for good writing</title> + +<para>A good way to catch simple errors is to read the text out loud, +or have someone else read it to you. Passages that don't +<quote>flow</quote> or have obviously awkward construction of the type +you may miss on the screen, will usually become blindingly obvious +when you hear them. This is especially the case with detecting really +long sentences, as you will run out of breath and turn blue.</para> + +<para>Be concise, be specific, and be direct. Choose your words +carefully, and be certain you know the exact meaning of every word +you use. Is it the right word? Use a dictionary, and find out.</para> + +<para>Use complete sentences. Not fragments. Like these ones.</para> + +<para>While talking about sentences:</para> +<itemizedlist> +<listitem> +<para>Avoid run on sentences, sentences that cover several different +subjects, or sentences that could be broken up into several sentences; +avoid sentences that can fill a whole paragraph all by themselves and +that are really long, like this one, which is all of the above.</para> +</listitem> +<listitem> +<para> +Use a comma before <quote>and</quote> in compound sentences, ⪚ +<quote>Use the left mouse button to select and copy text, and the +middle mouse button to paste it.</quote></para> +</listitem> +<listitem> +<para>Keep to logical sentence order.</para> +<para>For example, <quote>&konqueror; is a web browser with the +ability to browse file systems and it includes a javascript +interpreter.</quote> (Do you see why this is awkward?)</para> +</listitem> +<listitem> +<para>Try not to use the same word several times in the same sentence. +An exception to this, is an application command or technical word, +where this repetition is necessary, and improves clarity.</para> +</listitem> +<listitem> +<para>Do not start sentences with any of <quote>and,</quote> +<quote>so,</quote> <quote>but,</quote> <quote>because,</quote> or +<quote>however.</quote></para> +</listitem> +<listitem> +<para>Try to avoid contractions, rather spell out both words; ⪚, +<quote>it is</quote> rather than <quote>it's</quote>; <quote>can +not</quote> rather than <quote>can't</quote></para> +</listitem> +<listitem> +<para>There is no need to worry about simple text formatting such as +leaving two spaces after punctuation or indenting paragraphs. This is +all handled by Docbook &XML; and the <acronym>XSLT</acronym> +stylesheets in use.</para> +</listitem> +</itemizedlist> + +<para>Remember, we have also an active proofreading team, and there is +always someone to help you with grammar, so just +write and have fun!</para> + +</chapter> + +<chapter id="resources"> +<title>Resources</title> + +<sect1 id="general-purpose-sites"> +<title>General Purpose Websites</title> + +<para>A few sites you may find worth bookmarking, or at least +visiting.</para> + +<sect2 id="dictionary-sites"> +<title>Dictionary Sites</title> + +<itemizedlist> +<listitem> +<para><ulink url="http://www.m-w.com/">Merriam Webster +Online</ulink></para> +</listitem> +<listitem> +<para><ulink +url="http://www.dictionary.com/">Dictionary.com</ulink></para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="thesaurus-sites"> +<title>Thesaurus Sites</title> + +<itemizedlist> +<listitem> +<para><ulink url="http://www.m-w.com/">Merriam-Webster</ulink> have a +thesaurus as well as a dictionary</para> +</listitem> +<listitem> +<para><ulink url="http://www.thesaurus.com/">Roget's +Thesaurus</ulink></para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="other-style-guides"> +<title>Style Guides and Other Resources</title> + +<itemizedlist> +<listitem> +<para><ulink +url="http://www.cc.columbia.edu/acis/bartleby/strunk/">Strunk & +White</ulink> is the base style guide for many newspapers and press +galleries. If you want to look up a grammar or usage question, this is +the place to go.</para> </listitem> + +<listitem> +<para>The <ulink +url="news://alt.usage.english">alt.usage.english</ulink> newsgroup. +If you'd like every sentence chewed over, dissected, and then +rewritten several conflicting ways, or some great advice about bacon, +you'll find both here. Many real live editors and authors hang out +here, and they do know their stuff. Just make sure you read all ten +or so <acronym>FAQ</acronym>'s before asking a question.</para> +</listitem> +</itemizedlist> +<para>Other possibly useful sites</para> + +<itemizedlist> +<listitem><para><ulink +url="http://hotwired.lycos.com/hardwired/wiredstyle/biblio/">The Wired + Style Guide Bookmarks section</ulink></para> +</listitem> + +<listitem> +<para><ulink +url="http://www2.rscc.cc.tn.us/%7Ejordan_jj/OWL/Clutter.html">http://www2.rscc.cc.tn.us/~jordan_jj/OWL/Clutter.html</ulink> +If you tend to write very wordy sentences, here's a page with some +help for you. Includes a useful table of ways to rewrite common +mistakes.</para> +</listitem> +<listitem> +<para><ulink +url="http://owl.english.purdue.edu/Files/116.html">http://owl.english.purdue.edu/Files/116.html +</ulink> is a page about how to make sentences <quote>flow</quote> +better</para> +</listitem> +</itemizedlist> +</sect2> +</sect1> + +</chapter> + +<!-- &trademarks; --> + + +<chapter id="credits-and-license"> +<title>Credits and Licenses</title> + +<para>The &tde; Documentation Style Guide</para> + +<!-- FIXME proper credits section --> +<para>Copyright 2002, Lauri Watts, Mike McBride, Eric Bischoff, +Frederik Fouvry.</para> +<para>Copyright &tde-copyright-date;, &tde-authors;.</para> + +&underFDL; + +</chapter> + +<!-- &wordlist; --> + +</book> |
