mirror of https://github.com/tLDP/LDP
698 lines
31 KiB
Plaintext
698 lines
31 KiB
Plaintext
<!doctype linuxdoc system>
|
|
<article>
|
|
<author>David S. Lawyer
|
|
<date>v0.08, July 2007
|
|
<abstract>
|
|
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 advanced DocBook markup (including XML) see the LDP Authoring
|
|
Guide.</abstract>
|
|
|
|
<toc>
|
|
<!-- Change log
|
|
v0.08 -f option fixed so it does "-P-cbou", LDP's url is tldp,
|
|
LinuxDoc finds omitted tags, etc., fixed "Entities" heading
|
|
v0.07 Passed "-P-cbou" to groff via pass option of sgml2txt. Explained.
|
|
v0.06 Dec. 2006 Corrected explanation re why fix below works.
|
|
Updated procedure for submissions
|
|
v0.05 Oct. 2005: Fix for escape sequences in text output. Fix link
|
|
to linuxdoc howtos. Docbook XML
|
|
v0.04 Jan. 2005: Howto Generator
|
|
v0.03 Dec. 2003: Character codes are seldom needed, ref to HOWTO, misc
|
|
changes
|
|
v0.02 Nov. 2003: Comparison errors: don't need to type release twice
|
|
v0.01 generic url for Greg Ferg. hmtl a flavor of sgml (per D.
|
|
Merrill's suggestion but ...)
|
|
-->
|
|
<sect> Introduction
|
|
|
|
<sect1>If you want to start immediately
|
|
<p>To only learn LinuxDoc, skip to <ref id="learn_" name="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. <url
|
|
url="http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html"
|
|
name="The LDP HOWTO Generator">. You may use this to just start
|
|
writing your Howto and then finish it later by using a text editor on
|
|
your PC.
|
|
|
|
<sect1>Copyright and License
|
|
<p> Copyright (c) 2001-3 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.
|
|
|
|
<sect1> Should you write a HOWTO ?
|
|
<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. 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.
|
|
|
|
<sect1>Why I wrote this
|
|
<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.
|
|
|
|
Thanks to Matt Welsh for his example.sgml file which I used as a major
|
|
source of info for the example sections.
|
|
|
|
<sect> Information on Writing a HOWTO
|
|
<sect1> Copyright
|
|
<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.
|
|
|
|
<sect1> Choosing a topic
|
|
<p> If you are not sure what to write about, take look at some of
|
|
LDP's documents including the ones in <url
|
|
url="http://www.tldp.org/authors/unmaint.html" name="Unmaintained
|
|
HOWTOs">. Pick a topic you're interested in that has inadequate or no
|
|
coverage and that's needed by Linux users. 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
|
|
modfications and improvements, you can just write a new document on
|
|
the same topic from scratch, using a new outline new sources of
|
|
information.
|
|
|
|
<sect> The Format of HOWTOs
|
|
<sect1> Introduction
|
|
<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 which gets converted by computer into all of the others.
|
|
|
|
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.
|
|
|
|
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/ and
|
|
<em/DocBook/ as well as the <em/DocBook/ flavor of XML.
|
|
Interestingly, it turns out that html is just another flavor of sgml.
|
|
|
|
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).
|
|
|
|
<sect> Comparing LinuxDoc to DocBook
|
|
<p> One way to do this is to go to the LDP site <url
|
|
url="http://www.tldp.org"> click on HOWTOs and then compare the
|
|
sources of the same HOWTO in the two formats: LinuxDoc and DocBook.
|
|
The DocBook tags are often longer than the equivalent LinuxDoc tags
|
|
and there are sometimes more of them needed to do the same task.
|
|
DocBook uses <para> and &etago;para> tags to enclose each paragraph
|
|
while LinuxDoc uses only a blank line to separate paragraphs (no tags
|
|
needed). For some examples see <url
|
|
url="http://www.lafn.org/~dave/linux/ld_vs_db.txt" name="Comparison of
|
|
DocBook to LinuxDoc">
|
|
|
|
So there's much more to type with DocBook if you're typing in tags
|
|
manually. But DocBook has all sorts of tags that don't exist in
|
|
LinuxDoc so it's more advanced in a way. Just using a subset of
|
|
DocBook doesn't help as you can see from the examples reached by the
|
|
above link, partly because DocBook nests tags (uses more tags to do
|
|
the same thing). With a more and longer tags the DocBook source
|
|
becomes harder to read unless you use an editor that hides them. But
|
|
hiding them has it's drawbacks since it's nice to see what tags you've
|
|
used.
|
|
|
|
Still, the number of people who use DocBook greatly exceeds the number
|
|
using LinuxDoc. But if you do decide to migrate to DocBook there's a
|
|
program by Reuben Thomas (ld2db) which can help make the conversion.
|
|
It's not 100% perfect and you may have to do some manual editing. The
|
|
LDP also automatically converts a LinuxDoc HOWTO to DocBook after you
|
|
submit it.
|
|
|
|
The ease of LinuxDoc is due to it being SGML which allows omission of
|
|
tags (like using blank lines for paragraph markers). In most cases
|
|
ending tags like &etago;title> may also be omitted. This save a lot
|
|
of time for the author but puts more work on the software to find the
|
|
missing tags. If you were to look at a LinusDoc text after the
|
|
software has found and added all the missing tags, including tags that
|
|
most users don't even know exist, it would look just as complex and
|
|
unreadable as DocBook. But users of LinuxDoc normally never see this
|
|
since it's looked at mainly by people debugging the software, etc.
|
|
So while DocBook is more advanced because it has more tags, LinuxDoc
|
|
is more advanced since it's able to figure out where tags omitted by
|
|
the author should go. DocBook can't do this and the inferior XML
|
|
doesn't allow it.
|
|
|
|
<sect> Learning LinuxDoc <label id="learn_">
|
|
<sect1> Introduction
|
|
<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.
|
|
|
|
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: <url
|
|
url="http://cvsview.tldp.org/index.cgi/LDP/howto/linuxdoc/"
|
|
name="Howto Index (linuxdoc)"> Now for the first simple example.
|
|
|
|
<sect1> Example 1 (file name: example1.sgml)
|
|
<p>
|
|
<tscreen><verb>
|
|
<!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.
|
|
&etago;article>
|
|
</verb></tscreen>
|
|
|
|
<sect1> Example 2 (file name: example2.sgml)
|
|
<p>
|
|
<tscreen><verb>
|
|
<!-- 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.
|
|
&etago;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.
|
|
&etago;article>
|
|
</verb></tscreen>
|
|
|
|
<sect1> Example 3 <label id="example_3">
|
|
<p>
|
|
<tscreen><verb>
|
|
<!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.
|
|
&etago;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&etago;bf> <em>emphasis font&etago;em> <sf>sans serif&etago;sf>
|
|
<sl>slanted font&etago;sl> <tt>typewriter font&etago;tt> <it>italics font&etago;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
|
|
&etago;verb>&etago;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
|
|
&etago;code>&etago;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
|
|
&etago;itemize>
|
|
<enum>
|
|
<item> Enumerated lists using <tt/enum/ also work.
|
|
<item> This is item number 2
|
|
&etago;enum>
|
|
<item> The final item in the main list
|
|
&etago;itemize>
|
|
&etago;article>
|
|
</verb></tscreen>
|
|
|
|
<sect1> LinuxDoc Quick Reference Sheet
|
|
<sect2> Header Part
|
|
<p>
|
|
<tscreen><verb>
|
|
<!doctype linuxdoc system>
|
|
<article>
|
|
<title>Quick Reference Sheet
|
|
<author>David S. Lawyer
|
|
<date>v1.0, July 2000
|
|
<abstract> abstract here &etago;abstract>
|
|
<toc> <!-- Comment: toc = Table of Contents -->
|
|
</verb></tscreen>
|
|
|
|
<sect2> Body Layout
|
|
<p>
|
|
<tscreen><verb>
|
|
<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
|
|
&etago;article>
|
|
</verb></tscreen>
|
|
|
|
<sect2> Fonts
|
|
<p> There are two ways to get these:
|
|
<verb>
|
|
<bf>boldface font&etago;bf> <em>emphasis font&etago;em> <sf>sans serif font&etago;sf>
|
|
<sl>slanted font&etago;sl> <tt>typewriter font&etago;tt> <it>italics font&etago;it>
|
|
<bf/boldface/ <em/emphasis/ <sf/sans serif/
|
|
<sl/slanted/ <tt/typewriter/ <it/italics/
|
|
</verb>
|
|
|
|
<sect2> Lists (nesting is OK)
|
|
<p>
|
|
<tscreen><verb>
|
|
Ordinary unnumbered list: Numbered list:
|
|
<itemize> <enum>
|
|
<item> First item <item> First item
|
|
<item> Second item <item> Second item
|
|
<item> etc. <item> etc.
|
|
&etago;itemize> &etago;enum>
|
|
</verb></tscreen>
|
|
|
|
<sect2> Links <label id="links_">
|
|
<p>
|
|
<tscreen><verb>
|
|
Cross-References: An Email Link:
|
|
<ref id="links_" name="Links"> <url url="mailto:bob@tldp.org">
|
|
</verb></tscreen>
|
|
|
|
<sect2> Newline, Verbatim, URLs
|
|
<p>
|
|
<tscreen><verb>
|
|
To force a newline <newline>
|
|
<tscreen><verb>
|
|
<url url="http://www.tldp.org">
|
|
<url url="http://www.tldp.org" name="Linux Documentation Project">.
|
|
&etago;verb>&etago;tscreen>
|
|
</verb></tscreen>
|
|
|
|
<sect2> Character Codes (macros) <label id="ch_codes">
|
|
<p>You don't always need to use these.
|
|
<itemize>
|
|
<item>Use <tt>&amp;</tt> for the ampersand (&),
|
|
<item>Use <tt>&lt;</tt> for a left bracket (<),
|
|
<item>Use <tt>&gt;</tt> for a right bracket (>),
|
|
<item>Use <tt>&etago;</tt> for a left bracket with a slash
|
|
(<tt>&etago;</tt>)
|
|
</itemize>
|
|
|
|
Use of these are optional and I seldom use them. <itemize>
|
|
<item>Use <tt>``</tt> and <tt>''</tt> for opening and closing double
|
|
quotes
|
|
<item>Use <tt>&shy;</tt> 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).
|
|
</itemize>
|
|
|
|
Only use these if LinuxDoc complains about it or fails to generate
|
|
them in the formated document. I've seldom had to use them.
|
|
<itemize>
|
|
<item>Use <tt>&dollar;</tt> for a dollar sign ($),
|
|
<item>Use <tt>&num;</tt> for a hash (#),
|
|
<item>Use <tt>&percnt;</tt> for a percent (%),
|
|
<item>Use <tt>&tilde;</tt> for a tilde (˜),
|
|
<item>Use <tt>&dquot;</tt> for ".
|
|
</itemize>
|
|
|
|
<sect> Getting/Using the LinuxDoc Software
|
|
<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.
|
|
|
|
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 to get text output, type: "sgml2txt --pass="-P-cbou"
|
|
--blanks=1 my-HOWTO.sgml". 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.
|
|
|
|
For sgml2txt, the option --pass="-P-cbou" is needed to get pure text
|
|
output since otherwise you get text output which puts 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).
|
|
|
|
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.
|
|
|
|
What a mess! 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 don't use this --pass ... option
|
|
then if you 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 pagers to read it.
|
|
|
|
<sect>Errors and Error Messages
|
|
|
|
<sect1>Errors That Don't Create Error Messages
|
|
<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.
|
|
|
|
<sect1>Actual Error Messages
|
|
<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.
|
|
|
|
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. Here's some of the jargon that you may want to skip
|
|
over.
|
|
|
|
<sect>Jargon in Error Messages
|
|
|
|
<sect1>Introduction
|
|
<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 "elements", "entities",
|
|
and "attributes". 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).
|
|
|
|
<sect1>Elements
|
|
<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.
|
|
|
|
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). In some cases, a tag doesn't enclose anything, like the
|
|
url tag for a link to the internet. Such tags are elements also.
|
|
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, they may still exist as elements.
|
|
|
|
<sect1>Entities
|
|
<p>An entity is like a macro definition. For example, one could
|
|
define a 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.
|
|
|
|
<sect> Writing the HOWTO
|
|
<sect1> Before you start writing
|
|
<p>First join the discuss list by going to <url url="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.
|
|
|
|
<sect1> Guidelines
|
|
<p> These are mostly by Tim Bynum (a former HOWTO coordinator).
|
|
<itemize>
|
|
<item> Be sure and use an accepted format (such as LinuxDoc :-).
|
|
<item> 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.
|
|
<item> 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.
|
|
<item> Make sure that you are covering the most recent version of the
|
|
available software.
|
|
<item> Consider including a "FAQ" section or sections called
|
|
"Common Problems" or "Trouble Shooting".
|
|
<item> Be sure to copyright it in your name and include a license
|
|
which meets the requirements stated in the LDP manifesto.
|
|
<item> Use the standard header with title, author, and date
|
|
(including a version number). See <ref id="example_3" name="Example 3">
|
|
<item> 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.
|
|
</itemize>
|
|
<sect1> Submitting the HOWTO, etc.
|
|
<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.
|
|
|
|
<sect> More Information
|
|
<p> There's a HOWTO: Linuxdoc-Reference that covers it in much
|
|
greater detail than this mini-HOWTO.
|
|
|
|
</article>
|