408 lines
15 KiB
HTML
408 lines
15 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.21">
|
|
<TITLE>: Learning LinuxDoc </TITLE>
|
|
<LINK HREF="Howtos-with-LinuxDoc-6.html" REL=next>
|
|
<LINK HREF="Howtos-with-LinuxDoc-4.html" REL=previous>
|
|
<LINK HREF="Howtos-with-LinuxDoc.html#toc5" REL=contents>
|
|
</HEAD>
|
|
<BODY>
|
|
<A HREF="Howtos-with-LinuxDoc-6.html">Next</A>
|
|
<A HREF="Howtos-with-LinuxDoc-4.html">Previous</A>
|
|
<A HREF="Howtos-with-LinuxDoc.html#toc5">Contents</A>
|
|
<HR>
|
|
<H2><A NAME="learn_"></A> <A NAME="s5">5.</A> <A HREF="Howtos-with-LinuxDoc.html#toc5">Learning LinuxDoc </A></H2>
|
|
|
|
<H2><A NAME="ss5.1">5.1</A> <A HREF="Howtos-with-LinuxDoc.html#toc5.1">Introduction</A>
|
|
</H2>
|
|
|
|
<P> LinuxDoc is a lot easier to learn than DocBook. But most of what
|
|
you learn about LinuxDoc would also be useful for DocBook. So if you
|
|
eventually decide to go for DocBook, most of the effort spent on
|
|
learning LinuxDoc will not be wasted.</P>
|
|
<P>One way to learn it is by examples. I've written 3 example files
|
|
ranging from easy to intermediate. The contents of these files have
|
|
been copied into this Howto. To turn them into individual files you
|
|
may cut them out (start with the first tag) and write them to files.
|
|
Then you could try turning one into text by using say sgml2txt
|
|
--pass="-P-cbou" some-example.sgml to see what it looks like. Make
|
|
sure the sgml file names end in .sgml. </P>
|
|
<P>If you want to look at some real examples you can just go to an LDP
|
|
mirror site, find the HOWTOs and select LinuxDoc SGML. Or go to the
|
|
main site directly:
|
|
<A HREF="http://cvs.tldp.org/go.to/LDP/LDP/howto/linuxdoc/">Howto Index (linuxdoc)</A> Now for the first simple example.</P>
|
|
|
|
<H2><A NAME="example_1"></A> <A NAME="ss5.2">5.2</A> <A HREF="Howtos-with-LinuxDoc.html#toc5.2">Example 1 (file name: example1.sgml) </A>
|
|
</H2>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
<!doctype linuxdoc system>
|
|
<article>
|
|
<title>First Example (example1)
|
|
<author>David S.Lawyer
|
|
|
|
<sect> Introduction
|
|
<p> This is a very simple example of "source" for the LinuxDoc text
|
|
formatting system. This paragraph begins with a paragraph tag (a "p"
|
|
enclosed in angle brackets). Notice that there are other tags, also
|
|
enclosed in angle brackets. If you don't see any tags, then you are
|
|
reading a converted file so find the source file: example1.sgml (which
|
|
contains the tags).
|
|
|
|
This is the next paragraph. Note that it is separated from the above
|
|
paragraph by just a blank line. Thus it needs no "p" tag in front of
|
|
it. The "p" tag is only needed for the first paragraph of a section
|
|
(just after the sect-tag). The file suffix: sgml stands for Standard
|
|
Generalized Markup Language. You are now reading the LinuxDoc flavor
|
|
of sgml as specified in the very first line of this file.
|
|
|
|
<sect> Tags
|
|
<p> Tags are words inside angle brackets. The "sect" tag above
|
|
marks the start of a new section of this example document.
|
|
"Introduction" was the first section and you are now reading the
|
|
second section titled "Tags". If this were a long document (like a
|
|
book), a section would correspond to a chapter.
|
|
|
|
Note that there are "article", "title" and "author" tags at the start
|
|
of this article. At the end of this article is an "/article" tag
|
|
marking the end of this article. Thus there is a pair of "article"
|
|
tags, the first being the start tag and the second being the end tag.
|
|
Thus this entire article is enclosed in a pair of "article" tags. In
|
|
later examples you'll see that there are other tags that come in pairs
|
|
like this. They affect whatever is between the pairs (start tag and
|
|
end tag). Any tag name which has "/" just before it is an "end tag".
|
|
|
|
When this source code is converted to another format (such as plain
|
|
text using the program sgml2txt) the tags are removed. Tags only help
|
|
the sgml2txt program make the conversion. There are more tags to
|
|
learn. So once you understand this example1, please go on to the next
|
|
example: example2. You don't need to actually memorize the tags, as
|
|
they will be repeated (but with little or no explanation) in later
|
|
examples.
|
|
</article>
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H2><A NAME="ss5.3">5.3</A> <A HREF="Howtos-with-LinuxDoc.html#toc5.3">Example 2 (file name: example2.sgml)</A>
|
|
</H2>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
<!-- This is a comment. It's ignored when this source file gets
|
|
converted to other formats. -->
|
|
<!-- The tag below says that this file is in LinuxDoc format -->
|
|
<!doctype linuxdoc system>
|
|
|
|
<article>
|
|
|
|
<title>Second Example (example2)
|
|
<author>David S. Lawyer
|
|
<date>v1.0, July 2000
|
|
|
|
<abstract>
|
|
This is the abstract. This document is the second example of using
|
|
the Linuxdoc-SGML flavor of sgml. It's more complex than the first
|
|
example (example1.sgml) but simpler than the third example
|
|
(example3.sgml). After you digest this you'll be able to write a
|
|
simple HOWTO using LinuxDoc. End of the abstract.
|
|
</abstract>
|
|
|
|
<!-- The "toc" = Table of Contents. It will be created here. -->
|
|
<toc>
|
|
|
|
<!-- Begin the main part of the article (or document) here. The part
|
|
above this is sort of a long header. -->
|
|
|
|
<sect>This Second Example (example2.sgml)
|
|
|
|
<p>Unless you're familiar with markup languages, you should first
|
|
read example1.sgml. You may want to run these example files thru a
|
|
translator such as sgml2txt to convert them to text and notice how the
|
|
result looks different than this "source" document with all its tags.
|
|
|
|
<sect>Article Layout
|
|
<sect1> Document Body
|
|
|
|
<p> After the header comes the body of the document, consisting of
|
|
nested sections marked by sect-tags. Subsections are
|
|
marked by sect1-tags. Since this is the first subsection
|
|
within the 2nd main section, it's becomes section 2.1. Within a
|
|
subsection marked by sect1 there may be sub-subsections like
|
|
sect2. There are even tags like sect3, sect4, etc., but you are
|
|
unlikely to need them. Note the the real tags must be enclosed in
|
|
angle brackets < and >.
|
|
|
|
<sect2> This is a sub-sub-section
|
|
<p>
|
|
It's 2.1.1. Note that a "p" tag may be on a line by itself. This
|
|
doesn't change a thing in the resulting documents.
|
|
|
|
<sect1>Document Header
|
|
<p> One way to create a header part is just to copy one from another
|
|
.sgml file. Then replace everything except the tags with the correct
|
|
info for your document. This is like using a "template".
|
|
|
|
<sect> More Features in example3
|
|
<p> With the tags in this example2 you can write a simple short document
|
|
a few pages long. But for longer documents or for other important
|
|
features such as putting links into documents, you need to study the
|
|
next example: example3. It will also show you how to create lists and
|
|
fonts.
|
|
</article>
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H2><A NAME="example_3"></A> <A NAME="ss5.4">5.4</A> <A HREF="Howtos-with-LinuxDoc.html#toc5.4">Example 3 </A>
|
|
</H2>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
<!doctype linuxdoc system>
|
|
<!-- Note the mailto: after my name. This allows the reader of html
|
|
format to click on my email address to send me email -->
|
|
|
|
<article>
|
|
<title>Third Example (example3)
|
|
<author>David S. Lawyer <url url="mailto:dave@lafn.org">
|
|
<date>v1.0, July 2000
|
|
<abstract>
|
|
This document is the third example of using the LinuxDoc flavor of sgml.
|
|
It's more complex than the second example.
|
|
</abstract>
|
|
<!-- Comment: toc = Table of Contents -->
|
|
<toc>
|
|
|
|
<sect> Fonts
|
|
<p>
|
|
While they will not show up in a plain text output, they will work
|
|
for other conversions.
|
|
<bf>boldface font</bf> <em>emphasis font</em> <sf>sans serif</sf>
|
|
<sl>slanted font</sl> <tt>typewriter font</tt> <it>italics font</it>
|
|
There's another way to get these same fonts by enclosing the text in
|
|
slashes like this: <bf/boldface font/ <em/emphasis font/
|
|
<sf/sans serif/ <sl/slanted font/ <tt/typewriter font/
|
|
<it/italics font/ Note that DocBook doesn't have font tags so it may
|
|
be best not to use fonts if you plan to convert to DocBook.
|
|
|
|
<sect> Links <label id="links_">
|
|
<p> You may create links (something that html browsers may click on to
|
|
go somewhere else). They might just go to another part of this
|
|
document (cross-references) such as to the "label" above, or they
|
|
could go to a website on the Internet.
|
|
|
|
<sect1> Cross-References
|
|
<p> If you click on <ref id="links_" name="Links"> you will be taken to
|
|
the start of the "Links" section above (which is labeled links_).
|
|
The label id may be any word you choose but it's a good idea to avoid
|
|
common words so that you can search for unique labels using your
|
|
editor. That's why I use links_ (with the underline). The name of
|
|
this link will be shown (in html format) as the name to click on.
|
|
This name (Links) will also be present in the text rendition.
|
|
|
|
<sect1> URL Links
|
|
<p> If you click on <url url="http://www.tldp.org"> you will get
|
|
to the Linux Documentation Project website. The next link adds a name
|
|
which people will click on: <url url="http://www.tldp.org"
|
|
name="Linux Documentation Project">. Using this second method, you may
|
|
not even need to explain where the link leads to since it's obvious by
|
|
the name.
|
|
|
|
<sect> Prohibited Characters
|
|
<p> Any word you type between angle brackets will be interpreted as a
|
|
tag. But what if you want to display a tag in a document? For this
|
|
you use a code word for the angle characters.
|
|
|
|
You may use &lt for < and &gt for >. lt = Less Than, gt =
|
|
Greater Than. For example, here's a p-tag: &lt;p&gt;. Of
|
|
course it doesn't actually start any paragraph, but it will appear in
|
|
the converted document as <p>. These codes all start with an &
|
|
character. The ; after the lt is to separate it. It's not needed if
|
|
there is a space after it. For example: 3 &lt 4. Actually, if
|
|
you knew that its OK to use an unpaired > then you could have written
|
|
<p> as &lt;p>. This will not be mistakenly recognized as a tag
|
|
since there is no opening <. Actually 3 < 4 works fine too.
|
|
|
|
There are other characters that you can't put into the document text
|
|
directly. For & in an AT modem command use: AT&amp;. If other
|
|
characters cause you trouble (they seldom will) see <ref id="ch_codes"
|
|
name="Character Codes (macros)"> or the "guide" that comes with
|
|
linuxdoc-tools or sgml-tools.
|
|
|
|
<sect> Verbatim, Code & Newline
|
|
<sect1> Verbatim
|
|
<p> If you want to insure that it will look exactly like you typed it
|
|
after it's converted to other formats, use verbatim (verb). This is
|
|
useful for creating tables, etc. But some things still get recognized
|
|
as markup even though they are between verbatim tags. This includes
|
|
the macros starting with & and end tags with /.
|
|
|
|
<tscreen><verb>
|
|
% sgml2txt --pass="-P-cbou" example.sgml
|
|
</verb></tscreen>
|
|
The "tscreen" sets the font to typewriter and indents it nicely.
|
|
|
|
<sect1> Code
|
|
<p> This encloses computer code between two dashed lines.
|
|
<tscreen><code>
|
|
Put computer source code here
|
|
</code></tscreen>
|
|
|
|
<sect1> Newline
|
|
<p> To force a newline use <newline>
|
|
This sentence always starts at the left margin.
|
|
|
|
<sect>Lists
|
|
<p>
|
|
This puts items into a list with a bullet at the start of each item.
|
|
They start with the "itemize" tag.
|
|
<itemize>
|
|
<item> This is the first item in a list.
|
|
<item> This is the second item
|
|
<itemize>
|
|
<item> Multiple levels (nesting) are supported.
|
|
<item> The second item in this sublist
|
|
</itemize>
|
|
<enum>
|
|
<item> Enumerated lists using <tt/enum/ also work.
|
|
<item> This is item number 2
|
|
</enum>
|
|
<item> The final item in the main list
|
|
</itemize>
|
|
</article>
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H2><A NAME="ss5.5">5.5</A> <A HREF="Howtos-with-LinuxDoc.html#toc5.5">LinuxDoc Quick Reference Sheet</A>
|
|
</H2>
|
|
|
|
<H3>Header Part</H3>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
<!doctype linuxdoc system>
|
|
<article>
|
|
<title>Quick Reference Sheet
|
|
<author>David S. Lawyer
|
|
<date>v1.0, July 2000
|
|
<abstract> abstract here </abstract>
|
|
<toc> <!-- Comment: toc = Table of Contents -->
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H3>Body Layout</H3>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
<sect> Chapter 1 Note: Put a <p> on the first line of
|
|
<sect1> Subsection 1.1 each section (or subsection, etc.)
|
|
<sect1> Subsection 1.2
|
|
<sect> Chapter 2 Choose title names to replace "Chapter"
|
|
<sect1> Subsection 2.1 "Subsection", etc.
|
|
<sect2> Sub-subsection 2.1.1
|
|
<sect2> Sub-subsection 2.1.2
|
|
<sect1> Subsection 2.2
|
|
</article>
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H3>Fonts</H3>
|
|
|
|
<P> There are two ways to get these:
|
|
<PRE>
|
|
<bf>boldface font</bf> <em>emphasis font</em> <sf>sans serif font</sf>
|
|
<sl>slanted font</sl> <tt>typewriter font</tt> <it>italics font</it>
|
|
<bf/boldface/ <em/emphasis/ <sf/sans serif/
|
|
<sl/slanted/ <tt/typewriter/ <it/italics/
|
|
</PRE>
|
|
</P>
|
|
|
|
<H3>Lists (nesting is OK)</H3>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
Ordinary unnumbered list: Numbered list:
|
|
<itemize> <enum>
|
|
<item> First item <item> First item
|
|
<item> Second item <item> Second item
|
|
<item> etc. <item> etc.
|
|
</itemize> </enum>
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H3><A NAME="links_"></A> Links </H3>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
Cross-References: An Email Link:
|
|
<ref id="links_" name="Links"> <url url="mailto:bob@tldp.org">
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H3>Newline, Verbatim, URLs </H3>
|
|
|
|
<P>
|
|
<BLOCKQUOTE><CODE>
|
|
<PRE>
|
|
To force a newline <newline>
|
|
<tscreen><verb>
|
|
<url url="http://www.tldp.org">
|
|
<url url="http://www.tldp.org" name="Linux Documentation Project">.
|
|
</verb></tscreen>
|
|
</PRE>
|
|
</CODE></BLOCKQUOTE>
|
|
</P>
|
|
|
|
<H3><A NAME="ch_codes"></A> Character Codes (macros) </H3>
|
|
|
|
<P>You don't always need to use these.
|
|
<UL>
|
|
<LI>Use <CODE>&amp;</CODE> for the ampersand (&), </LI>
|
|
<LI>Use <CODE>&lt;</CODE> for a left bracket (<),</LI>
|
|
<LI>Use <CODE>&gt;</CODE> for a right bracket (>),</LI>
|
|
<LI>Use <CODE>&etago;</CODE> for a left bracket with a slash
|
|
(<CODE></</CODE>)</LI>
|
|
</UL>
|
|
</P>
|
|
<P>Use of these are optional and I seldom use them.
|
|
<UL>
|
|
<LI>Use <CODE>``</CODE> and <CODE>''</CODE> for opening and closing double
|
|
quotes</LI>
|
|
<LI>Use <CODE>&shy;</CODE> for a soft hyphen (that is, an indication
|
|
that this is a good place to break a very long word to insert a
|
|
hyphen for horizontal justification). </LI>
|
|
</UL>
|
|
</P>
|
|
<P>Only use these if LinuxDoc complains about it or fails to generate
|
|
them in the formated document. I've seldom had to use them.
|
|
<UL>
|
|
<LI>Use <CODE>&dollar;</CODE> for a dollar sign ($),</LI>
|
|
<LI>Use <CODE>&num;</CODE> for a hash (#),</LI>
|
|
<LI>Use <CODE>&percnt;</CODE> for a percent (%),</LI>
|
|
<LI>Use <CODE>&tilde;</CODE> for a tilde (~),</LI>
|
|
<LI>Use <CODE>&dquot;</CODE> for ".</LI>
|
|
</UL>
|
|
</P>
|
|
|
|
<HR>
|
|
<A HREF="Howtos-with-LinuxDoc-6.html">Next</A>
|
|
<A HREF="Howtos-with-LinuxDoc-4.html">Previous</A>
|
|
<A HREF="Howtos-with-LinuxDoc.html#toc5">Contents</A>
|
|
</BODY>
|
|
</HTML>
|