old-www/HOWTO/Linuxdoc-Reference-4.html

664 lines
16 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE>Linuxdoc Reference: Document Classes</TITLE>
<LINK HREF="Linuxdoc-Reference-5.html" REL=next>
<LINK HREF="Linuxdoc-Reference-3.html" REL=previous>
<LINK HREF="Linuxdoc-Reference.html#toc4" REL=contents>
</HEAD>
<BODY>
<A HREF="Linuxdoc-Reference-5.html">Next</A>
<A HREF="Linuxdoc-Reference-3.html">Previous</A>
<A HREF="Linuxdoc-Reference.html#toc4">Contents</A>
<HR>
<H2><A NAME="linuxdoc"></A> <A NAME="s4">4. Document Classes</A></H2>
<P>
<!--
documentclass
-->
<HR>
<PRE>
&lt;!element linuxdoc o o
(sect | chapt | article | report |
book | letter | telefax | slides | notes | manpage ) >
</PRE>
<HR>
<P>This is describing the overall class of the document, so naturally it has
(leave alone the doctype definition) to be the first tag enclosing your whole
document.
Some of the tags namely the <CODE>sect</CODE> and <CODE>chapt</CODE> (see section
<A HREF="Linuxdoc-Reference-6.html#sections">Sectioning Tags</A>) doesn't make any sense taken them
standalone despite being included as part of more complete classed document,
so we'll describe them later as a part of the other document classes.
Decide first which of the top mentioned document classes fits the type of the
document you want to write best.
<P>To find a detailed description of the document classes see table
<A HREF="#tclasses">Document classes</A>.
<P>
<CENTER><TABLE BORDER><TR><TD>
<BR>
Chapter</TD><TD>Class tag</TD></TR><TR><TD>
</TD></TR><TR><TD>
<A HREF="#article">Article Tag</A></TD><TD><CODE>&lt;atricle&gt;</CODE></TD></TR><TR><TD>
<A HREF="#report">Report Tag</A></TD><TD><CODE>&lt;report&gt;</CODE></TD></TR><TR><TD>
<A HREF="#book">Book Tag</A></TD><TD><CODE>&lt;book&gt;</CODE></TD></TR><TR><TD>
<A HREF="#letter">Letter Tag</A></TD><TD><CODE>&lt;letter&gt;</CODE></TD></TR><TR><TD>
<A HREF="#telefax">Telefax Tag</A></TD><TD><CODE>&lt;telefax&gt;</CODE></TD></TR><TR><TD>
<A HREF="#slides">Slides Tag</A></TD><TD><CODE>&lt;slides&gt;</CODE></TD></TR><TR><TD>
<A HREF="#notes">Notes Tag</A></TD><TD><CODE>&lt;notes&gt;</CODE></TD></TR><TR><TD>
<A HREF="#manpage">Manpage Tag</A></TD><TD><CODE>&lt;manpage&gt;</CODE>
<CAPTION>Document classes
<A NAME="tclasses"></A> </CAPTION>
</TD></TR></TABLE></CENTER>
<P>To me the <EM>article class</EM> is the most important one.
That<EFBFBD>s the reason why it<69>s described first and most detailed.
<P>
<H2><A NAME="article"></A> <A NAME="ss4.1">4.1 Article Tag</A>
</H2>
<P>
<!--
article!documentclass
-->
<!--
documentclass!article
-->
<!--
article
-->
<!--
tag!article
-->
<HR>
<PRE>
&lt;!element article - -
(titlepag, header?,
toc?, lof?, lot?, p*, sect*,
(appendix, sect+)?, biblio?) +(footnote)>
&lt;!attlist article
opts cdata "null">
</PRE>
<HR>
You can see that the <EM>article</EM> needs some tags included. They will be
explained in consequence.
<P>The <EM>options</EM> attribute (<CODE>opts</CODE>) takes a comma separated list with thy
different style (LaTeX <CODE>.sty</CODE>) sheets to inlude within the document.
<P>
<P>
<H3><A NAME="titlepag"></A> Titlepage Tag</H3>
<P>
<!--
titlepage
-->
<!--
tag!titlepage
-->
<HR>
<PRE>
&lt;!element titlepag o o (title, author, date?, abstract?)>
</PRE>
<HR>
The <EM>Titlepage</EM> Tag (<CODE>titlepag</CODE>) is implicitly placed as soon a you
started your <EM>document class</EM>. You don't need to write it explicitly.
Anyway you have to note it's mandatory tags. It's purpouse is to describe the
layout and elements of the titlepages.
<P>
<P>
<H3><A NAME="title"></A> Title Tag</H3>
<P>
<!--
title
-->
<!--
tag!title
-->
<HR>
<PRE>
&lt;!element title - o (%inline, subtitle?) +(newline)>
</PRE>
<HR>
Each <EM>document class</EM> wich owns a titlepage of course needs a <EM>title</EM>,
wich is noted down with a <CODE>&lt;title&gt;</CODE> tag.
You don't need to close thatone.
A title may contain a <EM>subtitle</EM> started by the <CODE>&lt;subtitle&gt;</CODE> tag.
<P>If you look at the headerpage of this document you'll find it to be mapped
from the tags:
<P>
<!--
example!title
-->
<!--
example!subtitle
-->
<PRE>
&lt;title>Linuxdoc Reference
&lt;subtitle>A introduction to the linuxdoc dtd
</PRE>
<H3><A NAME="author"></A> Author Tag</H3>
<P>
<!--
author
-->
<!--
tag!author
-->
<HR>
<PRE>
&lt;!element author - o (name, thanks?, inst?,
(and, name, thanks?, inst?)*)>
</PRE>
<HR>
Usually you place the (your) name here.
People should know who wrote the document,
so you place a <CODE>&lt;author&gt;</CODE> tag.
If you don't note the <CODE>name</CODE> tag it<69>s imlicitly placed.
The <EM>author</EM> has also optional items wich can be tagged within the
<CODE>author</CODE> tag.
<P>If you want to say thanks to anyone (might be somebody providing usefull
information) you place it within the <CODE>&lt;thanks&gt;</CODE> tag.
Next, if your writing is done in your position of an <EM>institution</EM>
staff member, place it within the <CODE>&lt;inst&gt;</CODE> tag.
<P>The <CODE>&lt;and&gt;</CODE> tag is starting the whole story again,
as if there would be a second <CODE>author</CODE> tag would have been started.
Clearly thisone is for coauthors.
<P>
<H3><A NAME="date"></A> Date Tag</H3>
<P>
<!--
date
-->
<!--
tag!date
-->
If you want to mark your document with a <EM>date</EM>, you can do that with the
<CODE>&lt;date&gt;</CODE> tag.
<BLOCKQUOTE>It's not checked weather you really place a valid date here, but
don't abuse it.</BLOCKQUOTE>
<P>
<H3><A NAME="abstract"></A> Abstract Tag</H3>
<P>
<!--
abstract
-->
<!--
tag!abstract
-->
This tag is intended for an <EM>abstract</EM> description of your document.
Don't mix the <CODE>&lt;abstract&gt;</CODE> tag withh an <EM>indruduction</EM> wich is
likely to be placed inside the first <EM>section</EM> of your document
(see section
<A HREF="Linuxdoc-Reference-6.html#sections">Sectioning</A>).
<P>
<P>
<H3><A NAME="header"></A> Header Tag</H3>
<P>
<!--
header
-->
<!--
tag!header
-->
<HR>
<PRE>
&lt;!element header - - (lhead, rhead) &gt;
&lt;!element lhead - o (%inline)&gt;
&lt;!element rhead - o (%inline)&gt;
</PRE>
<HR>
A <CODE>&lt;header&gt;</CODE> tag specifies what should be printed at the top of each
page.
It consists of a <EM>left heading</EM> i.e. <CODE>&lt;lhead&gt;</CODE> and a <EM>right
heading</EM> i.e. <CODE>&lt;rhead&gt;</CODE>).
Both elements are required, if a heading is used at all, but either may be
left empty, so that the effect of having only a left or right heading can be
achieved easily enough.
<P>As we will see, an initial header can be given after the title page.
Afterwards, a new header can be given for each new chapter or section. The
header printed on a page is the one which is in effect at the end of the
current page. So that the header will be that of the last section starting on
the page.
<P>
<P>
<H3><A NAME="toc"></A> Table Of Contents Tag</H3>
<P>
<!--
toc
-->
<!--
table of contense
-->
<!--
tag!toc
-->
If you place the <CODE>&lt;toc&gt;</CODE> tag, a <EM>table of contense</EM> will be
generated, by looking the section heading, and adding references.
<BLOCKQUOTE>In a hyperref document, this might be hyperrefs, in a LaTeX
document you will come to see the pagenumbers.</BLOCKQUOTE>
Only the sections major to the <CODE>sect3</CODE> will be included.
<P>
<P>
<H3><A NAME="lof"></A> List Of Figures Tag</H3>
<P>
<!--
lof
-->
<!--
list of figures
-->
<!--
tag!lof
-->
If you place the <CODE>&lt;lof&gt;</CODE> tag, a <EM>list of figures</EM> will be
generated, by looking the captions of the figures, and adding references.
<P>
<P>
<H3><A NAME="lot"></A> List Of Tables Tag</H3>
<P>
<!--
lot
-->
<!--
list of tables
-->
<!--
tag!lot
-->
If you place the <CODE>&lt;lot&gt;</CODE> tag, a <EM>list of tables</EM> will be
generated, by looking the captions of the tables, and adding references.
<P>
<P>
<H3><A NAME="body"></A> Body </H3>
<P>
<!--
body
-->
Here you place various sections according section
<A HREF="Linuxdoc-Reference-6.html#sections">Sectioning</A>.
There is no <EM>body tag</EM>.
The body starts with the first <EM>chapter</EM>, <EM>section</EM> or <EM>paragraph</EM>.
<P>
<P>
<H3><A NAME="appendix"></A> Appendix Tag</H3>
<P>
<!--
appendix
-->
<!--
tag!appendix
-->
In the end of the article you can place the <CODE>&lt;appendix&gt;</CODE> tag
<BLOCKQUOTE>Really you shouldn't think about people (e.g. m.d.s knifing your
belly here.</BLOCKQUOTE>
, wich starts a area of appended sections.
The <CODE>appendix</CODE> tag implies a different section numbering type to the
following section tags.
<P>
<H3><A NAME="biblio"></A> Bibliography Tag</H3>
<P>
<!--
bibliography
-->
<!--
biblio
-->
<!--
tag!biblio
-->
It's intended to gather all the <CODE>&lt;cites&gt;</CODE> and <CODE>&lt;ncites&gt;</CODE>
you used within your document. The <CODE>&lt;biblio&gt;</CODE> tag will be replaced
by a <EM>bibliography</EM> according the mapping type of the document,
maybe by hyperrefs maybe by section numbers or anything wich might be useful.
<BLOCKQUOTE>Until now I've not been able to create a <CODE>.bbl</CODE> file, so I
wasn't able to verify.</BLOCKQUOTE>
<P>
<P>
<H3><A NAME="footnote"></A> Footnote Tag</H3>
<P>
<!--
footnote
-->
<!--
tag!footnote
-->
A <EM>footnote</EM> may be place in any spot of your document.
Exactly the spot in yout document where you are placing
the <CODE>&lt;footnote&gt;</CODE> tag should be the one where the reference to the
tagged text shuld be rendered.
It should be used for additional information, wich is not necessary for
understanding the primary purpouse of yor document
but might be usefull, interesting, or funny.
<BLOCKQUOTE>Whereas the last one is not always true, even if you try.</BLOCKQUOTE>
anywhere within the article.
<P>
<H2><A NAME="report"></A> <A NAME="ss4.2">4.2 Report Tag</A>
</H2>
<P>
<!--
report
-->
<!--
tag!report
-->
<!--
documentclass!report
-->
<HR>
<PRE>
&lt;!element report - -
(titlepag, header?, toc?, lof?, lot?, p*,
chapt*, (appendix, chapt+)?, biblio?) +(footnote)>
</PRE>
<HR>
The <EM>report</EM> is a document class with a chapter oriented approach.
So within a document clasified by a <CODE>&lt;report&gt;</CODE> tag the
toplevel is grouped by the <CODE>&lt;chapt&gt;</CODE> tag (see
<A HREF="Linuxdoc-Reference-6.html#sections">Sectioning</A>). The rest of the structure is identical to the
<EM>article</EM> class
<A HREF="#article">Article Tag</A>.
<P>
<P>
<H2><A NAME="book"></A> <A NAME="ss4.3">4.3 Book Tag</A>
</H2>
<P>
<!--
book
-->
<!--
tag!book
-->
<!--
documentclass!book
-->
<HR>
<PRE>
&lt;!element book - -
(titlepag, header?, toc?, lof?, lot?, p*, chapt*,
(appendix, chapt+)?, biblio?) +(footnote) >
</PRE>
<HR>
You will notice that the <EM>book</EM> element is identical to the <EM>report</EM>
<A HREF="#report">Report Tag</A>.
So anything valid there is also valid if you classify your document with a
<CODE>&lt;book&gt;</CODE> tag.
<P>
<P>
<H2><A NAME="letter"></A> <A NAME="ss4.4">4.4 Letter Tag</A>
</H2>
<P>
<!--
letter
-->
<!--
tag!letter
-->
<!--
documentclass!letter
-->
<HR>
<PRE>
&lt;!entity % addr "(address?, email?, phone?, fax?)" >
&lt;!element letter - -
(from, %addr, to, %addr, cc?, subject?, sref?, rref?,
rdate?, opening, p+, closing, encl?, ps?)>
</PRE>
<HR>
<P>Also the purpose of the <EM>letter</EM> document class should be quite self
explaining. Place a <CODE>&lt;letter&gt;</CODE> tag if you want to write one.
<P>The letter's tags ar described in table
<A HREF="#tletter">Tags in a letter</A><P>
<CENTER><TABLE BORDER><TR><TD>
<BR>
tag</TD><TD>mandatory</TD><TD>what's it</TD></TR><TR><TD>
</TD></TR><TR><TD>
from</TD><TD>yes</TD><TD>from sender</TD></TR><TR><TD>
address</TD><TD>no</TD><TD>sender's address</TD></TR><TR><TD>
email</TD><TD>no</TD><TD>sender's email</TD></TR><TR><TD>
phone</TD><TD>no</TD><TD>sender's phone</TD></TR><TR><TD>
fax</TD><TD>no</TD><TD>sender's fax</TD></TR><TR><TD>
to</TD><TD>yes</TD><TD>receiver</TD></TR><TR><TD>
address</TD><TD>no</TD><TD>receiver's address</TD></TR><TR><TD>
email</TD><TD>no</TD><TD>receiver's email</TD></TR><TR><TD>
phone</TD><TD>no</TD><TD>receiver's phone</TD></TR><TR><TD>
fax</TD><TD>no</TD><TD>receiver's fax</TD></TR><TR><TD>
cc</TD><TD>no</TD><TD>carbon copy</TD></TR><TR><TD>
subject</TD><TD>no</TD><TD>letters subject</TD></TR><TR><TD>
sref</TD><TD>no</TD><TD>sender's reference</TD></TR><TR><TD>
rref</TD><TD>no</TD><TD>receiver's reference</TD></TR><TR><TD>
rdate</TD><TD>no</TD><TD>received date??</TD></TR><TR><TD>
opening</TD><TD>yes</TD><TD>opening</TD></TR><TR><TD>
paragraphs</TD><TD>yes</TD><TD>see
<A HREF="Linuxdoc-Reference-7.html#paragraph">Paragraphs</A></TD></TR><TR><TD>
closing</TD><TD>yes</TD><TD>closing</TD></TR><TR><TD>
encl</TD><TD>no</TD><TD>enclosure</TD></TR><TR><TD>
ps</TD><TD>no</TD><TD>post scriptum</TD></TR><TR><TD>
<CAPTION>Tags in a letter
<A NAME="tletter"></A> </CAPTION>
</TD></TR></TABLE></CENTER>
<P>
<H2><A NAME="telefax"></A> <A NAME="ss4.5">4.5 Telefax Tag</A>
</H2>
<P>
<!--
telefax
-->
<!--
tag!telefax
-->
<!--
documentclass!telefax
-->
<HR>
<PRE>
&lt;!element telefax - -
(from, %addr, to, address, email?,
phone?, fax, cc?, subject?,
opening, p+, closing, ps?)>
</PRE>
<HR>
Overall the structure is same to the <EM>letter</EM> class.
The only difference is that with the
<CODE>&lt;telefax&gt;</CODE> tag the receiver's <CODE>&lt;fax&gt;</CODE>
tag becomes mandatory.
<BLOCKQUOTE>Should be obvious why.</BLOCKQUOTE>
<P>
<P>
<H2><A NAME="slides"></A> <A NAME="ss4.6">4.6 Slides Tag</A>
</H2>
<P>
<!--
slides
-->
<!--
tag!slides
-->
<!--
documentclass!slides
-->
<HR>
<PRE>
&lt;!element slides - - (slide*) >
</PRE>
<HR>
The <EM>slides</EM> class is intended for overhead slides and transparencies.
So the structure of a document classified by a <CODE>&lt;slides&gt;</CODE> tag is a
very simple one.
It contains single slide(s) startes by a <CODE>&lt;slide&gt;</CODE> tag.
Nothing else.
If not explicitly written the first <EM>slide</EM> is started implicitly.
<P>
<H3><A NAME="slide"></A> Slide Tag</H3>
<P>
<HR>
<PRE>
&lt;!element slide - o (title?, p+) >
</PRE>
<HR>
A <CODE>&lt;slide&gt;</CODE> tag is only allowed within the <EM>slides</EM> document class.
A <EM>slide</EM> may contain:
<P>A <EM>title</EM> (see section
<A HREF="#title">The Title Tag</A>)
and one or more <EM>paragraph</EM>s
(see section
<A HREF="Linuxdoc-Reference-7.html#paragraph">Paragraphs</A>).
That's all.
<P>
<H2><A NAME="notes"></A> <A NAME="ss4.7">4.7 Note Tag</A>
</H2>
<P>
<!--
note
-->
<!--
tag!note
-->
<!--
documentclass!note
-->
<HR>
<PRE>
&lt;!element notes - - (title?, p+) >
</PRE>
<HR>
Intended as a class for personal notes the structure is even more simplified
than the <EM>slides</EM> document class
(see
<A HREF="#slide">The Slide Tag</A>).
After classifying a document with the <CODE>&lt;notes&gt;</CODE> tag only a
<EM>title</EM> (see section
<A HREF="#title">The Title Tag</A>)
and one or more <EM>paragraph</EM>s
(see section
<A HREF="Linuxdoc-Reference-7.html#paragraph">Paragraphs</A>) are allowed.
<P>
<P>
<H2><A NAME="manpage"></A> <A NAME="ss4.8">4.8 Manual Page Tag</A>
</H2>
<P>
<!--
manpage
-->
<!--
tag!manpage
-->
<!--
documentclass!manpage
-->
<HR>
<PRE>
&lt;!element manpage - - (sect1*)
-(sect2 | f | %mathpar | figure | tabular |
table | %xref | %thrm )>
</PRE>
<HR>
This document class is intended for writing <EM>manual pages</EM>, fitting the
need of the <CODE>man</CODE> programm.
In a document classified by a <CODE>&lt;manpage&gt;</CODE> tag the topleve
section tag is the <CODE>sect1</CODE> tag (see section
<A HREF="Linuxdoc-Reference-6.html#sections">Sectioning</A>), for easy pasting manual pages into an <EM>article</EM>
or <EM>book</EM> document class.
The exception here to the nortmal sectioning is, that there is only one
subsection level allowed (<CODE>sect2</CODE>).
<P>
<P>
<HR>
<A HREF="Linuxdoc-Reference-5.html">Next</A>
<A HREF="Linuxdoc-Reference-3.html">Previous</A>
<A HREF="Linuxdoc-Reference.html#toc4">Contents</A>
</BODY>
</HTML>