BillTihen
SEUL/EDU
Writing SEUL/EDU Documentation
Getting Started
Ramin Miraftabi
Review and corrections and adding some content
This article describes the software needed to write DocBooks. 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.
0.3
22 November 1999
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.
0.2
29 October 1999
Second draft for review - sections started.
0.1
20 October 1999
First draft for review - mostly a skeleton.
Introduction
Documentation Guide
This document is a Documentation Guide —
which means it is designed to help people write SEUL/EDU
Documentation or defines the SEUL/EDU documents standards.
Document Purpose
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.
Intended Audience
This document is intended to be read by people interested in writing
documentation for SEUL/EDU.
Background Information
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.
Software
Each tool is described to help you decide what tools will
be the most helpful for you.
<application>LyX</application>
<application>LyX</application> Description
LyX 1.04 and beyond are SGML capable if the proper
SGMLtools is installed.
LyX
will work with several other types of documents as well.
LyX allows the user to view the document
structure as one writes the document in a WYSIWYG format as
shown in the below image.
![]()
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.
Some drawbacks of using LyX.
LyX 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
LyX 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 yet anyway).
LyX 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.
LyX still uses
sect1, sect2,
sect3, 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 section tag.
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.
Therefore, LyX is only useful in creating simple DocBook
articles. Once they are exported and have the additional tags for files, keyboard strokes,
etc, LyX will not be able to maintain the document.
Obtaining <application>LyX</application>
You can download LyX from
RPMS are avaliable at:
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:
Using <application>LyX</application>
Using LyX is quite easy, however there are
a few steps you must
follow when creating a new DocBook article.
Open a new document and do the following:
ALT-n
File
New
Now check to see if the SGMLtools layout was found.
ALT-f
d
Layout
Document...
Now the Document Layout dialog box should open up.
Class
Towards the bottom of the list you should see: SGML
(DocBook article). Select this item. Then click on either
Apply or OK.
Now a confirmation dialog box should appear.
Click on Yes.
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.
Now the SGML document needs to be exported by going to
the menu bar and choosing:
File
Export
DocBook
<application>Emacs</application>
Description of <application>Emacs</application>
Emacs is a very powerful program that can do almost everything. It
is an editor, SGML verifier, SGML parser, a mail reader, a news reader and an IDE environment.
Some people love the program and other people find it complex and clumsy.
Advantages
All your SGML tools are in one spot.
Many people are familiar with it because it is also a powerful programming
environment.
The program runs under both text and graphical environments with the same
key-combinations.
Disadvantages
I have found psgml to run very slowly in Emacs.
Many people find the Emacs clumsy and overwhelming —
especially in the text only mode.
Obtaining <application>Emacs</application> and
<application>psgml</application>
Emacs is found at
and psgml is found at:
Configuring Emacs to use psgml
Emacs does this automatically? Ramin?
Using emacs and psgml
Save the file name with .sgml and the proper emacs menus will
appear. Or you can do:
I'll write something about using Emacs+psgml for DocBook authoring, that's
what I use, so I have some experience. (ramin)
<application>Jade</application>
Description of <application>Jade</application>
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 ) to simplify you life.
Obtaining <application>Jade</application>
Jade can be found at:
Configuring <application>Jade</application>
Nothing to configure?
Using <application>Jade</application>
To create an RTF file type the following command:
jade
-t rtf
-d /path-to-stylesheets/docbook/print/docbook.dssl
file.sgml
To create an HTML file type the following command:
jade
-t sgml
-d
/path-to-stylesheets/docbook/html/docbook.dssl
file.sgml
DocBook
Description of DocBook 3.1
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?)
Obtaining DocBook 3.1
It can be found here.
Using DocBook 3.1
Programs use it you don't directly.
Text Editors
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
jade to verify and generate the
documents for others to read.
There are a large number of possibilities — I personally
like to use nedit
in a graphical environment.
Be aware though that
nedit 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.
vi in a text screen environment —
which comes with most
operating systems. When you are finished typing simply use
SGMLtools (see ) or jade (see
) directly to create your target documents.
Including Graphics
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.
GIMP — GPL Image Software
GNU Image Manipulation Program (GIMP)
GIMP 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.
Obtaining <application>GIMP</application>
GIMP is part of the
GNOME effort.
GIMP can be found at the
GIMP homepage.
Configuring <application>GIMP</application>
GIMP configures itself the first
time you run it.
Using <application>GIMP</application>
<application>GIMP</application>'s Starting Point
When you start GIMP you will see
the following initial window.
![]()
Taking a Screenshot
To take a screen shot — go to the
GIMP's initial window and choose
Xtns
Screen Shot
.
The the following dialog box should appear.
![]()
Click on the Grab button.
The next window you click on will be captured and editable by
GIMP.
Saving and File Formats
Now that you have created the screen shot save the image. I
recommend always saving the image in
GIMP's native format (XCF)
first. To do this you need to right
click on the image and select
File
Save as
in the menu that pops up. Name the graphic with the
following format filename.xcf — the
.xcf at the end of the name is important!
NOTE: this is only true if the
Determine file type: is set to
By extension —
which is the default.
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
GIMP's native format.
Save the Image in Postscript Format
Saving an image in the postscript format is easy,
simply right click on the image
and choose
File
Save as
in the menu that pops up. Name the graphic with the
following format filename.eps — the
.eps at the end of the name is important!
NOTE: this is only true if the
Determine file type: is set to
By extension —
which is the default.
Save the Image in GIF Format
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 right
click on the image and select
image
indexed
in the menu that pops up. Now a dialog box should
appear. Be sure that the number of colors is
set to 256!. Now click the
OK button. If everything went
well you will see the word (indexed) at the end of the
filename in your window bar.
NOTE: Some of the colors might have changed
because GIMP might have had to
change a color somewhat so that the image only has 256
colors.
Now the image is properly prepared to be saved in a GIF
format. To save simply
simply right click on the image
and choose
File
Save as
in the menu that pops up. Name the graphic with the
following format filename.gif — the
.gif at the end of the name is
important!
NOTE: this is only true if the
Determine file type: is set to
By extension —
which is the default.
Inserting Graphics into SGML
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). Do not 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>
SGML and LyX Templates
Templates v0.1 are made and are available at:
Customizing the Output
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).
SEUL/EDU Document Expectations
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
Document Type
We will be using articles and each article will contain an article
header containing the author, publisher (SEUL/EDU), title, and revision
history.
Article Structure
Introduction
Every article's first chapter should be the introduction containing the
following information:
Document Category
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):
Software Guides — these are designed to teach
people how to use the Linux software we have found to be
valuable in an educational setting.
Teacher Guides — these are designed to show
teachers how to effectively use Linux software in an
educational setting.
Server Guides —
these will contain Linux server configuration files
and techniques that will provide schools with secure
and cost effective software and services needed by
schools.
Workstation Guides —
these will contain Linux workstation configuration files
and techniques that will provide schools with secure and
cost effective workstations for students, teachers
and administrators.
Documentation Guides — 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.
Document Purpose
A short description of what the document is designed to solve
for someone — or how it is suppose to help.
Intended Audience
A short description of who this document of the most likely
people who will be helped by the document.
Background Information
Description of relevant or interesting history related to
the topic at hand.
Additional Sections
Every article should contain as many sections as needed to
clearly cover the topic at hand.
Appendix
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.
References
Every document should list the references used and those that
may be helpful to the reader.
SEUL/EDU Conventions
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.
Pathnames, filenames & URLs
/usr/local/bin/
— is how directories are shown.
httpd.log — is how a
file is shown.
LyX — is how an
application is shown.
SEUL/EDU —
is how URLS will look.
Commands
Commands will look like the following:
sgmltools
-b html
filename.sgml
Screen Prompts & User Input
username: — is how information will
look when you are prompted to enter information.
userinput — is how text will look
when the user needs to enter information,
usually in response to a screen prompt.
Here is an example of these being used shown on a screen:
username: bill
Keys and Key Combinations
Esc is how an individual key will be shown.
Two keys pressed simultaneously will be displayed like the
following:
Ctrlc.
In this case the Ctrl is pressed and while
pressing this key one also strikes the c key.
When two keys are pressed followed by another key or
key-combination it will look like the following:
Altc
n
GUI Conventions
Keyboard Shortcuts
In the above example the keyboard short-cut is to
press the Alt & f key
simultaneously and afterwards press the d key:
Altf
d
to accomplish:
Layout
Document...
without using the mouse.
Mouse Actions
The words "right button" in the below paragraph is how mouse actions
will be displayed.
To get additional menus in GIMP click
on the image with the right button.
Labels
The words "Save as" in the below paragraph is GUI labels
will be displayed.
Click in the text field labeled Save as and
enter the name of the file.
Mouse Actions
The word "right" in the below paragraph is how mouse actions
will be displayed.
To get additional menus in GIMP click
on the image with the right.
New Words and Terms
These are most likely to be used in student tutorials.
First-Time —
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.
Glossary-Word — 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.
Sample Code
Program Listings
Sample Code will look like the following:
sub do_nothing_useful {
my($a, $b, $c);
$a = new A;
$a->does_nothing_either();
$b = new B;
$c = "frog";
return ($a, $c);
}
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:
Enclose the whole programlisting
inside <![CDATA[ and ]]>;
refer to the tile which holds the source using
the graphic-tag in the following way:
<graphic format=linespecific
fileref="program.c"></graphic>
Quotes
Citing Others
Short Quotes
In-line Quotes
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."
Long Quotes
Block Quotes
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:
Chögyam Trungpa,
Shambhala: The Sacred Path of the Warrior
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.
Example Glossary
Standard Generalized Markup Language
SGML
Some kind of definition goes here.
DebraCameron
BillRosenblatt
EricRaymond
199619921991
O'Reilly
1-56592-152-6
O'Reilly
Learning GNU Emacs
Second Edition
Michael J.Hammel
1999
Specialized System Consultants, Inc. (SSC)
1-57831-011-3
Specialized System Consultants, Inc. (SSC)
The Artists' Guide to the GIMP
The GNU Image Manipulation Program
NormanWalsh
LeonardMuellner
1999
O'Reilly
FrankWillison
1-56592-580-7
O'Reilly
DocBook
The Definitive Guide