LinuxDoc 比 DocBook 容易学习得多。但是，您学习到的关于 LinuxDoc 的大部分内容对于 DocBook 也很有用。因此，如果您最终决定使用 DocBook，那么在学习 LinuxDoc 上花费的大部分精力都不会浪费。
学习它的方法之一是通过示例。 我编写了 3 个示例文件，范围从简单到中级。 这些文件的内容已复制到本 Howto 中。 要将它们变成单独的文件，您可以将它们剪切出来（从第一个标签开始）并将它们写入文件。 然后，您可以尝试使用 sgml2txt --pass="-P-cbou" some-example.sgml 将其中一个转换为文本，看看它是什么样子。 确保 sgml 文件名以 .sgml 结尾。
如果您想查看一些真实的示例，您可以直接访问 LDP 镜像站点，找到 HOWTOs 并选择 LinuxDoc SGML。 或者直接访问主站点：Howto 索引 (linuxdoc) 现在是第一个简单示例。
<!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>
<!-- 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>
<!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>
<!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 -->
<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>
有两种方法可以获得这些
<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/
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>
Cross-References: An Email Link:
<ref id="links_" name="Links"> <url url="mailto:bob@tldp.org">
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>
您不总是需要使用这些。
& 表示 & 符号 (&)，< 表示左括号 (<)，> 表示右括号 (>)，&etago; 表示带斜杠的左括号 (</)这些是可选的，我很少使用它们。
`` 和 '' 表示开始和结束双引号­ 表示软连字符（即，指示这是一个断开很长的单词以插入连字符进行水平对齐的好位置）。仅当 LinuxDoc 抱怨它或无法在格式化文档中生成它们时才使用这些。 我很少需要使用它们。
$ 表示美元符号 ($)，# 表示井号 (#)，% 表示百分号 (%)，˜ 表示波浪号 (~)，&dquot; 表示 双引号 (").