Introduction

NewbieDoc Docbook Guide
Prev		Next

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 that they try and concern themselves with formatting. Where with HTML you are often forced to manipulate tables or other elements to make the page look just the way you want, SGML is content based and cannot be manipulated this way. When writing SGML documents, formatting should be the last thing on your mind. Concentrate on writing a clear and concise document, because you can never predict the final output. The best you can do, and what is expected of all NewbieDoc authors, is to pay close attention to the formatting you are using, making sure that you always use the appropriate elements. The SGML parser will then take care of all the formatting.

If you can write HTML documents, then you can write SGML documents. In fact, HTML was designed as a small, web browser-focused version of SGML. If you haven't ever written an HTML document, you can still write SGML. 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, as explained above. 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. 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

There are currently three versions of the DocBook guide available on the DocBook site. Version 2.0.4 is the most current edition, as well as the most well-written. However, that book describes DocBook V4.2, which is not exactly the same as the version we use, LinuxDoc (DocBook V3.1). The 2.0.3 version of the book covers DocBook V4.1.2, which is almost exactly the same as V4.2, though it's not as detailed. Finally, Version 1.0.3 covers DocBook V3.1/LinuxDoc, but, again, is less detailed than the others.

Our suggestion is to use the latest version of the book, even if it applies to a newer version. Anything describing something that was a part of V3.1 will still work, but be aware that there are some new additions that may not work as expected.

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: <newbiedoc-discuss@lists.sourceforge.net>. 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 to 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.