2006-5-24
| Revision History | ||
|---|---|---|
| Revision 1.0 | 2006-5-24 | Revised by: dsl |
| first official release | ||
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.
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.
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.
Feedback is most certainly welcome for this document. Send
your additions, comments and criticisms to the following
email address : <daniel.sangorrin@unican.es>.
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.
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:
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.
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).
Install Docbook-XML (see Section 3)
Download the LDP's DSSL ldp.dsl and copy it to the working directory.
Download the MaRTE OS template HOWTO.xml and copy it to the same directory.
Modify the template with an editor and the help of [1].
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 |
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:
Editing of big files
Extensible syntax highlighting
Folding
Dynamic word wrap
Selectable encoding
Filter command
Global grep dialog
Install kate and kate-plugins (or kde-addons).
Open your XML file.
Enable the Kate XML Completion plugin-in at ->
A new menu, titled XML, will show up. Select -> and choose /usr/share/apps/katexmltools/kde-docbook.dtd.xml
Docbook: The definitive Guide http://www.docbook.org/tdg/en/html/docbook.html
The Linux Documentation Project http://www.tldp.org