[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
docutg: DocStandard with Copyright
Here is my best shot at our DocStandards (with copyright
info included).
Sorry about the size -- I just figured if I send the
text file along someone might read it.
Bill
__________________________________________
TASIS (The American School In Switzerland)
Lugano-Montagnola, Switzerland
<http://www.tasis.ch/>
SEUL/edu Documentation Standards
A Writer's Guide
Bill Tihen
Copyright © 2000 by Bill Tihen
Revision History
Revision 1.2
o Make changes/corrections offered by reviewers. o Please pay extra
attentiong to the sections on quotes and references and tell me if
there is a better way. o How do I fix linespecific graphic tag
listings? It should be seen as CDATA (as you can see it didn't come
out very readable). o Please comment on the structure section (and
template). o build new stylesheet or add copyright to intro (yuck).
Revision 1.1 17 January 2000
Add copyright info.
Revision 1.0 9 January 2000
First Draft - copyright not yet chosen.
This article describes the lists expectations of writing SEUL/edu
documents. This will ensure that all SEUL/edu documents will be
structured so that:
1. a reader can determine if the article will be helpful to them,
2. the SEUL/edu documents volunteers can properly organizing cataolg
articles (when we get that organized/advanced),
3. future search SEUL/edu documents will will be able to provide
meaningful results.
_________________________________________________________________
Introduction
DocBook (SGML) and DocBook XML are the documentation formats of the
future. The previously used documentation format, LinuxDoc, doesn't
support screen shots -- will be necessary (or at least very helpful)
for some of the software tutorials planned.
_________________________________________________________________
Document Use & Purpose
This document is designed to define a standard for SEUL/edu documents.
Hopefully, by adhering to these standards will eventually have a
library of documents that can be searched and indexed in a meaningful
way (without having to go back and modify the documents at a later
date -- which might not happen anyway).
This document can also serve as a tutorial on how to write DocBook
SGML files. Not only does it define SEUL/edu standards, but it has
many examples of DocBook files.
It is expected that the reader already has the appropriate software
installed to write and process DocBooks. It is also expected that the
reader is familiar with the use of the appropriate software. If the
reader is not the it is suggested that the reader consult the SEUL/edu
Guide: _DocBook Software Guide: A Writer's Guide_ (see Appendix
Appendix C.
_________________________________________________________________
Document Information
This document can be found at http://www.seul.org/edu/docs/
Please send corrections and suggestions to Bill Tihen at:
<bill@tasis.ch>
_________________________________________________________________
SEUL/edu Document Guidelines
These expectation are designed to provide a consistent presentation of
content so that the readers will know what to expect and how to use
our documents. Furthermore, this will provide enough consistency so
that we will be able to search and catalog the SEUL/edu's
documentation in an organized and meaningful way.
_________________________________________________________________
DocBook Version
We will create SEUL/edu documentation using DocBook version 3.1 or
later. Therefore, the first line will look like the following:
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
Furthermore, SEUL/edu documents will also be as DocBk XML compliant as
is currently possible. This will also ensure that our articles will be
DocBook v 5.0 compliant or at least they will only need minor
modifications to become compliant. DocBook v 5.0 will be XML
compliant. XML is emerging as an important standard for web based
documents. Therefore, it is important that we work toward making out
articles useful to this future standard (see the section called XML
Complianiance).
_________________________________________________________________
Article Document Type
We will be using articles, therefore the second tag should be an
article tag. It should look something like the following:
<article id="index">
This also means that the last tag of the document must be:
</article>
_________________________________________________________________
Article Structure
This section defines the basic document structures. The SEUL/edu
DocBook template, is included in the template and is also located at:
http://www.seul.edu/edu/docs/.
_________________________________________________________________
Article Header
Next we will describes all the meta information about the article.
This is done with the artheader. Therefore the third tag in a document
needs to be:
<artheader>
Remember that the last tag of the artcile header needs to be:
</artheader>
_________________________________________________________________
Title
Every article should have an appropriately descriptive title. This is
done with the title tag. In this document the tag looks like:
<title>SEUL/edu Documentation Standards</title>
_________________________________________________________________
Subtitle -- Document Category
In SEUL/edu documents the subtitle tag will be used to define the
Document category: Documents should be in at least one of the
following categories (we can create more if the need arises):
* A Software Guide -- is designed to teach people how to use the
Linux software. Many of these guides may have a strong educational
bias. (I expect many of these guides may include exercizes useful
in a classroom setting).
* A Teacher's Guide -- is designed to show teachers how to
effectively use Linux software in an educational setting.
* A Server/Service Configuration Guide -- is designed to show how to
setup and configure Linux servers and services. These will usually
contain useful configuration files and techniques that will
provide schools with secure and cost effective solutions.
* A Workstation Configuration Guide -- will contain Linux
workstation configuration files and techniques that will provide
schools with secure and cost effective workstations for students,
teachers and administrators.
* A Writer's Guide -- is designed to help people write SEUL/EDU
Documentation. They also define the SEUL/EDU documentation
standard so that we will be able to search and catalog the
SEUL/EDU's documentation in an organized and meaningful way.
For this article the following tag was used:
<subtitle>A Writer's Guide</subtitle>
_________________________________________________________________
Author, Editor and Other Credits
The author's name should be listed using the author tag.
<author>
<firstname>Bill</firstname><surname>Tihen</surname>
</author>
If the document has an editor it is important to credit them using the
editor tag. Below is an example:
<editor>
<firstname>A Nice</firstname><surname>Volunteer</surname>
</editor>
Finally, if someone helps in some other way, such as a technical
reveiw, etc. Use the othercredit to give the person credit. Below is
an example:
<othercredit>
<firstname>Ramin</firstname> <surname>Miraftabi</surname>
<contrib>Technical review, corrections and content advise.</contrib>
</othercredit>
_________________________________________________________________
Abstract
The abstract tag is used to include a quick (one paragraph) overview
of the content and goals of the document. This allows people to
quickly assess if the document the information they are looking for.
An example abstract is:
<abstract>
<para>
This article describes the lists expectations of writing
SEUL/edu documents. This will ensure that all SEUL/edu
documents will be structured so that:
<orderedlist>
<listitem>
<para>
a reader can determine if the article will be
helpful to them,
</para>
</listitem>
<listitem>
<para>
the SEUL/edu documents volunteers can properly organizing
cataolg articles (when we get that organized/advanced),
</para>
</listitem>
<listitem>
<para>
future search SEUL/edu documents will will be able to
provide meaningful results.
</para>
</listitem>
</orderedlist>
</para>
</abstract>
_________________________________________________________________
Edition and Revision Information
The revhistory tags are optional, but can be helpful to provide a
short description of the date and changes in each version of the
document. This will help readers know what changes have occured and
which sections they should reread.
<revhistory>
<revision>
<revnumber>1.0</revnumber>
<date>3 January 2000</date>
<revremark>
The first public release.
</revremark>
</revision>
</revhistory>
_________________________________________________________________
Publisher
The publisher is used to designate SEUL/edu as the publisher of the
document. Below is an example:
<publisher>
<publishername>SEUL/edu</publishername>
</publisher>
_________________________________________________________________
Copyright
The copyright tag is used to designate the author as the copywrite
holder of the document. SEUL/edu documents will use the OpenContent
Liscence http://www.opencontent.org. This tag is a wrapper for the
holder and the year tag. The holder tag identifies the copyright
holder -- the author (or the designee). The year tag identifies the
year(s) it was copyrighted. Below is an example:
<copyright>
<year>2000</year>
<holder>The Author</holder>
</copyright>
_________________________________________________________________
Legal Notice
SEUL/edu documents will use the OpenContent Liscence which can be
found at: http://www.opencontent.org/. It looks like the following:
<legalnotice>
<para>
This Document uses the OpenContent License (OPL).
</para>
<para>
Version 1.0, July 14, 1998.
</para>
<para>
This document outlines the principles underlying the OpenContent (OC)
movement and may be redistributedprovided it remains unaltered. For
legal purposes, this document is the license under which OpenContent
is madeavailable for use.
</para>
<para>
The original version of this document may be found at
<ulink url="http://opencontent.org/opl.shtml">
http://opencontent.org/opl.shtml</ulink>
</para>
<para>
LICENSE
</para>
<para>
Terms and Conditions for Copying, Distributing, and Modifying
</para>
<para>
Items other than copying, distributing, and modifying the Content
with which this license was distributed (such asusing, etc.) are
outside the scope of this license.
<orderedlist>
<listitem>
<para>
You may copy and distribute exact replicas of the OpenContent (
OC)
as you receive it, in any medium, provided that you conspicuous
ly and
appropriately publish on each copy an appropriate copyright not
ice and
disclaimer of warranty; keep intact all the notices that refer
to this
License and to the absence of any warranty; and give any other
recipients of the OC a copy of this License along with the OC.
You may
at your option charge a fee for themedia and/or handling involv
ed in
creating a unique copy of the OC for use offline, you may at yo
ur option
offer instructional support for the OC in exchange for a fee, o
r you
may at your option offer warranty in exchange for a fee. You ma
y not
charge a fee for the OC itself. You may not charge a fee for th
e sole
service of providing access to and/or use of the OC via a netwo
rk (e.g.
the Internet), whether it be via the world wide web, FTP, or an
y other
method.
</para>
</listitem>
<listitem>
<para>
You may modify your copy or copies of the OpenContent or any po
rtion
of it, thus forming works based on the Content, and distribute
such
modifications or work under the terms of Section 1 above, provi
ded that
you also meet all of these conditions:
<itemizedlist>
<listitem>
<para>
You must cause the modified content to carry prominent no
tices
stating that you changed it, the exact nature and content
of the changes,
and the date of any change.
</para>
</listitem>
<listitem>
<para>
b) You must cause any work that you distribute or publish
, that in
whole or in part contains or is derived from the OC or an
y part thereof,
to be licensed as a whole at no charge to all third parti
es under the
terms of this License, unless otherwise permitted under a
pplicable
Fair Use law.
</para>
</listitem>
</itemizedlist>
</para>
<para>
These requirements apply to the modified work as a whole. If iden
tifiable
sections of that work are not derived from the OC, and can be rea
sonably
considered independent and separate works in themselves, then thi
s License,
and its terms, do not apply to those sections when you distribute
them
as separate works. But when you distribute the same sections as p
art of
a whole which is a work based on the OC, the distribution of the
whole
must be on the terms of this License, whose permissions for other
licensees
extend to the entire whole, and thus to each and every part regar
dless of
who wrote it. Exceptions are made to this requirement to release
modified
works free of charge under this license only in compliance with F
air Use
law where applicable.
</para>
</listitem>
<listitem>
<para>
You are not required to accept this License, since you have not
signed
it. However, nothing else grants you permission to copy, distri
bute or
modify the OC. These actions are prohibited by law if you do no
t accept
this License. Therefore, by distributing or translating the OC,
or by
deriving works herefrom, you indicate your acceptance of this L
icense
to do so, and all its terms and conditions for copying, distrib
uting or
translating the OC.
</para>
</listitem>
</orderedlist>
</para>
<para>
NO WARRANTY
<orderedlist>
<listitem>
<para>
BECAUSE THE OPENCONTENT (OC) IS LICENSED FREE OF CHARGE, THERE
IS NO
WARRANTY FOR THE OC, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT
WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR O
THER
PARTIES PROVIDE THE OC "AS IS" WITHOUT WARRANTY OF ANY KIND, EI
THER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIE
D
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURP
OSE. THE
ENTIRE RISK OF USE OF THE OC IS WITH YOU. SHOULD THE OC PROVE F
AULTY,
INACCURATE, OR OTHERWISE UNACCEPTABLE YOU ASSUME THE COST OF AL
L
NECESSARY REPAIR OR CORRECTION.
</para>
</listitem>
<listitem>
<para>
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN W
RITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MIRROR AN
D/OR
REDISTRIBUTE THE OC AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DA
MAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAM
AGES
ARISING OUT OF THE USE OR INABILITY TO USE THE OC, EVEN IF SUCH
HOLDER
OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMA
GES.
</para>
</listitem>
</orderedlist>
</para>
</legalnotice>
_________________________________________________________________
An Example Article Header
Below is a complete example of an article header as defined by the
SEUL/edu standards.
<artheader>
<title>SEUL/edu Documentation Standards</title>
<subtitle>A Writer's Guide</subtitle>
<author>
<firstname>Bill</firstname><surname>Tihen</surname>
</author>
<editor>
<firstname>A</firstname><surname>Volunteer</surname>
</editor>
<othercredit>
<firstname>Ramin</firstname> <surname>Miraftabi</surname>
<contrib>Review and corrections and adding some content</contrib>
</othercredit>
<publisher><publishername>SEUL/edu</publishername></publisher>
<copyright>
<year>2000</year>
<holder>SEUL/edu</holder>
</copyright>
<abstract>
<para>
This article describes the lists expectations of writing
SEUL/edu documents. This will ensure that all SEUL/edu
documents will have information so that: 1) a reader can
determine if the article will be helpful to them, 2) the
SEUL/edu documents volunteers can properly organizing
cataolg articles (when we get that organized/advanced),
3) future search SEUL/edu documents will will be able to
provide meaningful results.
</para>
</abstract>
<edition>Version 1.0</edition>
<revhistory>
<revision>
<revnumber>1.1</revnumber>
<date>28 January 2000</date>
<revremark>
Updates & corrections made to the GUI section.
</revremark>
</revision>
<revision>
<revnumber>1.0</revnumber>
<date>3 January 2000</date>
<revremark>
The first public release.
</revremark>
</revision>
</revhistory>
<copyright>
<year>2000</year>
<holder>Bill Tihen</holder>
</copyright>
<legalnotice>
<para>
This Document uses the OpenContent License (OPL).
</para>
<para>
Version 1.0, July 14, 1998.
</para>
<para>
This document outlines the principles underlying the OpenContent (O
C)
movement and may be redistributedprovided it remains unaltered. For
legal purposes, this document is the license under which OpenConten
t
is madeavailable for use.
</para>
<para>
The original version of this document may be found at
<ulink url="http://opencontent.org/opl.shtml">
http://opencontent.org/opl.shtml</ulink>
</para>
<para>
LICENSE
</para>
<para>
Terms and Conditions for Copying, Distributing, and Modifying
</para>
<para>
Items other than copying, distributing, and modifying the Content
with which this license was distributed (such asusing, etc.) are
outside the scope of this license.
<orderedlist>
<listitem>
<para>
You may copy and distribute exact replicas of the OpenContent
(OC)
as you receive it, in any medium, provided that you conspicuo
usly and
appropriately publish on each copy an appropriate copyright n
otice and
disclaimer of warranty; keep intact all the notices that refe
r to this
License and to the absence of any warranty; and give any othe
r
recipients of the OC a copy of this License along with the OC
. You may
at your option charge a fee for themedia and/or handling invo
lved in
creating a unique copy of the OC for use offline, you may at
your option
offer instructional support for the OC in exchange for a fee,
or you
may at your option offer warranty in exchange for a fee. You
may not
charge a fee for the OC itself. You may not charge a fee for
the sole
service of providing access to and/or use of the OC via a net
work (e.g.
the Internet), whether it be via the world wide web, FTP, or
any other
method.
</para>
</listitem>
<listitem>
<para>
You may modify your copy or copies of the OpenContent or any
portion
of it, thus forming works based on the Content, and distribut
e such
modifications or work under the terms of Section 1 above, pro
vided that
you also meet all of these conditions:
<itemizedlist>
<listitem>
<para>
You must cause the modified content to carry prominent
notices
stating that you changed it, the exact nature and conte
nt of the changes,
and the date of any change.
</para>
</listitem>
<listitem>
<para>
b) You must cause any work that you distribute or publi
sh, that in
whole or in part contains or is derived from the OC or
any part thereof,
to be licensed as a whole at no charge to all third par
ties under the
terms of this License, unless otherwise permitted under
applicable
Fair Use law.
</para>
</listitem>
</itemizedlist>
</para>
<para>
These requirements apply to the modified work as a whole. If id
entifiable
sections of that work are not derived from the OC, and can be r
easonably
considered independent and separate works in themselves, then t
his License,
and its terms, do not apply to those sections when you distribu
te them
as separate works. But when you distribute the same sections as
part of
a whole which is a work based on the OC, the distribution of th
e whole
must be on the terms of this License, whose permissions for oth
er licensees
extend to the entire whole, and thus to each and every part reg
ardless of
who wrote it. Exceptions are made to this requirement to releas
e modified
works free of charge under this license only in compliance with
Fair Use
law where applicable.
</para>
</listitem>
<listitem>
<para>
You are not required to accept this License, since you have n
ot signed
it. However, nothing else grants you permission to copy, dist
ribute or
modify the OC. These actions are prohibited by law if you do
not accept
this License. Therefore, by distributing or translating the O
C, or by
deriving works herefrom, you indicate your acceptance of this
License
to do so, and all its terms and conditions for copying, distr
ibuting or
translating the OC.
</para>
</listitem>
</orderedlist>
</para>
<para>
NO WARRANTY
<orderedlist>
<listitem>
<para>
BECAUSE THE OPENCONTENT (OC) IS LICENSED FREE OF CHARGE, THER
E IS NO
WARRANTY FOR THE OC, TO THE EXTENT PERMITTED BY APPLICABLE LA
W. EXCEPT
WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER
PARTIES PROVIDE THE OC "AS IS" WITHOUT WARRANTY OF ANY KIND,
EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPL
IED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PU
RPOSE. THE
ENTIRE RISK OF USE OF THE OC IS WITH YOU. SHOULD THE OC PROVE
FAULTY,
INACCURATE, OR OTHERWISE UNACCEPTABLE YOU ASSUME THE COST OF
ALL
NECESSARY REPAIR OR CORRECTION.
</para>
</listitem>
<listitem>
<para>
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MIRROR
AND/OR
REDISTRIBUTE THE OC AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL D
AMAGES
ARISING OUT OF THE USE OR INABILITY TO USE THE OC, EVEN IF SU
CH HOLDER
OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DA
MAGES.
</para>
</listitem>
</orderedlist>
</para>
</legalnotice>
</artheader>
_________________________________________________________________
Define Introduction
Every article's first section should be the introduction which should
contain the following information (or more as necessary). In anycase
to create the content we use the section tag. The attribute
id="introduction" is important for web pages. Use the title tag to
define the title shown. Finally, use the para tag to introduce the
topic to the reader and present any relevant or helpful background
information.
The below example is what is used in this document:
<section id="intro">
<title>Introduction</title>
<para>
DocBook (SGML) and DocBook XML are the documentation formats
of the future. The previously used documentation format,
LinuxDoc, doesn't support screen shots -- will be necessary
(or at least very helpful) for some of the software tutorials
planned.
</para>
And of course you will need to close the introduction with the
following tag:
</section> <!-- The end of the Introduction -->
_________________________________________________________________
Define Document Use & Purpose
This is section is used to describe to the reader why the document was
written and how to best use the document. This section may not be
necessary if the abstract contains the same information. Below is the
example used in this document.
<section id="doc-purpose">
<title>Document Use & Purpose</title>
<para>
This document is designed to define a standard for &seuledu;
documents. Hopefully, by adhering to these standards will
eventually have a library of documents that can be searched
and indexed in a meaningful way (without having to go back
and modify the documents at a later date -- which might not
happen anyway).
</para>
<para>
This document can also serve as a tutorial on how to write
DocBook &sgml; files. Not only does it define &seuledu;
standards, but it has many examples of DocBook files.
</para>
<para>
It is expected that the reader already has the appropriate
software installed to write and process DocBooks. It is
also expected that the reader is familiar with the use of
the appropriate software. If the reader is not the it is
suggested that the reader consult the &seuledu; Guide:
_DocBook Software Guide: A Writer's Guide_.
</para>
</section>
_________________________________________________________________
Define Document Information
Should include the SEUL/edu documents URL.
It should also contain the author(s) contact information so that
readers can and submit corrections, comments, suggestions and
(hopefully) gratitude.
For this document the document information section looks like:
<section id="doc-info">
<title>Document Information</title>
<para>
This document can be found at
<ulink url="http://www.seul.org/edu/docs/">
http://www.seul.org/edu/docs/</ulink>
</para>
<para>
Please send corrections and suggestions to Bill Tihen at:
<address><email>bill@tasis.ch</email></address>
</para>
</section>
_________________________________________________________________
Example Introduction
Below is the SGML code used in the Introduction section of this
article.
<section id="intro">
<title>Introduction</title>
<para>
DocBook (&sgml;) and DocBook &xml; are the documentation
formats of the future. The previously used documentation
format, LinuxDoc, doesn't support screen shots -- will be
necessary (or at least very helpful) for some of the
software tutorials planned.
</para>
<section id="doc-purpose">
<title>Document Use & Purpose</title>
<para>
This document is designed to define a standard for
&seuledu; documents. Hopefully, by adhering to these
standards will eventually have a library of documents
that can be searched and indexed in a meaningful way
(without having to go back and modify the documents at
a later date -- which might not happen anyway).
</para>
<para>
This document can also serve as a tutorial on how to write
DocBook &sgml; files. Not only does it define &seuledu;
standards, but it has many examples of DocBook files.
</para>
<para>
It is expected that the reader already has the appropriate
software installed to write and process DocBooks. It is
also expected that the reader is familiar with the use of
the appropriate software. If the reader is not the it is
suggested that the reader consult the &seuledu; Guide:
_DocBook Software Guide: A Writer's Guide_.
</para>
</section> <!-- Doc Purpose -->
<section id="doc-info">
<title>Document Information</title>
<para>
This document can be found at
<ulink url="http://www.seul.org/edu/docs/">
http://www.seul.org/edu/docs/</ulink>
</para>
<para>
Please send corrections and suggestions to Bill Tihen at:
<address><email>bill@tasis.ch</email></address>
</para>
</section> <!-- Doc info -->
</section> <!-- Introduction -->
_________________________________________________________________
Content Sections
Every article should contain as many sections as needed to clearly
cover the topic at hand. These will be done as additional sections
after the close of the Introduction. Please use helpful id attributes,
this will simplify HTML page generation. Therefore, a typical skelaton
section would look like:
<section id="important-topic">
<title>An Important Topic</title>
<para>
Important topics and groupings get their own sections
</para>
</section>
_________________________________________________________________
Appendices
Appendices use the appendix tag. Appendices are used to describe
related but somewhat offtopic (out of the scope of the article) but
may still be helpful for the reader to have included. An example
follows:
<appendix id="appendexample">
<title>An example</title>
<para>
Describe the information.
</para>
</appendix>
_________________________________________________________________
Defining Additional Resources
The final appendix will be titled "Defining Additional Resources". It
will be broken into two sections. The first one will be titled
"Non-Printed Resources" and the second section will be untitled,
because it will contain the bibliography, which will create its own
title. An example follows:
<appendix id="resources">
<title>Resources</title>
And remember that the last line of this appendix will be:
</appendix>
_________________________________________________________________
Define Non-Printed Resources
The non-printed resources should use the variablelist tag as a wrapper
to list the resources. The term tag should contain the title of the
resource. The listitem tag should contain a description and how to
find the resource. An example follows:
<section id="non-printed">
<title>Non-Printed Resources</title>
<variablelist>
<varlistentry>
<term>Open Source Writers Group</term>
<listitem>
<para>
This is a group dedicated to supporting writers
in the Open Source community. Thier website is
<ulink url="http://www.oswg.org/">
http://www.oswg.org/</ulink>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Linux &sgml; Software:
A Writer's Guide</term>
<listitem>
<para>
This is an introduction to Linux software useful
to writing &sgml; documents. It covers how to
configure and use the software. It can be found
at <ulink url="http://www.seul.org/edu/docs">
http://www.seul.org/edu/docs</ulink>
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
_________________________________________________________________
Define Printed Resources
The next section will contain the printed resources. In this section
use the bibliography tag. An example follows:
<section id="bibliography">
<title></title>
<para></para>
<bibliography>
<bibliodiv><title>Books</title>
<biblioentry>
<title>DocBook</title>
<subtitle>The Definitive Guide</subtitle>
<authorgroup>
<author>
<firstname>Norman</firstname>
<surname>Walsh</surname>
</author>
<author>
<firstname>Leonard</firstname>
<surname>Muellner</surname>
</author>
</authorgroup>
<isbn>1-56592-580-7</isbn>
<publisher>
<publishername>
O'Reilly & Associates, Inc.
</publishername>
<address>
<street>101 Morris Street</street>
<city>Sebastopol</city>
<state>California</state>
<postcode>95472</postcode>
</address>
</publisher>
<pubdate>October 1999</pubdate>
<bibliomisc>
This really is a complete guide. Buy the Book,
or if you really like reading webpages you can
find the book online at
<ulink url="http://www.docbook.org/">
http://www.docbook.org/</ulink>
</bibliomisc>
</biblioentry>
</bibliodiv>
<bibliodiv><title>Periodicals</title>
<biblioentry>
<abbrev>Walsh97</abbrev>
<biblioset relation=journal>
<title>Linux Journal</title>
<publisher>
<publishername>
Specialized Systems Consultants
(<abbrev>SSC</abbrev>), Inc.
</publishername>
</publisher>
<issn>1075-3583</issn>
<editor>
<firstname>Peter H.</firstname>
<surname>Salus</surname>
</editor>
</biblioset>
<biblioset relation=article>
<title>World Domniation</title>
<author>
<surname>Raymond</surname>
<firstname>Eric S.</firstname>
</author>
<copyright>
<year>2000</year>
<holder>
Specialized Systems Consultants
(<abbrev>SSC</abbrev>), Inc.
</holder>
</copyright>
<pagenums>48-49</pagenums>
</biblioset>
</biblioentry>
</bibliodiv>
</bibliography>
</section>
_________________________________________________________________
An Complete Example Resource Appendix
A complete example of a Reference Appendix follows:
<appendix id="resources">
<title>Resources</title>
<section id="non-printed">
<title>Non-Printed Resources</title>
<variablelist>
<varlistentry>
<term>DocBook: The Definitive Guide</term>
<listitem>
<para>This is the website for the book _DocBook:
The Definitive Guide_. This site has the most up
to date version of the book in &sgml;, &html; and
maybe other formats too. You can find this
information at: <ulink url="http://www.docbook.org/">
http://www.docbook.org/</ulink>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Open Source Writers Group</term>
<listitem>
<para>
This is a group dedicated to supporting writers
in the Open Source community. Thier website is
<ulink url="http://www.oswg.org/">
http://www.oswg.org/</ulink>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DocBook <acronym>DTD</acronym></term>
<listitem>
<para>
The latest DocBook <acronym>DTD</acronym> can
be found at
<ulink url="http://www.oasis-open.org/docbook/">
http://www.oasis-open.org/docbook/</ulink>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DkBook <acronym>XML</acronym>
<acronym>DTD</acronym></term>
<listitem>
<para>
The latest DkBook <acronym>XML</acronym>
<acronym>DTD</acronym>
can be found at Norman Walsh's site at
<ulink url="http://nwalsh.com/docbook/xml/">
http://nwalsh.com/docbook/xml/</ulink>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Linux &sgml; Software:
A Writer's Guide</term>
<listitem>
<para>
This is an introduction to Linux software useful
to writing &sgml; documents. It covers how to
configure and use the software. It can be found
at <ulink url="http://www.seul.org/edu/docs">
http://www.seul.org/edu/docs</ulink>
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="bibliography">
<title></title>
<para></para>
<bibliography>
<biblioentry>
<title>DocBook</title>
<subtitle>The Definitive Guide</subtitle>
<authorgroup>
<author>
<firstname>Norman</firstname>
<surname>Walsh</surname>
</author>
<author>
<firstname>Leonard</firstname>
<surname>Muellner</surname>
</author>
</authorgroup>
<isbn>1-56592-580-7</isbn>
<publisher>
<publishername>
O'Reilly & Associates, Inc.
</publishername>
<address>
<street>101 Morris Street</street>
<city>Sebastopol</city>
<state>California</state>
<postcode>95472</postcode>
</address>
</publisher>
<pubdate>October 1999</pubdate>
<bibliomisc>
This really is a complete guide. Buy the Book, or
if you really like reading webpages you can find the
book online at <ulink url="http://www.docbook.org/">
http://www.docbook.org/</ulink>
</bibliomisc>
</biblioentry>
</bibliography>
</section>
</appendix>
_________________________________________________________________
SEUL/edu Tag Guilelines
Please read this carefully -- if this section is adhered to, it will
ensure that we will eventually have a library of articles which can be
searched in a meaningful way. It will also ensure that our will be
compliant with new versions of DocBook with minimal effort.
_________________________________________________________________
Acronyms
Acronyms should be marked with the acronym tag. This is likely to be
very helpful when doing searches. Below is an example.
<acronym>HTML</acronym> is a format commonly used to describe
the look of a documents. However, describing only the look of
a document has drawback. It is often also useful to describe the
content of a document. <acronym>SGML</acronym> is a commonly used
format to accomplish this.
_________________________________________________________________
Applications
The name of applications should be marked with the application tag as
shown below.
<application>Nedit</application> was the application used
to create this <acronym>SGML</acronym> document.
Repeatedly, typing <application> while describing a program can become
quite a nusiance. Therefore, you can define your own entities in SGML
(see the section called Defining User Entities in Appendix Appendix
A).
_________________________________________________________________
Commands
When describing command please use the command tag. An example of the
command tag is shown below.
<cmdsynopsis>
<command>sgmltools</command>
<arg>-b html</arg>
<arg><replaceable>filename.sgml</replaceable></arg>
</cmdsynopsis>
These tags will result in the following output:
sgmltools [-b html] [filename.sgml]
_________________________________________________________________
Filenames, Paths & URLs
To describe files, paths we use the filename tag. An example of
describing a files are shown below.
<filename>httpd.log</filename>
or
<filename>/var/httpd/logs/httpd.log</filename>
an example of describing a path is:
<filename class=directory>/usr/local/bin/</filename>
Although fundamentally, a URL is similar to a filename or a directory,
we use the ulink tag instead because it allows us an active link on
html pages.
<ulink
url="http://www.seul.org/edu/docs">http://www.seul.org/edu/docs
</ulink>
_________________________________________________________________
Describing the Keyboard
When one is is describing the keys on the keyboard use the keycap tag.
If you would like to describe two keys being pressed simultaneously,
then put a plus sign "+" between them inside the keycap tag. Finally,
if you have a series of keys that need to be use to accomplish an
action then use the keycombo tag as a wrapper for the keycap tag.
Below is an example of how to use these tags.
<para>
To save (or <emphasis>w</emphasis>rite) while using
<application>vi</application> (a text-based text-editor)
you must be in command mode and then type:
<keycap>:</keycap><keycap>w</keycap>.
</para>
<para>
To save while using <application>Nedit</application>
(a gui-based text-editor) one either use the menu
accelerator keys: <keycombo><keycap>Alt+f</keycap>
<keycap>s</keycap></keycombo>
or simply use the shortcut
<keycombo><keycap>Ctrl+s</keycap></keycombo>.
</para>
The above example looks like this in a document:
To save (or write) while using vi (a text-based text-editor) you must
be in command mode and then type: :w.
To save while using Nedit (a gui-based text-editor) one either use the
menu accelerator keys: Alt+f-s or simply use the shortcut Ctrl+s.
_________________________________________________________________
Program Listings
Sample Code will use the programlisting tag. Below is an example of
the source code of a Java applet.
<programlisting>
import java.applet.*;
import java.awt.*;
public Howdy extends Applet {
public void init() {
Label myLabel = new label("Howdy");
add(myLabel);
}
}
</programlisting>
Sometimes it is helpful to be able to include an external file. To do
this you can use the graphic tag (see the section called List an
External Program in Appendix Appendix A).
Sometimes it is helpful to be able to include SGML or HTML symbols in
a program (especially when displaying SGML or HTML). Howerver, these
symbols arrise in other contexts too. The solution to this is to use
the CDATA structure (see the section called CDATA in Appendix Appendix
A) or to convert all the SGML symbols to their respective SDATA
entities (see the section called SDATA Entities in Appendix Appendix
A), YUCK!
Sometimes one would like to comment on the code listed. One can use
the lineannotation tag (see the section called Annotating a Line in
Appendix Appendix A) or callout (see the section called Appended
Annotations in Appendix Appendix A) to accomplish this.
_________________________________________________________________
Describing Screen Text
The screen should be used to describe text a user might see on the
screen. However, it is also important that we distinguish between what
is printed on the screen and what the user types in. Therefore, please
use the prompt tag to display what the computer prints to the screen
and the userinput tag for information the user inputs. Below is an
example of a description of the login process.
<screen>
<prompt>login:</prompt> <userinput>bill</userinput>
</screen>
It is also possible that one would like to comment on what is
displayed on the screen. One can use the lineannotation tag (see the
section called Annotating a Line in Appendix Appendix A) or callout
(see the section called Appended Annotations in Appendix Appendix A).
The second solution is to use the callout tags. This tag displays the
comment at the end of the screen display. This tag allows the author
to provide a much longler explanation and can be less confusing in an
unformatted text document. However, it can also be distracting to the
reader and is certainly a more complex tag to use. Below is an
example:
<screen>
<prompt>Login:</prompt> <userinput>bill</userinput> <co id="login">
<prompt>Password:</prompt> <userinput>secret</userinput> <co id="pass">
</screen>
<calloutlist>
<callout arearefs="login">
<para>
Some systems use <quote>Username:</quote> as the prompt.
</para>
</callout>
<callout arearefs="pass">
<para>
Enter the secret password, please be sure your password
is difficult to guess and easy to remember.
</para>
</callout>
</calloutlist>
Here is what this actually looks like.
Login: bill (1)
Password: secret (2)
(1)
Some systems use "Username:" as the prompt.
(2)
Enter the secret password, please be sure your password is
difficult to guess and easy to remember.
The CDATA structure may be used with the screen tag. Normally this is
not necessary. However, it is could be handy if you needed to use
callouts to describe a DOS directory listing, because it is not
possible to use the when using the callout (see the section called
Appended Annotations in Appendix Appendix A) or lineannotation tags
(see the section called Annotating a Line in Appendix Appendix A).
_________________________________________________________________
Quotes
Crediting Other People's Words and Ideas
It is very important that we remember to credit others if we use their
ideas or words.
_________________________________________________________________
Short Quotes
In-line Quotes
Short quotations use the quote tag. A short qute is defined as less
than three lines long. In this case you will need to give the credit
to the author in the context of your text. An example follows:
<para>
The Buddhist teacher, Chögyam Trungpa,
is known to have said, <quote>The mark of
learning is gentleness.</quote>
</para>
This will look like the following:
The Buddhist teacher, Chögyam Trungpa, is known to have said, "The
mark of learning is gentleness."
_________________________________________________________________
Long Quotes
Block Quotes
Long quotes (more than three lines long) are marked with the
blockquote tag. This acts as a wrapper for the attribution, citetitle
and para tags. These tags are used in the following way:
* The para tag is used to hold the actual quote.
* The attribution tag is used for the author.
* The citetitle tag is used for the title of the book/article or the
name of the speech when it was said.
Here is an example:
<blockquote>
<attribution>
Chögyam Trungpa,
<citetitle pubwork="book">
Shambhala: The Sacred Path of the Warrior
</citetitle>
</attribution>
<para>
Through the practice of sitting still and following your
breath as it goes out and dissolves, you are connecting with
your heart. By simply letting yourself be, as you are, you
will develop genuine sympathy towards yourself.
</para>
</blockquote>
Here is what this example looks like.
Through the practice of sitting still and following your breath as it
goes out and dissolves, you are connecting with your heart. By simply
letting yourself be, as you are, you will develop genuine sympathy
towards yourself.
-- Chögyam Trungpa, Shambhala: The Sacred Path of the Warrior
_________________________________________________________________
Describing SGML Tags
If you are authoring descriptions of SGML tags then use the sgmltag
tag to mark them. Below is an example:
If you are authoring descriptions of &sgml; tags then use the
<sgmltag>sgmltag</sgmltag> tag to mark them.
_________________________________________________________________
GUI Tag Conventions
Graphical User Interfaces (GUI) have become popular and we will
probably need to describe GUI environments more and more. As Linux
becomes easier to use (more GUI oriented).
_________________________________________________________________
GUI Menus
To describe menus and the items listed in menus use the guimenu and
guimenuitem tags. If the guimenu and guimenuitem will be used to
describe how to select some action while using a program then one
should use the wrapper menuchoice. Finally, it is good programming to
allow all menu items to be used without the mouse. To describe this
use the accel tag. Below is an example of how to use these tags.
To save when using <application>Nedit</application> you go
to the menu bar and choose:
<menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>S</accel>ave</guimenuitem>
</menuchoice>.
This will end up looking like the following:
To save when using Nedit you go to the menu bar and choose:
File->Save.
_________________________________________________________________
Keyboard Shortcuts
Often using a mouse is tedious for common tasks. Therefore,
programmers often build in keyboard-shortcuts to simplify their
program. These should be described using the shortcut tag as a wrapper
for the keyboard tags (see the section called Describing the Keyboard
for an explanation of these tags). The shortcut tag must be wrapped
inside the menuchoice tag. Below is an example of how to use this tag.
To save when using <application>Nedit</application>
you go to the menu bar and choose:
<menuchoice>
<shortcut>
<keycombo><keysym>Ctrl+s</keysym></keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>S</accel>ave</guimenuitem>
</menuchoice>.
This will look like:
To save when using Nedit you go to the menu bar and choose: File->Save
(Ctrl+s).
_________________________________________________________________
Mouse Actions
Describe mouse actions with the mousebutton tag. Below is an example
of it's use.
To get additional menus while using the program
<application>GIMP</application> you need to
<mousebutton>right click</mousebutton> on the image.
This looks like (in an unformated text document you won't see any
difference):
To get additional menus while using the program GIMP you need to right
click on the image.
_________________________________________________________________
Labels
Use the guilabel to describe a label on a GUI screen. This tag is
usually to identify the appropriate field where a user must do
something. Below is an example of using this tag.
Now that you have opened the Save as window, you will
need to <mousebutton>click</mousebutton> in the text
field labeled <guilabel>Save as</guilabel> and enter
the name you would like to call the file.
This will look like (in an unformated text document you won't see any
difference):
Now that you have opened the Save as window, you will need to click in
the text field labeled Save as and enter the name you would like to
call the file.
_________________________________________________________________
XML Complianiance
In case we eventually use a DocBook XML DTD, it is strongly
recommended that we use the following tagging conventions so that we
will be as XML compatible as possible. (p575-583).
Preventable Problems
* All SGML tags need to be closed (with the full closing tag). The
following is an example of XML compliant tags.
<title>A Title</title>
The following is valid SGML coding, but not XML compliant.
<title>A Title</>
Finally, even though it is acceptable to define tags that do not
need to be closed in SGML this is NEVER acceptable in XML
* Attribute default values may not always be respected in XML.
Therefore, it may be worthwhile to include this default attribute
values (or you could fix these problems as they arrise with a
style sheet for XML). I recommend the style sheet solution,
because it will be a lot of work to look up and include all the
default attributes of SGML.
* All attribute items should be quoted. For example the following is
XML compliant:
<section id="intro">
The following is valid SGML code, but not XML compliant.
<section id=intro>
* XML, unlike SGML is case sensitive, therefore keep your tag case
consistent (I suggest all lowercase). Below is an example of tags
that are XML compliant:
<title>A Title</title>
Below is an example that is SGML compliant, but not XML compliant:
<title>A Title</Title>
* No #CONFREF attributes (what ever they are). Do you want to
explain this one Ramin?
* Only explicit CDATA-marked sections allowed are allowed. This
means that you may NOT use variables you must use the CDATA
structure exactly as it is shown here:
<![CDATA[
<!DOCTYPE artcicle BUBLIC "-//Norman Walsh/DTD DocBk XML V1.4//EN"
"http://docbook.org/docbook/xml/1.4/db3xml.dtd" [
]>
]]>
Workarounds to problems that can't be prevented
* The system identifiers are different for SGML and XML. A SGML
system identifier looks like the following:
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ ]>
An XML system identifier looks like the following:
<!DOCTYPE artcicle BUBLIC "-//Norman Walsh/DTD DocBk XML V1.4//EN"
"http://docbook.org/docbook/xml/1.4/db3xml.dtd" [ ]>
* Minimize the use of SDATA, because XML uses unicode and does not
use SDATAs predefined character maps. To solve this one will need
to map all SDATA to unicode characaters by hand to use DocBk XML.
An example of the proper use of SGML SDATA is below.
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ ]>
<article>
<section>
<title>Tom & Jerry</title>
<para>They are funny.</para>
</section>
</article>
To do the same thing with XML one needs to map this to unicode.
<?xml vesion='1.0'?>
<!DOCTYPE artcicle BUBLIC "-//Norman Walsh/DTD DocBk XML V1.4//EN"
"http://docbook.org/docbook/xml/1.4/db3xml.dtd" [
<!ENTITY amp "&">
]>
<article>
<section>
<title>Tom & Jerry</title>
<para>They are funny.</para>
</section>
</article>
Eventually, there will (hopefully) be a better way to map ISO
SDATA to unicode and make this problem go away.
_________________________________________________________________
Appendix A. Additional Useful Tags & Tricks
This section is a tutorial on useful tags. This section is meant to be
useful to the author, but these tags do NOT relate to the SEUL/edu
DocBook standard. In otherwords, these tags will not help us build a
more searchable library of articles, they will simply make are
articles easier to read and understand.
_________________________________________________________________
CDATA
The CDATA structure looks like <![CDATA[ and ]]>. It is often helpful
when listing programs or screen text -- it allows one to use SGML and
HTML symbols freely without worry. In particular, it allows one to use
the symbols used in SGML and HTML such as the <, >, & and ----. If one
doesn't use the CDATA structure, SGML tags will be resolved even
within the programlisting, therefore, it is essential that examples of
SGML and HTML code use the CDATA structure. Below is an example that
shows the HTML page used to run the Java applet, in the above example.
<programlisting>
<![CDATA[
<html>
<head>
<title>Howdy Applet</title>
</head>
<body>
<h1>This is the Webpage for Howdy Applet</h1>
<applet code="Howdy.class" width="300" height="200">
</applet>
</body>
</html>
]]>
</programlisting>
_________________________________________________________________
Defining User Entities
It is often helpful to define your own Entity while writing SGML
documents. It can save a lot of typing if you find you are repeated
typing something relatively long. For example assume you are typing a
document about using Nedit to type SGML documents and you fear you
will become tired of typing: <application>Nedit</application> and
<acronym>SGML</acronym>. Below is an example of how to create your own
ENTITYs.
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!ENTITY nedit "<application>Nedit</application>">
<!ENTITY sgml "<acronym>SGML</acronym>">
]>
<article>
<section id="programs">
<title>Programs Used</title>
<para>
&nedit; was the application used
to create this &sgml; document.
</para>
</section>
</article>
_________________________________________________________________
SDATA Entities
SDATA Entities are predefined ENTITYs for many symbols (including
nearly every symbol for every language -- based on an alphabet). SDATA
is an ISO standard. There are published charts which are very helpful
(see the appendix of the DocBook Book). Below I have listed the SDATA
entities I used to create this document:
< is <
> is >
& is &
- is – (a short dash)
-- is — (a long dash)
For example, assume that you need to use a callout (see the section
called Appended Annotations) on an HTML page. You may NOT use the
CDATA (see the section called CDATA) structure with a callout.
Therefore, the HTML/SGML tag symbols will need to be converted to
their respective SDATA entities. The result of doing this would would
look like the following:
<programlisting>
<html>
<head>
<title>Howdy Applet</title>
</head>
<body>
<h1>This is the Webpage for Howdy Applet</h1>
<applet code="Howdy.class" width="300" height="200"> <co id="na
me">
</applet>
</body>
</html>
</programlisting>
<calloutlist>
<callout arearefs="name">
<para>
The <sgmltag>code</sgmltag> attribute is always refers
to the class file generated by the Java compiler. This file
always has the form ClassName.class.
</para>
</callout>
</calloutlist>
This will then look like the following:
<programlisting>
<html>
<head>
<title>Howdy Applet</title>
</head>
<body>
<h1>This is the Webpage for Howdy Applet</h1>
<applet code="Howdy.class" width="300" height="200"> (1)
</applet>
</body>
</html>
(1)
The code attribute is always refers to the class file generated
by the Java compiler. This file always has the form
ClassName.class.
Of course this is hard to maintain,because it is hard to read and
because with every little change the entire web page needs to
converted into SDATA entities. Therefore, I recommend using SDATA
entities sparingly and whenever possible, would use using the SGML and
HTML comment tag (see the section called Commenting SGML) instead of a
callout tag (see the section called Appended Annotations) or other
annotation structures such as lineannotation (see the section called
Annotating a Line) that do not allow CDATA structures (see the section
called CDATA) when working with code and screen listings.
_________________________________________________________________
Appended Annotations
Generally, the programs should be commented within the code, however,
occassionally, one might need to provide a longer explanation to help
the reader understand the code -- especially, when the explanation
would be an innapropriate program comment. Therefore, one could use
the callout tags. Below is an example.
<programlisting>
import java.applet.*;
import java.awt.*;
public Howdy extends Applet { <co id="name">
public void init() {
Label myLabel = new label("Howdy");
add(myLabel);
}
}
</programlisting>
<calloutlist>
<callout arearefs="name">
<para>
Java is very picky, if the class is called Howdy, then
the file MUST be called <filename>Howdy.java</filename>.
It is also important to note that the capitalization must
also be identical. (It is a convention that classes start
with Capitals).
</para>
</callout>
</calloutlist>
Here is what this would actually look like:
import java.applet.*;
import java.awt.*;
public Howdy extends Applet { (1)
public void init() {
Label myLabel = new label("Howdy");
add(myLabel);
}
}
(1)
Java is very picky, if the class is called Howdy, then the file
MUST be called Howdy.java. It is also important to note that
the capitalization must also be identical. (It is a convention
that classes start with Capitals).
It is important to note that to use the callout tags does not permit
one to use the CDATA structure. Therefore to use a callout on an HTML
page example, one would need to go through the effort of converting
all the HTML tag symbols to their proper SDATA entities (see the
section called SDATA Entities).
_________________________________________________________________
Commenting SGML
Sometimes it is helpful to include comments in SGML & HTML source
code. This is done by using the following symbols sequence: <!-- and
-->, below is an example.
<!--
Comment goes here and can
be as many lines as needed
-->
Using the comment removes the need (in most cases) for callouts (see
the section called Appended Annotations) on HTML and SGML code. Below
is an example callout in an HTML file.
<programlisting>
<![CDATA[
<html>
<head>
<title>Howdy Applet</title>
</head>
<body>
<h1>This is the Webpage for Howdy Applet</h1>
<!--
The code attribute is always refers to the class
file generated by the Java compiler. This file
always has the form ClassName.class.
-->
<applet code="Howdy.class" width="300" height="200">
</applet>
</body>
</html>
]]>
</programlisting>
I find this form much more readable for the maintainer. It is also
easier to maintain, because all I need to do is cut and paste -- no
need to convert all the HTML tags into SDATA entities.
_________________________________________________________________
Displaying Examples
Most examples are best shown with the informalexample or the example
tag. This tag ensures that the example fits well into the flow of the
text.
_________________________________________________________________
Informal Examples
Informal examples use the informalexample tag. These contain no
titles. Below is an example:
<informalexample>
<!-- Note: examples do not allow text, one MUST
use the para tag to include text! -->
<para>
My favorite program is listed below.
<programlisting>
import java.applet.*;
import java.awt.*;
public Howdy extends Applet {
public void init() {
Label myLabel = new label("Howdy");
add(myLabel);
}
}
</programlisting>
</para>
</informalexample>
Which looks like the following:
My favorite program is listed below.
import java.applet.*;
import java.awt.*;
public Howdy extends Applet {
public void init() {
Label myLabel = new label("Howdy");
add(myLabel);
}
}
_________________________________________________________________
Formal Examples
Formal examples use the example tag. These contain a title and are
easily cross referenced (see the section called Cross References).
<example>
<title>My Favorite Program</title>
<programlisting>
import java.applet.*;
import java.awt.*;
public Howdy extends Applet {
public void init() {
Label myLabel = new label("Howdy");
add(myLabel);
}
}
</programlisting>
</example>
Which looks like the following:
Example Appendix A-1. My Favorite Program
import java.applet.*;
import java.awt.*;
public Howdy extends Applet {
public void init() {
Label myLabel = new label("Howdy");
add(myLabel);
}
}
_________________________________________________________________
Graphic Tag
The graphic can be used to include external files. This includes
graphics, programs listings and external SGML files.
_________________________________________________________________
Include A Graphic
To include a graphic image you will need to use the graphic tag. Use
it like the following:
<graphic fileref="path/filename"></graphic>
Please Note: DO NOT include the file extension! Instead be sure you
include both a GIF image and a postscript grahpic image, with the
following respective extensions -- gif and eps. Be sure these both
have the path and filename given in the fileref attribute. In this
way, DocBook will include the proper image depending on the type of
document being published.
_________________________________________________________________
List an External Program
Sometimes you may want to list an external file in your SGML document.
To do this you use the graphic tag and you must declare the format
attribute to be linespecific. An example follows:
<graphic format="linespecific" fileref="path/filename"></graphic>
This is especially helpful when you want to list a file which is
maintained seperately from your document.
_________________________________________________________________
Including an External SGML File
Sometimes you may want to include an external SGML file in your
document and have the SGML tags resolved. To do this you use the
graphic tag and you must declare the format attribute as SGML. An
example follows:
<graphic format="SGML" fileref="path/filename"></graphic>
This is especially helpful when your document is becomming long and
complicated. I doubt you will need to do this writing SEUL/edu
articles.
_________________________________________________________________
Annotating a Line
To add a comment on a given line (usually on a text screen listing)
one can use the lineannotation tag. An example is shown below.
<para>
When one turns on the machine, one is greeting with the following
prompt:
<screen>
<prompt>Login:</prompt> <lineannotation>Also Username</lineannotation>
</screen>
</para>
Here is what this actually looks like. (In an unformatted text
document this comment will not be seen in a different font and may be
confusing to the reader.)
Login: Sometimes Username
_________________________________________________________________
Lists
Lists are very common (at least I like them). So I have included
several examples of creating lists. I have not included the different
attributes. To get fancy, refer the the _DocBook_ book.
_________________________________________________________________
Bullited Lists
Bullited lists use the itemizedlist tag. Below is an example:
There are several types of lists they are:
<itemizedlist>
<listitem>
<para>
Bullited — which uses the <sgmltag>itemizedlist</sgmltag> tag
.
</para>
</listitem>
<listitem>
<para>
Numbered — which uses the <sgmltag>orderedlist</sgmltag> tag.
</para>
</listitem>
<listitem>
<para>
Simple — which uses the <sgmltag>simplelist</sgmltag> tag.
</para>
</listitem>
</itemizedlist>
Which will look like the following:
There are several types of lists they are:
* Bullited -- which uses the itemizedlist tag.
* Numbered -- which uses the orderedlist tag.
* Simple -- which uses the simplelist tag.
_________________________________________________________________
Numbered Lists
Numbered lists use the orderedlist tag. Below is an example:
There are several types of lists they are:
<orderedlist>
<listitem>
<para>
Bullited — which uses the <sgmltag>itemizedlist</sgmltag> tag
.
</para>
</listitem>
<listitem>
<para>
Numbered — which uses the <sgmltag>orderedlist</sgmltag> tag.
</para>
</listitem>
<listitem>
<para>
Simple — which uses the <sgmltag>simplelist</sgmltag> tag.
</para>
</listitem>
</orderedlist>
This is what the above example looks like:
There are several types of lists they are:
1. Bullited -- which uses the itemizedlist tag.
2. Numbered -- which uses the orderedlist tag.
3. Simple -- which uses the simplelist tag.
_________________________________________________________________
Simple Lists
Simple lists use the simplelist tag. Below is an example:
There are several types of lists they are:
<simplelist type="vert" columns="1">
<member>
Bullited — which uses the <sgmltag>itemizedlist</sgmltag> tag.
</member>
<member>
Numbered — which uses the <sgmltag>orderedlist</sgmltag> tag.
</member>
<member>
Simple — which uses the <sgmltag>simplelist</sgmltag> tag.
</member>
</simplelist>
Which will look like the following:
There are several types of lists they are:
Bullited -- which uses the itemizedlist tag.
Numbered -- which uses the orderedlist tag.
Simple -- which uses the simplelist tag.
_________________________________________________________________
Setoff Text
There are several types of setoff text which can be used to emphasize
something, for example: a helpful tip, a warning, or some important
note, or just something noteworthy. There are different wrapper tags
for each of these situations, but they are all structurally similar.
_________________________________________________________________
A Caution
If the proceedure you are going to explain could have negative
consequences you could use the caution tag (you could also use a
warning -- see the section called A Warning). Here is an example:
<caution>
<title>Be Careful</title>
<para>
Although, this is a very effective way to make popcorn,
it is a bit dangerous. I nearly started a house fire
doing this. It is very important to pay complete
attention to what you are doing.
</para>
</caution>
This will look like the following:
Be Careful
Although, this is a very effective way to make popcorn, it is a bit
dangerous. I nearly started a house fire doing this. It is very
important to pay complete attention to what you are doing.
_________________________________________________________________
Important Comments
If you have important advice that should NOT be overlooked you could
use the important tag. Here is an example:
<important>
<title>Remember</title>
<para>
It is important to type shutdown your operating system
before turning off the power to your computer. If you
forget and just turn off the powet you may corrupt your
file system and loose data.
</para>
</important>
This will look like the following:
Remember: It is important to type shutdown your operating system
before turning off the power to your computer. If you forget and
just turn off the powet you may corrupt your file system and loose
data.
_________________________________________________________________
Noteworthy Comments
If you have a special note you would like to communicate, the note tag
can be used. Here is an example:
<note>
<title>Please Note</title>
<para>
Not everybody likes to wash behind their ears.
Although, my really does try.
</para>
</note>
This will look like the following:
Please Note: Not everybody likes to wash behind their ears.
Although, my cat really does try.
_________________________________________________________________
A Helpful Tip
If you have a helpful tip you would like your reader to know about you
could use the tip tag. Here is an example:
<tip>
<title>Helpful Tip</title>
<para>
I have found that the popcorn made with peanut oil has the
best flavor. You may want to try this.
</para>
</tip>
This will look like the following:
Helpful Tip: I have found that the popcorn made with peanut oil has
the best flavor. You may want to try this.
_________________________________________________________________
A Warning
If you have something you would like to warn the reader about you
could use the warning tag (you might also choose to use the caution --
see the section called A Caution). Here is an example:
<warning>
<title>Warning</title>
<para>
Reformatting your harddrive, will erase all of the data on
your hard drive. You will loose all your data. Consider
doing a backup before proceeding.
</para>
</warning>
This will look like the following:
Warning
Reformatting your harddrive, will erase all of the data on your hard
drive. You will loose all your data. Consider doing a backup before
proceeding.
_________________________________________________________________
Tables
Here is an example of how to make a simple table:
<informaltable frame=all>
<thead>
<row>
<entry>Header1</entry>
<entry>Header2</entry>
<entry>Header3</entry>
</row>
</thead>
<tbody>
<row>
<entry>row1-col1</entry>
<entry>row1-col3</entry>
<entry>row1-col4</entry>
</row>
<row>
<entry>row2-col1</entry>
<entry>row2-col2</entry>
<entry>row2-col3</entry>
</row>
</tbody>
</tgroup>
</informaltable>
This will look like:
Header1 Header2 Header3
row1-col1 row1-col2 row1-col3
row2-col1 row2-col2 row2-col3
An example of a more complicated table is:
<informaltable frame=all>
<tgroup cols=3 align=left colsep=1 rowsep=1>
<colspec colname=col1>
<colspec colname=col2>
<colspec colname=col3>
<!-- You need to name columns that will have variations in
their width. -->
<spanspec spanname=hspan namest=col1 nameend=col2 align=center>
<spanspec spanname=bspan namest=col2 nameend=col3 align=center>
<!-- You need to define and name which columns will span more
than one column -->
<thead>
<row>
<entry>Header1</entry>
<entry>Header2</entry>
<entry>Header3</entry>
</row>
</thead>
<tbody>
<row>
<entry spanname=hspan>row1-col1,2</entry>
<entry>row1-col3</entry>
</row>
<row>
<entry>row2-col1</entry>
<entry spanname=bspan morerows=1 valign=bottom><para>
<!-- If you are going to put an entry on more than 1 line,
then the content tag MUST be on the same line as the entry
tags (this includes the closing tag), otherwise you will
parsing errors! -->
row2,3-col2,3
</para></entry>
</row>
<row>
<entry>row3-col1</entry>
</row>
</tbody>
</tgroup>
</informaltable>
Here is what this looks like (unfortunately, these don't look very
nice in an unformatted text file).
Header1 Header2 Header3
row1-col1,2 row1-col3
row2-col1
row2,3-col2,3
row3-col1
_________________________________________________________________
Cross References
To cross reference a reader to another part of the article one uses
the xref tag. Below is an example of it's use.
Use the <sgmltag>xref</sgmltag> tag to reference
part of an article (see <xref linkend="xref">).
Which will look like the following:
Use the xref tag to reference part of an article (see the section
called Cross References).
_________________________________________________________________
Appendix B. SEUL/edu DocBook Template
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ <!ENTITY
seuledu "<acronym>SEUL/edu</acronym>"> ]> <article id="index">
<artheader> <title>Your Title</title> <subtitle>&seuledu; Doc
Category</subtitle> <authorgroup> <author>
<firstname>firstname</firstname><surname>lastname</surname> </author>
<author> <firstname>firstname</firstname><surname>lastname</surname>
</author> </authorgroup> <editor>
<firstname>firstname</firstname><surname>lastname</surname> </editor>
<othercredit> <firstname>firstname</firstname>
<surname>lastname</surname> <contrib>What they did</contrib>
</othercredit>
<publisher><publishername>SEUL/edu</publishername></publisher>
<abstract> <para> A brief one paragraph summary of the article.
</para> </abstract> <revhistory> <revision> <revnumber>1.1</revnumber>
<date>New Date</date> <revremark>Fixed spelling and grammar
errors</revremark> </revision> <revision> <revnumber>1.0</revnumber>
<date>The Date</date> <revremark> First public release. </revremark>
</revision> </revhistory> <copyright> <year>2000</year> <holder>the
authors</holder> </copyright> <legalnotice> <para> This Document uses
the OpenContent License (OPL). </para> <para> Version 1.0, July 14,
1998. </para> <para> This document outlines the principles underlying
the OpenContent (OC) movement and may be redistributedprovided it
remains unaltered. For legal purposes, this document is the license
under which OpenContent is madeavailable for use. </para> <para> The
original version of this document may be found at <ulink
url="http://opencontent.org/opl.shtml">
http://opencontent.org/opl.shtml</ulink> </para> <para> LICENSE
</para> <para> Terms and Conditions for Copying, Distributing, and
Modifying </para> <para> Items other than copying, distributing, and
modifying the Content with which this license was distributed (such
asusing, etc.) are outside the scope of this license. <orderedlist>
<listitem> <para> You may copy and distribute exact replicas of the
OpenContent (OC) as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the OC a copy of this License along
with the OC. You may at your option charge a fee for themedia and/or
handling involved in creating a unique copy of the OC for use offline,
you may at your option offer instructional support for the OC in
exchange for a fee, or you may at your option offer warranty in
exchange for a fee. You may not charge a fee for the OC itself. You
may not charge a fee for the sole service of providing access to
and/or use of the OC via a network (e.g. the Internet), whether it be
via the world wide web, FTP, or any other method. </para> </listitem>
<listitem> <para> You may modify your copy or copies of the
OpenContent or any portion of it, thus forming works based on the
Content, and distribute such modifications or work under the terms of
Section 1 above, provided that you also meet all of these conditions:
<itemizedlist> <listitem> <para> You must cause the modified content
to carry prominent notices stating that you changed it, the exact
nature and content of the changes, and the date of any change. </para>
</listitem> <listitem> <para> b) You must cause any work that you
distribute or publish, that in whole or in part contains or is derived
from the OC or any part thereof, to be licensed as a whole at no
charge to all third parties under the terms of this License, unless
otherwise permitted under applicable Fair Use law. </para> </listitem>
</itemizedlist> </para> <para> These requirements apply to the
modified work as a whole. If identifiable sections of that work are
not derived from the OC, and can be reasonably considered independent
and separate works in themselves, then this License, and its terms, do
not apply to those sections when you distribute them as separate
works. But when you distribute the same sections as part of a whole
which is a work based on the OC, the distribution of the whole must be
on the terms of this License, whose permissions for other licensees
extend to the entire whole, and thus to each and every part regardless
of who wrote it. Exceptions are made to this requirement to release
modified works free of charge under this license only in compliance
with Fair Use law where applicable. </para> </listitem> <listitem>
<para> You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to copy,
distribute or modify the OC. These actions are prohibited by law if
you do not accept this License. Therefore, by distributing or
translating the OC, or by deriving works herefrom, you indicate your
acceptance of this License to do so, and all its terms and conditions
for copying, distributing or translating the OC. </para> </listitem>
</orderedlist> </para> <para> NO WARRANTY <orderedlist> <listitem>
<para> BECAUSE THE OPENCONTENT (OC) IS LICENSED FREE OF CHARGE, THERE
IS NO WARRANTY FOR THE OC, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE OC "AS IS" WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK OF USE OF THE OC IS WITH YOU. SHOULD THE OC
PROVE FAULTY, INACCURATE, OR OTHERWISE UNACCEPTABLE YOU ASSUME THE
COST OF ALL NECESSARY REPAIR OR CORRECTION. </para> </listitem>
<listitem> <para> IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR
AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO
MAY MIRROR AND/OR REDISTRIBUTE THE OC AS PERMITTED ABOVE, BE LIABLE TO
YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
OC, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES. </para> </listitem> </orderedlist>
</para> </legalnotice> </artheader> <section id="intro">
<title>Introduction</title> <para> The introductory comments. </para>
<section id="doc-purpose"> <title>Document Use & Purpose</title>
<para> Describe purpose and how to best use (Optional Section).
</para> </section> <section id="doc-info"> <title>Document
Information</title> <para> This document can be found at <ulink
url="http://www.seul.org/edu/docs/">
http://www.seul.org/edu/docs/</ulink> </para> <para> Please send
corrections and suggestions to YOUR NAME at: <address><email>YOUR
EMAIL ADDRESS</email></address> </para> </section> </section> <section
id="first-subject"> <title>First Subject</title> <para> The text.
</para> <section id="subsection-first-subject">
<title>subsection</title> <para> More text. </para> </section>
</section> <section id="second-subject"> <title>Second Subject</title>
<para> The text. </para> <section id="subsection-second-subject">
<title>subsection</title> <para> More text. </para> </section>
</section> <appendix id="optional-appendix"> <title>Appendix
Title</title> <para> This is an optional appendix. </para> </appendix>
<appendix id="resources"> <title>Resources</title> <section
id="non-printed"> <title>Non-Printed Resources</title> <variablelist>
<varlistentry> <term>Title</term> <listitem> <para> Description and
location. </para> </listitem> </varlistentry> <varlistentry>
<term>Title</term> <listitem> <para> Description and location. </para>
</listitem> </varlistentry> </variablelist> </section> <section
id="bibliography"> <title></title> <para></para> <bibliography>
<bibliodiv><title>Books</title> <biblioentry> <title>Title</title>
<subtitle>The Subtitle</subtitle> <authorgroup> <author>
<firstname>firstname</firstname> <surname>lastname</surname> </author>
<author> <firstname>fistname</firstname> <surname>lastname</surname>
</author> </authorgroup> <isbn>the isbn number</isbn> <publisher>
<publishername> publisher </publishername> <address> <street>Street
address</street> <city>city</city> <state>state, canton,
province</state> <postcode>postalcode</postcode> </address>
</publisher> <pubdate>publication date</pubdate> <bibliomisc>
description (Optional) </bibliomisc> </biblioentry> </bibliodiv>
<bibliodiv><title>Periodicals</title> <biblioentry> <biblioset
relation=journal> <title>Journal Title</title> <publisher>
<publishername> Publisher Name </publishername> </publisher>
<issn>####-####</issn> <editor> <firstname>firstname</firstname>
<surname>lastname</surname> </editor> </biblioset> <biblioset
relation=article> <title>Article Title</title> <author>
<firstname>firstname</firstname> <surname>lastname</surname> </author>
<copyright> <year>Month Year</year> <holder> Copyright Owner </holder>
</copyright> <pagenums>startpage-endpage</pagenums> </biblioset>
</biblioentry> </bibliodiv> </bibliography> </section> </appendix>
</article>
_________________________________________________________________
Appendix C. Resources
Non-Printed Resources
DocBook: The Definitive Guide
This is the website for the book _DocBook: The Definitive
Guide_. This site has the most up to date version of the book
in SGML, HTML and maybe other formats too. You can find this
information at: http://www.docbook.org/.
Open Source Writers Group
This is a group dedicated to supporting writers in the Open
Source community. Thier website is http://www.oswg.org/.
DocBook DTD
The latest DocBook DTD can be found at
http://www.oasis-open.org/docbook/.
DkBook XML DTD
The latest DkBook XML DTD can be found at Norman Walsh's site
at http://nwalsh.com/docbook/xml/.
Linux SGML Software: A Writer's Guide
This is an introduction to Linux software useful to writing
SGML documents. It covers how to configure and use the
software. It can be found at http://www.seul.org/edu/docs/.
_________________________________________________________________
Bibliography
DocBook: The Definitive Guide, Norman Walsh and Leonard Muellner,
1-56592-580-7, O'Reilly & Associates, Inc., Sebastopol, October 1999.