[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
docutg: My additions to the Documentation guide...
Hi all!
Here are some of my additions to the documentation guide. I hope that
Bill will have the time to patch them into his version and send
something with both our changes in it.
I suggest we remoce the sections on Jade and DocBook in the
applications and I can describe them as components of SGMLtools in the
SGMLtools section.
Attached is also the dsl file that I use to process my docs, we could
maybe use it as the base for a SEUL/Edu stylesheet, comments are
welcome (as well as questions on what the hell does the stylesheet do
;).
The URL of my .emacs configuration that I refer to is not up yet, it
will be in a day or two (gotta get some work done first).
ramin
--
Ramin Miraftabi Student of Computer Science
email: ramin@cs.joensuu.fi University of Joensuu
WWW: http://dawn.joensuu.fi/~ramin/ Joensuu, Finland
- GPG public key ID 49C9CFF7 -- (c) Copyright 1999 -
Homepages *finally* updated!
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!-- Define some internal entities as shortcuts (ramin's lazy!) -->
<!ENTITY emacs "<application>Emacs</application>">
<!ENTITY psgml "<application>psgml</application>">
<!ENTITY Psgml "<application>Psgml</application>">
<!ENTITY SGMLtools "<application>SGMLtools</application>">
]>
<article id="index">
<artheader>
<author>
<firstname>Bill</firstname><surname>Tihen</surname>
</author>
<publisher><publishername>SEUL/EDU</publishername></publisher>
<title>Writing SEUL/EDU Documentation</title>
<subtitle>Getting Started</subtitle>
<othercredit>
<firstname>Ramin</firstname> <surname>Miraftabi</surname>
<contrib>Review and corrections and adding some content</contrib>
</othercredit>
<abstract>
<para>
This article describes the software needed to write DocBook documents.
It states where to find the software and describes how to install or
configure it so that it will produce SGML documents. It
describes the fundamentals of how to use the software. And finally
it lists expectations of SEUL/EDU documents so that the documents
will be able to provide meaningful search results for our future
document archives.
</para>
</abstract>
<!-- I'd leave this out for now, or then clear the list once we get to
rel 1.0 -->
<revhistory>
<revision>
<revnumber>0.3</revnumber>
<date>22 November 1999</date>
<revremark>
Lots of new content added. Updated chapter section to section section.
Added sections on RTF & PDF (no content yet). Removed one of the EMACS
sections & Syntax checking & Publishing Documents (they are covered in
other areas. Added a command section to examples -- changed quote
section to have long and short quotes.
</revremark>
</revision>
<revision>
<revnumber>0.2</revnumber>
<date>29 October 1999</date>
<revremark>Second draft for review - sections started.</revremark>
</revision>
<revision>
<revnumber>0.1</revnumber>
<date>20 October 1999</date>
<revremark>First draft for review - mostly a skeleton.</revremark>
</revision>
</revhistory>
</artheader>
<section id="intro">
<title>Introduction</title>
<section id="doc-type">
<title>Documentation Guide</title>
<para>
This document is a <emphasis>Documentation Guide</emphasis> —
which means it is designed to help people write SEUL/EDU
Documentation or defines the SEUL/EDU documents standards.
</para>
</section>
<section id="doc-purpose">
<title>Document Purpose</title>
<para>
This document is designed to help people get started writing
SEUL/EDU documents as well as layout the basic SGML expectations for SEUL/EDU
documentation. In this way we will be able to search and catalog the
information contained in these documents in an organized and meaningful way.
</para>
</section>
<section id="doc-audience">
<title>Intended Audience</title>
<para>
This document is intended to be read by people interested in writing
documentation for SEUL/EDU.
</para>
</section>
<section id="background-info">
<title>Background Information</title>
<para>
DocBook and XML are the documentation formats of the
future. LinuxDoc is being abandoned and doesn't support screen shots --
which we will need for our software tutorials.
</para>
</section>
</section>
<section id="software">
<title>Software</title>
<para>
Each tool is described to help you decide what tools will
be the most helpful for you.
</para>
<section id="lyx">
<title><application>LyX</application></title>
<section id="lyx-description">
<title><application>LyX</application> Description</title>
<para>
<application>LyX</application> 1.04 and beyond are SGML capable if the proper
&SGMLtools; is installed.
<application>LyX</application>
will work with several other types of documents as well.
</para>
<para>
<application>LyX</application> allows the user to view the document
structure as one writes the document in a WYSIWYG format as
shown in the below image.
<graphic fileref="LyX-screenshot"></graphic>
This simplifies the
creation of structured documents. It also creates tables,
lists, grahpics and equations. However,
I don't know how well it exports theses advanced features
to SGML documents.
</para>
<para>
Some drawbacks of using <application>LyX</application>.
<itemizedlist>
<listitem>
<para>
<application>LyX</application> does support all SGML
tags. It is unaware of the tags (or at least I don't
know how to include the following tags in a
<application>LyX</application> document)
such as application, file, etc. Which will ultimately
help us create searchable content in our documents.
So if you use this tool, please add the
additional tags we expect using a text editor.
(Unfortunately, once you do this you will not be able
to use LyX to edit it again -- as it doesn't import
SGML files <emphasis>yet anyway</emphasis>).
</para>
</listitem>
<listitem>
<para>
<application>LyX</application> does not (yet anyway)
import DocBook (SGML) files. Which means if you add some
tags by hand — as suggested above — you will
no longer be able to edit the document with LyX.
</para>
</listitem>
<listitem>
<para>
<application>LyX</application> still uses
<sgmltag>sect1</sgmltag>, <sgmltag>sect2</sgmltag>,
<sgmltag>sect3</sgmltag>, etc tags. This means if you
edit the file by hand you must be careful to renumber
the section tags properly. I find it easier to just
use the <sgmltag>section</sgmltag> tag.
</para>
</listitem>
</itemizedlist>
In all fairness I don't use LyX regullarly and it is quite
possible there are solutions for these difficulties. If you
know the solutions please share the solution with use so that
we can update this document.
</para>
<para>
Therefore, <application>LyX</application> is only useful in creating simple DocBook
articles. Once they are exported and have the additional tags for files, keyboard strokes,
etc, <application>LyX</application> will not be able to maintain the document.
</para>
</section> <!-- Lyx Description -->
<section id="obtaining-LyX">
<title>Obtaining <application>LyX</application></title>
<para>
You can download <application>LyX</application> from
<ulink url="http://www.lyx.org/"></ulink>
RPMS are avaliable at:
<ulink url="ftp://ftp.sylvan.com/pub/lyx/"></ulink>
To use DocBook you will also need the following version of
sgmltools — I am sure at some point other versions will be
okay, but for now please use this version:
<ulink
url="ftp://ftp.sylvan.com/pub/lyx/sgml/2.x/sgmltools/sgmltools-CVS19990807-2.i386.rpm"></ulink>
</para>
</section> <!-- Obtaining LyX -->
<section id="configure-lyx">
<title>Configure <application>LyX</application> to use DocBook</title>
<para>
Install both <application>LyX</application> and the appropriate version of
&SGMLtools;.
</para>
<para>
Now you must reconfigure <application>LyX</application> by
going to the menu bar and selecting
<menuchoice>
<shortcut>
<keycombo><keysym>ALT</keysym><keysym>o</keysym></keycombo>
<keysym> SPACE</keysym><keysym> r</keysym>
</shortcut>
<guimenu>Options</guimenu>
<guimenuitem>Reconfigure</guimenuitem>
</menuchoice>.
You should then get the following dialog box telling you to
restart <application>LyX</application>. It is important to
do this right away!
</para>
</section> <!-- Configuring LyX -->
<section id="using-lyx">
<title>Using <application>LyX</application></title>
<para>
Using <application>LyX</application> is quite easy, however there are
a few steps you must
follow when creating a new DocBook article.
<itemizedlist>
<listitem>
<para>
Open a new document and do the following:
<menuchoice>
<shortcut><keycombo><keysym>ALT-n</keysym></keycombo></shortcut>
<guimenu>File</guimenu>
<guimenuitem>New</guimenuitem>
</menuchoice>
Now check to see if the SGMLtools layout was found.
<menuchoice>
<shortcut>
<keycombo><keysym>ALT-f</keysym></keycombo>
<keysym> d</keysym>
</shortcut>
<guimenu>Layout</guimenu>
<guimenuitem>Document...</guimenuitem>
</menuchoice>
Now the Document Layout dialog box should open up.
<menuchoice>
<guimenu>Class</guimenu>
</menuchoice>
Towards the bottom of the list you should see: SGML
(DocBook article). Select this item. Then click on either
<guibutton>Apply</guibutton> or <guibutton>OK</guibutton>.
Now a confirmation dialog box should appear.
Click on <guibutton>Yes</guibutton>.
</para>
</listitem>
<listitem>
<para>
As you type the document select the structures you want using
the menu-bar and the
menu-items. It should be clear to most people how to do this
once the program is
running.
</para>
</listitem>
<listitem>
<para>
Now the SGML document needs to be exported by going to
the menu bar and choosing:
<menuchoice>
<guimenu>File</guimenu>
<guisubmenu>Export</guisubmenu>
<guimenuitem>DocBook</guimenuitem>
</menuchoice>
</para>
</listitem>
</itemizedlist>
</para>
</section> <!-- Using LyX -->
</section> <!-- LyX -->
<section id="emacs">
<sectioninfo>
<author><firstname>Ramin</firstname> <surname>Miraftabi</surname>
</author>
</sectioninfo>
<title>&emacs;</title>
<para>
&emacs; is a very powerful program that can
do almost everything. It is an editor, SGML verifier, a mail reader
(if you must), a news reader and an IDE environment. The power of
Emacs comes from the way it can be extended to support almost
anything, as long as someone bothers to create a mode or functions
for it. To use Emacs in a fast and efficient way, one needs to
become familiar with many keyboard shortcuts and some Emacs Lisp
to configure Emacs the way you want it. My
<filename>.emacs</filename> can be found at
<ulink url="http://dawn.joensuu.fi/~ramin/config/emacs.html">
http://dawn.joensuu.fi/~ramin/config/emacs.html</ulink>.
Some people love the program and other people find it complex and
clumsy. As you can expect, I'm one who loves and will leave a
WYSIWYG editor at any time to use Emacs.
</para>
<para>
Advantages
<itemizedlist>
<listitem>
<para>
All your SGML tools are in one spot. (With the exception of
running &SGMLtools; from the
command line.)
</para>
</listitem>
<listitem>
<para>
Many people are familiar with it because it is also a powerful
programming environment.
</para>
</listitem>
<listitem>
<para>
The program runs under both text and graphical environments
with the same key-combinations. It also runs on Windows
95/98/NT if needed, again with the same keyboard combinations.
</para>
</listitem>
</itemizedlist>
</para>
<para>
Disadvantages
<itemizedlist>
<listitem>
<para>
Many people find the &emacs; clumsy
and overwhelming — especially in the text only mode.
</para>
</listitem>
<listitem>
<para>
&emacs; is slow to start.
Once started, it should be fast enough. In many cases the
time to start it up can be minimized by learning to use
multiple frames and buffers, but again, the learning curve is
a bit steep.
</para>
</listitem>
</itemizedlist>
</para>
<section id="obtaining-emacs">
<title>
Obtaining &emacs; and &psgml;
</title>
<para>
&emacs; is best to install from your
Linux distribution's packages. I wouldn't try installing it by hand.
On RedHat systems the most interesting place to look to for adding
packages to Emacs is <filename class="directory">/usr/share/emacs
</filename>. I have installed &psgml;
in <filename class="directory">/usr/share/emacs/site-lisp</filename>
but another usual place to install it would be
<filename class="directory">
/usr/share/emacs/20.3/site-lisp</filename>. However, as the
directory names imply, it is better to use the former since it is
not dependent on &emacs;'s version. This means that it can be
used by both &emacs; and
<application>XEmacs</application>. &Psgml; is found at:
<ulink
url="http://http://www.lysator.liu.se/projects/about_psgml.html">
http://www.lysator.liu.se/projects/about_psgml.html</ulink>.
After downloading the latest version (1.2.1 at the time of this
writing) change in to the directory
<filename class="directory">/usr/local/src</filename> (or any
other place you see fit) and run the following commands. The
commands must be issued as root and output from them has been
supressed in some cases (represented by …).
</para>
<screen>
[root@reepycheep src]# tar xvfz ~ramin/tmp/psgml-1.2.1.tar.gz
…
[root@reepycheep src]# cd psgml-1.2.1/
[root@reepycheep psgml-1.2.1]# ./configure --prefix=/usr
loading cache ./config.cache
checking whether make sets ${MAKE}... (cached) yes
checking for a BSD compatible install... (cached) /usr/bin/install -c
checking for emacs... (cached) /usr/bin/emacs
checking where .elc files should go... $(prefix)/share/emacs/site-lisp
checking for makeinfo... (cached) /usr/bin/makeinfo
creating ./config.status
creating Makefile
[root@reepycheep psgml-1.2.1]# make
…
[root@reepycheep psgml-1.2.1]# make install
…
</screen>
<para>
This will compile and install &psgml; in <filename class="directory">
/usr/share/emacs/site-lisp/</filename>.
Read the <filename>README.psgml</filename> (in the psgml
distribution) for more information, if you like.
</para>
</section> <!-- obtaining Emacs -->
<section id="configuring-emacs">
<title>Configuring &emacs; to use
&psgml;</title>
<para>
The bare minimum that is needed to get &emacs; to use
&psgml; is to add the following lines to your
<filename>~/.emacs</filename>.
</para>
<literallayout>
(setq load-path (cons "/usr/share/emacs/site-lisp/" load-path))
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
(setq auto-mode-alist
(append '(
("\\.sgml$" . sgml-mode)
)
auto-mode-alist
)
)
</literallayout>
<para>
In this you should substitute the path to the one in which you
have &psgml; installed. Otherwise what you are doing is telling
&emacs; to automatically start &psgml; and telling it to use
&psgml; when opening a file that ends with
<filename>.sgml</filename> (it will also work with
<filename>.sgml~</filename>). Without any information on the
SGML catalog files &psgml; will not find the DTD. You need
to set this information somehow (see <xref
linkend="configuring-sgmltools"> for a discussion on how to do
this).
</para>
<para>
My own <filename>.emacs</filename> has many more settings that can be
used to make &psgml; (among others) work better. You can find it at
<ulink url="http://dawn.joensuu.fi/~ramin/config/emacs.html">
http://dawn.joensuu.fi/~ramin/config/emacs.html</ulink>.
</para>
</section> <!-- Configuring Emacs -->
<section id="using-emacs">
<title>Using &emacs; and &psgml;</title>
<para>
To begin using &emacs; and &psgml; all you need to do is open a
file with the suffix <filename>.sgml</filename>. &Psgml;
is also loaded when you save a file with the suffix <filename>
.sgml</filename>. To show that the SGML-mode has been loaded,
&emacs; changes its statusbar to
show that you are editing a SGML-document and what the top-level
element of the document is. &Psgml; itself, just like &emacs;,
has multiple settings and keyboard commands that you can use.
Customizing &psgml; as well as using many of its freatures are
outside the scope of this document. It is therefore strongly
recommended that you look at others &emacs; configurations
(such as my own) and read the &psgml; manual (found in the
distribution directory as <filename>psgml.info</filename> or
<filename>psgml.ps</filename>). In the following paragraph I
will describe how I use it. You might need to take a look at my
configuration files to get everything to work in the same way
though.
</para>
<para>
I originally only used &psgml; to nicely colorize my editing
buffer (with customized colorizations thanks to others). Later
I learned to use it to indent everything in a nice way with
elements considered as programming code blocks. This helped a lot
in visualizing the structure of the whole document in even greater
detail. Now, after spending some time reading the &psgml; manual,
I've learned to use some of it's keyboard combinations to speed
up the insertion of elements and attributes. Pressing
<keycombo moreinfo="None">
<keycombo moreinfo="None">
<keycap moreinfo="None">Ctrl</keycap>
<keycap moreinfo="None">c</keycap>
</keycombo>
<keycombo moreinfo="None">
<keycap moreinfo="None">Ctrl</keycap>
<keycap moreinfo="None">e</keycap>
</keycombo>
</keycombo>
will give you a mini-buffer in which you can type in the element
you would like to insert at the given point. The mini-buffer supports
tab completion, so you can press the tab-key to complete the
element's name. It will also place the end-tag either on the
same line (if the element does not require other elements) or
on a new line. With my settings it will also insert all of the
element's required attributes. Pressing
<keycombo moreinfo="None">
<keycombo moreinfo="None">
<keycap moreinfo="None">Ctrl</keycap>
<keycap moreinfo="None">c</keycap>
</keycombo>
<keycap moreinfo="None">+</keycap>
</keycombo>
will let you add attributes and their values to the next element
or current element if the pointer is in a start-tag at the time.
The minibuffers offered for this naturally support tab completion
as well. Note that when you use entities as shortcuts psgml might
encouter some problems. After inserting some new elements these
problems usually disappear.
</para>
</section> <!-- Using Emacs -->
</section> <!-- Emacs -->
<section id="sgmltools">
<sectioninfo>
<author><firstname>Ramin</firstname> <surname>Miraftabi</surname>
</author>
</sectioninfo>
<title>&SGMLtools;</title>
<para>
&SGMLtools; is a collection of tools and utilities to help users
process documents based on the DocBook DTD. It was formerly known as
<application>Linuxdoc-SGML</application>, but the name was changed
quite some time ago to clarify the fact that the tools were not
related only to Linux. Versions 1.0.x of &SGMLtools; used the
Linuxdoc DTD as their document type. Linuxdoc has some serious
limitations (such as not supporting images) that the Linux
Documentation Project and &SGMLtools; developers decided to move
on to DocBook. The development versions of &SGMLtools; (numbered
in the kernel style 1.1.x) already used DocBook. The first stable
release with DocBook was 2.0 in late 1998. During the Spring of
1999 the project was suspended, with the last release being 2.0.2.
The CVS version of &SGMLtools; has however been slightly updated.
</para>
<para>
Presently &SGMLtools; is a wrapper that combines
<application>Jade</application>, <application>Jadetex</application>,
<application>Hyperref</application>, the DocBook DTD, and the
Stylesheets. It simply presents a unified front-end to the whole
process of processing the SGML-file into different formats.
</para>
<section id="obtain-sgmltools">
<title>Obtaining &SGMLtools;</title>
<para>
&SGMLtools; is available from
<ulink url="http://www.sgmltools.org"></ulink>. Installing
&SGMLtools; requires <application>Python</application> and
converting SGML files to tex, dvi, and PostScript requires
<application>tetex</application>. Using version 0.9x of
<application>tetex</application> is recommended since you can
more easily update some essential configurations. The last release
of &SGMLtools; does not include DocBook 3.1 and has some other
problems as well, therefore I suggest you get the latest version
from CVS (instruction on how to do this below). There are also some
RPM packages that have been made of &SGMLtools; , you'll have to
look around for them.
</para>
<para>
To get the latest &SGMLtools; version out of the CVS repository where
it's held, you naturally need to have
<application>CVS</application> installed. The password to the CVS
repository is <quote>cvs</quote>. Again, the output from the
commands has been supressed. After running these commands you will
have a directory called
<filename class="directory">sgmltools</filename> in the present
working directory and all the files needed to compile and run
&SGMLtools; in this directory.
</para>
<screen format="linespecific">
export CVSROOT=:pserver:cvs@cvs.sgmltools.org:/home/cvs
cvs login
cvs -z6 get sgmltools
</screen>
</section> <!-- obtaining SGMLtools -->
<section id="configuring-sgmltools">
<title>Configuring and installing &SGMLtools;</title>
<para>
&SGMLtools; should configure itself if everything in the compile
stage goes as it should. However, at least I have noticed some
problems with the configuration of &SGMLtools; 2.0.2. The main
problems with this version are the fact that it does not support
DocBook 3.1 out of the box and it has problems in creating the
settings for the <property>SGML_CATALOG_FILES</property>
environment variable. &SGMLtools; works just fine without these
anyway, you just might get some strange error messages. The following
paragraphs describe
the compilation and basic configuration of &SGMLtools; source
versions. I will try to point out the differences between 2.0.2 and
the CVS version where possible.
</para>
<important>
<title>RedHat users!</title>
<para>
If you are using anything before RedHat 6.0 you need to install
the <application>tetex</application> version 0.9x packages
from RedHat 6.0. The packages with 6.1 might also work.
If you are using RedHat 6.0 you need to update the
<application>rpm</application> package and then reinstall
the <application>tetex</application> packages. Otherwise some
important files will be missing (bugs in the first
<application>rpm</application>).
</para>
</important>
<para>
In the following by the base directory I will mean the directory
root directory of the &SGMLtools distribution. All relative
paths are relative to this directory. I also recommend that you
you do all of the following steps as root even though I point out
the steps in which you must be root. First run
<command>./configure</command> to create the initial configuration.
</para>
<para>
If you have the CVS version of &SGMLtools;, change to the
directory
<filename class="directory">packages/cvs/sgmltools</filename>
and add open <filename>configure.in</filename> in your favourite
editor. On line 49 add
<programlisting>
test "$prefix" = "NONE" && prefix=/usr/local
</programlisting>
After this run <command>autoconf configure.in >
configure</command>.
</para>
<para>
For both versions the next is required for a succesful compilation.
At some point of time the default French package was removed
from the <application>tetex</application> distribution because of
copyright problems. The lack of this package causes problem in
compiling <application>Jadetex</application>. To fix this you have
to open <filename>packages/cvs/jadetex/jadetex.dtx</filename>
and go to line 117. On this line you will see the text
<programlisting>
\RequirePackage[german,french,english]{babel}[1997/01/23]
</programlisting>
Now you have to change the <parameter>french</parameter> to
<parameter>frenchb</parameter> if you want support for French.
Depending on your <application>tetex</application> distribution
you can add other languages as well (I've removed support for
French completely and added Finnish (<parameter>finnish</parameter>)
instead). To be precise, the support for other languages depends on
<application>Babel</application>. My thanks go to Sebastian Rahtz
(the author of Jadetex) for this fix.
</para>
<para>
After all of these steps you can finally run <command>make &&
make install</command> to compile and install &SGMLtools;.
Remember, that you have to be root to run
<command>make install</command>. This will install the binaries in
<filename class="directory">/usr/local/bin</filename> and the
other data files in
<filename class="directory">/usr/local/share/sgml</filename>. Some
environment information will be installed into
<filename class="directory">/etc/sgml</filename>. You can control
these locations by the configure parameters
<parameter class="option">--prefix</parameter> and
<parameter class="option">--with-etcsgml</parameter>.
</para>
<para>
To fix some problems that occur when processing into PostScript,
dvi, or jadetex you will need to fix the
<application>kpathsea</application> configuration. To do this you
again have to be root. Change into the directory
<filename class="directory">/usr/share/texmf/web2c</filename>.
Save the following text into a file (say
<filename>texmf.cnf.patch</filename>).
</para>
<programlisting>
--- texmf.cnf.orig Sun Dec 5 19:43:17 1999
+++ texmf.cnf Sun Dec 5 19:44:49 1999
@@ -396,6 +396,7 @@
% Extra space for the hash table of control sequences (which allows 10K
% names as distributed).
+hash_extra.jadetex = 15000
hash_extra.context = 15000
hash_extra.cont-en = 15000
hash_extra.cont-nl = 15000
@@ -404,6 +405,7 @@
% Max number of characters in all strings, including all error messages,
% help texts, font names, control sequences. These values apply to TeX and MP.
+pool_size.jadetex = 200000
pool_size.context = 500000
pool_size.cont-en = 500000
pool_size.cont-nl = 500000
@@ -417,6 +419,7 @@
string_vacancies.cont-de = 45000
string_vacancies = 25000
% Maximum number of strings.
+max_strings.jadetex = 50000
max_strings.context = 55000
max_strings.cont-en = 55000
max_strings.cont-nl = 55000
@@ -461,6 +464,7 @@
param_size.cont-nl = 1500
param_size.cont-de = 1500
param_size = 500 % simultaneous macro parameters
+save_size.jadetex = 15000
save_size.context = 5000
save_size.cont-en = 5000
save_size.cont-nl = 5000
</programlisting>
<para>
Now we only have one more final step to do in order to get &SGMLtools;
properly working for all users. As root, open
<filename>/etc/profile</filename> (for
<application>sh</application>-users) and add the following lines to
the end of the file:
<programlisting>
# Source /etc/sgml/sgml.env
if [ -f /etc/sgml/sgml.env ]; then
. /etc/sgml/sgml.env
fi
</programlisting>
With these lines you tell the enviroment to get the settings out
of the file <filename>/etc/sgml/sgml.env</filename> if it exists
and add them to the environment. The settings in
<application>csh</application> can be found in
<filename>/etc/sgml/sgml.cenv</filename>.
</para>
<para>
As an additional step, I recommend that you get the latest version
of the DocBook Stylesheets from Norman Walsh's site
(<ulink url="http://nwalsh.com/docbook/dsssl/"></ulink>).
The latest version at the time of this writing is 1.48 and they are
regularly updated. After you have downloaded the stylesheet
package, as root change to the directory <filename class="directory">
/usr/local/share/sgml/stylesheets</filename> and unzip the
stylesheet distribution (<command>unzip
<parameter>path/to/dbxxx.zip</parameter></command>). Overwrite
all of the files. The benefits in keeping up to date with the
stylesheets include support for additional features and languages, and
fixes for bugs in the stylesheets themselves (and therefore in the
presentation of the document). For example, the latest version
included support for PNG graphics in HTML and fixed some
annoying problems with extra space between paragraphs and lists.
</para>
</section> <!-- Configuring SGMLtools -->
<!-- I suggest that we remove all sections on Jade etc. below, and
describe them shortly here, as parts of SGMLtools. What do you say? -->
<section id="using-sgmltools">
<title>Using &SGMLtools;</title>
<para>
&SGMLtools; is used to verify the validity
of the SGML documents and publish SGML documents in
various formats.
</para>
<para>
Using &SGMLtools; you can easily create
various output file. To create a postscript file (PS) simply type
the command:
<cmdsynopsis>
<command>sgmltools</command>
<arg>-b ps</arg>
<arg><replaceable>filename.sgml</replaceable></arg>
</cmdsynopsis>
</para>
<para>
To create a web browsable document (HTML) from the file, you would use:
<cmdsynopsis>
<command>sgmltools</command>
<arg>-b html</arg>
<arg><replaceable>filename.sgml</replaceable></arg>
</cmdsynopsis>
</para>
<para>
To create a rich-text-formatted document (RTF) file use:
<cmdsynopsis>
<command>sgmltools</command>
<arg>-b rtf</arg>
<arg><replaceable>filename.sgml</replaceable></arg>
</cmdsynopsis>
</para>
<para>
To create a text (TXT) file use:
<cmdsynopsis>
<command>sgmltools</command>
<arg>-b rtf</arg>
<arg><replaceable>filename.sgml</replaceable></arg>
</cmdsynopsis>
</para>
<para>
To get additional help type:
<cmdsynopsis>
<command>sgmltools</command>
<arg>--help</arg>
</cmdsynopsis>
</para>
<para>
Unfortunately, &SGMLtools; is not (yet
anyway) able to create portable-document-format (PDF) files.
</para>
</section> <!-- Using SGML tools -->
</section> <!-- SGML tools -->
<section id="jade">
<title><application>Jade</application></title>
<section id="describe-jade">
<title>Description of <application>Jade</application></title>
<para>
This is a SGML verifier and also generates various document
formats from SGML files. This package is used by other
software. You will need it. However, it is clumsy to use you
are also wise to also install
&SGMLtools;
(see <xref linkend="using-sgmltools">) to simplify you life.
</para>
</section> <!-- description of Jade -->
<section id="obtain-jade">
<title>Obtaining <application>Jade</application></title>
<para>
<application>Jade</application> can be found at:
</para>
</section> <!-- Obtaining Jade -->
<section id="configuring-jade">
<title>Configuring <application>Jade</application></title>
<para>
Nothing to configure?
</para>
</section> <!-- Configure Jade -->
<section id="using-jade">
<title>Using <application>Jade</application></title>
<para>
To create an RTF file type the following command:
<cmdsynopsis>
<command>jade</command>
<arg>-t rtf</arg>
<arg>-d <replaceable>/path-to-stylesheets/docbook/print/docbook.dssl</replaceable></arg>
<arg><replaceable>file.sgml</replaceable></arg>
</cmdsynopsis>
</para>
<para>
To create an HTML file type the following command:
<cmdsynopsis>
<command>jade</command>
<arg>-t sgml</arg>
<arg>-d
<replaceable>/path-to-stylesheets/docbook/html/docbook.dssl</replaceable></arg>
<arg><replaceable>file.sgml</replaceable></arg>
</cmdsynopsis>
</para>
</section> <!-- Using Jade -->
</section> <!-- Jade -->
<section id="docbook">
<title>DocBook</title>
<section id="describe-docbook">
<title>Description of DocBook 3.1</title>
<para>
These are files that define something. (I don't really know what they do, but the docbook.dtd
files are needed. Maybe they come with other packages too. I think so. Is this really a
package we need to describe? Ramin?)
</para>
</section> <!-- Describe DocBook -->
<section id="obtain-docbook">
<title>Obtaining DocBook 3.1</title>
<para>
It can be found here.
</para>
</section> <!-- Obtain DocBook -->
<section id="configure-docbook">
<title>Configuring DocBook 3.1</title>
<para>
Is there anything to configure?
</para>
</section> <!-- Configure DocBook -->
<section id="using-docbook">
<title>Using DocBook 3.1</title>
<para>
Programs use it you don't directly.
</para>
</section> <!-- using DocBook -->
</section> <!-- DocBook -->
<!-- Should probably be presented before Emacs, since Emacs is just a
more specialized case of an editor. -->
<section id="text-editor-descriptions">
<title>Text Editors</title>
<para>
Text editors are for those who are not afraid to type the sgml
tags by themselves. Once the
files are created you will need to use
&SGMLtools; or
<application>jade</application> to verify and generate the
documents for others to read.
</para>
<para>
There are a large number of possibilities — I personally
like to use <application>nedit</application>
<ulink url="http://???.???.???"></ulink> in a graphical environment.
Be aware though that
<application>nedit</application> uses key-bindings of Macintosh and
Windows machines (the
command-key combinations) — not the meta-key (on most i386
keyboards this is the ALT key) which is the usual key-combination on Linux.
<application>vi</application> in a text screen environment —
which comes with most
operating systems. When you are finished typing simply use
&SGMLtools; (see <xref
linkend="using-sgmltools">) or <application>jade</application> (see
<xref linkend="using-jade">) directly to create your target documents.
</para>
</section> <!-- Text Editors -->
</section> <!-- Software -->
<section id="graphics">
<title>Including Graphics</title>
<para>
One of the major reasons we have chosen the DocBook format is that we
can easily include graphics (mostly screenshots to help describe
software) into the documentation. Since SGML can
produce a variety of document types — you will need to save
your images in several different formats. This section describes how
to capture screen shots, how to save them in different formats and
finally how to include them in the DocBook file.
</para>
<section id="GIMP">
<title>GIMP — GPL Image Software</title>
<subtitle>GNU Image Manipulation Program (<application>GIMP</application>)</subtitle>
<para>
<application>GIMP</application> is an excellent GPLed general purpose
image manipulation
program. Not only does it manipulate images effectively, but it also
allows one to take screen shots.
</para>
<section id="obtain-gimp">
<title>Obtaining <application>GIMP</application></title>
<para>
<application>GIMP</application> is part of the
<ulink url="http://www.gnome.org">GNOME</ulink> effort.
<application>GIMP</application> can be found at the
<ulink url="http://www.gimp.org">GIMP</ulink> homepage.
</para>
</section> <!-- Graphics, GIMP, Obtain -->
<section id="config-gimp">
<title>Configuring <application>GIMP</application></title>
<para>
<application>GIMP</application> configures itself the first
time you run it.
</para>
</section> <!-- Graphics, GIMP, Config -->
<section id="using-gimp">
<title>Using <application>GIMP</application></title>
<section id="starting-gimp">
<title><application>GIMP</application>'s Starting Point</title>
<para>
When you start <application>GIMP</application> you will see
the following initial window.
<graphic fileref="GIMP-window"></graphic>
</para>
</section> <!-- Graphics, GIMP, Using, Start up -->
<section id="taking-screenshot">
<title>Taking a Screenshot</title>
<para>
To take a screen shot — go to the
<application>GIMP</application>'s initial window and choose
<menuchoice>
<guimenu>Xtns</guimenu>
<guimenuitem>Screen Shot</guimenuitem>
</menuchoice>.
The the following dialog box should appear.
<graphic fileref="screenshot"></graphic>
Click on the <guibutton>Grab</guibutton> button.
The next window you click on will be captured and editable by
<application>GIMP</application>.
</para>
</section> <!-- Graphics, GIMP, Using, ScreenShot -->
<section id="GIMP-save">
<title>Saving and File Formats</title>
<para>
Now that you have created the screen shot save the image. I
recommend always saving the image in
<application>GIMP</application>'s native format (XCF)
first. To do this you need to <mousebutton>right
click</mousebutton> on the image and select
<menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save as</guimenuitem>
</menuchoice>
in the menu that pops up. Name the graphic with the
following format <filename>filename.xcf</filename> — the
<emphasis>.xcf</emphasis> at the end of the name is important!
<note>
<para>
NOTE: this is only true if the
<guimenu>Determine file type:</guimenu> is set to
<guimenuitem>By extension</guimenuitem> —
which is the default.
</para>
</note>
</para>
<para>
You now have an original image to do further
manipulations later. Other formats may not contain all the
graphical information (for example the JPEG format) and if you
editing this type of an image the quality may very poor.
The first website I build, I didn't realize this.
I stored all the graphics in JPEG format. A year or two later
when people wanted little changes. I had to go find the
original photos again and rescan the pictures, because the
quality after editing a JPEG image was unacceptable. So
save yourself some future work — keep a file in
<application>GIMP</application>'s native format.
</para>
<section id="create-ps">
<title>Save the Image in Postscript Format</title>
<para>
Saving an image in the postscript format is easy,
simply <mousebutton>right click</mousebutton> on the image
and choose
<menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save as</guimenuitem>
</menuchoice>
in the menu that pops up. Name the graphic with the
following format <filename>filename.eps</filename> — the
<emphasis>.eps</emphasis> at the end of the name is important!
<note>
<para>
NOTE: this is only true if the
<guimenu>Determine file type:</guimenu> is set to
<guimenuitem>By extension</guimenuitem> —
which is the default.
</para>
</note>
</para>
</section> <!-- Graphics, GIMP, Using, Save, PS -->
<section id="create-gif">
<title>Save the Image in GIF Format</title>
<para>
This is a little trickier for most of us because our
monitors use more then 256 colors. GIF, however, can
only store 256 colors. So first we need to reduce the
colors in the image. To do this <mousebutton>right
click</mousebutton> on the image and select
<menuchoice>
<guimenu>image</guimenu>
<guimenuitem>indexed</guimenuitem>
</menuchoice>
in the menu that pops up. Now a dialog box should
appear. <emphasis>Be sure that the number of colors is
set to 256!</emphasis>. Now click the
<guibutton>OK</guibutton> button. If everything went
well you will see the word (indexed) at the end of the
filename in your window bar.
<note>
<para>
NOTE: Some of the colors might have changed
because <application>GIMP</application> might have had to
change a color somewhat so that the image only has 256
colors.
</para>
</note>
</para>
<para>
Now the image is properly prepared to be saved in a GIF
format. To save simply
simply <mousebutton>right click</mousebutton> on the image
and choose
<menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save as</guimenuitem>
</menuchoice>
in the menu that pops up. Name the graphic with the
following format <filename>filename.gif</filename> — the
<emphasis>.gif</emphasis> at the end of the name is
important!
<note>
<para>
NOTE: this is only true if the
<guimenu>Determine file type:</guimenu> is set to
<guimenuitem>By extension</guimenuitem> —
which is the default.
</para>
</note>
</para>
</section> <!-- Graphics, GIMP, Using, Save, GIF -->
</section> <!-- Graphics, GIMP, Using, Save -->
</section> <!-- Graphics, GIMP, Using -->
</section> <!-- Graphics, GIMP -->
<section id="insert-graphics">
<title>Inserting Graphics into SGML</title>
<para>
For every graphic a GIF and an EPS file are needed so that
the graphic can be used in different output formats
(html, postscript & rtf). <emphasis>Do not</emphasis> include
file extensions in the SGML tag and the proper graphic will
be chosen automatically. Therefore a tag should look
like the following:
<graphic fileref="screenshot"></graphic>
</para>
</section> <!-- Graphics, Insert -->
</section> <!-- Graphics -->
<section id="template">
<title>SGML and LyX Templates</title>
<para>
Templates v0.1 are made and are available at:
<ulink url="http://???.???.???"></ulink>
</para>
</section>
<section id="customizing">
<title>Customizing the Output</title>
<para>
document the usage of own stylesheets with SGMLtools and Jade. Show an
example of such stylesheets and tell where to get more info on them.
(ramin).
</para>
</section>
<section id="expectations">
<title>SEUL/EDU Document Expectations</title>
<para>
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.
</para>
<section id="version">
<title>DocBook Version</title>
<para>
We will create SEUL/EDU documentation using DocBook version 3.1
</para>
</section> <!-- DocBook Version -->
<section id="doc-types">
<title>Document Type</title>
<para>
We will be using articles and each article will contain an article
header containing the author, publisher (SEUL/EDU), title, and revision
history.
</para>
</section>
<section id="structure">
<title>Article Structure</title>
<section id="header">
<title>Article Header</title>
<section id="title">
<title>Title</title>
<para>
Every article should have a title
</para>
</section> <!-- header title -->
<section id="authors-credits">
<title>Authors</title>
<para>
The author's name should be listed here.
(Where do we put the author's contact information?)
</para>
</section> <!-- Authors -->
<section id="abstract">
<title>Abstract</title>
<para>
Please include a quick overview of the document so that
people know if it contains the information that they need
without having to read the whole article.
</para>
</section> <!-- Aticle Abstract -->
<section id="rev-history">
<title>Revision History</title>
<para>
A short description of the date and changes in each version
of the document.
</para>
</section> <!-- Article History -->
</section> <!-- Article Header -->
<section id="introduction">
<title>Introduction</title>
<para>
Every article's first chapter should be the introduction containing the
following information:
</para>
<section id="doc-category">
<title>Document Category</title>
<para>
The document category: Documents should be in at one of the
following categories (we can create more categories if
needed -- but for now let's use these):
<itemizedlist>
<listitem>
<para>
<emphasis>Software Guides</emphasis> — these are designed to teach
people how to use the Linux software we have found to be
valuable in an educational setting.
</para>
</listitem>
<listitem>
<para>
<emphasis>Teacher Guides</emphasis> — these are designed to show
teachers how to effectively use Linux software in an
educational setting.
</para>
</listitem>
<listitem>
<para>
<emphasis>Server Guides</emphasis> —
these will contain Linux server configuration files
and techniques that will provide schools with secure
and cost effective software and services needed by
schools.
</para>
</listitem>
<listitem>
<para>
<emphasis>Workstation Guides</emphasis> —
these will contain Linux workstation configuration files
and techniques that will provide schools with secure and
cost effective workstations for students, teachers
and administrators.
</para>
</listitem>
<listitem>
<para>
<emphasis>Documentation Guides</emphasis> — are 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.
</para>
</listitem>
</itemizedlist>
</para>
</section> <!-- Document Types -->
<section id="purpose">
<title>Document Purpose</title>
<para>
A short description of what the document is designed to solve
for someone — or how it is suppose to help.
</para>
</section> <!-- intro purpose -->
<section id="audience">
<title>Intended Audience</title>
<para>
A short description of who this document of the most likely
people who will be helped by the document.
</para>
</section> <!-- intro Audience -->
<section id="background">
<title>Background Information</title>
<para>
Description of relevant or interesting history related to
the topic at hand.
</para>
</section> <!-- Intro Background -->
</section> <!-- Introduction -->
<section id="sections">
<title>Additional Sections</title>
<para>
Every article should contain as many sections as needed to
clearly cover the topic at hand.
</para>
</section> <!-- Sections -->
<section id="appendix">
<title>Appendix</title>
<para>
Every article should have an appendix with a listing of
conventions used. This will be included in the template
— no reason for everybody to type this. Other appendices
can be added as needed.
</para>
</section> <!-- Appendix -->
<section id="Bibliography">
<title>References</title>
<para>
Every document should list the references used and those that
may be helpful to the reader.
</para>
</section> <!-- Bibliography -->
</section> <!-- Structure -->
</section> <!-- Expectations -->
<appendix id="conventions">
<title>SEUL/EDU Conventions</title>
<para>
This section shows how different items will be displayed in the
document. This ensures a consistent look and feel and a unified
way to do a meaningful search of SEUL/EDU Documents.
</para>
<section id="filenames">
<title>Pathnames, filenames & URLs</title>
<para>
<itemizedlist>
<listitem>
<para>
<filename class=directory>/usr/local/bin/</filename>
— is how directories are shown.
</para>
</listitem>
<listitem>
<para>
<filename>httpd.log</filename> — is how a
file is shown.
</para>
</listitem>
<listitem>
<para>
<application>LyX</application> — is how an
application is shown.
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.seul.org/edu/">SEUL/EDU</ulink> —
is how URLS will look.
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section id="commands">
<title>Commands</title>
<para>
Commands will look like the following:
<cmdsynopsis>
<command>sgmltools</command>
<arg>-b html</arg>
<arg><replaceable>filename.sgml</replaceable></arg>
</cmdsynopsis>
</para>
</section>
<section id="prompts">
<title>Screen Prompts & User Input</title>
<para>
<prompt>username:</prompt> — is how information will
look when you are prompted to enter information.
</para>
<para>
<userinput>userinput</userinput> — is how text will look
when the user needs to enter information,
usually in response to a screen prompt.
</para>
<para>
Here is an example of these being used shown on a screen:
</para>
<screen>
<prompt>username:</prompt> <userinput>bill</userinput>
</screen>
</section>
<section id="keyboard">
<title>Keys and Key Combinations</title>
<para>
<keycap>Esc</keycap> is how an individual key will be shown.
</para>
<para>
Two keys pressed simultaneously will be displayed like the
following:
<keycombo><keycap>Ctrl</keycap><keycap>c</keycap></keycombo>.
In this case the <keycap>Ctrl</keycap> is pressed and while
pressing this key one also strikes the <keycap>c</keycap> key.
</para>
<para>
When two keys are pressed followed by another key or
key-combination it will look like the following:
<keycombo><keycap>Alt</keycap><keycap>c</keycap></keycombo>
<keycap> n</keycap>
<!-- note I cheated here and added a space because it wasn't
working properly for me (or I am making a mistake) -->
</para>
</section>
<section id="gui">
<title>GUI Conventions</title>
<section id="menus">
<title>Menus</title>
<para>
If the menu item is <guimenu>Layout</guimenu> and the menu-item
to choose is <guimenuitem>Document...</guimenuitem>. Then together
they would like like:
<menuchoice>
<guimenu>Layout</guimenu>
<guimenuitem>Document...</guimenuitem>
</menuchoice>
</para>
</section>
<section id="keyboard-shortcuts">
<title>Keyboard Shortcuts</title>
<para>
In the above example the keyboard short-cut is to
press the <keycap>Alt</keycap> & <keycap>f</keycap> key
simultaneously and afterwards press the <keycap>d</keycap> key:
<menuchoice>
<shortcut>
<keycombo>
<keycap>Alt</keycap><keycap>f</keycap>
</keycombo>
<keycap> d</keycap>
</shortcut>
<!-- I put the extra space in because it doesn't seem to work
- am I doing something wrong or is it broken? -->
<guimenu></guimenu>
</menuchoice>
to accomplish:
<menuchoice>
<guimenu>Layout</guimenu>
<guimenuitem>Document...</guimenuitem>
</menuchoice>
without using the mouse.
</para>
</section>
<section id="mouse">
<title>Mouse Actions</title>
<para>
The words "right button" in the below paragraph is how mouse actions
will be displayed.
</para>
<para>
To get additional menus in <application>GIMP</application> click
on the image with the <mousebutton>right button</mousebutton>.
</para>
</section>
<section id="labels">
<title>Labels</title>
<para>
The words "Save as" in the below paragraph is GUI labels
will be displayed.
</para>
<para>
Click in the text field labeled <guilabel>Save as</guilabel> and
enter the name of the file.
</para>
</section>
<section id="gui-layout">
<title>Mouse Actions</title>
<para>
The word "right" in the below paragraph is how mouse actions
will be displayed.
</para>
<para>
To get additional menus in <application>GIMP</application> click
on the image with the <mousebutton>right</mousebutton>.
</para>
</section>
</section>
<section id="word-terms">
<title>New Words and Terms</title>
<para>
These are most likely to be used in student tutorials.
<itemizedlist>
<listitem>
<para>
<firstterm>First-Time</firstterm> —
Important words that are (probably) being introduced for the
first time to the reader will look like the above words
"First-Time". Since this word/concepte is
expected to be an important new term/concept — it is
very reasonable to explain the word in the text. Often these
new terms will also be found in the Glossary.
</para>
</listitem>
<listitem>
<para>
<glossterm>Glossary-Word</glossterm> — this is how a word
is displayed if it is in the glossary. This is usually used
with a word/concept that should not necessarily be new to the
reader — however, the reader may need a reminder or the
author may want to include a detailed clarification to the
reader.
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section id="sample-code">
<title>Sample Code</title>
<subtitle>Program Listings</subtitle>
<para>
Sample Code will look like the following:
<programlisting>
sub do_nothing_useful {
my($a, $b, $c);
$a = new A;
$a->does_nothing_either();
$b = new B;
$c = "frog";
return ($a, $c);
}
</programlisting>
</para>
<para>
To ensure that all of the < and > signs (and other that are used
in SGML mark-up) are shown correctly in the code, you can use one of
the following options:
<itemizedlist>
<listitem>
<para>
Enclose the whole <sgmltag>programlisting</sgmltag>
inside <![CDATA[ and ]]>;
</para>
</listitem>
<listitem>
<para>
refer to the tile which holds the source using
the <sgmltag>graphic</sgmltag>-tag in the following way:
<sgmltag><graphic format=linespecific
fileref="program.c"></graphic></sgmltag>
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section id="quoting">
<title>Quotes</title>
<subtitle>Citing Others</subtitle>
<section id="short-quotes">
<title>Short Quotes</title>
<subtitle>In-line Quotes</subtitle>
<para>
Short quotes (less than three lines long) will look like the following: I was skiing in Switzerland,
but missing the icy, narrow ski trails in Vermont. I said, "Well,
at least the views are nice," and my colleague Jim Shields responded,
"Yeah, but you get used to the view."
</para>
</section>
<section id="long-quotes">
<title>Long Quotes</title>
<subtitle>Block Quotes</subtitle>
<para>
Long quotes (block quotes) are used when the quote will be
longer than three lines if it were an inline quote. These
longer quotes will look like the following:
<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>
</para>
</section>
</section>
</appendix>
<glossary id="glossary">
<title>Example Glossary</title>
<glossentry id=sgml>
<glossterm>Standard Generalized Markup Language</glossterm>
<acronym>SGML</acronym>
<glossdef>
<para>
Some kind of definition goes here.
</para>
</glossdef>
</glossentry>
</glossary>
<bibliography>
<!-- The bibliography's title is generated automatically, a title isn't
necessary -->
<biblioentry>
<authorgroup>
<author><firstname>Debra</firstname><surname>Cameron</surname></author>
<author><firstname>Bill</firstname><surname>Rosenblatt</surname></author>
<author><firstname>Eric</firstname><surname>Raymond</surname></author>
</authorgroup>
<copyright>
<year>1996</year><year>1992</year><year>1991</year>
<holder>O'Reilly</holder>
</copyright>
<isbn>1-56592-152-6</isbn>
<publisher>
<publishername>O'Reilly</publishername>
</publisher>
<title>Learning GNU Emacs</title>
<subtitle>Second Edition</subtitle>
</biblioentry>
<biblioentry>
<author><firstname>Michael J.</firstname><surname>Hammel</surname></author>
<copyright>
<year>1999</year>
<holder>Specialized System Consultants, Inc. (SSC)</holder>
</copyright>
<isbn>1-57831-011-3</isbn>
<publisher>
<publishername>Specialized System Consultants, Inc. (SSC)</publishername>
</publisher>
<title>The Artists' Guide to the GIMP</title>
<subtitle>The GNU Image Manipulation Program</subtitle>
</biblioentry>
<biblioentry>
<authorgroup>
<author><firstname>Norman</firstname><surname>Walsh</surname></author>
<author><firstname>Leonard</firstname><surname>Muellner</surname></author>
</authorgroup>
<copyright>
<year>1999</year>
<holder>O'Reilly</holder>
</copyright>
<editor><firstname>Frank</firstname><surname>Willison</surname></editor>
<isbn>1-56592-580-7</isbn>
<publisher>
<publishername>O'Reilly</publishername>
</publisher>
<title>DocBook</title>
<subtitle>The Definitive Guide</subtitle>
</biblioentry>
</bibliography>
</article>
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY html-ss
PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA dsssl>
<!ENTITY print-ss
PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA dsssl>
]>
<style-sheet>
;; Use [stylesheet]#print to use this part...
<style-specification id="print" use="print-stylesheet">
<style-specification-body>
;; customize the print stylesheet
(define %generate-article-toc% #t)
(define (article-titlepage-recto-elements)
(list (normalize "title")
(normalize "subtitle")
(normalize "graphic")
(normalize "date")
(normalize "corpauthor")
(normalize "authorgroup")
(normalize "author")
(normalize "orgname")
(normalize "editor")
(normalize "releaseinfo")
(normalize "copyright")
(normalize "revhistory")
(normalize "abstract")
(normalize "legalnotice")))
;; Returns the depth of auto TOC that should be made at the nd-level
(define (toc-depth nd)
; (if (string=? (gi nd) (normalize "book"))
; 3
; 1))
2)
;; Automatically number the sections ???
(define %section-autolabel% #t)
(define %paper-type% "A4")
;; Undefine this if you don't want two-sided output
(define %two-side% #t)
;; To really get bottom of page footnotes, we need to define both of the
;; following lines.
(define bop-footnotes #t)
(define tex-backend #t) ;; Need to explicitly define the backend ...
;; The above might brake if converting to RTF (or other non-TeX)
;; We want numbers for literallayout
(define %number-literallayout-lines% #t)
;; This should use full justification instead of just left justification.
(define %default-quadding%
;; The default quadding
'justify)
</style-specification-body>
</style-specification>
;; Use [stylesheet]#html to use this part...
<style-specification id="html" use="html-stylesheet">
<style-specification-body>
;; customize the html stylesheet
(define %html-ext% ".html")
(define nochunks #f)
(define %generate-article-toc% #t)
(define %use-id-as-filename% #t)
(define %stylesheet% "db_default.css")
(define %stylesheet-type% "text/css")
(define %css-decoration% #t)
;; I don't like defining anything for the body in the HTML, I use CSS for it
(define %body-attr% '())
;; Returns the depth of auto TOC that should be made at the nd-level
;(define (toc-depth nd)
;; Uncomment to use depth of n (2) for any type
; 2)
;; Uncomment to use depth of n (3) for book or m (1) for any other type
; (if (string=? (gi nd) (normalize "book"))
; 3
; 1))
(define %section-autolabel% #t)
(define bop-footnotes #t)
(define %number-literallayout-lines% #t)
</style-specification-body>
</style-specification>
<external-specification id="print-stylesheet" document="print-ss">
<external-specification id="html-stylesheet" document="html-ss">
</style-sheet>