735 lines
31 KiB
Plaintext
735 lines
31 KiB
Plaintext
<!-- This is a linuxdoc-sgml User's Guide, by Matt Welsh
|
|
See guide.txt or guide.dvi for formatted output.
|
|
(You need to read this before you can format the source!)
|
|
-->
|
|
|
|
<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN">
|
|
|
|
<article>
|
|
|
|
<title>Linuxdoc-SGML User's Guide
|
|
<author>Matt Welsh, <tt/mdw@sunsite.unc.edu/
|
|
<date>v1.3, 7 June 1994
|
|
<abstract>
|
|
This document is a user's guide to the linuxdoc-sgml formatting system,
|
|
an SGML-based text formatter which allows you to produce LaTeX, plain
|
|
ASCII, and HTML from a single source format. This guide documents
|
|
Linuxdoc-SGML version 1.1.
|
|
</abstract>
|
|
|
|
<toc>
|
|
|
|
<sect>Introduction
|
|
|
|
<p>
|
|
This is a user's guide to the <tt/linuxdoc-sgml/ document
|
|
processing system, for use with Linux documentation. <tt/linuxdoc-sgml/
|
|
is an SGML DTD (Document Type Definition) and set of ``replacement files''
|
|
which convert the SGML to <tt/groff/, LaTeX, and HTML source. In the future,
|
|
<tt/linuxdoc-sgml/ will support <tt/texinfo/, as well as other
|
|
formats.
|
|
|
|
<tt/linuxdoc-sgml/ is based heavily on the QWERTZ DTD by Tom Gordon,
|
|
<tt/thomas.gordon@gmd.de/. I have only made revisions to his DTD and
|
|
replacement files for use by Linux documentation.
|
|
|
|
<tt/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. There's nothing binding <tt/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.
|
|
|
|
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 ASCII through manual editing. A system like <tt/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
|
|
<tt/texinfo/. Therefore, if there are features missing from this system
|
|
that you would like, <em/please let me know!/ The idea is that we shouldn't
|
|
have to use a lot of hackery to produce good-looking docs in multiple formats.
|
|
The author should have to do as little as possible.
|
|
|
|
<sect1>About this document
|
|
|
|
<p>
|
|
This document is written using the <tt/linuxdoc-sgml/ DTD. It contains
|
|
more or less everything you need to know to write SGML docs with this
|
|
DTD. See <tt/example.sgml/ for an example of an SGML document that you
|
|
can use as a model for your own docs.
|
|
|
|
<sect1>Why SGML?
|
|
|
|
<p>
|
|
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 <em/structure/ 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). <tt/linuxdoc-sgml/ is one DTD that specifies
|
|
the structure for Linux HOWTOs and other docs. 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 <em/emphasized text/. Unlike LaTeX, however,
|
|
these elements are not in any way intrinsic to SGML itself. The
|
|
<tt/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 <tt/linuxdoc-sgml/ DTD is like LaTeX.
|
|
|
|
Don't be confused by this analogy. SGML is <em/not/ a text-formatting system.
|
|
There is no ``SGML formatter'' per se. SGML source is <em/only/ 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.
|
|
|
|
<sect1>How it works
|
|
|
|
<p>
|
|
Here's how processing a document with SGML and the <tt/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 <tt/linuxdoc-sgml/ DTD for our purposes.
|
|
The DTD simply sets up the structure of the document. A small portion of
|
|
it looks like this:
|
|
<tscreen><verb>
|
|
<!element article - -
|
|
(titlepag, header?,
|
|
toc?, lof?, lot?, p*, sect*,
|
|
(appendix, sect+)?, biblio?) +(footnote)>
|
|
</verb></tscreen>
|
|
This part sets up the overall structure for an ``article'', which is like
|
|
a ``documentstyle'' within LaTeX. The article consists of a titlepage
|
|
(<tt/titlepag/), an optional header (<tt/header/), an optional table of
|
|
contents (<tt/toc/), optional lists of figures (<tt/lof/) and tables
|
|
(<tt/lot/), any number of paragraphs (<tt/p/), any number of top-level
|
|
sections (<tt/sect/), optional appendices (<tt/appendix/), an optional
|
|
bibliography (<tt/biblio/) and footnotes (<tt/footnote/).
|
|
|
|
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
|
|
<tt/titlepag/, <tt/header/, <tt/sect/, 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 <em/do/ need to be familiar with
|
|
the document <em/structure/ 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 <tt/linuxdoc-sgml/ documents in detail later.
|
|
|
|
The next step is to write a document using the structure defined by the
|
|
DTD. Again, the <tt/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 nroff) for processing, the SGML source (the document that you wrote)
|
|
is <em/parsed/ along with the DTD by (you guessed it) the SGML <em/parser/.
|
|
I'm using the <tt/sgmls/ parser by James Clark, <tt/jjc@jclark.com/, who
|
|
also happens to be the author of <tt/groff/. We're in good hands.
|
|
The parser (the executable <tt/sgmls/ 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 <tt/sgmlsasp/, the next part of the
|
|
process.
|
|
|
|
<tt/sgmlsasp/ is responsible for converting the output of <tt/sgmls/ to
|
|
another format (such as LaTeX). It does this using <em/replacement files/,
|
|
which describe how to convert elements in the original SGML document into
|
|
corresponding source in the ``target'' format (such as LaTeX or <tt/nroff/).
|
|
|
|
For example, part of the replacement file for LaTeX looks like:
|
|
<tscreen><verb>
|
|
<itemize> + "\\begin{itemize}" +
|
|
&etago;itemize> + "\\end{itemize}" +
|
|
</verb></tscreen>
|
|
Which says that whenever you begin an <tt/itemize/ element in the
|
|
SGML source, it should be replaced with
|
|
<tscreen><verb>
|
|
\begin{itemize}
|
|
</verb></tscreen>
|
|
in the LaTeX source. (As I said, elements in the <tt/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
|
|
analogues 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 <tt/sgmlsasp/ 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.
|
|
|
|
<sect>Installation
|
|
<p>
|
|
The file <tt/linuxdoc-sgml.tar.gz/ contains everything that you need
|
|
to write SGML documents and convert them to LaTeX, nroff, and HTML.
|
|
In addition to this package, you will need one or both of the following:
|
|
<enum>
|
|
<item><tt/groff/. You <em/need/ version 1.08 or 1.09. Apparently some of
|
|
the margin-handling in <tt/groff/ 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 <em/will not work/.
|
|
You can get this from <tt/prep.ai.mit.edu/ in
|
|
<tt>/pub/gnu</tt>. There is a Linux binary version on <tt/sunsite/ as well.
|
|
You will need <tt/groff/ to produce plain ASCII from your SGML docs.
|
|
(TeX/LaTeX will be used to produce nicely-printed PostScript and .dvi).
|
|
|
|
<item>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 <tt/sunsite/). Of course, you only need TeX/LaTeX
|
|
if you want to format your SGML docs with LaTeX. So, installing TeX/LaTeX
|
|
is optional. See the section on the Linux HOWTO project below for how we'll
|
|
manage this vis-a-vis the Linux HOWTOs.
|
|
|
|
<item>If you want to view the generated HTML, I suggest getting NCSA Mosaic
|
|
2.2 or later.
|
|
|
|
</enum>
|
|
Neither of these are required by the SGML system, but I suggest that you get
|
|
one or the other in order to format your docs and verify that they look
|
|
all right before distributing them.
|
|
|
|
<sect1>Installing the software
|
|
|
|
<p>
|
|
The steps needed to install and configure the <tt/linuxdoc-sgml/ stuff are
|
|
as follows:
|
|
|
|
<enum>
|
|
<item>First, unpack the tar file <tt/linuxdoc-sgml.tar.gz/ somewhere.
|
|
This will create the directory <tt/linuxdoc-sgml/ where all of the SGML
|
|
files live. It doesn't matter where you unpack this file; just don't
|
|
move things around within the <tt/linuxdoc-sgml/ directory.
|
|
|
|
<item>Next, you need to compile the <tt/sgmls/ parser. In the
|
|
<tt>linuxdoc-sgml/sgmls-1.1</tt> directory, issue the commands:
|
|
<tscreen><verb>
|
|
$ make config.h
|
|
$ make
|
|
$ make install
|
|
$ make install.man
|
|
</verb></tscreen>
|
|
This should compile the parser and translator, and place the binaries
|
|
<tt/sgmls/, <tt/sgmlsasp/, and <tt/rast/ in <tt>linuxdoc-sgml/bin</tt>.
|
|
I suggest that you don't move those binaries from that location; instead,
|
|
make symlinks to them from <tt>/usr/local/bin</tt> or place
|
|
<tt>linuxdoc-sgml/bin</tt> on your path. (If you move things around
|
|
within the <tt/linuxdoc-sgml/ tree you'll have to edit a number of files
|
|
to get everything to cooperate again. Best to leave things as-is.)
|
|
|
|
If things don't work try editing the <tt/Makefile/ in the <tt/sgmls-1.1/
|
|
directory. I have it set to use <tt/gcc/ as the compiler, and use
|
|
rather malignant options. Compiles fine on Linux and sun-4 systems.
|
|
|
|
This will also install man pages for the three binaries in
|
|
<tt>linuxdoc-sgml/man</tt>. You can move those or link them to your
|
|
regular man page tree, should you need them.
|
|
|
|
<item>Edit the variables at the top of the scripts <tt/format/, <tt/qroff/,
|
|
<tt/preroff/, <tt/prehtml/, and <tt/qtex/ in <tt>linuxdoc-sgml/bin</tt>.
|
|
All you really need to edit is the value of the <tt>LINUXDOC</tt>
|
|
shell variable which gives the full pathname of the <tt>linuxdoc-sgml</tt>
|
|
directory.
|
|
|
|
<item>In the <tt>html-fix</tt> directory, issue the commands:
|
|
<tscreen><verb>
|
|
$ make
|
|
$ make install
|
|
</verb></tscreen>
|
|
This will build <tt>fixref</tt> and <tt>html2html</tt>, which are post
|
|
processors for the HTML conversion, and place them in the <tt>bin</tt>
|
|
directory.
|
|
|
|
</enum>
|
|
|
|
If all went well, you should be ready to use the system. Just be sure
|
|
that <tt>linuxdoc-sgml/bin</tt> is on your path or you've linked the
|
|
files therein to your standard binary directories. Again, don't just copy
|
|
them somewhere else; the scripts expect to find each other in that
|
|
directory.
|
|
|
|
<sect1>Testing it out
|
|
|
|
<p>
|
|
You can now test the system. The <tt/format/ script takes an SGML
|
|
document as input and translates it to a given format. The <tt/qtex/
|
|
script will process the output of <tt/format/ using LaTeX, and
|
|
<tt/qroff/ will process it using nroff.
|
|
|
|
Let's say you have the SGML document <tt/foo.sgml/. You can translate
|
|
it to LaTeX, and produce PostScript output (via <tt/dvips/) with
|
|
the command:
|
|
<tscreen><verb>
|
|
$ format -T latex foo | qtex > foo.ps
|
|
</verb></tscreen>
|
|
Or, you can produce a DVI file using the <tt>-d</tt> switch with
|
|
<tt>qtex</tt>, as so:
|
|
<tscreen><verb>
|
|
$ format -T latex foo | qtex -d > foo.dvi
|
|
</verb></tscreen>
|
|
|
|
If you want to produce plain ASCII, through <tt/groff/, use the command:
|
|
<tscreen><verb>
|
|
$ format -T nroff foo | qroff > foo.txt
|
|
</verb></tscreen>
|
|
Note that I have tailored the <tt/groff/ conversion for plain ASCII 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
|
|
<tt/groff/ resulting from <tt/format/, but I suggest that you use LaTeX
|
|
for that instead.
|
|
|
|
If you want to produce HTML, the procedure is a bit more complicated,
|
|
because of cross-references. Here's an example:
|
|
<tscreen><verb>
|
|
$ format -T html foo.sgml | prehtml | fixref > tmp.html
|
|
$ format -T html foo.sgml | prehtml >> tmp.html
|
|
$ cat tmp.html | html2html foo > foo.html
|
|
$ rm tmp.html
|
|
</verb></tscreen>
|
|
This will produce <tt>foo.html</tt>, as well as <tt>foo-1.html</tt>,
|
|
<tt/foo-2.html/, and so on---one file for each section of the document.
|
|
Run your WWW client on <tt>foo.html</tt>, which is the toplevel 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.
|
|
|
|
A good way to test this would be to run it on this file,
|
|
<tt/guide.sgml/.
|
|
|
|
If you just want to capture your errors from the SGML conversion,
|
|
use something like
|
|
<tscreen><verb>
|
|
$ format -T nroff foo > /dev/null
|
|
</verb></tscreen>
|
|
|
|
<sect1>Development note
|
|
<p>
|
|
|
|
The HTML conversion is, at this time, rudimentary but adequate. In the
|
|
future there will be support for cross-references, navigation buttons,
|
|
external URLs, and the like. Something is better than nothing. :)
|
|
|
|
Also, if you'd like to help me implement a texinfo (or plain Info)
|
|
conversion for Linuxdoc-SGML, let me know! As with HTML we'll have to
|
|
do some pre- and post-processing (which you supposedly shouldn't need with
|
|
SGML, ah well), but that's not a big issue.
|
|
|
|
<sect>Writing Documents with <tt/linuxdoc-sgml/
|
|
|
|
<p>
|
|
For the most part, writing documents using the <tt/linuxdoc/ 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 docs.
|
|
See the file <tt/example.sgml/ for an SGML example document (and tutorial)
|
|
which you can use as a model when writing your own docs. 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 <tt/example.sgml/ so you have a real live case to
|
|
refer to.
|
|
|
|
<sect1>Basic concepts
|
|
|
|
<p>
|
|
Looking at the source of the example document, you'll notice right off
|
|
that there are a number of ``tags'' marked within angle brackets
|
|
(<tt><</tt> and <tt/>/). 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 <tt>\item</tt> or
|
|
<tt>\section{...}</tt>.
|
|
|
|
As a simple example, to produce <bf>this boldfaced text</bf>, I typed
|
|
<tscreen><verb>
|
|
As a simple example, to produce <bf>this boldfaced text&etago;bf>, ...
|
|
</verb></tscreen>
|
|
in the source. <tt><bf></tt> begins the region of bold text, and
|
|
<tt>&etago;bf></tt> ends it. Alternately, use can use the abbreviated form
|
|
<tscreen><verb>
|
|
As a simple example, to produce <bf/this boldfaced text/, ...
|
|
</verb></tscreen>
|
|
which encloses the bold text within slashes. (Of course, you'll need to
|
|
use the long form if the enclosed text contains slashes, such as the
|
|
case with UNIX filenames).
|
|
|
|
There are other things to watch out with respect to special characters
|
|
(that's why you'll notice all of these bizarre-looking ampersand
|
|
expressions if you look at the source; I'll talk about those shortly).
|
|
|
|
In some cases, the end-tag for a particular element is optional. For
|
|
example, to begin a section, you use the <tt><sect></tt> 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 (<tt/example.sgml/), and feel free to ask me if you
|
|
have any questions about the particulars.
|
|
|
|
<sect1>Special characters
|
|
|
|
<p>
|
|
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: <tt><foo></tt>. In order to get the left angle bracket, you
|
|
must use the <tt>&lt</tt> element, which is a ``macro'' that expands
|
|
to the actual left-bracket character. Therefore, in the source, I typed
|
|
<tscreen><verb>
|
|
angle brackets around it, as so: <tt>&ero;lt;foo>&etago;tt>.
|
|
</verb></tscreen>
|
|
Generally, something beginning with an ampersand is a special macro. For
|
|
example, there's <tt/&percnt/ to produce <tt>%</tt>,
|
|
<tt/&verbar/ to produce <tt>|</tt>, 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:
|
|
<itemize>
|
|
<item>Use <tt>&amp;</tt> for the ampersand (<tt>&</tt>),
|
|
<item>Use <tt>&lt;</tt> for a left bracket (<tt><</tt>),
|
|
<item>Use <tt>&gt;</tt> for a right bracket (<tt>></tt>),
|
|
<item>Use <tt>&etago;</tt> for a left bracket with a slash
|
|
(<tt>&etago;</tt>)
|
|
<item>Use <tt>&dollar;</tt> for a dollar sign (<tt>$</tt>),
|
|
<item>Use <tt>&num;</tt> for a hash (<tt>#</tt>),
|
|
<item>Use <tt>&percnt;</tt> for a percent (<tt>%</tt>),
|
|
<item>Use <tt>``</tt> and <tt>''</tt> for quotes, or use
|
|
<tt>&dquot</tt> for <tt>&dquot;</tt>.
|
|
</itemize>
|
|
|
|
<sect1>Verbatim and code environments
|
|
|
|
<p>
|
|
While we're on the subject of special characters, I might as well mention
|
|
the verbatim ``environment'' used for including literal text in the output
|
|
(with spaces and indentation preserved, and so on). The
|
|
<tt>verb</tt> element is used for this; it looks like the following:
|
|
<tscreen><verb>
|
|
<verb>
|
|
Some literal text to include as example output.
|
|
&etago;verb>
|
|
</verb></tscreen>
|
|
The <tt>verb</tt> environment doesn't allow you to use <em/everything/
|
|
within it literally. Specifically, you must do the following within
|
|
<tt/verb/ environments.
|
|
<itemize>
|
|
<item>Use <tt>&ero;</tt> to get an ampersand,
|
|
<item>Use <tt>&etago;</tt> to get <tt>&etago;</tt>,
|
|
<item>Don't use <tt>\end{verbatim}</tt> within a <tt>verb</tt>
|
|
environment, as this is what LaTeX uses to end the <tt>verbatim</tt>
|
|
environment. (In the future, it should be possible to hide the underlying
|
|
text formatter entirely, but the parser doesn't support this feature yet.)
|
|
</itemize>
|
|
The <tt>code</tt> environment is much just like the <tt/verb/ environment,
|
|
except that horizontal rules are added to the surrounding text, as so:
|
|
<code>
|
|
Here is an example code environment.
|
|
</code>
|
|
|
|
You should use the <tt/tscreen/ environment around any <tt/verb/ environments,
|
|
as so:
|
|
<tscreen><verb>
|
|
<tscreen><verb>
|
|
Here is some example text.
|
|
&etago;verb>&etago;tscreen>
|
|
</verb></tscreen>
|
|
<tt/tscreen/ is an environment that simply indents the text and sets the
|
|
sets the default font to <tt/tt/. This makes examples look much nicer, both
|
|
in the LaTeX and plain ASCII versions. You can use <tt/tscreen/
|
|
without <tt/verb/, however, if you use any special characters in your
|
|
example you'll need to use both of them. <tt/tscreen/ does nothing to
|
|
special characters. See <tt/example.sgml/ for examples.
|
|
|
|
The <tt/quote/ environment is like <tt/tscreen/, except that it does
|
|
not set the default font to <tt/tt/. So, you can use <tt/quote/ for
|
|
non-computer-interaction quotes, as in:
|
|
<tscreen><verb>
|
|
<quote>
|
|
Here is some text to be indented, as in a quote.
|
|
&etago;quote>
|
|
</verb></tscreen>
|
|
which will generate:
|
|
<quote>
|
|
Here is some text to be indented, as in a quote.
|
|
</quote>
|
|
|
|
<sect1>Overall document structure
|
|
|
|
<p>
|
|
Before we get too in-depth with details, I'm going to describe the
|
|
overall structure of a document as defined by the <tt/linuxdoc/ DTD.
|
|
Look at <tt/example.sgml/ for a good example of how a document is set up.
|
|
|
|
<sect2>The preamble
|
|
|
|
<p>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:
|
|
<tscreen><verb>
|
|
<!doctype linuxdoc system>
|
|
|
|
<article>
|
|
|
|
<title>The Linux Food-Processing HOWTO
|
|
<author>Norbert Ebersol, <tt/norbert@foo.com/
|
|
<date>v1.0, 9 March 1994
|
|
<abstract>
|
|
This document describes how to connect your Linux machine to a food-processor
|
|
for dicing vegetables.
|
|
&etago;abstract>
|
|
|
|
<toc>
|
|
</verb></tscreen>
|
|
|
|
The elements should go more or less in this order. The first line tells
|
|
the SGML parser to use the <tt/linuxdoc/ DTD. The <tt><article></tt>
|
|
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 <tt/linuxdoc-sgml/. Just use <tt/article/ for
|
|
you SGML docs, for now.)
|
|
|
|
The <tt/title/, <tt/author/, and <tt/date/ tags should be obvious; in the
|
|
<tt>date</tt> tag include the version number and last modification time of
|
|
the document.
|
|
|
|
Thr <tt/abstract/ tag sets up the text to be printed at the top of the
|
|
document, <em/before/ the table of contents. If you're not going to
|
|
include a table of contents (the <tt/toc/ tag), you probably don't
|
|
need an <tt/abstract/. 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.
|
|
|
|
<sect2>Sectioning and paragraphs
|
|
|
|
<p>After the preamble, you're ready to dive into the document. The following
|
|
sectioning commands are available:
|
|
<itemize>
|
|
<item><tt/sect/: For top-level sections (i.e. 1, 2, and so on.)
|
|
<item><tt/sect1/: For second-level subsections (i.e. 1.1, 1.2, and so on.)
|
|
<item><tt/sect2/: For third-level subsubsections.
|
|
<item><tt/sect3/: For fourth-level subsubsubsections.
|
|
<item><tt/sect4/: For fifth-level subsubsubsubsections.
|
|
</itemize>
|
|
These are roughly equivalent to their LaTeX counterparts <tt/section/,
|
|
<tt/subsection/, and so on.
|
|
|
|
After the <tt/sect/ (or <tt/sect1/, <tt/sect2/, etc.) tag comes the
|
|
name of the section. For example, at the top of this document, after
|
|
the preamble, comes the tag:
|
|
<tscreen><verb>
|
|
<sect>Introduction
|
|
</verb></tscreen>
|
|
And at the beginning of this section (Sectioning and paragraphs), there
|
|
is the tag:
|
|
<tscreen><verb>
|
|
<sect2>Sectioning and paragraphs
|
|
</verb></tscreen>
|
|
|
|
After the section tag, you begin the body of the section. However, you
|
|
must start the body with a <tt><p></tt> tag, as so:
|
|
<tscreen><verb>
|
|
<sect>Introduction
|
|
|
|
<p>
|
|
This is a user's guide to the <tt/linuxdoc-sgml/ document processing...
|
|
</verb></tscreen>
|
|
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,
|
|
<tscreen><verb>
|
|
Here is the end of the first paragraph.
|
|
|
|
And we start a new paragraph here.
|
|
</verb></tscreen>
|
|
There is no reason to use <tt><p></tt> tags at the beginning of
|
|
every paragraph; only at the beginning of the first paragraph after
|
|
a sectioning command.
|
|
|
|
<sect2>Ending the document
|
|
|
|
<p>At the end of the document, you must use the tag:
|
|
<tscreen><verb>
|
|
&etago;article>
|
|
</verb></tscreen>
|
|
|
|
to tell the parser that you're done with the <tt/article/ element (which
|
|
embodies the entire document).
|
|
|
|
</sect2>
|
|
<sect1>Cross-references<label id="cross-ref">
|
|
|
|
<p>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:
|
|
<tscreen><verb>
|
|
<sect1>Introduction<label id="sec-intro">
|
|
</verb></tscreen>
|
|
You can then refer to that section somewhere in the text using the
|
|
expression:
|
|
<tscreen><verb>
|
|
See section <ref id="sec-intro" name="Introduction"> for an introduction.
|
|
</verb></tscreen>
|
|
This will replace the <tt/ref/ tag with the section number labeled
|
|
as <tt/sec-intro/. The <tt/name/ argument to <tt/ref/ is necessary for
|
|
<tt/nroff/ and HTML translations (at the moment). The <tt/nroff/
|
|
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 <ref id="cross-ref" name="Cross-references">.
|
|
|
|
There is also a <tt/url/ 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,
|
|
<tscreen><verb>
|
|
You can get the Linux HOWTO documents from
|
|
<url url="http://sunsite.unc.edu/mdw/linux.html"
|
|
name="the Linux Documentation Project home page">.
|
|
</verb></tscreen>
|
|
The <tt/url/ argument specifies the actual URL itself. A link to the
|
|
URL in question will be automatically added to the HTML document.
|
|
The optional <tt/name/ 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 <tt/nroff/). If no <tt/name/ argument is given, the
|
|
URL itself will be used.
|
|
|
|
For example, you can get the Linuxdoc-SGML package from
|
|
<url url="ftp://ftp.cs.cornell.edu/mdw/linuxdoc-sgml-1.1.tar.gz">.
|
|
|
|
<sect1>Fonts
|
|
|
|
<p>Essentially, the same fonts supported by LaTeX are supported
|
|
by <tt/linuxdoc-sgml/. Note, however, that the conversion to
|
|
plain ASCII (through <tt/groff/) does away with the font
|
|
information---I might hack up plain-ASCII representations of the
|
|
various fonts if the need arises. 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
|
|
ASCII version.
|
|
|
|
In particular, the <tt/tt/ 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:
|
|
<tscreen><verb>
|
|
Here is some <tt>typewriter text&etago;tt> to be included in the document.
|
|
</verb></tscreen>
|
|
Equivalently:
|
|
<tscreen><verb>
|
|
Here is some <tt/typewriter text/ to be included in the document.
|
|
</verb></tscreen>
|
|
Remember that you can only use this abbreviated form if the enclosed
|
|
text doesn't contain slashes.
|
|
|
|
Other fonts can be achieved with <tt/bf/ for <bf/boldface/ and <tt/em/
|
|
for <tt/italics/. 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.
|
|
|
|
<sect1>Lists
|
|
|
|
<p>There are various kinds of supported lists. They are:
|
|
<itemize>
|
|
<item><tt/itemize/ for bulleted lists such as this one.
|
|
<item><tt/enum/ for numbered lists.
|
|
<item><tt/descrip/ for ``descriptive'' lists.
|
|
</itemize>
|
|
Each item in an <tt/itemize/ or <tt/enum/ list must be marked
|
|
with an <tt/item/ tag. Items in a <tt/descrip/ are marked with <tt/tag/.
|
|
For example,
|
|
<tscreen><verb>
|
|
<itemize>
|
|
<item>Here is an item.
|
|
<item>Here is a second item.
|
|
&etago;itemize>
|
|
</verb></tscreen>
|
|
Looks like this:
|
|
<itemize>
|
|
<item>Here is an item.
|
|
<item>Here is a second item.
|
|
</itemize>
|
|
Or, for an <tt/enum/,
|
|
<tscreen><verb>
|
|
<enum>
|
|
<item>Here is the first item.
|
|
<item>Here is the second item.
|
|
&etago;enum>
|
|
</verb></tscreen>
|
|
You get the idea. Lists can be nested as well; see the example document
|
|
for details.
|
|
|
|
A <tt/descrip/ list is slightly different, and slightly ugly, but
|
|
you might want to use it for some situations:
|
|
<tscreen><verb>
|
|
<descrip>
|
|
<tag/Gnats./ Annoying little bugs that fly into your cooling fan.
|
|
<tag/Gnus./ Annoying little bugs that run on your CPU.
|
|
&etago;descrip>
|
|
</verb></tscreen>
|
|
ends up looking like:
|
|
<descrip>
|
|
<tag/Gnats./ Annoying little bugs that fly into your cooling fan.
|
|
<tag/Gnus./ Annoying little bugs that run on your CPU.
|
|
</descrip>
|
|
|
|
<sect1>Miscellany
|
|
|
|
<p>
|
|
There are various other esoteric features in the system as well, most
|
|
of which you probably won't use. If you're curious, read the QWERTZ
|
|
User's Guide (from <tt/ftp.cs.cornell.edu/ in <tt>pub/mdw/SGML</tt>).
|
|
QWERTZ (and hence, <tt/linuxdoc/) 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 ASCII. If you'd like to write general documentation in
|
|
SGML, I suggest using the original QWERTZ DTD instead of the hacked-up
|
|
<tt/linuxdoc/ DTD, which I've modified for use particularly by the Linux
|
|
HOWTOs and other documentation.
|
|
|
|
The bottom line is, <tt/linuxdoc-sgml/ supports many other features found
|
|
in the QWERTZ DTD, but I haven't necessarily tweaked them to work well
|
|
with <tt/linuxdoc-sgml/. If you encounter problems with any of them,
|
|
please let me know.
|
|
|
|
<sect>The Linux HOWTO project
|
|
|
|
<p>How does this tie into writing HOWTOs? First of all, I'd like to see
|
|
everyone eventually convert their HOWTOs to SGML using this DTD. This has
|
|
a number of advantages. First of all, it will allow you to just send me
|
|
the SGML source, which I'll convert to plain ASCII, TeX, whatever, for
|
|
posting and archiving. Also, it will give the HOWTOs a common look and feel;
|
|
any changes that I make to the DTD will be reflected in all of the HOWTOs.
|
|
|
|
I have set up the <tt/linuxdoc/ DTD to have a certain look and feel.
|
|
If you want your document to look differently, please let me know, because
|
|
I'll need to make those changes in the DTD itself. That is, <em/do not/
|
|
modify your version of the DTD or replacement files to get other features
|
|
in the system. We all must use the same DTD and replacement files or
|
|
this whole system will break down. If you find bugs in it, or have suggestions
|
|
for how we can change thing or add/modify features, let me know. I'll be
|
|
more than happy to accommodate you.
|
|
|
|
</article>
|