#This file was created by LinuxDoc-SGML #(conversion : Frank Pavageau and Jose' Matos) \lyxformat 2.15 \textclass linuxdoc \language default \inputencoding default \fontscheme default \papersize Default \paperfontsize default \spacing single \secnumdepth 3 \tocdepth 3 \paragraph_separation indent \defskip medskip \quotes_language default \quotes_times 2 \paperorientation portrait \papercolumns 1 \papersides 1 \paperpagestyle default \layout Title \added_space_top vfill \added_space_bottom vfill LinuxDoc-Tools User's Guide \layout Author written by Matt Welsh as the LinuxDoc-SGML User's Guide. and Updated by Greg Hankins, and rewritten by Eric S. Raymond for SGML-Tools. and Updated and renamed by Taketoshi Sano, for LinuxDoc-Tools \layout Date $Date: 2002/03/18 13:39:10 $ ($Revision: 1.2 $) \layout Abstract This document is a user's guide to the LinuxDoc-Tools formatting system, a SGML-based system which allows you to produce a variety of output formats. You can create plain text output (ASCII, ISO-8859-1, and EUC-JP), DVI, PostScript, PDF, HTML, GNU info, LyX, and RTF output from a single document source file. LinuxDoc-Tools is a new branch from SGML-Tools 1.0.9, and an descendant of the original LinuxDoc-SGML. \layout Standard \begin_inset LatexCommand \tableofcontents \end_inset \layout Section Introduction \layout Standard This document is the user's guide to the LinuxDoc-Tools document processing system. LinuxDoc-Tools is a suite of programs to help you write source documents that can be rendered as plain text, hypertext, or LaTeX files. It contains what you need to know to set up LinuxDoc-Tools and write documents using it. See \family typewriter example.sgml \family default for an example of an LinuxDoc DTD SGML document that you can use as a model for your own documents. The ``LinuxDoc'' means the name of a specific SGML DTD here. \layout Subsection What's the DTD ? \layout Standard 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 \shape italic emphasized text \shape default . You may know the HTML has their own DTD. \layout Standard Don't be confusing. SGML is \shape italic not \shape default a text-formatting system. 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. For more Detail, please refer the later section of this document ( \begin_inset LatexCommand \ref{ \end_inset sgml \begin_inset LatexDel }{ \end_inset How LinuxDoc-Tools Works \begin_inset LatexDel } \end_inset ). \layout Subsection History of the LinuxDoc \layout Standard The LinuxDoc DTD is created by Matt Welsh as the core part of his Linuxdoc-SGML document processing system. This DTD is based heavily on the QWERTZ DTD by Tom Gordon, \family typewriter thomas.gordon@gmd.de \family default . The target of the QWERTZ DTD is to provide the simple way to create LaTeX source for document publishing. Matt Welsh took and shaped it into Linuxdoc-SGML because he needed it to produce a lot of Linux Documentations. It can convert a single source of documentation into various output formats such as plain text, html, and PS. No work for synchronization between various output formatted documents are needed. \layout Standard The Linuxdoc-SGML system had been maintained for years by Matt Welsh and many others, but it has some limitations. Then Cees de Groot came and created the new system using perl. The new system is called as ``SGML-Tools''. The perl based version for LinuxDoc had been maintained for a year, then totally new system using the original python scripts and some stylesheets with the jade has been released. This system is called as ``SGML-Tools 2.0'' and it does not use the LinuxDoc DTD as the main DTD, but uses the new standard one, the DocBook DTD. Now ``SGML-Tools 2.0'' becomes ``SGMLtools-Lite'' and is distributed from \begin_inset LatexDel \url{ \end_inset http://sgmltools-lite.sourceforge.net/ \begin_inset LatexDel }{ \end_inset \begin_inset LatexDel } \end_inset . \layout Standard Recently, the DocBook DTD is the standard DTD for the technical software documentation, and used by many project such as GNOME and KDE, as well as many professional authors and commercial publishers. But some people in the LDP, and users of the various LinuxDoc SGML documents, still needs the support of the tools for the LinuxDoc. This ``LinuxDoc-Tools'' is created for those people. If you need the tools for the LinuxDoc DTD, then you may wish to use this. But remember, the LinuxDoc DTD is not the standard way now even in the Linux world. If you can, try the DocBook DTD. It is the standard, and full-featured way of writing the documentations. \layout Section Installation \layout Subsection Where to get the source archive \layout Standard You can get the source archive of the linuxdoc-tools from: \layout Itemize \begin_inset LatexDel \url{ \end_inset http://www.debian.org/~sano/linuxdoc-tools/ \begin_inset LatexDel }{ \end_inset \begin_inset LatexDel } \end_inset The name of the archive may be \family typewriter linuxdoc-tools_x.y.z.tar.gz \family default or \family typewriter linuxdoc-tools_x.y.z-rel.tar.gz \family default or \family typewriter linuxdoc-tools_x.y.z.orig.tar.gz \family default . These have the equivalent contents. You can use anyone. \layout Subsection What LinuxDoc-Tools Needs \layout Standard LinuxDoc-Tools depends on the usage of sgml parser from Jade or OpenJade (nsgmls or onsgmls). You have to install either of them to use this. \layout Standard The source archive of the linuxdoc-tools contains the tools and data that you need to write SGML documents and convert them to groff, LaTeX, PostScript, HTML, GNU info, LyX, and RTF. In addition to this package, you will need some additional tools for generating formatted output. \layout Enumerate \family typewriter groff \family default . You \shape italic need \shape default version 1.08 or greater. You can get this from \begin_inset LatexDel \url{ \end_inset ftp://prep.ai.mit.edu/pub/gnu \begin_inset LatexDel }{ \end_inset \begin_inset LatexDel } \end_inset . There is a Linux binary version at \begin_inset LatexDel \htmlurl{ \end_inset ftp://sunsite.unc.edu/pub/Linux/utils/text \begin_inset LatexDel }{ \end_inset ftp://sunsite.unc.edu/pub/Linux/utils/text \begin_inset LatexDel } \end_inset as well. You will need \family typewriter groff \family default to produce plain text from your SGML documents. \family typewriter nroff \family default will \shape italic not \shape default work! You can find the version of your \family typewriter groff \family default from \family typewriter groff -v < /dev/null \family default . \layout Enumerate 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 \family typewriter sunsite.unc.edu \family default ). Of course, you only need TeX/LaTeX if you want to format your SGML documents with LaTeX. So, installing TeX/LaTeX is optional. If you need PDF output, then you need pdfLaTeX also. \layout Enumerate \family typewriter flex \family default . \family typewriter lex \family default will probably not work. You can get flex from \family typewriter \begin_inset LatexDel \htmlurl{ \end_inset ftp://prep.ai.mit.edu/pub/gnu \begin_inset LatexDel }{ \end_inset ftp://prep.ai.mit.edu/pub/gnu \begin_inset LatexDel } \end_inset \family default . \layout Enumerate \family typewriter gawk \family default and the GNU info tools, for formatting and viewing info files. These are also available on \family typewriter \begin_inset LatexDel \htmlurl{ \end_inset ftp://prep.ai.mit.edu/pub/gnu \begin_inset LatexDel }{ \end_inset ftp://prep.ai.mit.edu/pub/gnu \begin_inset LatexDel } \end_inset \family default , or on \family typewriter \begin_inset LatexDel \htmlurl{ \end_inset ftp://sunsite.unc.edu/pub/Linux/utils/text \begin_inset LatexDel }{ \end_inset ftp://sunsite.unc.edu/pub/Linux/utils/text \begin_inset LatexDel } \end_inset \family default (for \family typewriter gawk \family default ) and \family typewriter \begin_inset LatexDel \htmlurl{ \end_inset ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers \begin_inset LatexDel }{ \end_inset ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers \begin_inset LatexDel } \end_inset \family default (for GNU info tools). \family typewriter awk \family default will not work. \layout Enumerate LyX (a quasi-WYSIWYG interface to LaTeX, with SGML layouts), is available on \begin_inset LatexDel \htmlurl{ \end_inset ftp://ftp.via.ecp.fr \begin_inset LatexDel }{ \end_inset ftp://ftp.via.ecp.fr \begin_inset LatexDel } \end_inset . \layout Subsection Installing The Software \layout Standard The steps needed to install and configure the LinuxDoc-Tools are: \layout Enumerate First, unpack the tar file of the source archive somewhere. This will create the directory \family typewriter linuxdoc-tools-x.y.z \family default . It doesn't matter where you unpack this file; just don't move things around within the extracted source tree. \layout Enumerate Read the \family typewriter INSTALL \family default file - it has detailed installation instructions. Follow them. If all went well, you should be ready to use the system immediately once you have done so. \layout Section Writing Documents With LinuxDoc-Tools \layout Standard For the most part, writing documents using LinuxDoc-Tools is very simple, and rather like writing HTML. However, there are some caveats to watch out for. In this section we'll give an introduction on writing SGML documents. See the file \family typewriter example.sgml \family default for a SGML example document (and tutorial) which you can use as a model when writing your own documents. Here we're just going to discuss the various features of LinuxDoc-Tools, but the source is not very readable as an example. Instead, print out the source (as well as the formatted output) for \family typewriter example.sgml \family default so you have a real live case to refer to. \layout Subsection Basic Concepts \layout Standard Looking at the source of the example document, you'll notice right off that there are a number of ``tags'' marked within angle brackets ( \family typewriter < \family default and \family typewriter > \family default ). 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 an HTML tag, or a LaTeX command such as \family typewriter \backslash item \family default or \family typewriter \backslash section{...} \family default . \layout Standard As a simple example, to produce \series bold this boldfaced text \series default , you would type \begin_deeper \layout Verbatim As \protected_separator a \protected_separator simple \protected_separator example, \protected_separator to \protected_separator produce \protected_separator this \protected_separator boldfaced \protected_separator text, \protected_separator ... \protected_separator \protected_separator \end_deeper \layout Standard in the source. \family typewriter \family default begins the region of bold text, and \family typewriter \family default ends it. Alternately, you can use the abbreviated form \begin_deeper \layout Verbatim As \protected_separator a \protected_separator simple \protected_separator example, \protected_separator to \protected_separator produce \protected_separator \family default 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 ( \family typewriter example.sgml \family default ). \layout Subsection Special Characters \layout Standard 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: \family typewriter \family default . In order to get the left angle bracket, you must use the \family typewriter < \family default element, which is a ``macro'' that expands to the actual left-bracket character. Therefore, in the source, I typed \begin_deeper \layout Verbatim angle \protected_separator brackets \protected_separator around \protected_separator it, \protected_separator as \protected_separator so: \protected_separator <foo>. \protected_separator \protected_separator \end_deeper \layout Standard Generally, anything beginning with an ampersand is a special character. For example, there's \family typewriter % \family default to produce %, \family typewriter | \family default to produce |, and so on. For every special character that might otherwise confuse LinuxDoc-Tools if typed by itself, there is an ampersand "entity" to represent it. The most commonly used are: \layout Itemize Use \family typewriter & \family default for the ampersand (&), \layout Itemize Use \family typewriter < \family default for a left bracket (<), \layout Itemize Use \family typewriter > \family default for a right bracket (>), \layout Itemize Use \family typewriter &etago; \family default for a left bracket with a slash ( \family typewriter ) \protected_separator greater-than sign \layout Description ÷ \protected_separator (/) \protected_separator division sign \layout Description × \protected_separator \protected_separator (×) \protected_separator multiplication sign \layout Description ¤ \protected_separator (¤) \protected_separator currency symbol \layout Description £ \protected_separator \protected_separator (£) \protected_separator symbol for ``pounds'' \layout Description &dollar \protected_separator ($) \protected_separator dollar sign \layout Description ¢ \protected_separator \protected_separator \protected_separator (¢) \protected_separator cent sign \layout Description ¥ \protected_separator \protected_separator \protected_separator \protected_separator (¥) \protected_separator yen sign \layout Description &num \protected_separator \protected_separator \protected_separator \protected_separator (#) \protected_separator number or hash sign \layout Description &percnt \protected_separator (%) \protected_separator percent sign \layout Description & \protected_separator \protected_separator \protected_separator \protected_separator (&) \protected_separator ampersand \layout Description &ast \protected_separator \protected_separator \protected_separator \protected_separator (*) \protected_separator asterisk \layout Description &commat \protected_separator (@) \protected_separator commercial-at sign \layout Description &lsqb \protected_separator \protected_separator \protected_separator ([) \protected_separator left square bracket \layout Description &bsol \protected_separator \protected_separator \protected_separator (\backslash \protected_separator ) \protected_separator backslash \layout Description &rsqb \protected_separator \protected_separator \protected_separator (]) \protected_separator right square bracket \layout Description &lcub \protected_separator \protected_separator \protected_separator ({) \protected_separator left curly brace \layout Description &horbar \protected_separator (-) \protected_separator horizontal bar \layout Description &verbar \protected_separator (|) \protected_separator vertical bar \layout Description &rcub \protected_separator \protected_separator \protected_separator (}) \protected_separator right curly brace \layout Description µ \protected_separator \protected_separator (µ) \protected_separator greek mu (micro prefix) \layout Description &ohm \protected_separator \protected_separator \protected_separator \protected_separator ({ohm}) \protected_separator greek capital omega (Ohm sign) \layout Description ° \protected_separator \protected_separator \protected_separator \protected_separator (°) \protected_separator small superscript circle sign (degree sign) \layout Description º \protected_separator \protected_separator \protected_separator ({ordm}) \protected_separator masculine ordinal \layout Description ª \protected_separator \protected_separator \protected_separator ({ordf}) \protected_separator feminine ordinal \layout Description § \protected_separator \protected_separator \protected_separator (§) \protected_separator section sign \layout Description ¶ \protected_separator \protected_separator \protected_separator (¶) \protected_separator paragraph sign \layout Description · \protected_separator (·) \protected_separator centered dot \layout Description &larr \protected_separator \protected_separator \protected_separator (<-) \protected_separator left arrow \layout Description &rarr \protected_separator \protected_separator \protected_separator (->) \protected_separator right arrow \layout Description &uarr \protected_separator \protected_separator \protected_separator ({uarr}) \protected_separator up arrow \layout Description &darr \protected_separator \protected_separator \protected_separator ({darr}) \protected_separator down arrow \layout Description © \protected_separator \protected_separator \protected_separator (©) \protected_separator copyright \layout Description ® \protected_separator \protected_separator \protected_separator \protected_separator (®) \protected_separator r-in-circle marl \layout Description &trade \protected_separator \protected_separator ((TM)) \protected_separator trademark sign \layout Description ¦ \protected_separator (¦) \protected_separator broken vertical bar \layout Description ¬ \protected_separator \protected_separator \protected_separator \protected_separator (¬) \protected_separator logical-negation sign \layout Description &sung \protected_separator \protected_separator \protected_separator ({sung}) \protected_separator sung-note sign \layout Description &excl \protected_separator \protected_separator \protected_separator (!) \protected_separator exclamation point \layout Description ¡ \protected_separator \protected_separator (¡) \protected_separator inverted exclamation point \layout Description " \protected_separator \protected_separator \protected_separator (") \protected_separator double quote \layout Description &apos \protected_separator \protected_separator \protected_separator (') \protected_separator apostrophe (single quote) \layout Description &lpar \protected_separator \protected_separator \protected_separator (() \protected_separator left parenthesis \layout Description &rpar \protected_separator \protected_separator \protected_separator ()) \protected_separator right parenthesis \layout Description &comma \protected_separator \protected_separator (,) \protected_separator comma \layout Description &lowbar \protected_separator (_) \protected_separator under-bar \layout Description &hyphen \protected_separator (-) \protected_separator hyphen \layout Description &period \protected_separator (.) \protected_separator period \layout Description &sol \protected_separator \protected_separator \protected_separator \protected_separator (/) \protected_separator solidus \layout Description &colon \protected_separator \protected_separator (:) \protected_separator colon \layout Description &semi \protected_separator \protected_separator \protected_separator (;) \protected_separator semicolon \layout Description &quest \protected_separator \protected_separator (?) \protected_separator question mark \layout Description ¿ \protected_separator (¿) \protected_separator interrobang \layout Description « \protected_separator \protected_separator («) \protected_separator left guillemot \layout Description » \protected_separator \protected_separator (») \protected_separator right guillemot \layout Description &lsquo \protected_separator \protected_separator (`) \protected_separator left single quote \layout Description &rsquo \protected_separator \protected_separator (') \protected_separator right single quote \layout Description &ldquo \protected_separator \protected_separator (") \protected_separator left double quote \layout Description &rdquo \protected_separator \protected_separator (") \protected_separator right double quote \layout Description   \protected_separator \protected_separator \protected_separator ( ) \protected_separator non-breaking space \layout Description ­ \protected_separator \protected_separator \protected_separator \protected_separator () \protected_separator soft hyphen \layout Subsection Verbatim and Code Environments \layout Standard While we're on the subject of special characters, we might as well mention the verbatim ``environment'' used for including literal text in the output (with spaces and indentation preserved, and so on). The \family typewriter verb \family default element is used for this; it looks like the following: \begin_deeper \layout Verbatim \protected_separator \protected_separator \newline \protected_separator Some \protected_separator literal \protected_separator text \protected_separator to \protected_separator include \protected_separator as \protected_separator example \protected_separator output. \protected_separator \newline \protected_separator \end_deeper \layout Standard The \family typewriter verb \family default environment doesn't allow you to use \shape italic everything \shape default within it literally. Specifically, you must do the following within \family typewriter verb \family default environments. \layout Itemize Use \family typewriter &ero; \family default to get an ampersand, \layout Itemize Use \family typewriter &etago; \family default to get \family typewriter \protected_separator \protected_separator \newline Here \protected_separator is \protected_separator some \protected_separator example \protected_separator text. \protected_separator \protected_separator \protected_separator \newline \protected_separator \end_deeper \layout Standard \family typewriter tscreen \family default is an environment that simply indents the text and sets the sets the default font to \family typewriter tt \family default . This makes examples look much nicer, both in the LaTeX and plain text versions. You can use \family typewriter tscreen \family default without \family typewriter verb \family default , however, if you use any special characters in your example you'll need to use both of them. \family typewriter tscreen \family default does nothing to special characters. See \family typewriter example.sgml \family default for examples. \layout Standard The \family typewriter quote \family default environment is like \family typewriter tscreen \family default , except that it does not set the default font to \family typewriter tt \family default . So, you can use \family typewriter quote \family default for non-computer-interaction quotes, as in: \begin_deeper \layout Verbatim \protected_separator \protected_separator \newline Here \protected_separator is \protected_separator some \protected_separator text \protected_separator to \protected_separator be \protected_separator indented, \protected_separator as \protected_separator in \protected_separator a \protected_separator quote. \protected_separator \newline \protected_separator \end_deeper \layout Standard which will generate: \layout Quote Here is some text to be indented, as in a quote. \layout Subsection Overall Document Structure \layout Standard Before we get too in-depth with details, we're going to describe the overall structure of an LinuxDoc-Tools document. Look at \family typewriter example.sgml \family default for a good example of how a document is set up. \layout Subsubsection The Preamble \layout Standard In the document ``preamble'' you set up things such as the title information and document style: \begin_deeper \layout Verbatim \protected_separator \protected_separator \newline \protected_separator \newline
\protected_separator \newline \protected_separator \newline Linux \protected_separator Foo \protected_separator HOWTO \protected_separator \newline <author>Norbert \protected_separator Ebersol, \protected_separator <tt/norb@baz.com/ \protected_separator \newline <date>v1.0, \protected_separator 9 \protected_separator March \protected_separator 1994 \protected_separator \newline <abstract> \protected_separator \newline This \protected_separator document \protected_separator describes \protected_separator how \protected_separator to \protected_separator use \protected_separator the \protected_separator <tt/foo/ \protected_separator tools \protected_separator to \protected_separator frobnicate \protected_separator \newline bar \protected_separator libraries, \protected_separator using \protected_separator the \protected_separator <tt/xyzzy/ \protected_separator relinker. \protected_separator \newline </abstract> \protected_separator \newline \protected_separator \newline <toc> \protected_separator \end_deeper \layout Standard The elements should go more or less in this order. The first line tells the SGML parser to use the linuxdoc DTD. We'll explain that in the later section on \begin_inset LatexCommand \ref{ \end_inset sgml \begin_inset LatexDel }{ \end_inset How LinuxDoc-Tools Works \begin_inset LatexDel } \end_inset ; for now just treat it as a bit of necessary magic. The \family typewriter <article> \family default tag forces the document to use the ``article'' document style. \layout Standard The \family typewriter title \family default , \family typewriter author \family default , and \family typewriter date \family default tags should be obvious; in the \family typewriter date \family default tag include the version number and last modification time of the document. \layout Standard The \family typewriter abstract \family default tag sets up the text to be printed at the top of the document, \shape italic before \shape default the table of contents. If you're not going to include a table of contents (the \family typewriter toc \family default tag), you probably don't need an \family typewriter abstract \family default . \layout Subsubsection Sectioning And Paragraphs \layout Standard After the preamble, you're ready to dive into the document. The following sectioning commands are available: \layout Itemize \family typewriter sect \family default : For top-level sections (i.e. 1, 2, and so on.) \layout Itemize \family typewriter sect1 \family default : For second-level subsections (i.e. 1.1, 1.2, and so on.) \layout Itemize \family typewriter sect2 \family default : For third-level subsubsections. \layout Itemize \family typewriter sect3 \family default : For fourth-level subsubsubsections. \layout Itemize \family typewriter sect4 \family default : For fifth-level subsubsubsubsections. These are roughly equivalent to their LaTeX counterparts \family typewriter section \family default , \family typewriter subsection \family default , and so on. \layout Standard After the \family typewriter sect \family default (or \family typewriter sect1 \family default , \family typewriter sect2 \family default , etc.) tag comes the name of the section. For example, at the top of this document, after the preamble, comes the tag: \begin_deeper \layout Verbatim <sect>Introduction \protected_separator \protected_separator \end_deeper \layout Standard And at the beginning of this section (Sectioning and paragraphs), there is the tag: \begin_deeper \layout Verbatim <sect2>Sectioning \protected_separator And \protected_separator Paragraphs \protected_separator \protected_separator \end_deeper \layout Standard After the section tag, you begin the body of the section. However, you must start the body with a \family typewriter <p> \family default tag, as so: \begin_deeper \layout Verbatim <sect>Introduction \protected_separator \protected_separator \newline <p> \protected_separator \newline This \protected_separator is \protected_separator a \protected_separator user's \protected_separator guide \protected_separator to \protected_separator the \protected_separator LinuxDoc-Tools \protected_separator document \protected_separator processing... \protected_separator \end_deeper \layout Standard 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, \begin_deeper \layout Verbatim Here \protected_separator is \protected_separator the \protected_separator end \protected_separator of \protected_separator the \protected_separator first \protected_separator paragraph. \protected_separator \protected_separator \newline \protected_separator \newline And \protected_separator we \protected_separator start \protected_separator a \protected_separator new \protected_separator paragraph \protected_separator here. \protected_separator \end_deeper \layout Standard There is no reason to use \family typewriter <p> \family default tags at the beginning of every paragraph; only at the beginning of the first paragraph after a sectioning command. \layout Subsubsection Ending The Document \layout Standard At the end of the document, you must use the tag: \begin_deeper \layout Verbatim </article> \protected_separator \protected_separator \end_deeper \layout Standard to tell the parser that you're done with the \family typewriter article \family default element (which embodies the entire document). \layout Subsection Internal Cross-References \begin_inset LatexCommand \label{cross-ref} \end_inset \layout Standard 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: \begin_deeper \layout Verbatim <sect1>Introduction<label \protected_separator id="sec-intro"> \protected_separator \protected_separator \end_deeper \layout Standard You can then refer to that section somewhere in the text using the expression: \begin_deeper \layout Verbatim See \protected_separator section \protected_separator <ref \protected_separator id="sec-intro" \protected_separator name="Introduction"> \protected_separator for \protected_separator an \protected_separator introduction. \protected_separator \protected_separator \end_deeper \layout Standard This will replace the \family typewriter ref \family default tag with the section number labeled as \family typewriter sec-intro \family default . The \family typewriter name \family default argument to \family typewriter ref \family default is necessary for groff and HTML translations. The groff macro set used by LinuxDoc-Tools does not currently support cross-references, and it's often nice to refer to a section by name instead of number. \layout Standard For example, this section is \begin_inset LatexCommand \ref{ \end_inset cross-ref \begin_inset LatexDel }{ \end_inset Cross-References \begin_inset LatexDel } \end_inset . \layout Standard Some back-ends may get upset about special characters in reference labels. In particular, latex2e chokes on underscores (though the latex back end used in older versions of this package didn't). Hyphens are safe. \layout Subsection Web References \layout Standard There is also a \family typewriter url \family default 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, \begin_deeper \layout Verbatim You \protected_separator can \protected_separator get \protected_separator the \protected_separator Linux \protected_separator HOWTO \protected_separator documents \protected_separator from \protected_separator \protected_separator \protected_separator \newline <url \protected_separator url="http://sunsite.unc.edu/mdw/HOWTO/" \protected_separator \protected_separator \newline \protected_separator \protected_separator \protected_separator name="The \protected_separator Linux \protected_separator HOWTO \protected_separator INDEX">. \protected_separator \end_deeper \layout Standard The \family typewriter url \family default argument specifies the actual URL itself. A link to the URL in question will be automatically added to the HTML document. The optional \family typewriter name \family default 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 \family typewriter name \family default argument is given, the URL itself will be used. \layout Standard A useful variant of this is \family typewriter htmlurl \family default , 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 \begin_deeper \layout Verbatim <htmlurl \protected_separator url="mailto:esr@snark.thyrsus.com" \protected_separator \protected_separator \newline \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator name="esr@snark.thyrsus.com"> \protected_separator \end_deeper \layout Standard 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. \layout Subsection Fonts \layout Standard Essentially, the same fonts supported by LaTeX are supported by LinuxDoc-Tools. Note, however, that the conversion to plain text (through \family typewriter groff \family default ) does away with the font information. So, you should use fonts as 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. \layout Standard In particular, the \family typewriter tt \family default 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: \begin_deeper \layout Verbatim Here \protected_separator is \protected_separator some \protected_separator <tt>typewriter \protected_separator text</tt> \protected_separator to \protected_separator be \protected_separator included \protected_separator in \protected_separator the \protected_separator document. \protected_separator \protected_separator \end_deeper \layout Standard Equivalently: \begin_deeper \layout Verbatim Here \protected_separator is \protected_separator some \protected_separator <tt/typewriter \protected_separator text/ \protected_separator to \protected_separator be \protected_separator included \protected_separator in \protected_separator the \protected_separator document. \protected_separator \protected_separator \end_deeper \layout Standard Remember that you can only use this abbreviated form if the enclosed text doesn't contain slashes. \layout Standard Other fonts can be achieved with \family typewriter bf \family default for \series bold boldface \series default and \family typewriter em \family default for \shape italic italics \shape default . Several other fonts are supported as well, but we 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. \layout Subsection Lists \layout Standard There are various kinds of supported lists. They are: \layout Itemize \family typewriter itemize \family default for bulleted lists such as this one. \layout Itemize \family typewriter enum \family default for numbered lists. \layout Itemize \family typewriter descrip \family default for ``descriptive'' lists. Each item in an \family typewriter itemize \family default or \family typewriter enum \family default list must be marked with an \family typewriter item \family default tag. Items in a \family typewriter descrip \family default are marked with \family typewriter tag \family default . For example, \begin_deeper \layout Verbatim <itemize> \protected_separator \protected_separator \newline <item>Here \protected_separator is \protected_separator an \protected_separator item. \protected_separator \newline <item>Here \protected_separator is \protected_separator a \protected_separator second \protected_separator item. \protected_separator \newline </itemize> \protected_separator \end_deeper \layout Standard Looks like this: \layout Itemize Here is an item. \layout Itemize Here is a second item. Or, for an \family typewriter enum \family default , \begin_deeper \layout Verbatim <enum> \protected_separator \protected_separator \newline <item>Here \protected_separator is \protected_separator the \protected_separator first \protected_separator item. \protected_separator \newline <item>Here \protected_separator is \protected_separator the \protected_separator second \protected_separator item. \protected_separator \newline </enum> \protected_separator \end_deeper \layout Standard You get the idea. Lists can be nested as well; see the example document for details. \layout Standard A \family typewriter descrip \family default list is slightly different, and slightly ugly, but you might want to use it for some situations: \begin_deeper \layout Verbatim <descrip> \protected_separator \protected_separator \newline <tag/Gnats./ \protected_separator Annoying \protected_separator little \protected_separator bugs \protected_separator that \protected_separator fly \protected_separator into \protected_separator your \protected_separator cooling \protected_separator fan. \protected_separator \newline <tag/Gnus./ \protected_separator Annoying \protected_separator little \protected_separator bugs \protected_separator that \protected_separator run \protected_separator on \protected_separator your \protected_separator CPU. \protected_separator \newline </descrip> \protected_separator \end_deeper \layout Standard ends up looking like: \layout Description Gnats. \protected_separator Annoying little bugs that fly into your cooling fan. \layout Description Gnus. \protected_separator Annoying little bugs that run on your CPU. \layout Subsection Conditionalization \layout Standard The overall goal of LinuxDoc-tools is to be able to produce from one set of masters output that is semantically equivalent on all back ends. Nevertheless, it is sometimes useful to be able to produce a document in slightly different variants depending on back end and version. LinuxDoc-Tools supports this through the <#if> and <#unless> bracketing tags. \layout Standard These tags allow you to selectively include and uninclude portions of an SGML master in your output, depending on filter options set by your driver. Each tag may include a set of attribute/value pairs. The most common are ``output'' and ``version'' (though you are not restricted to these) so a typical example might look like this: \begin_deeper \layout Verbatim Some \protected_separator <#if \protected_separator output=latex2e \protected_separator version=drlinux>conditional</#if> \protected_separator text. \protected_separator \protected_separator \end_deeper \layout Standard Everything from this <#if> tag to the following </#if> would be considered conditional, and would not be included in the document if either the filter option ``output'' were set to something that doesn't match ``latex2e'' or the filter option ``version'' were set to something that doesn't match ``drlinux''. The double negative is deliberate; if no ``output'' or ``version'' filter options are set, the conditional text will be included. \layout Standard Filter options are set in one of two ways. Your format driver sets the ``output'' option to the name of the back end it uses; thus, in particular, `` \family typewriter linuxdoc -B latex \family default '' sets ``output=latex2e'', Or you may set an attribute-value pair with the ``-D'' option of your format driver. Thus, if the above tag were part of a file a file named ``foo.sgml'', then formatting with either \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator latex \protected_separator -D \protected_separator version=drlinux \protected_separator foo.sgml \protected_separator \protected_separator \end_deeper \layout Standard or \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator latex \protected_separator foo.sgml \protected_separator \protected_separator \end_deeper \layout Standard would include the ``conditional'' part, but neither \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator html \protected_separator -D \protected_separator version=drlinux \protected_separator foo.sgml \protected_separator \protected_separator \end_deeper \layout Standard nor \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator latex \protected_separator -D \protected_separator private=book \protected_separator foo.sgml \protected_separator \protected_separator \end_deeper \layout Standard would do so. \layout Standard So that you can have conditionals depending on one or more of several values matching, values support a simple alternation syntax using ``|''. Thus you could write: \begin_deeper \layout Verbatim Some \protected_separator <#if \protected_separator output="latex2e|html" \protected_separator version=drlinux>conditional</#if> \protected_separator text. \protected_separator \protected_separator \end_deeper \layout Standard and formatting with either ``-B latex'' or ``-B html'' will include the ``conditional'' text (but formatting with, say, ``-B txt'' will not). \layout Standard The <#unless> tag is the exact inverse of <#if>; it includes when <#if>; would exclude, and vice-versa. \layout Standard Note that these tags are implemented by a preprocessor which runs before the SGML parser ever sees the document. Thus they are completely independent of the document structure, are not in the DTD, and usage errors won't be caught by the parser. You can seriously confuse yourself by conditionalizing sections that contain unbalanced bracketing tags. \layout Standard The preprocessor implementation also means that standalone SGML parsers will choke on LinuxDoc-Tools documents that contain conditionals. However, you can validity-check them with `` \family typewriter linuxdoc -B check \family default ''. \layout Standard Also note that in order not to mess up the source line numbers in parser error messages, the preprocessor doesn't actually throw away everything when it omits a conditionalized section. It still passes through any newlines. This leads to behavior that may suprise you if you use <if> or <unless> within a <verb> environment, or any other kind of bracket that changes SGML's normal processing of whitespace. \layout Standard These tags are called ``#if'' and ``#unless'' (rather than ``if'' and ``unless'') to remind you that they are implemented by a preprocessor and you need to be a bit careful about how you use them. \layout Subsection Index generation \layout Standard To support automated generation of indexes for book publication of SGML masters, LinuxDoc-Tools supports the <idx> and <cdx> tags. These are bracketing tags which cause the text between them to be saved as an index entry, pointing to the page number on which it occurs in the formatted document. They are ignored by all backends except LaTeX, which uses them to build a .ind file suitable for processing by the TeX utility makeindex. \layout Standard The two tags behave identically, except that <idx> sets the entry in a normal font and <cdx> in a constant-width one. \layout Standard If you want to add an index entry that shouldn't appear in the text itself, use the <nidx> and <ncdx> tags. \layout Subsection Controlling justification \layout Standard In order to get proper justification and filling of paragraphs in typeset output, LinuxDoc-Tools includes the ­ entity. This becomes an optional or `soft' hyphen in back ends like latex2e for which this is neaningful. \layout Standard The bracketing tag <file> can be used to surround filenames in running text. It effectively inserts soft hyphens after each slash in the filename. \layout Standard One of the advantages of using the <url> and <htmlurl> tags is that they do likewise for long URLs. \layout Section Formatting SGML Documents \layout Standard Let's say you have the SGML document \family typewriter foo.sgml \family default , 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. \layout Subsection Checking SGML Syntax \layout Standard If you just want to capture your errors from the SGML conversion, use the `` \family typewriter linuxdoc -B check \family default ''. For example. \layout Standard \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator check \protected_separator foo.sgml \protected_separator \protected_separator \protected_separator \end_deeper \layout Standard If you see no output from this check run other than the ``Processing...'' message, that's good. It means there were no errors. \layout Subsection Creating Plain Text Output \layout Standard If you want to produce plain text, use the command: \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator txt \protected_separator foo.sgml \protected_separator \protected_separator \protected_separator \end_deeper \layout Standard You can also create groff source for man pages, which can be formatted with \family typewriter groff -man \family default . To do this, do the following: \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator txt \protected_separator --man \protected_separator foo.sgml \protected_separator \protected_separator \protected_separator \end_deeper \layout Subsection Creating LaTeX, DVI, PostScript or PDF Output \layout Standard To create a LaTeX documents from the SGML source file, simply run: \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator latex \protected_separator foo.sgml \protected_separator \protected_separator \protected_separator \end_deeper \layout Standard If you want to produce PostScript output (via \family typewriter dvips \family default ), use the `` \family typewriter -o \family default '' option: \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator latex \protected_separator --output=ps \protected_separator foo.sgml \protected_separator \protected_separator \protected_separator \end_deeper \layout Standard Or you can produce a DVI file: \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator latex \protected_separator --output=dvi \protected_separator foo.sgml \protected_separator \protected_separator \protected_separator \end_deeper \layout Standard Also, you can produce a PDF file: \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator latex \protected_separator --output=pdf \protected_separator foo.sgml \protected_separator \protected_separator \protected_separator \end_deeper \layout Subsection Creating HTML Output \layout Standard If you want to produce HTML output, do this: \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator html \protected_separator --imagebuttons \protected_separator foo.sgml \protected_separator \protected_separator \protected_separator \end_deeper \layout Standard This will produce \family typewriter foo.html \family default , as well as \family typewriter foo-1.html \family default , \family typewriter foo-2.html \family default , and so on -- one file for each section of the document. Run your WWW browser on \family typewriter foo.html \family default , which is the top level file. You must make sure that all of the HTML files generated from your document are all installed in the directory, as they reference each other with local URLs. \layout Standard The `` \family typewriter --imagebuttons \family default '' option tells html backend driver to use graphic arrows as navigation buttons. The names of these icons are ``next.png'', ``prev.png'', and ``toc.png'', and the LinuxDoc-Tools system supplies appropriate PNGs in its library directory. \layout Standard If you use `` \family typewriter linuxdoc -B html \family default '' without the `` \family typewriter -img \family default '' flag, HTML documents will by default have the English labels ``Previous'', ``Next'', and ``Table of Contents'' for navigation. If you specify one of the accepted language codes in a `` \family typewriter --language \family default '' option, however, the labels will be given in that language. \layout Subsection Creating GNU Info Output \layout Standard If you want to format your file for the GNU info browser, just run the following command: \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator info \protected_separator foo.sgml \protected_separator \protected_separator \protected_separator \end_deeper \layout Subsection Creating LyX Output \layout Standard For LyX output, use the the command: \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator lyx \protected_separator foo.sgml \protected_separator \protected_separator \protected_separator \end_deeper \layout Subsection Creating RTF Output \layout Standard If you want to produce RTF output, run the command: \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator rtf \protected_separator foo.sgml \protected_separator \protected_separator \protected_separator \end_deeper \layout Standard This will produce \family typewriter foo.rtf \family default , as well as \family typewriter foo-1.rtf \family default , \family typewriter foo-2.rtf \family default , and so on; one file for each section of the document. \layout Section Internationalization Support \layout Standard 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 `` \family typewriter --charset=latin \family default '' flag, for example: \begin_deeper \layout Verbatim % \protected_separator linuxdoc \protected_separator -B \protected_separator txt \protected_separator --charset=latin \protected_separator foo.sgml \protected_separator \protected_separator \protected_separator \end_deeper \layout Standard You also can use ISO 8859-1 characters in the SGML source, they will automatically be translated to the proper escape codes for the corresponding output format. \layout Standard Currently, EUC-JP (ujis) character set is partially supported. Source SGML file using this character set can be converted in plain text, HTML, and LaTeX. Other output formats are not tested fully. \layout Section How LinuxDoc-Tools Works \begin_inset LatexCommand \label{sgml} \end_inset \layout Standard Technically, the tags and conventions we've explored in previous sections of this use's guide are what is called a \shape italic markup language \shape default -- a way to embed formatting information in a document so that programs can do useful things with it. HTML, Tex, and Unix manual-page macros are well-known examples of markup languages. \layout Subsection Overview of SGML \layout Standard LinuxDoc-Tools uses a way of describing markup languages called SGML (Standard Generalized Markup Language). SGML itself doesn't describe a markup language; rather, it's a language for writing specifications for markup languages. The reason SGML is useful is that an SGML markup specification for a language can be used to generate programs that ``know'' that language with much less effort (and a much lower bugginess rate!) than if they had to be coded by hand. \layout Standard In SGML jargon, a markup language specification is called a ``DTD'' (Document Type Definition). A DTD allows you to specify the \shape italic structure \shape default of a kind of document; that is, what parts, in what order, make up a document of that kind. Given a DTD, an SGML parser can check a document for correctness. An SGML-parser/DTD combination can also make it easy to write programs that translate that structure into another markup language -- and this is exactly how LinuxDoc-Tools actually works. \layout Standard LinuxDoc-Tools provides a SGML DTD called ``linuxdoc'' and a set of ``replacement files'' which convert the linuxdoc documents to groff, LaTeX, HTML, GNU info, LyX, and RTF source. This is why the example document has a magic cookie at the top of it that says ``linuxdoc system''; that is how one tells an SGML parser what DTD to use. \layout Standard Actually, LinuxDoc-Tools provides a couple of closely related DTDs. But the ones other than linuxdoc are still experimental, and you probably do not want to try working with them unless you are an LinuxDoc-Tools guru. \layout Standard If you are an SGML guru, you may find it interesting to know that the LinuxDoc-Tools DTDs are based heavily on the QWERTZ DTD by Tom Gordon, \family typewriter thomas.gordon@gmd.de \family default . \layout Standard If you are not an SGML guru, you may not know that HTML (the markup language used on the World Wide Web) is itself defined by a DTD. \layout Subsection How SGML Works \layout Standard An SGML DTD like linuxdoc specifies the names of ``elements'' within a document type. An element is just a bit of structure; like a section, a subsection, a paragraph, or even something smaller like \shape italic emphasized text \shape default . \layout Standard Unlike in LaTeX, however, these elements are not in any way intrinsic to SGML itself. The linuxdoc 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 DTD is like LaTeX. \layout Standard Don't be confused by this analogy. SGML is \shape italic not \shape default a text-formatting system. There is no ``SGML formatter'' per se. SGML source is \shape italic only \shape default 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. \layout Subsection What Happens When LinuxDoc-Tools Processes A Document \layout Standard Here's how processing a document with LinuxDoc-Tools works. First, you need a DTD, which sets up the structure of the document. A small portion of the normal (linuxdoc) DTD looks like this: \layout Standard \begin_deeper \layout Verbatim <!element \protected_separator article \protected_separator - \protected_separator - \protected_separator \protected_separator \newline \protected_separator \protected_separator \protected_separator \protected_separator (titlepag, \protected_separator header?, \protected_separator \protected_separator \newline \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator toc?, \protected_separator lof?, \protected_separator lot?, \protected_separator p*, \protected_separator sect*, \protected_separator \protected_separator \newline \protected_separator \protected_separator \protected_separator \protected_separator \protected_separator (appendix, \protected_separator sect+)?, \protected_separator biblio?) \protected_separator +(footnote)> \protected_separator \end_deeper \layout Standard This part sets up the overall structure for an ``article'', which is like a ``documentstyle'' within LaTeX. The article consists of a titlepage ( \family typewriter titlepag \family default ), an optional header ( \family typewriter header \family default ), an optional table of contents ( \family typewriter toc \family default ), optional lists of figures ( \family typewriter lof \family default ) and tables ( \family typewriter lot \family default ), any number of paragraphs ( \family typewriter p \family default ), any number of top-level sections ( \family typewriter sect \family default ), optional appendices ( \family typewriter appendix \family default ), an optional bibliography ( \family typewriter biblio \family default ) and footnotes ( \family typewriter footnote \family default ). \layout Standard 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 \family typewriter titlepag \family default , \family typewriter header \family default , \family typewriter sect \family default , and other elements are defined. \layout Standard You don't need to know anything about the syntax of the DTD in order to write documents. We're just presenting it here so you know what it looks like and what it does. You \shape italic do \shape default need to be familiar with the document \shape italic structure \shape default 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. \layout Standard The next step is to write a document using the structure defined by the DTD. Again, the linuxdoc DTD makes documents look a lot like LaTeX or HTML -- 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. \layout Standard 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 \shape italic parsed \shape default along with the DTD by the SGML \shape italic parser \shape default . LinuxDoc-Tools uses the \family typewriter onsgmls \family default parser in OpenJade, or \family typewriter nsgmls \family default parser in Jade. The former is the successor of the latter. \family typewriter sgmls \family default parser was written by James Clark, \family typewriter jjc@jclark.com \family default , who also happens to be the author of \family typewriter groff \family default . We're in good hands. The parser ( \family typewriter onsgmls \family default or \family typewriter nsgmls \family default ) 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 \family typewriter sgmlsasp \family default , the next part of the process. \layout Standard \family typewriter sgmlsasp \family default is responsible for converting the output of \family typewriter sgmls \family default to another format (such as LaTeX). It does this using \shape italic replacement files \shape default , which describe how to convert elements in the original SGML document into corresponding source in the ``target'' format (such as LaTeX or groff). \layout Standard For example, part of the replacement file for LaTeX looks like: \begin_deeper \layout Verbatim <itemize> \protected_separator \protected_separator \protected_separator \protected_separator + \protected_separator \protected_separator \protected_separator \protected_separator "\backslash \protected_separator \backslash \protected_separator begin{itemize} \protected_separator \protected_separator \protected_separator + \protected_separator \protected_separator \newline </itemize> \protected_separator \protected_separator \protected_separator + \protected_separator \protected_separator \protected_separator \protected_separator " \protected_separator \backslash \protected_separator \protected_separator \backslash \protected_separator end{itemize} \protected_separator \protected_separator \protected_separator \protected_separator + \protected_separator \end_deeper \layout Standard Which says that whenever you begin an \family typewriter itemize \family default element in the SGML source, it should be replaced with \begin_deeper \layout Verbatim \backslash \protected_separator begin{itemize} \protected_separator \protected_separator \end_deeper \layout Standard in the LaTeX source. (As I said, elements in the DTD are very similar to their LaTeX counterparts). \layout Standard 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. \layout Standard Once \family typewriter sgmlsasp \family default 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. \layout Subsection Further Information \layout Itemize The QWERTZ User's Guide is available from \family typewriter \begin_inset LatexDel \htmlurl{ \end_inset ftp://ftp.cs.cornell.edu/pub/mdw/SGML \begin_inset LatexDel }{ \end_inset ftp://ftp.cs.cornell.edu/pub/mdw/SGML \begin_inset LatexDel } \end_inset \family default . QWERTZ (and hence, LinuxDoc-Tools) supports many features such as mathematical formulae, tables, figures, and so forth. 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. \layout Itemize Tom Gordon's original QWERTZ tools can be found at \family typewriter \begin_inset LatexDel \htmlurl{ \end_inset ftp://ftp.gmd.de/GMD/sgml \begin_inset LatexDel }{ \end_inset ftp://ftp.gmd.de/GMD/sgml \begin_inset LatexDel } \end_inset \family default . \layout Itemize More information on SGML can be found at the following WWW pages: \begin_deeper \layout Enumerate \family typewriter \begin_inset LatexDel \url{ \end_inset http://www.w3.org/hypertext/WWW/MarkUp/SGML/ \begin_inset LatexDel }{ \end_inset SGML and the Web \begin_inset LatexDel } \end_inset \family default \layout Enumerate \family typewriter \begin_inset LatexDel \url{ \end_inset http://www.sil.org/sgml/sgml.html \begin_inset LatexDel }{ \end_inset SGML Web Page \begin_inset LatexDel } \end_inset \family default \layout Enumerate \family typewriter \begin_inset LatexDel \url{ \end_inset http://www.yahoo.com/Computers_and_Internet/Software/Data_Formats/SGML \begin_inset LatexDel }{ \end_inset Yahoo's SGML Page \begin_inset LatexDel } \end_inset \family default \end_deeper \layout Itemize James Clark's \family typewriter sgmls \family default parser, and it's successor \family typewriter nsgmls \family default and other tools can be found at \family typewriter \begin_inset LatexDel \htmlurl{ \end_inset ftp://ftp.jclark.com \begin_inset LatexDel }{ \end_inset ftp://ftp.jclark.com \begin_inset LatexDel } \end_inset \family default and at \family typewriter \begin_inset LatexDel \url{ \end_inset http://www.jclark.com \begin_inset LatexDel }{ \end_inset James Clark's WWW Page \begin_inset LatexDel } \end_inset \family default . \layout Itemize The emacs psgml package can be found at \family typewriter \begin_inset LatexDel \htmlurl{ \end_inset ftp://ftp.lysator.liu.se/pub/sgml \begin_inset LatexDel }{ \end_inset ftp://ftp.lysator.liu.se/pub/sgml \begin_inset LatexDel } \end_inset \family default . This package provides a lot of SGML functionality. \layout Itemize More information on \family typewriter LyX \family default can be found at the \family typewriter \begin_inset LatexDel \url{ \end_inset http://wsiserv.informatik.uni-tuebingen.de/~ettrich/ \begin_inset LatexDel }{ \end_inset LyX WWW Page \begin_inset LatexDel } \end_inset \family default . \family typewriter LyX \family default 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. \the_end