discuss: My LinuxDoc Learning Template
Subject:
My LinuxDoc Learning Template
From:
David Lawyer ####@####.####
Date:
3 Mar 2005 07:36:30 -0000
Message-Id: <20050303073523.GA765@lafn.org>
<! This is all in Linuxdoc. Any comment or suggestions to improve it? -->
<!doctype linuxdoc system>
<!-- Here's an example of a LinuxDoc article. This paragraph is just
a comment. It's ignored when this source file gets converted to other
formats. -->
<article>
<!-- the above article-tag means that this is an "article" type of
document. Another type is "notes" which is even simpler than this.
-->
<!-- Begin the document heading. The tags shown below: title, author,
date, and abstract need no explanation. But don't change their order:
title must come first, etc. -->
<title>LinuxDoc Example
<author>David Lawyer
<date>v1.0, February 2005
<abstract>
This is the abstract. This article is an example of using the
Linuxdoc markup language (a flavor of sgml = Standard Generalized
Markup Language). The following explains it all.
<!-- A table of contents will automatically be created here due to the
toc-tag (toc = Table Of Contents) -->
<toc>
<!-- Begin the document body -->
<sect>First Section
<p>
This is the first sentence in the first section, also titled:
"First Section". The p-tag (in angle brackets < and > just above
"This") denotes the start of the this paragraph. p = paragraph. If
you don't see the p-tag, look at the sgml source of this file.
This is the second paragraph of the section: "First Section". The blank
line between paragraphs substitutes for a p-tag so this paragraph
needs no p-tags.
<sect> Second Section
<sect1> First Sub-Section
<p>Just like a book is divided up into chapters, a Linuxdoc article is
divided up into sections and subsections). This is the "Second
Section". Each section my opionally have subsections so this is the
"First Sub-Section". Note the sect-tag for sections and the sect1 tag
for subsections.
<sect1> Subsections Explained
<p>This is the 2nd subsection titled "Subsections Explained". We are
still in the section "Second Section". If sections are like chapters,
then each subsection is like just a portion of a chapter. As you see,
sect1 is the tag for a subsection. If you want some subsections
nested inside sect1 you just use a sect2 tag. There's even a sect3
tag for more nesting.
Here's the second paragraph of this subsection. To better understand
all this, you may want to convert this file to html by typing:
sgml2html --split=0 example.sgml. Ignore error messages. Then look
at the resulting html file using a browser.
<sect>Tags
<p>
This is a section titled "Tags". Tags are anything enclosed by the
brackets < and > such as the p-tag or sect-tag. These tags provide
formatting information, so the tags themselves don't appear in the
final converted documents. At the end of this paragraph is a
p-end-tag. It's not needed but shows that to create an end-tag you
just add a / to the tag. Many tags don't require any end-tags.</p>
<sect1> More About Tags
<p> Note that the p-tag doesn't have to be on a line by itself. This is
true for other tags too. Blank lines separate paragraphs. Of course
a p-tag, like the one above, starts a paragraph and is required after
a section type of tag: sect, sect1, sect2, etc.
Many tags enclose some text between the start and end tags. For
example: <em> this text will appear emphasized</em> since em =
emphasize. In some other cases the end tag is missing, but it's still
there implicitly even though you don't type it or see it. For
example, look at the title tag at the start of this document or the
missing p-end-tag for the paragraph above. Certain other tags don't
come in start-end pairs; like the newline-tag <newline>. This forces
a new line when the article gets converted to html for example.
<sect>The Source File
<p>A file with some tags in it is called the source file. What you
are reading right now is a source file if you see tags enclosed in <
and > brackets. Otherwise, what you're reading now has likely been
converted to another format such as plain text or html and the tags
have been eaten by the conversion. The reason for using a source file
is so that it can be converted to various other formats that people
like to read.
<sect>Links, Tables, Fonts, and Lists
<sect1>Links to the Internet (URLs)
<p>Here's an example of a link to the Internet (a url). In the html
rendition of this LinuxDoc article, just click on the link with the
specified name. Of course your PC must be connected to the Internet
but the html file may either reside at a website or in a file on your
PC.
<label id="ld_howto"> <!-- See next section for the label-tag -->
To learn LinuxDoc better, you may want to also read: <url
url="http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/Howtos-with-LinuxDoc.html"
name="Howtos-with-LinuxDoc">.
<sect1>Cross References <label id="cross-ref">
<p>
This subsection has been marked with a label-tag so that it can be
cross-referenced in the html version. This tag contains the id
(Identification) of the label: cross-ref. You may create a link
within this article that will go to this label (if clicked on).
For example: <ref id="cross-ref" name="Cross References">. When you
click on "Cross References" you go to location of the cross-ref label.
In this example the link to the label is so close to the actual label
that the link not really needed here. But normally such a link is much
further away.
<sect1>Tables and Fonts
<p> This sub-section shows both how to create tables and fonts. A
simple way to create a table is just to type in something that looks
like a table. Then you use tags to tell the converter not to change
the fonts or change the length of lines. You need to use 2 tags for
this: tscreen-tag (screen type fonts) and the verb-tag (verbatim:
don't format the lines). Don't try to use fonts other than "tscreen"
with the verb-tag.
<tscreen><verb>
TABLE of FONTS
FONT NAME TAG EXAMPLE 1 EXAMPLE 2
emphasized <em> <em>this is emphasized</em> <em/this is emphasized/
italics <it> <it>this is in italics</it> <it/this is in italics/
boldface <bf> <bf>boldface</bf> <bf/boldface/
typewriter <tt> <tt>typewriter</tt> <tt/typewriter/
sans serif <sf> <sf>sans serif</sf> <sf/sans serif/
slanted <sl> <sl>slanted</sl> <sl/slanted/
</verb></tscreen>
Note the required end tags for verb and tscreen. Since the tags in
this table are in a verbatim (verb) environment, they should be shown
verbatim (just like they look in the source) when you view the html
output in a browser. You don't see any fonts when you look at it. If
you use font-tags like this elsewhere and you'll actually see the
fonts when using a html browser on the html output. Actually there's
a bug in the linuxdoc software that results in the end-tags in the
above table not being recognized as verbatim.
<sect1>Character Codes
<p>How does one make a tag verbatim other then enclosing it with
verbatim tags? One way is to use character codes starting with &.
For example, in the above table one could use &etago; for </. etago =
End TAG Open. This would fix the bug. But to get the & itself where
& might be confused with the start of a character code, use &
There are more character codes in my Howto on <ref id="ld_howto"
name="LinuxDoc">.
<sect1>Lists
<p> For lists use the <tt/itemize/ tag or the <tt/enum/ tag:
<itemize>
<item> First item in list
<item> Second item in list
<itemize>
<item> First item of sub-list
<item> Second item of sub-list
</itemize>
<enum>
<item> Item number 1. of an enumerated list (note enum-tags)
<item> Item number 2. of the enumerated list
</enum>
<item> Third item in main list
</itemize>
</article>
