HOWTO Write Tutorials for MaRTE OS

Daniel Sangorrin

2006-5-24

Revision History
Revision 1.02006-5-24Revised by: dsl
first official release

This document describes how to write tutorials for MaRTE OS.


Table of Contents
1. Preface
1.1. Copyright and License
1.2. Disclaimer
1.3. Feedback
2. Introduction to Docbook-XML
3. Install Docbook-XML
4. A tutorial for MaRTE OS step-by-step
5. Editors: Kate
5.1. How to use Kate for Docbook editing
6. Troubleshooting
7. Further Information

1. Preface

In this document we describe how to write tutorials for MaRTE OS. The objective is to write consistent documentation that can be presented in various formats like HTML, TXT, PDF or PS, and to be able to focus on the topic and not on the format options.


1.1. Copyright and License

This document, HOWTO Write Tutorials for MaRTE OS, is copyrighted (c) 2006 by Daniel Sangorrin. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 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. A copy of the license is available at http://www.gnu.org/copyleft/fdl.html.

Linux is a registered trademark of Linus Torvalds.


1.2. Disclaimer

No liability for the contents of this document can be accepted. Use the concepts, examples and information at your own risk. There may be errors and inaccuracies, that could be damaging to your system. Proceed with caution, and although this is highly unlikely, the author(s) do not take any responsibility.

All copyrights are held by their by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark. Naming of particular products or brands should not be seen as endorsements.


1.3. Feedback

Feedback is most certainly welcome for this document. Send your additions, comments and criticisms to the following email address : .


2. Introduction to Docbook-XML

MaRTE OS tutorials try to follow the Linux Documentation Project (LDP) guidelines. We use an useful mark-up language for software documents called Docbook. Docbook is similar to HTML, but it has its own tags. For example, there is a tag for listing code, etc. You can get a complete list of usable tags from [1]. The Docbook language has been defined by two meta-languages (SGML and XML). We prefer, as LDP, the XML flavour. The language is defined in a file called DTD (Document Type Definition). See http://docbook.org/xml/4.2/docbookx.dtd

By now, we could write a file example.xml using the docbook tags and check if our file conform to DTD rules. But apart from this we don't have anything, just a mix of tags and text. We need another file for mapping those tags into HTML, TXT, PDF, etc. There are two alternatives for that: DSSSL and XLS. We prefer to use DSSSL (Document Style Semantics and Specification Language).

To sum up, we are going to create Tutorials using a Mark-up language called Docbook-XML. You can look up the tags of the language in [1]. Once you have your tutorial in a file (i.e. example.xml) you will need to apply a script in order to convert that file into HTML, TXT, PDF... with some style.


3. Install Docbook-XML

The procedure for installing depends on your Linux flavour. In Debian-based distributions like Ubuntu you can use the tool apt or its front-end synaptics. In Red-Hat based distributions you may want to use the tool yum.

Install the following software and its dependencies:

docbook-xml

This package contains the XML DTD for DocBook, which describes the formal structure for documents following this format. DocBook is an XML document type definition (DTD). That is, it contains the "DocBook" document structure. This is used by authors or editors writing documents in the DocBook XML format. DocBook was designed for books, articles, or reference documentation about technical matters or software. It has emerged as an open, standard DTD in the software industry, and is the documentation system of choice for many free software projects.

docbook-utils

The docbook-utils is a set of a few small programs intended to ease everyday use of technical documentation software and more generally use of SGML and XML. We will use it to convert Docbook files to other formats (HTML, RTF, Postscript, PDF).


4. A tutorial for MaRTE OS step-by-step

  1. Install Docbook-XML (see Section 3)

  2. Download the LDP's DSSL ldp.dsl and copy it to the working directory.

  3. Download the MaRTE OS template HOWTO.xml and copy it to the same directory.

  4. Modify the template with an editor and the help of [1].

  5. Apply one of the following commands to convert your tutorial to other format.

    [user@machine ~/dir]$ docbook2html -u -d ldp.dsl#html yourfile.xml
    [user@machine ~/dir]$ docbook2html -d ldp.dsl#html yourfile.xml
    [user@machine ~/dir]$ docbook2txt -d ldp.dsl#html yourfile.xml
    [user@machine ~/dir]$ docbook2pdf -d ldp.dsl#print yourfile.xml
    [user@machine ~/dir]$ docbook2ps -d ldp.dsl#print yourfile.xml


5. Editors: Kate

Kate (KDE Advanced Text Editor) is my favourite editor for programming in any language. It is a multi-view editor that lets you view several instances of the same document with all instances being synced, or view more files at the same time for easy reference or simultaneous editing. The terminal emulation and sidebar are docked windows that can be plugged out of the main window, or replaced therein according to your preference.

Some random features:

It comes with an interesting plug-in for editing XML documents, Docbook included. This plug-in enables you to auto-complete each tag and properties when writing the code. A very useful feature when there are lots of tags that you can't remeber.


5.1. How to use Kate for Docbook editing

  1. Install kate and kate-plugins (or kde-addons).

  2. Open your XML file.

  3. Enable the Kate XML Completion plugin-in at Settings->Configure Kate

  4. A new menu, titled XML, will show up. Select XML->Assign Meta DTD and choose /usr/share/apps/katexmltools/kde-docbook.dtd.xml


6. Troubleshooting

6.1. docbook2text doesn't work well

6.1. docbook2text doesn't work well

Make sure lynx is already installed.


7. Further Information

  1. Docbook: The definitive Guide http://www.docbook.org/tdg/en/html/docbook.html

  2. The Linux Documentation Project http://www.tldp.org