1. Introduction

1.1. Why sgml?

We chose to use sgml because of its inherent benefits. With sgml we can write one source document and render it to many formats.

One of the pitfalls many people fall into when writing sgml is they try and concern themselves with formatting. Sgml is content based. It does not worry about formatting. When writing sgml documents, formatting should be the last thing on your mind. Concentrate on writing a clear and concise document. The sgml parser will take care of the formatting.

If you can write html documents you can write sgml documents. If you can't or haven't written html documents you can still write sgml documents. For some people, it's actually harder to transfer writing skills developed for html than it is to learn sgml from scratch. Writing sgml requires a different philosophy than writing html. Quit worrying about formatting, that will come later!!

1.2. What you need to install

1.2.1. sgmltools-2

The package you need to install is sgmltools-2. This will give you a complete, working sgml parser. At the command line do (as root):

bash# apt-get install sgmltools-2

To use sgmltools-2 simply do this at the command line (as a regular user):

bash$ sgmltools -b html name-of-sgml-file.sgml

You should execute the command exactly as you see above, substituting the name of your sgml file for name-of-sgml-file.sgml. This will create a subdirectory called name-of-sgml-file with your sgml file rendered as an html document inside it. (For the rest of the document I will use the term "build", "parse", or "render" to refer to running your file through the sgmltools) As you are going through this tutorial feel free to cut and paste the examples into your favorite text editor. Then, simply save the file with any name you choose with an extension of .sgml. Then practice running your sgml parser on the file and then look at the html file you created with your favorite browser. If you need more help on the options for sgmltools simply type:

bash$ sgmltools --help

1.2.2. sgmltools-lite

Sgmltools-lite is the replacement to sgmltools-2 but is only apt-gettable in unstable. Luckily, I came upon a version for potato. It can be downloaded from here. I recommend you install sgmltools-2 first using the instructions in sgmltools-2, and then use dpkg to upgrade the package. Since it's not apt-gettable you'll have to install/upgrade it like this (as root):

bash# dpkg -i sgmltools-lite_3.0.2.3.cvs0-0potato2_all.deb

As with all things Debian, upgrades rarely change the way you do things. Sgmltools-lite uses the same command and options (almost) as sgmltools-2. Here's how you would use sgmltools-lite to render your sgml file as html:

bash$ sgmltools -b html -s howtoh name-of-sgml-file.sgml

And for print based documents do this:

bash$ sgmltools -b html -s howtop name-of-sgml-file.sgml

1.2.3. Other tools?

Someone please add other tools here.

1.2.4. Docbook: The definitive guide

Once you have mastered this document you will need this reference (it will probably help even before that!). You can browse this book online at http://www.docbook.org/tdg/html/docbook.html or you can download it at http://www.docbook.org/tdg/index.html If you do download it get the ZIP archive that is the same as the online version. This file will be called html.zip and when you unzip it it will put everything in a directory called html. Also, pay attention to their note that the root page is docbook.html, not index.html. You will need the program unzip to unzip it. This program is non-free so make sure you have the appropriate lines in your /etc/apt/sources.list file. At the command line do (the first command as root, the second as any user):

bash# apt-get install unzip

Then do:

bash$ unzip html.zip

1.3. Using the custom stylesheets

If you installed sgmltools-2 you should already have a working system to render sgml documents into the format you choose. So this section is a little bit ahead of itself. If you wish, you can easily skip to the next section and continue on, coming back later when want your documents to be formatted in the same manner as this one.

In order to format your documents in the same manner as this one you should use the newbiedoc custom stylesheets. The stylesheets are called newbiedoc-html.dsl, newbiedoc-onehtml.dsl, and newbiedoc-pdf.dsl. You can download them from newbiedoc cvs or you can post to: . Someone on the mailing list should be able to get you a copy. Once you get the custom stylesheets, save the stylesheets in the same directory as the sgml file you wish to parse. Here's the formal usage of sgmltools:

sgmltools {-b {html | onehtml | pdf | ps}} [-s | stylesheet] {sgml-file}

If you don't understand the above syntax don't worry about it. I'll be giving specific examples of how to use the stylesheets in the following sections.

1.3.1. newbiedoc-html.dsl

Here's how you use the custom stylesheet for html using sgmltools-2:

bash$ sgmltools -b html -s newbiedoc-html.dsl name-of-sgml-file.sgml

You should execute the command exactly as you see above, substituting the name of your sgml file for name-of-sgml-file.sgml. This will create a subdirectory called name-of-sgml-file with your sgml file rendered as multiple html documents inside it. The sgml document is split into seperate html files at each <sect1> tag.

1.3.2. newbiedoc-onehtml.dsl

This stylesheet as the name implies creates one single html file as its output. Here's how you use the custom stylesheet for onehtml using sgmltools-2:

bash$ sgmltools -b onehtml -s newbiedoc-onehtml.dsl name-of-sgml-file.sgml

You should execute the command exactly as you see above, substituting the name of your sgml file for name-of-sgml-file.sgml. This will create a single html file called name-of-sgml-file.html.

1.3.3. newbiedoc-pdf.dsl

Here's how you use the pdf stylesheet:

bash$ sgmltools -b pdf -s newbiedoc-pdf.dsl name-of-sgml-file.sgml

Again, you should execute the command exactly as you see above, substituting the name of your sgml file for name-of-sgml-file.sgml. This will create a file called name-of-sgml-file.pdf.