LDP/LDP/howto/linuxdoc/Howtos-with-LinuxDoc.sgml

<!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 &lt;angle brackets&gt;.  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 &lt;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 &amp;lt for < and &amp;gt for >.  lt = Less Than, gt =
Greater Than.  For example, here's a p-tag: &amp;lt;p&amp;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 &amp;lt 4.  Actually, if
you knew that its OK to use an unpaired > then you could have written
<p> as &amp;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;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>
&lt;tscreen>&lt;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;amp;</tt> for the ampersand (&amp;), 
<item>Use <tt>&amp;lt;</tt> for a left bracket (&lt;),
<item>Use <tt>&amp;gt;</tt> for a right bracket (&gt),
<item>Use <tt>&amp;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>&amp;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>&amp;dollar;</tt> for a dollar sign (&dollar;),
<item>Use <tt>&amp;num;</tt> for a hash (&num;),
<item>Use <tt>&amp;percnt;</tt> for a percent (&percnt;),
<item>Use <tt>&amp;tilde;</tt> for a tilde (&tilde;),
<item>Use <tt>&amp;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 &lt;p&gt;. 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:
&lt;.... id="my home page &gt; 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 &gt; 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 &lt;itemize> tag was missed, then  &lt;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 &lt;article> tag for
your document, then all of the document is the &lt;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 &lt;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>