The &kde; Documentation Team'> meinproc"> checkXML"> Subversion"> ]> &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 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. 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. 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. 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. &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. 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. 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. 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? &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! 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. 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;) 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. 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! 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 . 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. 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; 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. 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; 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;. 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 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. 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: &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. 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 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. 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. 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. 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.) (<book> <chapter> <sectn> <para>) TDE-isms: entities, necessary bits (credits, translation stuff) 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 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). 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. 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. You can find detailed information about how to use &svn; in conjunction with &tde; in the Managing &tde; Sources with Subversion guide 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. 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. &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. 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. 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;. &underFDL; Steal from (and extend) the Visual Guide to &tde;. &documentation.index;