895 lines
37 KiB
Plaintext
895 lines
37 KiB
Plaintext
David S. Lawyer
|
||
v0.09, November 2007
|
||
|
||
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.
|
||
______________________________________________________________________
|
||
|
||
Table of Contents
|
||
|
||
|
||
1. Introduction
|
||
1.1 If you want to start immediately
|
||
1.2 Copyright and License
|
||
1.3 Should you write a HOWTO ?
|
||
1.4 Why I wrote this
|
||
|
||
2. Information on Writing a HOWTO
|
||
2.1 Copyright
|
||
2.2 Choosing a topic
|
||
|
||
3. The Format of HOWTOs
|
||
3.1 Introduction
|
||
|
||
4. Comparing LinuxDoc to DocBook
|
||
5. Learning LinuxDoc
|
||
5.1 Introduction
|
||
5.2 Example 1 (file name: example1.sgml)
|
||
5.3 Example 2 (file name: example2.sgml)
|
||
5.4 Example 3
|
||
5.5 LinuxDoc Quick Reference Sheet
|
||
5.5.1 Header Part
|
||
5.5.2 Body Layout
|
||
5.5.3 Fonts
|
||
5.5.4 Lists (nesting is OK)
|
||
5.5.5 Links
|
||
5.5.6 Newline, Verbatim, URLs
|
||
5.5.7 Character Codes (macros)
|
||
|
||
6. Getting/Using the LinuxDoc Software
|
||
7. Errors and Error Messages
|
||
7.1 Errors That Don't Create Error Messages
|
||
7.2 Actual Error Messages
|
||
|
||
8. Jargon in Error Messages
|
||
8.1 Introduction
|
||
8.2 Elements
|
||
8.3 Literals and Delimiters
|
||
|
||
9. Writing the HOWTO
|
||
9.1 Before you start writing
|
||
9.2 Guidelines
|
||
9.3 Submitting the HOWTO, etc.
|
||
|
||
10. More Information
|
||
11. Appendix
|
||
11.1 Old Problem of Escape Sequences in Text Output
|
||
|
||
|
||
______________________________________________________________________
|
||
|
||
|
||
|
||
1. Introduction
|
||
|
||
1.1. If you want to start immediately
|
||
|
||
To only learn LinuxDoc, skip to ``Learning LinuxDoc''. If you want
|
||
to start writing immediately, then you may try a "fill in the blanks"
|
||
template which will generate LinuxDoc formatted output. The LDP HOWTO
|
||
Generator <http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html>.
|
||
You may use this to just start writing your Howto and then finish it
|
||
later by using a text editor on your PC.
|
||
|
||
|
||
1.2. Copyright and License
|
||
|
||
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.
|
||
|
||
|
||
1.3. Should you write a HOWTO ?
|
||
|
||
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.
|
||
|
||
|
||
1.4. Why I wrote this
|
||
|
||
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.
|
||
|
||
Thanks to Matt Welsh for his example.sgml file which I used as a major
|
||
source of info for the example sections.
|
||
|
||
|
||
2. Information on Writing a HOWTO
|
||
|
||
2.1. Copyright
|
||
|
||
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.
|
||
|
||
|
||
2.2. Choosing a topic
|
||
|
||
If you are not sure what to write about, take look at some of LDP's
|
||
documents including the ones in Unmaintained HOWTOs
|
||
<http://www.tldp.org/authors/unmaint.html>. 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.
|
||
|
||
|
||
3. The Format of HOWTOs
|
||
|
||
3.1. Introduction
|
||
|
||
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.
|
||
|
||
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: Hypertext Markup Language. The
|
||
LDP uses formats something like this for its documents.
|
||
|
||
The markup languages LDP uses meet the requirements of either Standard
|
||
Generalized Markup Language (SGML) or XML. The LDP now uses the
|
||
following two flavors of sgml: LinuxDoc and DocBook as well as the
|
||
DocBook 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).
|
||
|
||
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.
|
||
|
||
|
||
4. Comparing LinuxDoc to DocBook
|
||
|
||
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 ``Example 1'' for LinuxDoc
|
||
markup.
|
||
|
||
One way to compare is to inspect real HOWTOs at the LDP site. Click
|
||
on either DocBook Index
|
||
<http://cvs.tldp.org/go.to/LDP/LDP/howto/docbook/> or LinuxDoc Index
|
||
<http://cvs.tldp.org/go.to/LDP/LDP/howto/linuxdoc/> 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.
|
||
|
||
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.
|
||
|
||
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).
|
||
|
||
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 Comparison of DocBook to LinuxDoc
|
||
<http://www.lafn.org/~dave/linux/ld_vs_db.txt>
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
|
||
5. Learning LinuxDoc
|
||
|
||
5.1. Introduction
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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: Howto Index (linuxdoc)
|
||
<http://cvs.tldp.org/go.to/LDP/LDP/howto/linuxdoc/> Now for the first
|
||
simple example.
|
||
|
||
|
||
5.2. Example 1 (file name: example1.sgml)
|
||
|
||
|
||
|
||
<!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>
|
||
|
||
|
||
|
||
5.3. Example 2 (file name: example2.sgml)
|
||
|
||
|
||
|
||
<!-- 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>
|
||
|
||
|
||
|
||
5.4. Example 3
|
||
|
||
|
||
|
||
<!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 < for < and > for >. lt = Less Than, gt =
|
||
Greater Than. For example, here's a p-tag: <p>. 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 < 4. Actually, if
|
||
you knew that its OK to use an unpaired > then you could have written
|
||
<p> as <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&. 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>
|
||
|
||
|
||
|
||
5.5. LinuxDoc Quick Reference Sheet
|
||
|
||
5.5.1. Header Part
|
||
|
||
|
||
|
||
<!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 -->
|
||
|
||
|
||
5.5.2. Body Layout
|
||
|
||
|
||
|
||
<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>
|
||
|
||
|
||
|
||
5.5.3. Fonts
|
||
|
||
There are two ways to get these:
|
||
|
||
<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/
|
||
|
||
|
||
|
||
5.5.4. Lists (nesting is OK)
|
||
|
||
|
||
|
||
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>
|
||
|
||
|
||
|
||
5.5.5. Links
|
||
|
||
|
||
|
||
Cross-References: An Email Link:
|
||
<ref id="links_" name="Links"> <url url="mailto:bob@tldp.org">
|
||
|
||
|
||
|
||
5.5.6. Newline, Verbatim, URLs
|
||
|
||
|
||
|
||
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>
|
||
|
||
|
||
|
||
5.5.7. Character Codes (macros)
|
||
|
||
You don't always need to use these.
|
||
|
||
<20> Use & for the ampersand (&),
|
||
|
||
<20> Use < for a left bracket (<),
|
||
|
||
<20> Use > for a right bracket (>),
|
||
|
||
<20> Use &etago; for a left bracket with a slash (</)
|
||
|
||
Use of these are optional and I seldom use them.
|
||
|
||
<20> Use `` and '' for opening and closing double quotes
|
||
|
||
<20> Use ­ 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).
|
||
|
||
Only use these if LinuxDoc complains about it or fails to generate
|
||
them in the formated document. I've seldom had to use them.
|
||
|
||
<20> Use $ for a dollar sign ($),
|
||
|
||
<20> Use # for a hash (#),
|
||
|
||
<20> Use % for a percent (%),
|
||
|
||
<20> Use ˜ for a tilde (~),
|
||
|
||
<20> Use &dquot; for ".
|
||
|
||
|
||
6. Getting/Using the LinuxDoc Software
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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
|
||
``Old Problem of Escape Sequences in Text Output'' 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.
|
||
|
||
|
||
7. Errors and Error Messages
|
||
|
||
7.1. Errors That Don't Create Error Messages
|
||
|
||
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.
|
||
|
||
|
||
7.2. Actual Error Messages
|
||
|
||
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.
|
||
|
||
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 ".
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
|
||
8. Jargon in Error Messages
|
||
|
||
8.1. Introduction
|
||
|
||
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).
|
||
|
||
|
||
|
||
8.2. Elements
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
|
||
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.
|
||
|
||
|
||
8.3. Literals and Delimiters
|
||
|
||
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.
|
||
|
||
|
||
9. Writing the HOWTO
|
||
|
||
9.1. Before you start writing
|
||
|
||
First join the discuss list by going to <www.en.tldp.org> 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.
|
||
|
||
|
||
9.2. Guidelines
|
||
|
||
These are mostly by Tim Bynum (a former HOWTO coordinator).
|
||
|
||
<20> Be sure and use an accepted format (such as LinuxDoc :-).
|
||
|
||
<20> 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.
|
||
|
||
<20> 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.
|
||
|
||
<20> Make sure that you are covering the most recent version of the
|
||
available software.
|
||
|
||
<20> Consider including a "FAQ" section or sections called "Common
|
||
Problems" or "Trouble Shooting".
|
||
|
||
<20> Be sure to copyright it in your name and include a license which
|
||
meets the requirements stated in the LDP manifesto.
|
||
|
||
<20> Use the standard header with title, author, and date (including a
|
||
version number). See ``Example 3''
|
||
|
||
<20> 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.
|
||
|
||
9.3. Submitting the HOWTO, etc.
|
||
|
||
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.
|
||
|
||
|
||
10. More Information
|
||
|
||
There's a HOWTO: Linuxdoc-Reference that covers it in much greater
|
||
detail than this mini-HOWTO.
|
||
|
||
|
||
11. Appendix
|
||
|
||
11.1. Old Problem of Escape Sequences in Text Output
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
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.
|
||
|
||
|
||
|