918 lines
41 KiB
HTML
918 lines
41 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
|
|
<TITLE>
|
|
First Example (example1)
|
|
</TITLE>
|
|
</HEAD>
|
|
<BODY BGCOLOR=white>
|
|
|
|
<HR>
|
|
<H1></H1>
|
|
|
|
<H2>David S. Lawyer</H2>v0.09, November 2007
|
|
<HR>
|
|
<EM>This is about how to write HOWTOs using the simple LinuxDoc markup.
|
|
It's primarily for Linux Documentation Project authors (and future
|
|
fledging authors who want to get started fast). If you want to use
|
|
the more difficult and complex DocBook markup (including XML) see the
|
|
LDP Authoring Guide.</EM>
|
|
<HR>
|
|
<P>
|
|
<H2><A NAME="toc1">1.</A> <A HREF="#s1">Introduction </A></H2>
|
|
|
|
<UL>
|
|
<LI><A NAME="toc1.1">1.1</A> <A HREF="#ss1.1">If you want to start immediately</A>
|
|
<LI><A NAME="toc1.2">1.2</A> <A HREF="#ss1.2">Copyright and License</A>
|
|
<LI><A NAME="toc1.3">1.3</A> <A HREF="#ss1.3">Should you write a HOWTO ?</A>
|
|
<LI><A NAME="toc1.4">1.4</A> <A HREF="#ss1.4">Why I wrote this</A>
|
|
</UL>
|
|
<P>
|
|
<H2><A NAME="toc2">2.</A> <A HREF="#s2">Information on Writing a HOWTO</A></H2>
|
|
|
|
<UL>
|
|
<LI><A NAME="toc2.1">2.1</A> <A HREF="#ss2.1">Copyright</A>
|
|
<LI><A NAME="toc2.2">2.2</A> <A HREF="#ss2.2">Choosing a topic</A>
|
|
</UL>
|
|
<P>
|
|
<H2><A NAME="toc3">3.</A> <A HREF="#s3">The Format of HOWTOs </A></H2>
|
|
|
|
<UL>
|
|
<LI><A NAME="toc3.1">3.1</A> <A HREF="#ss3.1">Introduction</A>
|
|
</UL>
|
|
<P>
|
|
<H2><A NAME="toc4">4.</A> <A HREF="#s4">Comparing LinuxDoc to DocBook </A></H2>
|
|
|
|
<P>
|
|
<H2><A NAME="toc5">5.</A> <A HREF="#s5">Learning LinuxDoc </A></H2>
|
|
|
|
<UL>
|
|
<LI><A NAME="toc5.1">5.1</A> <A HREF="#ss5.1">Introduction</A>
|
|
<LI><A NAME="toc5.2">5.2</A> <A HREF="#ss5.2">Example 1 (file name: example1.sgml) </A>
|
|
<LI><A NAME="toc5.3">5.3</A> <A HREF="#ss5.3">Example 2 (file name: example2.sgml)</A>
|
|
<LI><A NAME="toc5.4">5.4</A> <A HREF="#ss5.4">Example 3 </A>
|
|
<LI><A NAME="toc5.5">5.5</A> <A HREF="#ss5.5">LinuxDoc Quick Reference Sheet</A>
|
|
</UL>
|
|
<P>
|
|
<H2><A NAME="toc6">6.</A> <A HREF="#s6">Getting/Using the LinuxDoc Software</A></H2>
|
|
|
|
<P>
|
|
<H2><A NAME="toc7">7.</A> <A HREF="#s7">Errors and Error Messages</A></H2>
|
|
|
|
<UL>
|
|
<LI><A NAME="toc7.1">7.1</A> <A HREF="#ss7.1">Errors That Don't Create Error Messages</A>
|
|
<LI><A NAME="toc7.2">7.2</A> <A HREF="#ss7.2">Actual Error Messages</A>
|
|
</UL>
|
|
<P>
|
|
<H2><A NAME="toc8">8.</A> <A HREF="#s8">Jargon in Error Messages</A></H2>
|
|
|
|
<UL>
|
|
<LI><A NAME="toc8.1">8.1</A> <A HREF="#ss8.1">Introduction</A>
|
|
<LI><A NAME="toc8.2">8.2</A> <A HREF="#ss8.2">Elements</A>
|
|
<LI><A NAME="toc8.3">8.3</A> <A HREF="#ss8.3">Literals and Delimiters</A>
|
|
</UL>
|
|
<P>
|
|
<H2><A NAME="toc9">9.</A> <A HREF="#s9">Writing the HOWTO</A></H2>
|
|
|
|
<UL>
|
|
<LI><A NAME="toc9.1">9.1</A> <A HREF="#ss9.1">Before you start writing</A>
|
|
<LI><A NAME="toc9.2">9.2</A> <A HREF="#ss9.2">Guidelines</A>
|
|
<LI><A NAME="toc9.3">9.3</A> <A HREF="#ss9.3">Submitting the HOWTO, etc.</A>
|
|
</UL>
|
|
<P>
|
|
<H2><A NAME="toc10">10.</A> <A HREF="#s10">More Information </A></H2>
|
|
|
|
<P>
|
|
<H2><A NAME="toc11">11.</A> <A HREF="#s11">Appendix</A></H2>
|
|
|
|
<UL>
|
|
<LI><A NAME="toc11.1">11.1</A> <A HREF="#ss11.1">Old Problem of Escape Sequences in Text Output</A>
|
|
</UL>
|
|
<HR>
|
|
<H2><A NAME="s1">1.</A> <A HREF="Howtos-with-LinuxDoc.html#toc1">Introduction </A></H2>
|
|
|
|
<H2><A NAME="ss1.1">1.1</A> <A HREF="Howtos-with-LinuxDoc.html#toc1.1">If you want to start immediately</A>
|
|
</H2>
|
|
|
|
<P>To only learn LinuxDoc, skip to
|
|
<A HREF="#learn_">Learning LinuxDoc</A>. If you want to start writing immediately, then you may try a
|
|
"fill in the blanks" template which will generate LinuxDoc formatted
|
|
output.
|
|
<A HREF="http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html">The LDP HOWTO Generator</A>. You may use this to just start
|
|
writing your Howto and then finish it later by using a text editor on
|
|
your PC.</P>
|
|
|
|
<H2><A NAME="ss1.2">1.2</A> <A HREF="Howtos-with-LinuxDoc.html#toc1.2">Copyright and License</A>
|
|
</H2>
|
|
|
|
<P> Copyright (c) 2001-7 by David S. Lawyer. You may freely copy and
|
|
distribute (sell or give away) this document. You may create a
|
|
derivative work and distribute it provided that you license it in the
|
|
spirit of this license and give proper credits. The author would like
|
|
to receive your comments, suggestions, and plans for any derivative
|
|
work based on this.</P>
|
|
|
|
<H2><A NAME="ss1.3">1.3</A> <A HREF="Howtos-with-LinuxDoc.html#toc1.3">Should you write a HOWTO ?</A>
|
|
</H2>
|
|
|
|
<P> Do you know things about Linux for which no good free
|
|
documentation is available and which would be useful to others? Even
|
|
if you don't know the subject well, you can still write about it if
|
|
you're eager, willing, and able to learn more about it and have the
|
|
time to do it. Can you write clearly using a word processor or
|
|
editor? Do you want to help thousands of others and let them read
|
|
what you write at no cost to them? Once you've written a document,
|
|
are you willing to receive email suggestions from readers and
|
|
selectively use this info for improving your HOWTO? Would you like to
|
|
have your writings be available on hundreds of websites throughout the
|
|
world? If you can answer yes to these, then you're encouraged to
|
|
write something for the Linux Documentation Project (LDP). But be
|
|
warned that it may take more time than you expected.</P>
|
|
|
|
<H2><A NAME="ss1.4">1.4</A> <A HREF="Howtos-with-LinuxDoc.html#toc1.4">Why I wrote this</A>
|
|
</H2>
|
|
|
|
<P>Why did I write this when there is already an "LDP Authoring
|
|
Guide"? Well, the LDP guide is a long and detailed work. If you want
|
|
to get started quickly, you need something much simpler and shorter.</P>
|
|
<P>Thanks to Matt Welsh for his example.sgml file which I used as a major
|
|
source of info for the example sections.</P>
|
|
|
|
<HR>
|
|
<H2><A NAME="s2">2.</A> <A HREF="Howtos-with-LinuxDoc.html#toc2">Information on Writing a HOWTO</A></H2>
|
|
|
|
<H2><A NAME="ss2.1">2.1</A> <A HREF="Howtos-with-LinuxDoc.html#toc2.1">Copyright</A>
|
|
</H2>
|
|
|
|
<P> All HOWTOs and other LDP documents are copyright by the authors so
|
|
the LDP doesn't have any special rights to your writing. We only accept
|
|
documents that have a license which permits anyone to copy and
|
|
distribute the document. We encourage authors to also allow
|
|
modification in their license. This way, if the author stops
|
|
maintaining a document, someone else can do so. For more details see
|
|
our Manifesto.</P>
|
|
|
|
<H2><A NAME="ss2.2">2.2</A> <A HREF="Howtos-with-LinuxDoc.html#toc2.2">Choosing a topic</A>
|
|
</H2>
|
|
|
|
<P> If you are not sure what to write about, take look at some of
|
|
LDP's documents including the ones in
|
|
<A HREF="http://www.tldp.org/authors/unmaint.html">Unmaintained HOWTOs</A>. Pick a topic you're interested in that needs good
|
|
documentation. If you find something already written and maintained
|
|
that needs improvement, try to contact the author, first and make
|
|
suggestions. If you can't reach the author, look at the license and
|
|
see if you're allowed to modify the document. But even in the cases
|
|
where you are not allowed to make modifications and improvements, you
|
|
can just write a new document on the same topic from scratch, using a
|
|
new outline new sources of information.</P>
|
|
|
|
<HR>
|
|
<H2><A NAME="s3">3.</A> <A HREF="Howtos-with-LinuxDoc.html#toc3">The Format of HOWTOs </A></H2>
|
|
|
|
<H2><A NAME="ss3.1">3.1</A> <A HREF="Howtos-with-LinuxDoc.html#toc3.1">Introduction</A>
|
|
</H2>
|
|
|
|
<P> Our HOWTOs are released to the public in various formats: Plain
|
|
Text, HTML, PostScript, and PDF. Instead of having to write the same
|
|
HOWTO in all of these formats, just one HOWTO is written in a source
|
|
format, DocBook or LinuxDoc, which gets converted by computer into all
|
|
of the other formats.</P>
|
|
<P>To get an idea of what a source format looks like, take a look at the
|
|
source file of a webpage (if you haven't already). You will see all
|
|
sorts of words in <angle brackets>. These are called tags.
|
|
These webpages (tags and all) are in html: <EM>Hypertext Markup
|
|
Language</EM>. The LDP uses formats something like this for its
|
|
documents.</P>
|
|
<P>The markup languages LDP uses meet the requirements of either
|
|
<EM>Standard Generalized Markup Language (SGML)</EM> or <EM>XML</EM>.
|
|
The LDP now uses the following two flavors of sgml: <EM>LinuxDoc</EM> and
|
|
<EM>DocBook</EM> as well as the <EM>DocBook</EM> flavor of XML.
|
|
Interestingly, it turns out that html is just another flavor of sgml
|
|
(but some features people use in html violate sgml rules so it's not
|
|
pure sgml anymore).</P>
|
|
<P>This mini-HOWTO is all about using the simple LinuxDoc flavor of sgml.
|
|
You may call it "LinuxDoc markup". It can be converted by computer to
|
|
html, plain text, postscript, pdf, and DocBook. It's a lot easier
|
|
than HTML or DocBook and you don't need a special editor for it as
|
|
it's easy to type in the tags (or use macros for them) using your
|
|
favorite editor or word processor.</P>
|
|
|
|
<HR>
|
|
<H2><A NAME="ld_vs_db"></A> <A NAME="s4">4.</A> <A HREF="Howtos-with-LinuxDoc.html#toc4">Comparing LinuxDoc to DocBook </A></H2>
|
|
|
|
<P>Before reading this section it's best to have at least an
|
|
elementary knowledge of tags in markup languages. So if you don't
|
|
know much about this, you may first want to look at
|
|
<A HREF="#example_1">Example 1</A> for LinuxDoc markup.</P>
|
|
<P>One way to compare is to inspect real HOWTOs at the LDP site. Click
|
|
on either
|
|
<A HREF="http://cvs.tldp.org/go.to/LDP/LDP/howto/docbook/">DocBook Index</A> or
|
|
<A HREF="http://cvs.tldp.org/go.to/LDP/LDP/howto/linuxdoc/">LinuxDoc Index</A> to find them. You'll notice that the DocBook docs are
|
|
cluttered with tags while the LinuxDoc docs have far fewer tags and
|
|
are thus more readable and easier to write and modify. Some documents
|
|
at LDP are marked up much more clearly than others so you should
|
|
inspect at least a few documents.</P>
|
|
<P>You may at first think that DocBook is more advanced since there are
|
|
so many more tags but this isn't necessarily so. If you create a
|
|
document in LinuxDoc and convert it to DocBook (by computer) there
|
|
will be many more tags in the DocBook version, including new tags that
|
|
were not in the LinuxDoc version. Why? Because LinuxDoc permits the
|
|
omission of tags while DocBook doesn't. And in this way LinuxDoc is
|
|
more flexible and advanced than DocBook. Not only does LinuxDoc often
|
|
allow the omission of end-tags like </title> but allows the
|
|
omission of both start and end tag pairs. For example, in LinuxDoc
|
|
paragraphs are normally separated by blank lines instead of pairs of
|
|
paragraph tags <p> (<para> in DocBook) so that paragraph
|
|
tags are seldom needed. Another example is just after the start of
|
|
a new section of a LinuxDoc document. You just type in the title of
|
|
the section after the <sect> tag while DocBook requires one to
|
|
also enclose the title in a pair of <title> tags.</P>
|
|
<P>When one runs a program to convert LinuxDoc to say HTML, the first
|
|
thing the program does is to find all the omitted tags and add them to
|
|
the document. For example, a pair of tags are added which are
|
|
equivalent to the pair of <title> tags after a <sect> tag
|
|
(including the cases of <sect1> tags, etc.). So in a sense,
|
|
LinuxDoc also has a lot of tags, but they are hidden from the user to
|
|
make the document both much easier to write and read. In most cases,
|
|
the author writing a document in LinuxDoc is unaware of the existence
|
|
of most of the missing tags. There's no need (in most cases) for the
|
|
author to know about them since they exist only in the computer memory
|
|
(or a temporary file) when the PC is converting LinuxDoc to some other
|
|
format (like to HTML). Well, it is possible to save a file showing
|
|
the added tags but that is done mainly by programmers debugging the
|
|
LinuxDoc computer code (or by people like me that are curious about
|
|
how it works).</P>
|
|
<P>The DocBook tags are often longer than the equivalent LinuxDoc tags
|
|
such as <em> instead of <emphasis>. For a short
|
|
comparison see the author's website
|
|
<A HREF="http://www.lafn.org/~dave/linux/ld_vs_db.txt">Comparison of DocBook to LinuxDoc</A></P>
|
|
<P>However, the fact that many tags are omitted when writing LinuxDoc (but
|
|
are found by the software) is only one reason why LinuxDoc documents
|
|
have fewer tags. Another reason is that DocBook actually has many
|
|
more tags to use than LinuxDoc does. For example, LinuxDoc has just
|
|
one tag for the author's name while DocBook has separate tags for the
|
|
first middle and last names. So in this sense DocBook is more
|
|
powerful than LinuxDoc but in another sense it's weaker since it can't
|
|
find missing tags. The solution to this dilemma would be to merge
|
|
LinuxDoc with DocBook so as to retain the advantages of each. DocBook
|
|
would then need to abandon it's current status as a "xml" language
|
|
since xml prohibits the omission of tags, etc. while sgml allows it.</P>
|
|
<P>One reason why omitted tags are not allowed in DocBook is that it makes
|
|
it easier for programmers to write software to parse it and convert it
|
|
to other formats. There is no need for software capable of finding
|
|
and adding missing tags. But making it easier for programmers, makes
|
|
it more difficult for the much large number of writers that have to
|
|
use DocBook.</P>
|
|
<P>There are special editors or word processors like Lyx and Bluefish
|
|
that make it easier to type DocBook documents. For example, Bluefish
|
|
automatically adds end tags. But for people who don't want to learn a
|
|
new editor or word processor, LinuxDoc is a lot easier since one can
|
|
type in the tags by hand or create a set of macros to insert the
|
|
(<emphasis> tags. I use the vim editor and if I type ;s it
|
|
inserts the <sect1> tag. ;r does <sect>, ;i does
|
|
<item>, etc. For the header tags on the first several lines of
|
|
the document, I just copy them from another document and change the
|
|
words after the tags. Of course I don't need to change the author's
|
|
name or email. So a major advantage of LinuxDoc is that one can
|
|
easily use it with the same editor or word processor that they
|
|
currently use and know.</P>
|
|
<P>Some people who don't understand the situation have advocated making
|
|
DocBook about as easy as LinuxDoc by just using a subset of the
|
|
DocBook tags. This doesn't work because DocBook will still require
|
|
a few times as many tags to get the same results due to the
|
|
requirement of DocBook to not permit any omitted tags.</P>
|
|
<P>In spite of the advantages of LinuxDoc, the number of people who use
|
|
DocBook greatly exceeds the number using LinuxDoc partly because
|
|
Linuxdoc was promoted by book publishers. There's a program by Reuben
|
|
Thomas (ld2db) which can convert LinuxDoc documents to DocBook. It's
|
|
not perfect and you will likely need to do some manual editing. The
|
|
LDP also automatically converts a LinuxDoc HOWTO to DocBook after you
|
|
submit it. It would be nice to have another program to automatically
|
|
convert DocBook docs to LinuxDoc so they can be modified by people
|
|
using the simpler LinuxDoc markup.</P>
|
|
|
|
<HR>
|
|
<H2><A NAME="learn_"></A> <A NAME="s5">5.</A> <A HREF="Howtos-with-LinuxDoc.html#toc5">Learning LinuxDoc </A></H2>
|
|
|
|
<H2><A NAME="ss5.1">5.1</A> <A HREF="Howtos-with-LinuxDoc.html#toc5.1">Introduction</A>
|
|
</H2>
|
|
|
|
<P> LinuxDoc is a lot easier to learn than DocBook. But most of what
|
|
you learn about LinuxDoc would also be useful for DocBook. So if you
|
|
eventually decide to go for DocBook, most of the effort spent on
|
|
learning LinuxDoc will not be wasted.</P>
|
|
<P>One way to learn it is by examples. I've written 3 example files
|
|
ranging from easy to intermediate. The contents of these files have
|
|
been copied into this Howto. To turn them into individual files you
|
|
may cut them out (start with the first tag) and write them to files.
|
|
Then you could try turning one into text by using say sgml2txt
|
|
--pass="-P-cbou" some-example.sgml to see what it looks like. Make
|
|
sure the sgml file names end in .sgml. </P>
|
|
<P>If you want to look at some real examples you can just go to an LDP
|
|
mirror site, find the HOWTOs and select LinuxDoc SGML. Or go to the
|
|
main site directly:
|
|
<A HREF="http://cvs.tldp.org/go.to/LDP/LDP/howto/linuxdoc/">Howto Index (linuxdoc)</A> Now for the first simple example.</P>
|
|
|
|
<H2><A NAME="example_1"></A> <A NAME="ss5.2">5.2</A> <A HREF="Howtos-with-LinuxDoc.html#toc5.2">Example 1 (file name: example1.sgml) </A>
|
|
</H2>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
<!doctype linuxdoc system>
|
|
<article>
|
|
<title>First Example (example1)
|
|
<author>David S.Lawyer
|
|
|
|
<sect> Introduction
|
|
<p> This is a very simple example of "source" for the LinuxDoc text
|
|
formatting system. This paragraph begins with a paragraph tag (a "p"
|
|
enclosed in angle brackets). Notice that there are other tags, also
|
|
enclosed in angle brackets. If you don't see any tags, then you are
|
|
reading a converted file so find the source file: example1.sgml (which
|
|
contains the tags).
|
|
|
|
This is the next paragraph. Note that it is separated from the above
|
|
paragraph by just a blank line. Thus it needs no "p" tag in front of
|
|
it. The "p" tag is only needed for the first paragraph of a section
|
|
(just after the sect-tag). The file suffix: sgml stands for Standard
|
|
Generalized Markup Language. You are now reading the LinuxDoc flavor
|
|
of sgml as specified in the very first line of this file.
|
|
|
|
<sect> Tags
|
|
<p> Tags are words inside angle brackets. The "sect" tag above
|
|
marks the start of a new section of this example document.
|
|
"Introduction" was the first section and you are now reading the
|
|
second section titled "Tags". If this were a long document (like a
|
|
book), a section would correspond to a chapter.
|
|
|
|
Note that there are "article", "title" and "author" tags at the start
|
|
of this article. At the end of this article is an "/article" tag
|
|
marking the end of this article. Thus there is a pair of "article"
|
|
tags, the first being the start tag and the second being the end tag.
|
|
Thus this entire article is enclosed in a pair of "article" tags. In
|
|
later examples you'll see that there are other tags that come in pairs
|
|
like this. They affect whatever is between the pairs (start tag and
|
|
end tag). Any tag name which has "/" just before it is an "end tag".
|
|
|
|
When this source code is converted to another format (such as plain
|
|
text using the program sgml2txt) the tags are removed. Tags only help
|
|
the sgml2txt program make the conversion. There are more tags to
|
|
learn. So once you understand this example1, please go on to the next
|
|
example: example2. You don't need to actually memorize the tags, as
|
|
they will be repeated (but with little or no explanation) in later
|
|
examples.
|
|
</article>
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H2><A NAME="ss5.3">5.3</A> <A HREF="Howtos-with-LinuxDoc.html#toc5.3">Example 2 (file name: example2.sgml)</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
<!-- This is a comment. It's ignored when this source file gets
|
|
converted to other formats. -->
|
|
<!-- The tag below says that this file is in LinuxDoc format -->
|
|
<!doctype linuxdoc system>
|
|
|
|
<article>
|
|
|
|
<title>Second Example (example2)
|
|
<author>David S. Lawyer
|
|
<date>v1.0, July 2000
|
|
|
|
<abstract>
|
|
This is the abstract. This document is the second example of using
|
|
the Linuxdoc-SGML flavor of sgml. It's more complex than the first
|
|
example (example1.sgml) but simpler than the third example
|
|
(example3.sgml). After you digest this you'll be able to write a
|
|
simple HOWTO using LinuxDoc. End of the abstract.
|
|
</abstract>
|
|
|
|
<!-- The "toc" = Table of Contents. It will be created here. -->
|
|
<toc>
|
|
|
|
<!-- Begin the main part of the article (or document) here. The part
|
|
above this is sort of a long header. -->
|
|
|
|
<sect>This Second Example (example2.sgml)
|
|
|
|
<p>Unless you're familiar with markup languages, you should first
|
|
read example1.sgml. You may want to run these example files thru a
|
|
translator such as sgml2txt to convert them to text and notice how the
|
|
result looks different than this "source" document with all its tags.
|
|
|
|
<sect>Article Layout
|
|
<sect1> Document Body
|
|
|
|
<p> After the header comes the body of the document, consisting of
|
|
nested sections marked by sect-tags. Subsections are
|
|
marked by sect1-tags. Since this is the first subsection
|
|
within the 2nd main section, it's becomes section 2.1. Within a
|
|
subsection marked by sect1 there may be sub-subsections like
|
|
sect2. There are even tags like sect3, sect4, etc., but you are
|
|
unlikely to need them. Note the the real tags must be enclosed in
|
|
angle brackets < and >.
|
|
|
|
<sect2> This is a sub-sub-section
|
|
<p>
|
|
It's 2.1.1. Note that a "p" tag may be on a line by itself. This
|
|
doesn't change a thing in the resulting documents.
|
|
|
|
<sect1>Document Header
|
|
<p> One way to create a header part is just to copy one from another
|
|
.sgml file. Then replace everything except the tags with the correct
|
|
info for your document. This is like using a "template".
|
|
|
|
<sect> More Features in example3
|
|
<p> With the tags in this example2 you can write a simple short document
|
|
a few pages long. But for longer documents or for other important
|
|
features such as putting links into documents, you need to study the
|
|
next example: example3. It will also show you how to create lists and
|
|
fonts.
|
|
</article>
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H2><A NAME="example_3"></A> <A NAME="ss5.4">5.4</A> <A HREF="Howtos-with-LinuxDoc.html#toc5.4">Example 3 </A>
|
|
</H2>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
<!doctype linuxdoc system>
|
|
<!-- Note the mailto: after my name. This allows the reader of html
|
|
format to click on my email address to send me email -->
|
|
|
|
<article>
|
|
<title>Third Example (example3)
|
|
<author>David S. Lawyer <url url="mailto:dave@lafn.org">
|
|
<date>v1.0, July 2000
|
|
<abstract>
|
|
This document is the third example of using the LinuxDoc flavor of sgml.
|
|
It's more complex than the second example.
|
|
</abstract>
|
|
<!-- Comment: toc = Table of Contents -->
|
|
<toc>
|
|
|
|
<sect> Fonts
|
|
<p>
|
|
While they will not show up in a plain text output, they will work
|
|
for other conversions.
|
|
<bf>boldface font</bf> <em>emphasis font</em> <sf>sans serif</sf>
|
|
<sl>slanted font</sl> <tt>typewriter font</tt> <it>italics font</it>
|
|
There's another way to get these same fonts by enclosing the text in
|
|
slashes like this: <bf/boldface font/ <em/emphasis font/
|
|
<sf/sans serif/ <sl/slanted font/ <tt/typewriter font/
|
|
<it/italics font/ Note that DocBook doesn't have font tags so it may
|
|
be best not to use fonts if you plan to convert to DocBook.
|
|
|
|
<sect> Links <label id="links_">
|
|
<p> You may create links (something that html browsers may click on to
|
|
go somewhere else). They might just go to another part of this
|
|
document (cross-references) such as to the "label" above, or they
|
|
could go to a website on the Internet.
|
|
|
|
<sect1> Cross-References
|
|
<p> If you click on <ref id="links_" name="Links"> you will be taken to
|
|
the start of the "Links" section above (which is labeled links_).
|
|
The label id may be any word you choose but it's a good idea to avoid
|
|
common words so that you can search for unique labels using your
|
|
editor. That's why I use links_ (with the underline). The name of
|
|
this link will be shown (in html format) as the name to click on.
|
|
This name (Links) will also be present in the text rendition.
|
|
|
|
<sect1> URL Links
|
|
<p> If you click on <url url="http://www.tldp.org"> you will get
|
|
to the Linux Documentation Project website. The next link adds a name
|
|
which people will click on: <url url="http://www.tldp.org"
|
|
name="Linux Documentation Project">. Using this second method, you may
|
|
not even need to explain where the link leads to since it's obvious by
|
|
the name.
|
|
|
|
<sect> Prohibited Characters
|
|
<p> Any word you type between angle brackets will be interpreted as a
|
|
tag. But what if you want to display a tag in a document? For this
|
|
you use a code word for the angle characters.
|
|
|
|
You may use &lt for < and &gt for >. lt = Less Than, gt =
|
|
Greater Than. For example, here's a p-tag: &lt;p&gt;. Of
|
|
course it doesn't actually start any paragraph, but it will appear in
|
|
the converted document as <p>. These codes all start with an &
|
|
character. The ; after the lt is to separate it. It's not needed if
|
|
there is a space after it. For example: 3 &lt 4. Actually, if
|
|
you knew that its OK to use an unpaired > then you could have written
|
|
<p> as &lt;p>. This will not be mistakenly recognized as a tag
|
|
since there is no opening <. Actually 3 < 4 works fine too.
|
|
|
|
There are other characters that you can't put into the document text
|
|
directly. For & in an AT modem command use: AT&amp;. If other
|
|
characters cause you trouble (they seldom will) see <ref id="ch_codes"
|
|
name="Character Codes (macros)"> or the "guide" that comes with
|
|
linuxdoc-tools or sgml-tools.
|
|
|
|
<sect> Verbatim, Code & Newline
|
|
<sect1> Verbatim
|
|
<p> If you want to insure that it will look exactly like you typed it
|
|
after it's converted to other formats, use verbatim (verb). This is
|
|
useful for creating tables, etc. But some things still get recognized
|
|
as markup even though they are between verbatim tags. This includes
|
|
the macros starting with & and end tags with /.
|
|
|
|
<tscreen><verb>
|
|
% sgml2txt --pass="-P-cbou" example.sgml
|
|
</verb></tscreen>
|
|
The "tscreen" sets the font to typewriter and indents it nicely.
|
|
|
|
<sect1> Code
|
|
<p> This encloses computer code between two dashed lines.
|
|
<tscreen><code>
|
|
Put computer source code here
|
|
</code></tscreen>
|
|
|
|
<sect1> Newline
|
|
<p> To force a newline use <newline>
|
|
This sentence always starts at the left margin.
|
|
|
|
<sect>Lists
|
|
<p>
|
|
This puts items into a list with a bullet at the start of each item.
|
|
They start with the "itemize" tag.
|
|
<itemize>
|
|
<item> This is the first item in a list.
|
|
<item> This is the second item
|
|
<itemize>
|
|
<item> Multiple levels (nesting) are supported.
|
|
<item> The second item in this sublist
|
|
</itemize>
|
|
<enum>
|
|
<item> Enumerated lists using <tt/enum/ also work.
|
|
<item> This is item number 2
|
|
</enum>
|
|
<item> The final item in the main list
|
|
</itemize>
|
|
</article>
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H2><A NAME="ss5.5">5.5</A> <A HREF="Howtos-with-LinuxDoc.html#toc5.5">LinuxDoc Quick Reference Sheet</A>
|
|
</H2>
|
|
|
|
<H3>Header Part</H3>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
<!doctype linuxdoc system>
|
|
<article>
|
|
<title>Quick Reference Sheet
|
|
<author>David S. Lawyer
|
|
<date>v1.0, July 2000
|
|
<abstract> abstract here </abstract>
|
|
<toc> <!-- Comment: toc = Table of Contents -->
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H3>Body Layout</H3>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
<sect> Chapter 1 Note: Put a <p> on the first line of
|
|
<sect1> Subsection 1.1 each section (or subsection, etc.)
|
|
<sect1> Subsection 1.2
|
|
<sect> Chapter 2 Choose title names to replace "Chapter"
|
|
<sect1> Subsection 2.1 "Subsection", etc.
|
|
<sect2> Sub-subsection 2.1.1
|
|
<sect2> Sub-subsection 2.1.2
|
|
<sect1> Subsection 2.2
|
|
</article>
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H3>Fonts</H3>
|
|
|
|
<P> There are two ways to get these:
|
|
<PRE>
|
|
<bf>boldface font</bf> <em>emphasis font</em> <sf>sans serif font</sf>
|
|
<sl>slanted font</sl> <tt>typewriter font</tt> <it>italics font</it>
|
|
<bf/boldface/ <em/emphasis/ <sf/sans serif/
|
|
<sl/slanted/ <tt/typewriter/ <it/italics/
|
|
</PRE>
|
|
</P>
|
|
|
|
<H3>Lists (nesting is OK)</H3>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
Ordinary unnumbered list: Numbered list:
|
|
<itemize> <enum>
|
|
<item> First item <item> First item
|
|
<item> Second item <item> Second item
|
|
<item> etc. <item> etc.
|
|
</itemize> </enum>
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H3><A NAME="links_"></A> Links </H3>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
Cross-References: An Email Link:
|
|
<ref id="links_" name="Links"> <url url="mailto:bob@tldp.org">
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H3>Newline, Verbatim, URLs </H3>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
To force a newline <newline>
|
|
<tscreen><verb>
|
|
<url url="http://www.tldp.org">
|
|
<url url="http://www.tldp.org" name="Linux Documentation Project">.
|
|
</verb></tscreen>
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H3><A NAME="ch_codes"></A> Character Codes (macros) </H3>
|
|
|
|
<P>You don't always need to use these.
|
|
<UL>
|
|
<LI>Use <CODE>&amp;</CODE> for the ampersand (&), </LI>
|
|
<LI>Use <CODE>&lt;</CODE> for a left bracket (<),</LI>
|
|
<LI>Use <CODE>&gt;</CODE> for a right bracket (>),</LI>
|
|
<LI>Use <CODE>&etago;</CODE> for a left bracket with a slash
|
|
(<CODE></</CODE>)</LI>
|
|
</UL>
|
|
</P>
|
|
<P>Use of these are optional and I seldom use them.
|
|
<UL>
|
|
<LI>Use <CODE>``</CODE> and <CODE>''</CODE> for opening and closing double
|
|
quotes</LI>
|
|
<LI>Use <CODE>&shy;</CODE> for a soft hyphen (that is, an indication
|
|
that this is a good place to break a very long word to insert a
|
|
hyphen for horizontal justification). </LI>
|
|
</UL>
|
|
</P>
|
|
<P>Only use these if LinuxDoc complains about it or fails to generate
|
|
them in the formated document. I've seldom had to use them.
|
|
<UL>
|
|
<LI>Use <CODE>&dollar;</CODE> for a dollar sign ($),</LI>
|
|
<LI>Use <CODE>&num;</CODE> for a hash (#),</LI>
|
|
<LI>Use <CODE>&percnt;</CODE> for a percent (%),</LI>
|
|
<LI>Use <CODE>&tilde;</CODE> for a tilde (~),</LI>
|
|
<LI>Use <CODE>&dquot;</CODE> for ".</LI>
|
|
</UL>
|
|
</P>
|
|
|
|
<HR>
|
|
<H2><A NAME="s6">6.</A> <A HREF="Howtos-with-LinuxDoc.html#toc6">Getting/Using the LinuxDoc Software</A></H2>
|
|
|
|
<P> You could write a LinuxDoc document without having any LinuxDoc
|
|
software. However, it's likely that it would contain some errors in
|
|
the tags (or their use) so that it would be returned to you for
|
|
correction. Even if there were no errors, the results might not
|
|
not look quite right. So it's best for you to have the software to
|
|
convert your source code on your computer.</P>
|
|
<P>The Debian distribution of Linux has a linuxdoc-tools package. There
|
|
is also a rpm package for non-Debian distributions. It was formerly
|
|
called sgml-tools. Don't use the sgmltools-2 package which is
|
|
primarily for DocBook-sgml. </P>
|
|
<P>To use linuxdoc-tools you run converter programs on the *.sgml files.
|
|
For example for versions after 0.9.21-0.8 to get text output, type:
|
|
"sgml2txt -f --blanks=1 my-HOWTO.sgml". For earlier versions due to a
|
|
bug you must substitute --pass="-P-cbou" for -f. (If interested, see
|
|
<A HREF="#esc_seqs">Old Problem of Escape Sequences in Text Output</A> for more info on this bug.) To get html output,type:
|
|
"sgml2html my-HOWTO.sgml". If it shows errors, it will show the line
|
|
number and the column number where the error is in the source file.
|
|
Typing "man -k sgml" should show you a number of other programs with a
|
|
one-line description of each but not all of them are for
|
|
linuxdoc-sgml.</P>
|
|
|
|
<HR>
|
|
<H2><A NAME="s7">7.</A> <A HREF="Howtos-with-LinuxDoc.html#toc7">Errors and Error Messages</A></H2>
|
|
|
|
<H2><A NAME="ss7.1">7.1</A> <A HREF="Howtos-with-LinuxDoc.html#toc7.1">Errors That Don't Create Error Messages</A>
|
|
</H2>
|
|
|
|
<P>A major error is to forget to put a <p>. tag after a section
|
|
heading. Then there is no end to the section heading and all the
|
|
following paragraphs become part of the section heading and get into
|
|
the table of contents. Linuxdoc should be improved to spot this
|
|
error. To spot it manually, look at the table of contents in html or
|
|
text format. Fixing it requires just adding the missing p-tag.</P>
|
|
|
|
<H2><A NAME="ss7.2">7.2</A> <A HREF="Howtos-with-LinuxDoc.html#toc7.2">Actual Error Messages</A>
|
|
</H2>
|
|
|
|
<P> When you are running the linuxdoc program (sgml2html or sgml2txt
|
|
for example) you are likely to see some error messages. You need to
|
|
edit your document and fix the errors.</P>
|
|
<P>Omission of closing quotes is a common error. If you get an error
|
|
message that makes no sense and notice that at the error location are
|
|
some quotes (" ") that are OK, then the likely error is that you have
|
|
previously typed an opening quote with no closing quote. Like:
|
|
<.... id="my home page > so linuxdoc thinks that the next quote,
|
|
which may be many paragraphs after the missing quote location, is the
|
|
closing quote. Then after the false closing quote it expects a > to
|
|
finish the tag but doesn't find one. To find and fix the missing
|
|
quote, just search backwards for a ".</P>
|
|
<P>A single error can cause a lot of error messages. In the example
|
|
above, a number of tags may be inside erroneous quotes that shouldn't
|
|
have been inside any quotes. So the linuxdoc will not find these tags.
|
|
As a result, it will not know that a certain tag is open and if it
|
|
finds a closing tag it will tell you that that tag was not open.
|
|
For example, if the <itemize> tag was missed, then <item>
|
|
tags may make no sense to linuxdoc and it will report an error for
|
|
each such tag found beyond the false closing quote. </P>
|
|
<P>One thing you should know is that the tag names are not case sensitive
|
|
so the error messages will show tag names in upper case (capital
|
|
letters) even though you typed them in lower case.</P>
|
|
<P>To understand the error messages better requires an understanding of
|
|
the jargon on sgml which you don't really need to learn unless you get
|
|
errors which you can't seem to get fixed and you don't understand the
|
|
error message. The following sector is about such jargon.</P>
|
|
|
|
<HR>
|
|
<H2><A NAME="s8">8.</A> <A HREF="Howtos-with-LinuxDoc.html#toc8">Jargon in Error Messages</A></H2>
|
|
|
|
<H2><A NAME="ss8.1">8.1</A> <A HREF="Howtos-with-LinuxDoc.html#toc8.1">Introduction</A>
|
|
</H2>
|
|
|
|
<P>You really shouldn't need to read this section unless either you're
|
|
either having problems or you're curious about how sgml and linuxdoc
|
|
work. Error messages may contain words like "element", "entities,
|
|
"attribute", "literal", and delimiter". Various elements, entities
|
|
and attributes are defined for linuxdoc in the "Data Type Definition"
|
|
(or dtd) for LinuxDoc. The dtd doesn't define them in sentences but
|
|
uses a rather cryptic format to define their syntax (but not their
|
|
semantics).</P>
|
|
|
|
<H2><A NAME="ss8.2">8.2</A> <A HREF="Howtos-with-LinuxDoc.html#toc8.2">Elements</A>
|
|
</H2>
|
|
|
|
<P>An "element" is something like a tag. But it's a much broader
|
|
concept. Elements exist not only in linuxdoc but in all sgml
|
|
languages like say html. Your entire document is partitioned into
|
|
elements. But elements are nested, which is to say that some elements
|
|
may occur within other elements. If you use the <article> tag for
|
|
your document, then all of the document is the <article> element,
|
|
except for the very first tag which says that what follows is
|
|
linuxdoc. And within this article element are nested many other
|
|
elements.</P>
|
|
<P>For example, each paragraph is an element, even though the paragraphs
|
|
are separated from each other by blank lines instead of tags. But
|
|
there's an implicit tag surrounding each paragraph and the software
|
|
that parses a linuxdoc writing will actually insert these missing tags.
|
|
It will also insert end tags (closing tags) where you didn't need to
|
|
write any. In this way, linuxdoc saves you a lot of time. So an
|
|
element will consist of a start tag and the end tag (for this start
|
|
tag) and everything in between (often including other elements and
|
|
their tags). Note that the tags omitted but they still are implicitly
|
|
there. In some cases, a tag doesn't enclose anything, like the url
|
|
tag for a link to the internet. Such tags are themselves elements.
|
|
Within the article-element are found sect-elements (sections) starting
|
|
with <sect>. Then within sect-elements are often found
|
|
sect1-elements (subsections), etc.</P>
|
|
<P>There are few cases where an element occurs but the use of both start
|
|
and end tags are optional. So even if you have no such tags in your
|
|
document, the parts of the document that they should have enclosed are
|
|
still elements for the missing tags.</P>
|
|
|
|
<P>An entity is like a macro definition. For example, one could
|
|
define the name "list" to mean the various types of lists. Then this
|
|
name list is used only in the dtd to specify, for example, that a list
|
|
may occur within a paragraph. It's just a shorthand for the writer of
|
|
a dtd. This kind of an entity is never used in a linuxdoc document.
|
|
But there's also another type of entity that can be used inside a
|
|
document and that's one that defines a special character such as
|
|
amp;etago for </ (end tag open). You would use this when you
|
|
want to, for example, put </article> in the middle of a sentence
|
|
to explain what it means so that the software that converts LinuxDoc
|
|
doesn't think it's really at the end of the article.</P>
|
|
|
|
<H2><A NAME="ss8.3">8.3</A> <A HREF="Howtos-with-LinuxDoc.html#toc8.3">Literals and Delimiters</A>
|
|
</H2>
|
|
|
|
<P>A "literal" is a name of something, like the name one clicks on in
|
|
an html link. It may be one or more words long. A delimiter is what
|
|
separates something from something else. For a "quote" the last " is
|
|
the closing delimiter. So for name="my website" the literal is 'my
|
|
website' and the delimiters of this literal are the two " marks, the
|
|
first " an opening delimiter and second " a closing delimiter. So if
|
|
a "literal is missing a closing delimiter it means that you neglected
|
|
to put an ending " after a name.</P>
|
|
|
|
<HR>
|
|
<H2><A NAME="s9">9.</A> <A HREF="Howtos-with-LinuxDoc.html#toc9">Writing the HOWTO</A></H2>
|
|
|
|
<H2><A NAME="ss9.1">9.1</A> <A HREF="Howtos-with-LinuxDoc.html#toc9.1">Before you start writing</A>
|
|
</H2>
|
|
|
|
<P>First join the discuss list by going to
|
|
<A HREF="www.en.tldp.org">www.en.tldp.org</A>
|
|
and submit your proposal to this list. If you're taking over an
|
|
unmaintained HOWTO, contact the former author. This may required by
|
|
the copyright-license but you should do it out of courtesy even it
|
|
it's not required.</P>
|
|
|
|
<H2><A NAME="ss9.2">9.2</A> <A HREF="Howtos-with-LinuxDoc.html#toc9.2">Guidelines</A>
|
|
</H2>
|
|
|
|
<P> These are mostly by Tim Bynum (a former HOWTO coordinator).
|
|
<UL>
|
|
<LI> Be sure and use an accepted format (such as LinuxDoc :-).</LI>
|
|
<LI> Try to use meaningful structure and organization, and write
|
|
clearly. Remember that many of the people reading HOWTOs do not speak
|
|
English as their first language.</LI>
|
|
<LI> Make sure that all of the information is correct. I can't stress
|
|
this enough. When in doubt, speculate, but make it clear that you're
|
|
only guessing. I use ?? if I'm not sure.</LI>
|
|
<LI> Make sure that you are covering the most recent version of the
|
|
available software.</LI>
|
|
<LI> Consider including a "FAQ" section or sections called
|
|
"Common Problems" or "Trouble Shooting".</LI>
|
|
<LI> Be sure to copyright it in your name and include a license
|
|
which meets the requirements stated in the LDP manifesto.</LI>
|
|
<LI> Use the standard header with title, author, and date
|
|
(including a version number). See
|
|
<A HREF="#example_3">Example 3</A></LI>
|
|
<LI> Lastly, be prepared to receive email questions and comments
|
|
from readers. How much you help people is up to you but you should
|
|
make use of good suggestions and reports of errors. You may also
|
|
get some "thank you for writing this" email. </LI>
|
|
</UL>
|
|
</P>
|
|
<H2><A NAME="ss9.3">9.3</A> <A HREF="Howtos-with-LinuxDoc.html#toc9.3">Submitting the HOWTO, etc.</A>
|
|
</H2>
|
|
|
|
<P> After you have written the HOWTO, email the SGML source to
|
|
submit@tldp.org. Then all you need to do is to keep the HOWTO
|
|
up-to date by submitting periodic updates to the same email as you
|
|
used for the first edition.</P>
|
|
|
|
<HR>
|
|
<H2><A NAME="s10">10.</A> <A HREF="Howtos-with-LinuxDoc.html#toc10">More Information </A></H2>
|
|
|
|
<P> There's a HOWTO: Linuxdoc-Reference that covers it in much
|
|
greater detail than this mini-HOWTO.</P>
|
|
|
|
<HR>
|
|
<H2><A NAME="s11">11.</A> <A HREF="Howtos-with-LinuxDoc.html#toc11">Appendix</A></H2>
|
|
|
|
<H2><A NAME="esc_seqs"></A> <A NAME="ss11.1">11.1</A> <A HREF="Howtos-with-LinuxDoc.html#toc11.1">Old Problem of Escape Sequences in Text Output</A>
|
|
</H2>
|
|
|
|
<P>Prior to version 0.9.21-0.8 there was a bug for the case of text
|
|
output. For sgml2txt, the option --pass="-P-cbou" was needed to get
|
|
pure text output since otherwise if you used the -f option, you got
|
|
text output which put emphasis on words and letters by the use of
|
|
escape sequences and overstriking. An example of a bullet made by
|
|
overstriking is +^Ho which on a printer would type +, then backspace
|
|
(^H), and then type o over the existing +. This doesn't seem to work
|
|
on display terminals (they can't overstrike). Note that even if you
|
|
have the most recent version, you'll still get this unwanted output if
|
|
you fail to use the -f option.</P>
|
|
<P>In case you are interested, the --pass passes the -P-cbou option to the
|
|
groff program (used by sgml2txt) and the -P option of groff passes the
|
|
-cbou options to grotty (a post-processor for groff) forcing grotty to
|
|
generate just plain text output. See the grotty man page. In brief:
|
|
-c avoids escape sequences but allows overstrikes but -bou prohibits
|
|
overstrikes when the -c option is used. The result is no overstrikes
|
|
and no escape sequences in the output. -b prohibits overstrikes to
|
|
make a character look bold; -u prevents overstrikes for underlining;
|
|
and -o prohibits other kinds of overstrikes like the bullet example
|
|
above. An alternate way to eliminate overstrikes is to use the -f
|
|
option with sgml2txt but you still have to pass the -c option to
|
|
grotty to eliminate escape sequences unless you have the newer
|
|
version.</P>
|
|
<P>What a mess it was! The default should probably be plain text so that
|
|
all of this passing of options wouldn't be needed. I've finally got
|
|
them to fix this so after about mid-2007 you can use just the -f
|
|
option instead of --pass="-P-cbou". If you get these escape sequences
|
|
and overstrikes in your output file but use the Linux "cat" command to
|
|
display the text, it looks great. But using pagers or editors on the
|
|
text output file usually results in the escape characters being eaten
|
|
so you see a bunch of unwanted characters in your text that were
|
|
supposed to be part of escape sequences. In some cases, pagers can
|
|
display certain overstrikes OK but editors (like vim) don't. So
|
|
eliminating all overstrikes permits you to use any editor or pager to
|
|
read it.</P>
|
|
<HR>
|
|
</BODY>
|
|
</HTML>
|