This is an SGML example file using the Linuxdoc DTD SGML. You can format it using the command % linuxdoc -B txt example.sgml this will produce a plain ASCII file. You can also produce files in various formats including LaTeX, HTML and GNU info with the commands in linuxdoc-tools.

The command name is ``linuxdoc''. It is ``-B'' option to choose the proper backend driver. Old command names are now obsoleted. Old (obsoleted) New (prefered) ------------------- ------------------ sgml2txt linuxdoc -B txt sgml2html linuxdoc -B html sgml2latex linuxdoc -B latex sgml2info linuxdoc -B info sgml2lyx linuxdoc -B lyx sgml2rtf linuxdoc -B rtf You can use ``linuxdoc -B latex'' to produce the tex, dvi, ps and pdf output.

You can also use ``linuxdoc -B check'' command to check the syntax of your document sources.

The linuxdoc-tool provides the general command &dquot;linuxdoc&dquot;, and you can use it with &dquot;--backend=format&dquot; option in order to access the facility of all the command above. Check the online manual of linuxdoc command.

Looking at the source for this file will be instructive to show you how to use many of the Linuxdoc-SGML constructs. You should also read the Some examples

Here are examples of things that you'll be using in the source. First, let's decend into a subsection: This is a subsection

As the header says. Note that you need to use the This is a subsubsection

Right. 5 levels of sections are available. Use the commands article document style, which is appropriate for HOWTOs and other docs; the report style (which includes the Example text

All right, so you're typing along, and you want to show some example code, or example I/O with a program, whatever. Use the This is an example verb environment. As well as: This is an example code environment. The Cross references

What about cross-references? This section has been marked with the label command; using ref will provide a cross reference, as in ``See Section '' for more.

Right now cross-references don't work in the Using fonts

You want fonts, we got fonts. Of course these won't show up in the plain ASCII text, but they all map into the various output formats: Lists

Lists are easy as well. Just use the This is a list. Nothing exciting about that. Multiple levels are supported as well. Again, that's no surprise. Enumerated lists using enum also work. Description environments using descrip along with tag are also available, as seen here. A final item to top it all off. Tables and Figures

The Linuxdoc DTD itself has the element definition for tables and figures which exists in the original QWERTZ DTD. They are not used widely because the Linuxdoc DTD is created for multiple outputs with the same contents. Tables can be used only in text, html, and latex formats. And figures can be used only in html and latex formats.

The usage of these tags without very strong reasons is not recommended. If you wish to enhance your documents, then it may be the time you should move up to the DocBook DTD. But if you think you have enough reasons to use graphics with Linuxdoc DTD for your documents, then it is your choice.

One more point. Please remember that text only documents can be listened by a blind person, while the heavy graphical documents can't.

Table

Here is an example of table. Check this in various output formats. Please take care in using this. There are several limitation. Each row can not be folded into multiple lines, and too long row will be corrupted in the output. The output in info, lyx, and rtf may not be correct at all. Anyway, you are warned. Be carefull. DTD |comments |tools @ Linuxdoc|What this document aimed at|linuxdoc-tools@ DocBook|Now the de facto standard|openjade, sgmltools-lite@ QWERTZ|The origin of Linuxdoc|sgml2latex-format

Comparison on Some DTD

Figure

In html and latex output, the graphics can be included with the figure element. It is not encouraged to use this feature since the LinuxDoc DTD is created for fairiy simple and light way of producing the multiple output formats with the same content. Using graphics only in some outputs will spoil the value of a simple plain text output in many cases. And heavy usage of huge graphics files was just a pain when the network (and the machine) was too slow. But when you only need the versions in html and latex format, and if you don't need to concern the network speed, then you can use this.

Here is an example to use the figure in html or tex (tex, dvi, and ps). This example uses the (unofficial) logo of Linux kernel 2.0, which was created by Larry Ewing with the GIMP. Check his site: I use &dquot;convert&dquot; command from ImageMagic and ghostscript to get the png and eps files from the original GIF.

You should put all the graphic files into the same directory as the SGML source file. For html and pdf, use img element with png or jpeg graphic file. For other latex (tex, dvi, and ps), use eps element with ps or eps graphic file.

The Penguin Logo of the Linux

Summary

This is just about everything that you need to get started with writing SGML docs using the SGML world

SGML is an ISO standard (ISO 8879:1986) for information processing. You can read some introduction of SGML related to HTML from . SGML provides the scheme to express the logical structure of a document (such as chapter, section, subsection, and so on.) and it call a piece of document as an element. When we write a document in SGML, we need the specification of structure of the document. This specification is called DTD (abbreviated from &dquot;Document Type Definition&dquot;), and this DTD defines the relation of various elements in the specific type of documents.

This document uses the word Linuxdoc DTD without explanation so far. Here is the meaning of &dquot;DTD&dquot;. We can't write any document in SGML without an appropriate DTD.

You should also note that Linuxdoc DTD is created as a simple and easy introduction for SGML world. Matt Welsh (the original author of the Linuxdoc DTD and the tool for it) wrote in his guide: If you'd like to write general documentation in SGML, I suggest using the original QWERTZ DTD instead of the hacked-up linuxdoc DTD, which I've modified for use particularly by the Linux HOWTOs and other such documentation.

Now the DocBook DTD, which is maintained by OASIS, has been around for a while, and is very popular for technical documentation. Moreover, it uses DSSSL, which is an ISO standard for doing rendering. In the future this might move to and XML DTD and using XSL instead of DSSSL, but that doesn't matter to the author. See the following URLs for more info:

You should use the DocBook DTD if you are serious to be a writer in the technical documentation world. The Linuxdoc DTD is intended as an easy introduction, and is considered now as the work-around to help many useful documents until they can be converted into the DocBook based.