Next Previous Contents

5. An introduction to linuxdoc-sgml

Linuxdoc-sgml is evolving with new features. Linuxconf use a subset of them so learning how to write help file is simple.

5.1 The heading

Each help file start with the following lines

        <!doctype linuxdoc system>
        <article>
        <title>Some title
        <author>Introduction
        

I use the author field to store the sub-title. Looks good. So you copy that and you change the title and subtitle.

5.2 The abstract

You may want to introduce the general idea about the topic in a short paragraph. You do this this way.

        <abstract>
         Linuxconf is great, yet some help files are missing. Here is
         your chance to be a hero.
        </abstract>
        

The abstract section is optional.

5.3 The sections

The keyword sect, sect1 sect2 etc... are used to start a section and provide its title. No need for a </sect> like HTML. You need to enter a

<p>
on the next line.

Further, sect sect1 sect2 must be properly match. You can't jump from a sect to a sect2 without a sect1 somewhere in the middle, unlike HTML which lets you put h1 h2 in any order. the sect verb really means a heading (section title).

Here is a short document

        <sect>what is Linuxconf
        <p>
                bla bla bla
        <sect1>When did it started ?
        <p>
                bla bla bla
        <sect1>Is it expected to end ?
        <p>
                bla bla bla
        <sect>Licensing
        <p>
                bla bla bla
        

5.4 Paragraphs

Paragraphs are implied by an empty line. No need to the

<p>
everywhere like in HTML.

5.5 Presentation controls

linuxdoc-sgml has few mechanism to control the look of some part of the document. This is somewhat limited. Remember that the goal is to produce documents readable on a text console and in HTML (linuxdoc-sgml can also translate to LaTeX, producing a very nice looking document).

Lists

Bullet lists

List are controlled by the itemize and item keywords. Here is an example.

        Linuxconf features are:

        <itemize>
        <item>Networking
        <item>DNS management
        </itemize>
        

Emphasis

The keyword em is used to high-lit some part of the document generally a word. You can use both the long and short form to quote something. For example

        <em/Linuxconf/ is <em>great</em>.
        

Typewriter (screen) fonts

The tscreen keyword force the selection of a non proportional fonts where it applies. You can use the short and long form. It is generally used (in Linuxconf help files at least) in combination with the verb keyword. See below.

Pre formatted text

The verb keyword is used to suppress the formating done by the various tools in linuxdoc-sgml. You use this either to disable the parsing of linuxdoc-sgml or to present Linux commands. For example, here is some C source code

        int main (int argc, char *argv[])
        {
            for (i=0; i<10; i++){
                printf ("hello\n");
            }
        }
        

Url

You can specify urls (www pointers) that will be effective in the HTML version of the help screen. This is done using the htmlurl command:

        <htmlurl
          url="http://server/path"
          name="text to present"
        >
        


Next Previous Contents