From dd581bd656a10e51b22ff7a7c2d6b55fb6c7d90a Mon Sep 17 00:00:00 2001 From: Darrell Anderson Date: Sun, 5 Oct 2014 10:50:02 -0500 Subject: Move Tutorials from tdebase. Add docbook & markup tutorials. Tutorials need editing and updating. Thus the default configuration is -DBUILD_TUTORIALS=OFF. --- doc/tutorials/docprimer/index.docbook | 2160 +++++++++++++++++++++++++++++++++ 1 file changed, 2160 insertions(+) create mode 100644 doc/tutorials/docprimer/index.docbook (limited to 'doc/tutorials/docprimer/index.docbook') 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 @@ + +The &kde; Documentation Team'> + meinproc"> + checkXML"> + Subversion"> + + +]> + + + + +The &tde; Documentation Primer + + +&kde-authors; + +CarlosWoelz + +&tde-authors; + + + +2004 +The KDE Documentation Team + + +2004 +Carlos Woelz + + +&tde-copyright-date; +&tde-team; + + +&FDLNotice; + +&tde-release-date; +&tde-release-version; + + + +This document provides information to start writing documentation for &tde;. +Please report any errors or omissions to +trinity-devel@lists.pearsoncomputing.net. + + + + +TDE +Writing +Documentation + + + + + +Introduction + + +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. + +The &tde; English Documentation Team 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;. +The team is made up of people doing several different tasks: + +Writing documentation for individual applications + +Writing wider documentation for the whole of &tde; (like +the User Guide, or this document). + +Proofreading and/or updating documentation to ensure +that it is correct and up-to-date. + + +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, +kde-doc-english@kde.org, or on IRC in the channel #kde-docs on +irc.freenode.net. + + + +The &tde; Quality Team provides support for +new contributors, and to coordinates the efforts of the volunteers. +The &tde; Quality Team Website +provides guides to help you with some general development tasks, +such as getting the sources, +Building +&tde; From Source Step By Step, and + +Working with Subversion, &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, kde-quality@kde.org, or on IRC +in the channel #kde-quality on +irc.freenode.net. + + + + + + +Getting Started + +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. + + + + +Things You'll Need + +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. + +Notice that the list of requirements does +not 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. + + + +English Knowledge + +All &tde; documentation is originally written in English, so you +have to be able to write English to a reasonable level. That said, you +don't 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 +some 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 http://i18n.kde.org. + +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 kde-doc-english@kde.org if +you'd like to help the proofreaders. + + + + + +Deciding What to Write About +&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: + +Find a topic that you'll enjoy writing about; It will +increase your motivation and help you to produce better documentation. + +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! + + + + + +If you are looking for an application to document, or just checking the status +of the application you want to work with, the + +&tde; Quality Team Wiki 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. + +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 kde-doc-english@kde.org 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!). + + +Another place to check is the &tde; bug list at http://bugs.kde.org. 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 +http://i18n.kde.org/doc/current.php page. + +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 +Helpappname +Handbook. 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: + + +Inaccurate information about how an application +worksFor 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. + + +GUI options or menu items (or sometimes, entire +dialogs)This often happens in configuration dialogs, when +new items are added, a new grouping of existing options may be +created. + +New Features that are available and are not yet +documented. + + + + + +Access to a Recent Version + +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: + + + +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. + + + +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 kde-quality@kde.org mailing list +about it, if you think this is the way to go. + + + + + + +If you want to try out building &tde; from sources, the &tde; Quality +website provides +a detailed, +step by step building guide. You can find even more information at the +&tde; Developers Website. +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 kde-quality@kde.org. + + + + + + + +&tde; Writing Recommendations and Guidelines + +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. + +We also offer some general writing tips to help you to +get started, provided by experienced &tde; documenters. + + +Writing for your Audience + +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: + +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. + + +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. + + + +Remember also that different types of documentation have different +purposes: + + + +Application Handbooks + +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. 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.) +The Application Handbook should be answering the question: +What are all the things I can do with this application? + + + +User Guide + +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. +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. +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. +The User Guide should be answering the question: How do I +do this common task, ⪚ send an email, play a +movie?. + + + +What's This Help + +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. +Provide an example of the expected input, if that is not clear +from the context. +The What's This Help is most often answering the question: Do I +need to fill in this box? If so, what do I put in it? + + + + + + + + +English Usage Guidelines and Recommendations + +&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 +email instead of e-mail) to improve +consistency across all documentation. Work is underway to expand and +formalize this list, but for the moment, it is located at http://www.kde.me.uk/index.php?page=Consistency+rules. +There are also standard names for &tde; widgets, which are listed in + + +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. + +Some tips about writing readable sentences: + +Use complete sentences. Not fragments. Like these ones. + + +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. + + + +Use a comma before and in compound sentences, ⪚ +Use the left mouse button to select and copy text, and the +middle mouse button to paste it. + + +Keep to logical sentence order. +For example, &konqueror; is a web browser with the +ability to browse file systems and it includes a javascript +interpreter. (Do you see why this is awkward?) + + +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. + + +Do not start sentences with any of and, +so, but, because, or +however. + + +Try to avoid contractions, rather spell out both words; ⪚, +it is rather than it's; can +not rather than can't + + +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 XSLT +stylesheets in use. + + + + +Remember, we have also an active proofreading team, and there is +always someone to help you with grammar, so just +write and have fun! + + + + + +What to Include +For most applications, a structure something like this would be +appropriate: + + +Introduction: A basic description of what the application does and +any noteworthy features, &etc;. + + +Using KApp: Task-based description of +the most common uses of the application. + + +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. +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.) +Note that although this is a required section, and for some +applications it is the only section, it should be considered a +minimum. + + +Frequently Asked Questions: List the most common questions and +problems that users have with the application, and their +solutions. How do I ...?-type questions are especially +appropriate. + + +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. +This chapter is required for all &tde; documents, and must have +at least the two license links (one for the +document, and one for the application) + + +Installation: This chapter can be automatically generated, +provided that the application follows the usual &tde; compilation +procedure (&ie; ./configure, make && make +install). If you need to add extra information about compiling +or installing the application, it can go here. + + + + +You will find a template document with these sections in +trunk/KDE/kdelibs/kdoctools/template.docbook file in &tde; +&svn; repository. + + + + + +Writing Documentation: Procedures and Tools + +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 do have +some tools we use and procedures we follow, it's not vital that everyone +knows them in detail, especially when starting out. + +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. + +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. + +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;) + + + + +Getting the Documentation Sources + + +If you are starting your document from scratch, you probably do not +need to read this section, and may start working right now. + + + +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 +. + + +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. + +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 +repository. Each developer can download the files to make +their own private copy, named working copy or +sandbox. 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. + + +There are two main ways edit the contents of a &tde; document you +want to improve: using plain text or DocBook. + + + +Working with plain text sources + + +The docs.kde.org +website displays most of the &tde; documentation in &HTML; format, updated +daily from the &svn; repository. There are two versions available in the website: the +stable version and the +&tde; from &svn; version. +You will always use the latest version of the documentation, &ie; the +&tde; from &svn; version. + + +The docs.kde.org +website 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, +kde-doc-english@kde.org. 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. + + + +Now you know everything you need to start working. When you are +finished writing, you may want to read . Have fun! + + + + + +Retrieving the DocBook sources + + +The latest DocBook sources are located inside the &tde; repository. +Now you need to find and retrieve them. + + +The software inside the &tde; repository is divided into +modules, 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 packages. 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. + + + +To access the repository, you can use the svn command line application or browse the &tde; WebSVN website (websvn.kde.org). + + +The websvn.kde.org is a +web +based representation of the contents of the &svn; repository. It is easy +to download files using websvn.kde.org, +the operating system or desktop you use does not matter. + + + +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; the easiest way we can. +You can get more information about these tools (they are really useful) +by reading the . + + +Retrieving documentation sources using WebSVN + + +Go to http://websvn.kde.org +using your favorite web browser. Let's suppose you are looking for +&cervisia;'s documentation sources. + + + The &tde; repository is divided into trunk +(also known as HEAD, where development is going on, +branches, where both stable and working branches live, +and tags, where you can retrieve snapshots of sources at +a release. Most work for documentation goes on in trunk, +so click there. + +The main &tde; modules are in the TDE folder, +so click on that. + + + +Click the "trunk" link to get the main branch listing. Click on "TDE" +to get the list of modules from a &tde; release. + + + +&cervisia; is part of the tdesdk module (&tde; software +development kit module). Therefore, click the tdesdk item on the +list. The contents of the tdesdk module will be displayed. + + + Click the doc 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. + + +Select the application you want to work with from +the list (in our case, cervisia). All &cervisia;'s +documentation source files will be displayed, being images or DocBook files. + + + +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 +*.docbook. In this case, there is only +one file file in this format: index.docbook. Click this +file on the list. A list of revisions (versions) +of that file will be displayed. + + + +Click the download 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. + + + + +We use &kmail;'s documentation sources as example in the +following procedures. + + + +Retrieving documentation sources using &svn; + + +Check if you have the &svn; client installed (hint: enter svn in the +terminal screen). If not, install the &svn; package using the tools provided by +your distribution. + + + +Now it is time to download, or checkout the sources. +Using &svn;, type in the terminal: +mkdir path/to/working/folder +cd path/to/working/folder +svn checkout svn://anonsvn.kde.org/home/kde/trunk/KDE/module/doc/application + +where path/to/working/folder is the folder you want +to install the sources in your system, trunk/KDE/module is the +application's module location in the repository and application 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: +svn checkout svn://anonsvn.kde.org/home/kde/trunk/KDE/kdepim/doc/kmail + +Note that only applications which are part of a regular &tde; release are under +trunk/KDE/. Amarok 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 Amarok docs, type in the terminal: + +svn checkout svn://anonsvn.kde.org/home/kde/trunk/extragear/multimedia/doc/amarok + + + + + + + + + + +&quanta; + + +&quanta; is a friendly editor for SGML and &XML; +documents. &quanta; features syntax highlighting, autocompletion, autoclosing +and code folding for DocBook tags, easy access for the &tde; documentation +tools, &meinproc; and +&checkxml;. + + + +A screenshot of &quanta;'s main window + + +A screenshot of &quanta;'s main window +A screenshot of &quanta;'s main window + + + + +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. + + + + + + + +DocBook Toolbars + + +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 + +checkXML button from the +Tools toolbar: the output of the script will be displayed +in he Messages 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 + + +meinproc button on the same toolbar. + + + +Depending on the version of some XML utilities used by &quanta;, the + + +checkXML and + +meinproc 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 +meinproc script or there is no output when using the +checkXML script, you can get and install the +updated docbook +scripts from kde-files.org to solve these issues. + + + +A screenshot of &quanta;'s DocBook toolbar + + +A screenshot of &quanta;'s DocBook toolbar +A screenshot of &quanta;'s DocBook toolbar + + + + + + + + + + +Tag Editor + + +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 Value column of any attribute to edit it. + + + +A screenshot of &quanta;'s attribute editor sidebar + + +A screenshot of &quanta;'s attribute editor sidebar +A screenshot of &quanta;'s attribute editor sidebar + + + + + + + + + +Documentation Sidebar + + +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 +&tde; Doc +Primer documentation package. The documentation sidebar is on the right +side of the main window. + + + +A screenshot of &quanta;'s documentation sidebar + + +A screenshot of &quanta;'s documentation sidebar +A screenshot of &quanta;'s documentation sidebar, showing the +&tde; Doc Primer + + + + + + + + +Entities Autocompletion + + +&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: + + + +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. + + + +Generating and installing the <filename>entities.tag</filename> file + + +Open &quanta;. Choose the DTD +Load & Convert DTD menu item. + + + +Now, we have to select the right dtd file to convert. +On the dialog, select the &tde; installation folder (usually +/usr or +/opt/trinity. If you cannot find it, type +$tde-config --prefix +on a terminal application. The dtd file we want is named +kdex.dtd under +share/apps/ksgmltools2/customization/dtd/. +Select it and press OK. A new Document Type Editing +Package (DTEP) for kdex will be created. + + + +Now that you have converted the dtd, you can either use it directly, +by choosing the DTD +Change the DTD... and selecting the +kdex dtd. But the best solution is to install the +entities.tag file for automatic use with the &tde; +docbook dtds. + + +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 TDEHOME +folder, the folder that contains your &tde; settings and application data, +usually, ~/.trinity. If you cannot find it, type +$tde-config --localprefix +on a terminal application. The dtep folder is under +TDEHOME/share/apps/quanta/dtep. +The simplest way to do copy it is using a terminal application (⪚ &konsole;). + + + +Start a console application and enter the 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 + + +Restart &quanta;. + + + + + +A screenshot of &quanta;'s entities auto-completion feature + + +A screenshot of &quanta;'s entities auto-completion feature +A screenshot of &quanta;'s entities auto-completion feature + + + + + + + + +Document Structure + + +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. + + + +A screenshot of &quanta;'s document structure sidebar + + +A screenshot of &quanta;'s document structure sidebar +A screenshot of &quanta;'s document structure sidebar + + + + + + + + +&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. + + + + + +&kate; + + +&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;. + + + +Installing the XML plugin for &kate; + + +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. + + + +Open the Configure &kate; +dialog by choosing the +Settings +Configure &kate;... menu item. + + + +Select the Plugins item from the +Application tree. Check the &kate; XML +Completion and the &kate; XML Validation boxes. + + + +A screenshot of &kate;'s Plugin Manager Configure +Dialog + + +A screenshot of &kate;'s Plugin Manager Configure +Dialog +A screenshot of &kate;'s Plugin Manager Configure +Dialog + + + + + +Press OK. + + + + + +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 XML menu (in special, trough the +Validate XML menu item, which will allow you to +check your DocBook documents). The output of this action will appear in the +XML Checker Output button in the side bar located in +the lower part of &kate;'s main window. + + + +A screenshot of &kate;'s Main Window showing the XML Checker +Output + + +A screenshot of &kate;'s Main Window showing the XML Checker +Output +A screenshot of &kate;'s Main Window showing the XML Checker +Output + + + + + + + +Emacs and Psgml +The venerable &Emacs; editor has a powerful +SGML 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. + +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 .emacs file: + +(setq sgml-catalog-files + (list "CATALOG" "TDEDIR/share/apps/ksgmltools2/customization/catalog")) + +where you should replace TDEDIR 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 .docbook files: + +(setq auto-mode-alist + (cons '("\\.docbook$" . sgml-mode) auto-mode-alist)) + + + +There are of course plenty of other settings in psgml mode which +you can change to your taste: see the psgml info +documentation for more details. A sample .emacs +file, with some customizations useful for writing &tde; documentation, +can be found at http://people.fruitsalad.org/phil/kde/dot-emacs-psgml. + +Some basic keystrokes in psgml are: + + + + +&Ctrl;C +/ +End current element. This inserts an end tag for the +currently open element. + + + + +MetaTab + +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 Tab key. + + + + + +&Ctrl;C +&Ctrl;F +&Ctrl;E + +Fold current element. This compresses the current +element so that only the starting tag appears. One use of this is to +fold all the chapter 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 +&Ctrl;C +&Ctrl;U +&Ctrl;E +. + + + + + + +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): + +Local Variables: +sgml-parent-document:("index.docbook" "book" "chapter") +End: + +The first argument is the name of the parent file (which will almost +always be index.docbook in &tde; +documentation). The second argument is the top-level (or +root) element of the whole document (&ie;, in the parent +file). The third argument is the top-level element in this file. + + + + + + +Checking and Viewing the Documents +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: + + +Using &checkxml; + +&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. + + +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: + + + + +Opening and ending tag mismatch + + + +index.docbook:880: parser error : Opening and ending tag mismatch: para +line 879 and sect2 +</sect2> + ^ + + + +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: + + + +... +878: running &meinproc;, the same procedure applies. +879: &checkxml; is a simple command with +880: +...]]> + + + + + +The para tag on line 879 has +not been closed before the sect2 on +line 880, causing the error. The simple fix in this case is to add a para before the closing sect2. + + + + +Element does not follow the DTD + + + + +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> + ^ + + + +This error is caused by an element in the document not matching +the requirements of the DocBook DTD (Document Type +Definition). The DTD specifies what each element must +contain. This list is shown after expecting in +the error message. This so-called content model is quite +difficult to understand at first: refer to the Duck Book and the section +Understanding Content Models for full information. + +The text after got shows the content +actually found in the document. + +In the example above, we have a qandaentry +which is missing the required question element. This +was generated by the following input: + + + +An answer + + +]]> + + + + +Adding a question element before the +answer fixes the problem. + +An easy mistake to make is to forget to put a +para element around text in, for example, a +listitem or a +sectn. This will be shown +as CDATA in the got +section of the error. + + + + + + + +Using &meinproc; + +The most common way to run &meinproc; is simply as + +&meinproc; docbook-file where + +docbook-file is usually +index.docbook. 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 + +&meinproc; stylesheet-name docbook-file + + +where +stylesheet-name is the +full path to one of the &XSL; stylesheets in $TDEDIR/share/apps/ksgmltools/customization. +To produce output suitable for the web, you can use +tde-web.xsl or +tde-chunk-online.xsl. See the +README file in that directory for more details. + + + + + + + + + +DocBook Introduction + +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. + +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 +The TDE DocBook Markup Guide. + + +Overview +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: + + + + +paraTo display the clipboard history, click on the klipper icon + in the tde panel, or press keycombo +action="simul"CtrlAltkeycapVkeycapkeycombo. Previous +clipboard entries are shown + at the top of the pop-up menu which +appears.para + +The para and para show the start and end, respectively, of a +paragraph. These delimiting marks are called tags, and +the content they contain (along with the tags) is called an +element. The keycombo +tag has an extra piece of information specified: action="simul". This is called an +attribute, and makes the tag more specific. The words +surrounded by & and ; are entities. They're simply +variables that expand to some other text, and are widely used in &tde; +documentation. See for more +information about entities. Tags, entities, comments and other parts of +&XML; that aren't simple text are referred to as markup. + + + + +Content and Presentation + +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: + + +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. + + +All &tde; documentation has a similar look, so once readers are +familiar with conventions in one document, they're familiar with all documents. + + +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. + + + + +In practice, this means that you should add markup that describes +what things are and not how they should appear. So, +in the example above, the keycombo (a +keyboard shortcut) tells the reader (or computer) that the keys &Ctrl;, +&Alt; and V should be pressed simultaneously, but +doesn't say anything about how that should be displayed in the final +output. (In fact, it appears as &Ctrl;&Alt;V, but it +could equally be converted to C-M-V à la &Emacs; +or even some other way of showing keyboard shortcuts. What's important +is that the DocBook source has the information +necessary to work out what is being referred to.) + + + + + + + +Structure + (<book> <chapter> <sectn> +<para>) + + + +&tde; Specialities +TDE-isms: entities, necessary bits (credits, translation + stuff) + + +Entities +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: + +konqueror is, among other things, a +web browser. + + +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. + + + +There are entities defined for several classes of names: + + + +All &tde; applications + +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: tde. + + + + +Common English and technology abbreviations + +For example, &ie; is written as ie and ⪚ as eg. 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;, HTTP and XML for the previous examples). + + + + +Trademarks + +Names of companies and their products are often trademarked. For +this reason, it is important to mark them up with the +trademark tag, using the class="registered" 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 X-Window expands to &X-Window;. + + + + +Contributor Names + +Names of contributors to &tde; documentation have entities of the +form Firstname.Lastname (or +Firstname.Initial.Lastname). Email +addresses of contributors have entities of the form Firstname.Lastname.mail. + + + + +Names of special keys + +Names of keys on the keyboard are always marked up with either +keycap or keysym. Since it can be +difficult to distinguish between these two tags, entities have been +created for common keys, ⪚, Ctrl +and Alt. + + + + + + +The definitions of these entities can be found in the following +locations in &tde; 3: + + + +Items not requiring translation (&tde; application names, +technology abbreviations, trademarks) + +tdelibs/kdoctools/customization/entities/general.entities + + + + +Contributor names and email addresses + +tdelibs/kdoctools/customization/entities/contributor.entities + + + + +Language-specific terms and key names + +tdelibs/kdoctools/customization/en/user.entities + + + + + + + + + +Necessary Sections +There are several sections that appear in all &tde; DocBook files, +even though they are not required by DocBook itself: + + + + +<!ENTITY package "tde-module"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> + + +This appears in the prologue immediately after the +FPI. See prologue +for more details about this section. + + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +This appears after the authorgroup element, and is a required +placeholder for use in translation (also known as i18n +from the number of letters between the first and the last of the word internationalization). + + + + + + + + + + + +Sending the New Documents and Changes to &tde; + +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. + + +Respecting the Release Schedule +String freezes, when we write, etc + + +This needs reviewing by someone who pays more attention to +releases than I do. + + + +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: + +A schedule for the next release of &tde; is published at developer.kde.org, with the +definitive guide to what will be happening and when. There will be two +or more freezes, when changes of a certain type are not +allowed in the &tde; &svn; repository: + + +Feature Freeze + +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. + + + + +String Freeze + +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. + + + + + + + +Managing the Sources with &svn; + +You can find detailed information about how to use &svn; in conjunction +with &tde; in the +Managing &tde; Sources with Subversion guide + + + + + + +Working With Other Documenters and Developers + +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. + +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 kde-doc-english@kde.org mailing list and on +IRC in the fkde-docs channel on the server +irc.freenode.net. 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. + +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: kde-quality@kde.org. 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. + +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 +Help About +KApp menu item for +the maintainer. If you can't find a maintainer, ask on +kde-doc-english@kde.org or +kde-devel@kde.org. 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. + + + + +Updating Documentation + +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? + +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. + + + + +Licenses for &tde; Documentation + +&tde; uses the FDL (Free Documentation License) for +all documentation. This license has several variants, some of which place +restrictions on how content is used in other contexts. + +The specific terms we use are: + +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. + +This is the only version of the license that is safe to use for +documentation that is to be distributed with &tde;. + +The items that may differ in other uses of the FDL +are as follows: + + + +with no Invariant Sections + +Invariant sections are, as you might expect, sections that +must not 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. + +For instance, if you say Foo is a terrible piece of +software and the section is marked invariant, the developers of +Foo can not take your writing, change it to say Foo is +a great piece of software and still attribute that opinion to +you. + +For many people, this restriction is incompatible with the +GPL and therefore some distributions choose not to +include any user manuals that contain Invariant Sections. +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. + +For this reason, Invariant Sections 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. + +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 +Invariant Sections 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. + + + + +with Front-Cover Texts names of +sectionswith Back-Cover Texts names +of sections + +As with Invariant Sections, 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 +Invariant Sections. + +This one mainly comes up if we want to use FDL +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. + + + + + +The terms of the FDL as used by &tde; +documentation, are entirely GPL 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. + + + + + +Using bugs.kde.org +Note how we use b.k.o (general to-do items). Also point to Carlos' +guide on quality.k.o + +The &tde; bug tracking system, located at http://bugs.kde.org, is now part of +the documentation team's toolkit. Issues with the &tde; documentation +can be filed in the docs +product of the bug tracker. Incorrect or outdated content, missing +content, outdated screenshots and typos are all appropriate reasons to +file bugs. + +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. + +For more information on using the &tde; bug tracking system, see +http://quality.kde.org/develop/howto/howtobugs.php. + + + + + + +Leveraging your Newly Acquired Knowledge + + 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. + + + +Writing context help and configuration descriptions: the handbook +is not the only source of help available for &tde; applications. Context help, +or whatsthis 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. + + + + +Performing usability analysis and tests: 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. + + +Writing guides and articles about the application: 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;. + + + + + + + +Credits and License + + +&underFDL; + + + +Widget Names +Steal from (and extend) the Visual Guide to +&tde;. + + + + + + +&documentation.index; + + + -- cgit v1.2.1