Linuxdoc-SGML User's Guide by Matt Welsh. Updated by Greg Hankins, ggrreegg..hhaannkkiinnss@@cccc..ggaatteecchh..eedduu v1.5, 8 March 1996 This document is a user's guide to the Linuxdoc-SGML formatting sys- tem, a SGML-based system which allows you to produce a variety of out- put formats. You can create plain text output (ASCII and ISO-8859-1), DVI, PostScript, HTML, GNU info, LyX, and RTF output from a single SGML source file. This guide documents Linuxdoc-SGML version 1.5. ______________________________________________________________________ Table of Contents: 1. Introduction 1.1. About This Document 1.2. Why SGML? 1.3. How It Works 2. Installation 2.1. Installing The Software 2.2. Formatting SGML Documents 2.2.1. Creating Plain Text Output 2.2.2. Creating LaTeX, DVI or PostScript Output 2.2.3. Creating HTML Output 2.2.4. Creating GNU Info Output 2.2.5. Creating LyX Output 2.2.6. Creating RTF Output 2.2.7. Checking SGML Syntax 2.3. ISO 8859-1 Character Set 3. Writing Documents With Linuxdoc-SGML 3.1. Basic Concepts 3.2. Special Characters 3.3. Verbatim and Code Environments 3.4. Overall Document Structure 3.4.1. The Preamble 3.4.2. Sectioning And Paragraphs 3.4.3. Ending The Document 3.5. Cross-References 3.6. Fonts 3.7. Lists 3.8. Further Information ______________________________________________________________________ 11.. IInnttrroodduuccttiioonn This is a user's guide to the Linuxdoc-SGML document processing system, for use with Linux documentation. Linuxdoc-SGML is a SGML DTD (Document Type Definition) and set of ``replacement files'' which convert the SGML to groff, LaTeX, HTML, GNU info, LyX, and RTF source. Linuxdoc-SGML is based heavily on the QWERTZ DTD by Tom Gordon, tthhoommaass..ggoorrddoonn@@ggmmdd..ddee. I have only made revisions to his DTD and replacement files for use with Linux documentation. Linuxdoc-SGML is not meant to be a general document-processing system. Although it can be used for documents of many types, I have tailored it for use by the Linux documenters in producing HOWTOs, FAQs, and (later) the Linux Documentation Project manuals. Therefore, I have tweaked features into and out of the system for this purpose. If you see a lack of generality in the system, that is the reason. However, there's nothing binding Linuxdoc-SGML to Linux documentation, but all documents produced by the system will look a certain way. If you want things to look differently I suggest that you use a more generalized system such as the plain QWERTZ DTD, in combination with the Linuxdoc- SGML tools. One of the goals of this system is to make documents easy to produce in numerous formats. Until now, most Linux documentation has been produced in plain text through manual editing. A system like groff can take care of the plain text formatting, but that still doesn't give you HTML (for use on the World Wide Web), LaTeX (for nicely printed documents), or other various output formats. Therefore, if there are features missing from this system that you would like, _p_l_e_a_s_e _l_e_t _m_e _k_n_o_w_! The idea is that we shouldn't have to use a lot of hackery to produce good-looking documentss in multiple formats. The author should have to do as little as possible. 11..11.. AAbboouutt TThhiiss DDooccuummeenntt This document is written using the Linuxdoc-SGML DTD. It contains more or less everything you need to know to write SGML documents with this DTD. See eexxaammppllee..ssggmmll for an example of an SGML document that you can use as a model for your own documents. 11..22.. WWhhyy SSGGMMLL?? I chose SGML for this system because SGML is made specifically for translation to other formats. SGML, which stands for Standard Generalized Markup Language, allows you to specify the _s_t_r_u_c_t_u_r_e of a document---that is, what kinds of things make up the document. You specify the structure of a document with a DTD (Document Type Definition). Linuxdoc-SGML is one DTD that specifies the structure for Linux HOWTOs and other documents. QWERTZ is another DTD; the SGML standard provides DTD's for books, articles, and other generic document types. The DTD specifies the names of ``elements'' within the document. An element is just a bit of structure---like a section, a subsection, a paragraph, or even something smaller like _e_m_p_h_a_s_i_z_e_d _t_e_x_t. Unlike LaTeX, however, these elements are not in any way intrinsic to SGML itself. The Linuxdoc-SGML DTD happens to define elements that look a lot like their LaTeX counterparts---you have sections, subsections, verbatim ``environments'', and so forth. However, using SGML you can define any kind of structure for the document that you like. In a way, SGML is like low-level TeX, while the Linuxdoc-SGML DTD is like LaTeX. Don't be confused by this analogy. SGML is _n_o_t a text-formatting system. There is no ``SGML formatter'' per se. SGML source is _o_n_l_y converted to other formats for processing. Furthermore, SGML itself is used only to specify the document structure. There are no text- formatting facilities or ``macros'' intrinsic to SGML itself. All of those things are defined within the DTD. You can't use SGML without a DTD---a DTD defines what SGML does. 11..33.. HHooww IItt WWoorrkkss Here's how processing a document with SGML and the Linuxdoc-SGML DTD works. First, you need a DTD. I'm using the QWERTZ DTD which was produced, originally, by a group of people who needed a LaTeX-like DTD. I've modified the QWERTZ DTD to produce the Linuxdoc-SGML DTD for our purposes. The DTD simply sets up the structure of the document. A small portion of it looks like this: This part sets up the overall structure for an ``article'', which is like a ``documentstyle'' within LaTeX. The article consists of a titlepage (ttiittlleeppaagg), an optional header (hheeaaddeerr), an optional table of contents (ttoocc), optional lists of figures (llooff) and tables (lloott), any number of paragraphs (pp), any number of top-level sections (sseecctt), optional appendices (aappppeennddiixx), an optional bibliography (bbiibblliioo) and footnotes (ffoooottnnoottee). As you can see, the DTD doesn't say anything about how the document should be formatted or what it should look like. It just defines what parts make up the document. Elsewhere in the DTD the structure of the ttiittlleeppaagg, hheeaaddeerr, sseecctt, and other elements are defined. You don't need to know anything about the syntax of the DTD in order to write documents. I'm just presenting it so you know what it looks like and what it does. You _d_o need to be familiar with the document _s_t_r_u_c_t_u_r_e that the DTD defines. If not, you might violate the structure when attempting to write a document, and be very confused about the resulting error messages. We'll describe the structure of Linuxdoc-SGML documents in detail later. The next step is to write a document using the structure defined by the DTD. Again, the Linuxdoc-SGML DTD makes documents look a lot like LaTeX---it's very easy to follow. In SGML jargon a single document written using a particular DTD is known as an ``instance'' of that DTD. In order to translate the SGML source into another format (such as LaTeX or groff) for processing, the SGML source (the document that you wrote) is _p_a_r_s_e_d along with the DTD by (you guessed it) the SGML _p_a_r_s_e_r. I'm using the ssggmmllss parser by James Clark, jjjjcc@@jjccllaarrkk..ccoomm, who also happens to be the author of ggrrooffff. We're in good hands. The parser (ssggmmllss) simply picks through your document and verifies that it follows the structure set forth by the DTD. It also spits out a more explicit form of your document, with all ``macros'' and elements expanded, which is understood by ssggmmllssaasspp, the next part of the process. ssggmmllssaasspp is responsible for converting the output of ssggmmllss to another format (such as LaTeX). It does this using _r_e_p_l_a_c_e_m_e_n_t _f_i_l_e_s, which describe how to convert elements in the original SGML document into corresponding source in the ``target'' format (such as LaTeX or groff). For example, part of the replacement file for LaTeX looks like: + "\\begin{itemize} + + "\\end{itemize} + Which says that whenever you begin an iitteemmiizzee element in the SGML source, it should be replaced with \begin{itemize} in the LaTeX source. (As I said, elements in the Linuxdoc-SGML DTD are very similar to their LaTeX counterparts). So, to convert the SGML to another format, all you have to do is write a new replacement file for that format that gives the appropriate analogies to the SGML elements in that new format. In practice, it's not that simple---for example, if you're trying to convert to a format that isn't structured at all like your DTD, you're going to have trouble. In any case, it's much easier to do than writing individual parsers and translators for many kinds of output formats; SGML provides a generalized system for converting one source to many formats. Once ssggmmllssaasspp has completed its work, you have LaTeX source which corresponds to your original SGML document, which you can format using LaTeX as you normally would. Later in this document I'll give examples and show the commands used to do the translation and formatting. You can do this all on one command line. But first, I should describe how to install and configure the software. 22.. IInnssttaallllaattiioonn Get lliinnuuxxddoocc--ssggmmll--11..55..ttaarr..ggzz from one of the following ftp sites: +o ffttpp::////ssuunnssiittee..uunncc..eedduu//ppuubb//LLiinnuuxx//uuttiillss//tteexxtt//lliinnuuxxddoocc--ssggmmll--11..55..ttaarr..ggzz +o ffttpp::////ttssxx--1111..mmiitt..eedduu//ppuubb//lliinnuuxx//ddooccss//lliinnuuxxddoocc--ssggmmll--11..55..ttaarr..ggzz +o ffttpp::////ffttpp..cccc..ggaatteecchh..eedduu//ppuubb//ppeeooppllee//ggrreegghh//lliinnuuxxddoocc--ssggmmll//lliinnuuxxddoocc-- ssggmmll--11..55..ttaarr..ggzz Uptodate patches to version 1.5 can be found at ffttpp::////ffttpp..cccc..ggaatteecchh..eedduu//ppuubb//ppeeooppllee//ggrreegghh//lliinnuuxxddoocc--ssggmmll. You can also get uptodate information from the LLiinnuuxxddoocc--SSGGMMLL WWWWWW PPaaggee <. The file lliinnuuxxddoocc--ssggmmll--11..55..ttaarr..ggzz contains everything that you need to write SGML documents and convert them to groff, LaTeX, HTML, GNU info, LyX, and RTF. In addition to this package, you will need the following tools - these are not required by the SGML system, but I suggest that you get them in order to format your documents and verify that they look all right before distributing them. 1. ggrrooffff. You _n_e_e_d version 1.08 or 1.09. Apparently some of the margin-handling in ggrrooffff is in a state of flux from version to version; they both work, but you get slightly different results (particularly, with 1.09 the left margin isn't indented two characters as it is in 1.08. There is a way around it, but it looks terrible on 1.08). Versions previous to 1.08 _w_i_l_l _n_o_t _w_o_r_k. You can get this from ffttpp::////pprreepp..aaii..mmiitt..eedduu//ppuubb//ggnnuu. There is a Linux binary version on ffttpp::////ssuunnssiittee..uunncc..eedduu//ppuubb//LLiinnuuxx//uuttiillss//tteexxtt as well. You will need ggrrooffff to produce plain text from your SGML documents. nnrrooffff will _n_o_t work! 2. TeX and LaTeX. This is available more or less everywhere; you should have no problem getting it and installing it (there is a Linux binary distribution on ssuunnssiittee..uunncc..eedduu). Of course, you only need TeX/LaTeX if you want to format your SGML documents with LaTeX. So, installing TeX/LaTeX is optional. 3. If you want to view the generated HTML, I suggest getting NCSA Mosaic 2.6 or later, available on ffttpp::////ssuunnssiittee..uunncc..eedduu//ppuubb//LLiinnuuxx//ssyysstteemm//NNeettwwoorrkk//iinnffoo--ssyysstteemmss. 4. ggaawwkk and the GNU info tools, for formatting and viewing info files. These are also available on ffttpp::////pprreepp..aaii..mmiitt..eedduu//ppuubb//ggnnuu, or on ffttpp::////ssuunnssiittee..uunncc..eedduu//ppuubb//LLiinnuuxx//uuttiillss//tteexxtt (for ggaawwkk) and ffttpp::////ssuunnssiittee..uunncc..eedduu//ppuubb//LLiinnuuxx//ssyysstteemm//MMaannuuaall--ppaaggeerrss (for GNU info tools). aawwkk will not work without hacking. 5. LyX (a quasi-WYSIWYG interface to LaTeX, with SGML layouts), is available on ffttpp::////ffttpp..vviiaa..eeccpp..ffrr. 22..11.. IInnssttaalllliinngg TThhee SSooffttwwaarree The steps needed to install and configure the lliinnuuxxddoocc--ssggmmll stuff are as follows: 1. First, unpack the tar file lliinnuuxxddoocc--ssggmmll--11..55..ttaarr..ggzz somewhere. This will create the directory lliinnuuxxddoocc--ssggmmll--11..55. It doesn't matter where you unpack this file; just don't move things around within the lliinnuuxxddoocc--ssggmmll--11..55 directory. 2. Read the IINNSSTTAALLLL file - it has detailed installation instructions. If all went well, you should be ready to use the system. 22..22.. FFoorrmmaattttiinngg SSGGMMLL DDooccuummeennttss Let's say you have the SGML document ffoooo..ssggmmll, which you want to format. Here is a general overview of formatting the document for different output. For a complete list of options, consult the man pages. 22..22..11.. CCrreeaattiinngg PPllaaiinn TTeexxtt OOuuttppuutt If you want to produce plain text, use the command: % sgml2txt foo.sgml Note that I have tailored the groff conversion for plain text output. That is, I've removed page headers, page numbers, changed the margins, and so on. With some hacking you can produce PostScript and DVI from the groff output, but I suggest that you use LaTeX for that instead. You can also create groff source for man pages, which can be formatted with ggrrooffff --mmaann. To do this, do the following: % sgml2txt -man foo.sgml 22..22..22.. CCrreeaattiinngg LLaaTTeeXX,, DDVVII oorr PPoossttSSccrriipptt OOuuttppuutt To create a LaTeX documents from the SGML source file, simply run: % sgml2latex foo.sgml If you want to produce PostScript output (via ddvviippss), use the --pp option: % sgml2latex -p foo.sgml Or, you can produce a DVI file using the --dd switch, as so: % sgml2latex -d foo.sgml 22..22..33.. CCrreeaattiinngg HHTTMMLL OOuuttppuutt If you want to produce HTML output, do this: % sgml2html -img foo.sgml This will produce ffoooo..hhttmmll, as well as ffoooo--11..hhttmmll, ffoooo--22..hhttmmll, and so on---one file for each section of the document. Run your WWW browser on ffoooo..hhttmmll, which is the top level file. Also make sure that all of the HTML files corresponding to your document are in one directory, as they reference each other with local URLs. The icons referenced in the HTML output are located in $$LLIINNUUXXDDOOCCLLIIBB//iiccoonnss. These will also need to be copied to the final location of the HTML documents. $$LLIINNUUXXDDOOCCLLIIBB is defined at the beginning of the SGML conversion scripts. If you use ssggmmll22hhttmmll without the --iimmgg flag, HTML documents will have the labels ``Previous'', ``Next'', and ``Table of Contents'' for navigation. You can override these defaults by creating a file in $$LLIINNUUXXDDOOCCLLIIBB//rreepp//hhttmmll//<>, and substituting your own words for different languages. The file has the following format: PrevPage: newvalue NextPage: newvalue TOC: newvalue See ddeeuuttsscchh for an example. 22..22..44.. CCrreeaattiinngg GGNNUU IInnffoo OOuuttppuutt If you want to format your file for the GNU info browser, just run the following command: % sgml2info foo.sgml 22..22..55.. CCrreeaattiinngg LLyyXX OOuuttppuutt For LyX output, use the the command: % sgml2lyx foo.sgml 22..22..66.. CCrreeaattiinngg RRTTFF OOuuttppuutt If you want to produce RTF output, run the command: % sgml2rtf foo.sgml This will produce ffoooo..rrttff, as well as ffoooo--11..rrttff, ffoooo--22..rrttff, and so on---one file for each section of the document. 22..22..77.. CChheecckkiinngg SSGGMMLL SSyynnttaaxx If you just want to capture your errors from the SGML conversion, use the ssggmmllcchheecckk script. For example. % sgmlcheck foo.sgml 22..33.. IISSOO 88885599--11 CChhaarraacctteerr SSeett The ISO 8859-1 (latin1) character set may be used for international characters in plain text, LaTeX, HTML, LyX, and RTF output (GNU info support for ISO 8859-1 may be possible in the future). To use this feature, give the formatting scripts the --ll flag, for example: % sgml2txt -l foo.sgml You also can use ISO 8859-1 characters in the SGML source, they will automatically be translated to the proper escape codes for the corre- sponding output format. 33.. WWrriittiinngg DDooccuummeennttss WWiitthh LLiinnuuxxddoocc--SSGGMMLL For the most part, writing documents using the Linuxdoc-SGML DTD is very simple, and somewhat like LaTeX. However, there are some caveats to watch out for. In this section I'll give an introduction on writing SGML documents. See the file eexxaammppllee..ssggmmll for a SGML example document (and tutorial) which you can use as a model when writing your own documents. Here I'm just going to discuss the various features of SGML, but the source is not very readable as an example. Instead, print out the source (as well as the formatted output) for eexxaammppllee..ssggmmll so you have a real live case to refer to. 33..11.. BBaassiicc CCoonncceeppttss Looking at the source of the example document, you'll notice right off that there are a number of ``tags'' marked within angle brackets (<< and >>). A tag simply specifies the beginning or end of an element, where an element is something like a section, a paragraph, a phrase of italicized text, an item in a list, and so on. Using a tag is like using a LaTeX command such as \\iitteemm or \\sseeccttiioonn{{......}}. As a simple example, to produce tthhiiss bboollddffaacceedd tteexxtt, I typed As a simple example, to produce this boldfaced text, ... in the source. <> begins the region of bold text, and <> ends it. Alternately, you can use the abbreviated form As a simple example, to produce > tag, however, the end- tag for the section (which could appear at the end of the section body itself, not just after the name of the section!) is optional and implied when you start another section of the same depth. In general you needn't worry about these details; just follow the model used in the tutorial (eexxaammppllee..ssggmmll). 33..22.. SSppeecciiaall CChhaarraacctteerrss Obviously, the angle brackets are themselves special characters in the SGML source. There are others to watch out for. For example, let's say that you wanted to type an expression with angle brackets around it, as so: <>. In order to get the left angle bracket, you must use the &&lltt;; element, which is a ``macro'' that expands to the actual left- bracket character. Therefore, in the source, I typed angle brackets around it, as so: <foo>. Generally, something beginning with an ampersand is a special macro. For example, there's &&ppeerrccnntt;; to produce %, &&vveerrbbaarr;; to produce |, and so on. For all ``special characters'' there exist these ampersanded- entities to represent them. Usually, you don't need to use the ampersand macro to get a special character, however, in some cases it is necessary. The most commonly used are: +o Use &&aammpp;; for the ampersand (&), +o Use &&lltt;; for a left bracket (<), +o Use &&ggtt;; for a right bracket (>), +o Use &&eettaaggoo;; for a left bracket with a slash (< Some literal text to include as example output. The vveerrbb environment doesn't allow you to use _e_v_e_r_y_t_h_i_n_g within it literally. Specifically, you must do the following within vveerrbb envi- ronments. +o Use &&eerroo;; to get an ampersand, +o Use &&eettaaggoo;; to get < Here is some example text. ttssccrreeeenn is an environment that simply indents the text and sets the sets the default font to tttt. This makes examples look much nicer, both in the LaTeX and plain text versions. You can use ttssccrreeeenn without vveerrbb, however, if you use any special characters in your example you'll need to use both of them. ttssccrreeeenn does nothing to special char- acters. See eexxaammppllee..ssggmmll for examples. The qquuoottee environment is like ttssccrreeeenn, except that it does not set the default font to tttt. So, you can use qquuoottee for non-computer-interaction quotes, as in: Here is some text to be indented, as in a quote. which will generate: Here is some text to be indented, as in a quote. 33..44.. OOvveerraallll DDooccuummeenntt SSttrruuccttuurree Before we get too in-depth with details, I'm going to describe the overall structure of a document as defined by the Linuxdoc-SGML DTD. Look at eexxaammppllee..ssggmmll for a good example of how a document is set up. 33..44..11.. TThhee PPrreeaammbbllee In the document ``preamble'' you set up things such as the title information and document style. For a Linux HOWTO document this should look like:
Linux Foo HOWTO <author>Norbert Ebersol, <tt/norb@baz.com/ <date>v1.0, 9 March 1994 <abstract> This document describes how to use the <tt/foo/ tools to frobnicate bar libraries, using the <tt/xyzzy/ relinker. </abstract> <toc> The elements should go more or less in this order. The first line tells the SGML parser to use the Linuxdoc-SGML DTD. The <<aarrttiiccllee>> tag forces the document to use the ``article'' document style. (The original QWERTZ DTD defines ``report'' and ``book'' as well; I haven't tweaked these for use with Linuxdoc-SGML). The ttiittllee, aauutthhoorr, and ddaattee tags should be obvious; in the ddaattee tag include the version number and last modification time of the document. The aabbssttrraacctt tag sets up the text to be printed at the top of the document, _b_e_f_o_r_e the table of contents. If you're not going to include a table of contents (the ttoocc tag), you probably don't need an aabbssttrraacctt. I suggest that all Linux HOWTOs use this same format for the preamble, so that the title, abstract, and table of contents are all there and look the same. 33..44..22.. SSeeccttiioonniinngg AAnndd PPaarraaggrraapphhss After the preamble, you're ready to dive into the document. The following sectioning commands are available: +o sseecctt: For top-level sections (i.e. 1, 2, and so on.) +o sseecctt11: For second-level subsections (i.e. 1.1, 1.2, and so on.) +o sseecctt22: For third-level subsubsections. +o sseecctt33: For fourth-level subsubsubsections. +o sseecctt44: For fifth-level subsubsubsubsections. These are roughly equivalent to their LaTeX counterparts sseeccttiioonn, ssuubbsseeccttiioonn, and so on. After the sseecctt (or sseecctt11, sseecctt22, etc.) tag comes the name of the section. For example, at the top of this document, after the preamble, comes the tag: <sect>Introduction And at the beginning of this section (Sectioning and paragraphs), there is the tag: <sect2>Sectioning And Paragraphs After the section tag, you begin the body of the section. However, you must start the body with a <<pp>> tag, as so: <sect>Introduction <p> This is a user's guide to the Linuxdoc-SGML document processing... This is to tell the parser that you're done with the section title and are ready to begin the body. Thereafter, new paragraphs are started with a blank line (just as you would do in TeX). For example, Here is the end of the first paragraph. And we start a new paragraph here. There is no reason to use <<pp>> tags at the beginning of every para- graph; only at the beginning of the first paragraph after a sectioning command. 33..44..33.. EEnnddiinngg TThhee DDooccuummeenntt At the end of the document, you must use the tag: </article> to tell the parser that you're done with the aarrttiiccllee element (which embodies the entire document). 33..55.. CCrroossss--RReeffeerreenncceess Now we're going to move onto other features of the system. Cross- references are easy. For example, if you want to make a cross- reference to a certain section, you need to label that section as so: <sect1>Introduction<label id="sec-intro"> You can then refer to that section somewhere in the text using the expression: See section <ref id="sec-intro" name="Introduction"> for an introduction. This will replace the rreeff tag with the section number labeled as sseecc-- iinnttrroo. The nnaammee argument to rreeff is necessary for groff and HTML trans- lations. The groff macro set used by Linuxdoc-SGML does not currently support cross-references, and it's often nice to refer to a section by name instead of number. For example, this section is ``Cross-References''. There is also a uurrll element for Universal Resource Locators, or URLs, used on the World Wide Web. This element should be used to refer to other documents, files available for FTP, and so forth. For example, You can get the Linux HOWTO documents from <url url="http://sunsite.unc.edu/mdw/HOWTO/" name="The Linux HOWTO INDEX">. The uurrll argument specifies the actual URL itself. A link to the URL in question will be automatically added to the HTML document. The optional nnaammee argument specifies the text that should be anchored to the URL (for HTML conversion) or named as the description of the URL (for LaTeX and groff). If no nnaammee argument is given, the URL itself will be used. For example, you can get the Linuxdoc-SGML package from ffttpp::////ssuunnssiittee..uunncc..eedduu//ppuubb//LLiinnuuxx//uuttiillss//tteexxtt//lliinnuuxxddoocc--ssggmmll--11..55..ttaarr..ggzz. A useful variant of this is hhttmmlluurrll, which suppresses rendering of the URL part in every context except HTML. What this is useful for is things like a person's email addresses; you can write <htmlurl url="mailto:esr@snark.thyrsus.com" name="esr@snark.thyrsus.com"> and get ``esr@snark.thyrsus.com'' in text output rather than the duplicative ``esr@snark.thyrsus.com <mailto:esr@snark.thyrsus.com>'' but still have a proper URL in HTML documents. 33..66.. FFoonnttss Essentially, the same fonts supported by LaTeX are supported by Linuxdoc-SGML. Note, however, that the conversion to plain text (through ggrrooffff) does away with the font information. So, you should use fonts as much as possible, for the benefit of the conversion to LaTeX. But don't depend on the fonts to get a point across in the plain text version. In particular, the tttt tag described above can be used to get constant- width ``typewriter'' font which should be used for all e-mail addresses, machine names, filenames, and so on. Example: Here is some <tt>typewriter text</tt> to be included in the document. Equivalently: Here is some <tt/typewriter text/ to be included in the document. Remember that you can only use this abbreviated form if the enclosed text doesn't contain slashes. Other fonts can be achieved with bbff for bboollddffaaccee and eemm for _i_t_a_l_i_c_s. Several other fonts are supported as well, but I don't suggest you use them, because we'll be converting these documents to other formats such as HTML which may not support them. Boldface, typewriter, and italics should be all that you need. 33..77.. LLiissttss There are various kinds of supported lists. They are: +o iitteemmiizzee for bulleted lists such as this one. +o eennuumm for numbered lists. +o ddeessccrriipp for ``descriptive'' lists. Each item in an iitteemmiizzee or eennuumm list must be marked with an iitteemm tag. Items in a ddeessccrriipp are marked with ttaagg. For example, <itemize> <item>Here is an item. <item>Here is a second item. </itemize> Looks like this: +o Here is an item. +o Here is a second item. Or, for an eennuumm, <enum> <item>Here is the first item. <item>Here is the second item. </enum> You get the idea. Lists can be nested as well; see the example docu- ment for details. A ddeessccrriipp list is slightly different, and slightly ugly, but you might want to use it for some situations: <descrip> <tag/Gnats./ Annoying little bugs that fly into your cooling fan. <tag/Gnus./ Annoying little bugs that run on your CPU. </descrip> ends up looking like: GGnnaattss.. Annoying little bugs that fly into your cooling fan. GGnnuuss.. Annoying little bugs that run on your CPU. 33..88.. FFuurrtthheerr IInnffoorrmmaattiioonn +o The QWERTZ User's Guide is available from ffttpp::////ffttpp..ccss..ccoorrnneellll..eedduu//ppuubb//mmddww//SSGGMMLL. QWERTZ (and hence, Linuxdoc-SGML) supports many features such as mathematical formulae, tables, figures, and so forth. I don't recommend using most of these features in the Linux HOWTOs because they won't render well in plain text. If you'd like to write general documentation in SGML, I suggest using the original QWERTZ DTD instead of the hacked-up Linuxdoc-SGML DTD, which I've modified for use particularly by the Linux HOWTOs and other such documentation. +o Tom Gordon's original QWERTZ tools can be found at ffttpp::////ffttpp..ggmmdd..ddee//GGMMDD//ssggmmll. +o More information on SGML can be found at the following WWW pages: 1. SSGGMMLL aanndd tthhee WWeebb <<hhttttpp::////wwwwww..ww33..oorrgg//hhyyppeerrtteexxtt//WWWWWW//MMaarrkkUUpp//SSGGMMLL//> 2. SSGGMMLL WWeebb PPaaggee <<hhttttpp::////wwwwww..ssiill..oorrgg//ssggmmll//ssggmmll..hhttmmll> +o James Clark's ssggmmllss parser, and it's successor nnssggmmllss and other tools can be found at ffttpp::////ffttpp..jjccllaarrkk..ccoomm and at JJaammeess CCllaarrkk''ss WWWWWW PPaaggee <<hhttttpp::////wwwwww..jjccllaarrkk..ccoomm>. +o You can join the Linuxdoc-SGML mailing list by sending mail to mmaajjoorrddoommoo@@vviiaa..eeccpp..ffrr with ssuubbssccrriibbee lliinnuuxxddoocc--ssggmmll in the message body. The list address is lliinnuuxxddoocc--ssggmmll@@vviiaa..eeccpp..ffrr. +o More information on LLyyXX can be found at the LLyyXX WWWWWW PPaaggee <<hhttttpp::////wwssiisseerrvv..iinnffoorrmmaattiikk..uunnii--ttuueebbiinnggeenn..ddee//~~eettttrriicchh//>. LLyyXX is a high-level word processor frontend to LaTeX. Quasi-WYSIWYG interface, many LaTeX styles and layouts automatically generated. Speeds up learning LaTeX and makes complicated layouts easy and intuitive.