Table of Contents
This document is for those want to write or build SCIRun documentation.
It describes:
The organization of the documentation tree.
The types of documents in the tree.
Building document products from their sources and the tools needed.
Editing documents.
Table 1, “Doc Tree Organization” shows the organization of the doc tree. It shows only those directories and files that are part of CVS. Generated files (aka products) are discussed in Building Docs.
Table 1. Doc Tree Organization
| Directories | Description | ||
|---|---|---|---|
doc/ | Root of doc tree.
| ||
Documentum/ | “Document documentation”. Document templates for XHTML, DocBook, and LaTeX documents. | ||
Utilities/ | Utility directory. | ||
XML/ |
XSL style files, DTDs and CEDs (precompiled dtds for use with Emacs PSGML mode), and XML related scripts. | ||
TeX/ |
LaTeX related style files, macros files, and scripts. | ||
HTML/ | CSS style files, javascript sources, and HTML related scripts. | ||
Figures/ | Shared figures (e.g. page header and footer banners). | ||
User/ |
User documentation root. | ||
Tutorials/ | HTML sources and figures for SCIRun user-level tutorials | ||
Guide/ | LaTeX sources for the SCIRun users guide.
| ||
FAQ/ | XML sources for the user FAQ and
| ||
Developer/ |
Developer documentation root. | ||
Guide/ |
XML and HTML sources for the SCIRun developers
guide. | ||
FAQ/ |
XML sources for developer FAQ and | ||
CodeViews/ |
Tools ( | ||
Modules/ |
| ||
Installation/ |
Installation documentation root. | ||
Guide/ |
XML sources for installation guide and
| ||
FAQ/ |
XML sources for installation FAQ and
| ||
ReleaseNotes/ |
Release notes. Plain text. | ||
SCIRun documents are written in markup languages: XML, LaTeX, and HTML (plus their eruby equivalents—see Documents and Their Markup Languages for more information). XML and LaTeX document sources must be “built” or transformed into other forms (e.g. HTML) for presentation. This section briefly describes the build system and its use.
The term sources refers to files that are created and edited manually. The term products refers to files that are generated from sources by a tool. Sources are always part of the CVS repository. Products are never part of the CVS repository.
Makefiles generate products from sources.
The doc tree uses a conventional recursive makefile approach to
building documentation. Some Makefiles generate products, while others
(doc/Developer/Makefile,
doc/Installation/Makefile,
doc/User/Makefile) invoke sub-make
processes. The topmost Makefile (doc/Makefile
initiates the build of the entire documentation set, and also creates a documentation tarball
The doc tree and its build system are designed so that anyone can build documentation with the proper tools. This facilitates the edit/compile/test/debug cycle. Bugs and errors can be discovered before the doc tree is published on the internal website. The doc developer can edit sources, invoke make to build products, test and debug the docs with his or her web browser, and correct problems before committing changes to the CVS repository.
Note that Makefiles are written in the GNU make dialect.
Source files with extensions
.rxml, .rhtml, and
.rtex are eruby
sources. Information on these files can be found in Documents and Their Markup Languages.
Before using the build system:
Install the required tools. See Tools.
The build system can be invoked from the command line, from a script, or from the program Publish.rb
This section assumes OpenJade and the ISO character entity sets have been installed. See Tools for information on these tools.
Two catalog files must be prepared. The first maps ISO entity set public identifiers (abstract names) to corresponding system identifiers (file names). The second catalog lists system identifiers of other catalog files (including the ISO entity set catalog) needed by OpenJade.
The ISO entity set catalog is named
isoent.cat and has the following content:
PUBLIC "ISO 8879:1986//ENTITIES Diacritical Marks//EN" "ISOdia" PUBLIC "ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN" "ISOnum" PUBLIC "ISO 8879:1986//ENTITIES Publishing//EN" "ISOpub" PUBLIC "ISO 8879:1986//ENTITIES General Technical//EN" "ISOtech" PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN" "ISOlat1" PUBLIC "ISO 8879:1986//ENTITIES Added Latin 2//EN" "ISOlat2" PUBLIC "ISO 8879:1986//ENTITIES Greek Letters//EN" "ISOgrk1" PUBLIC "ISO 8879:1986//ENTITIES Monotoniko Greek//EN" "ISOgrk2" PUBLIC "ISO 8879:1986//ENTITIES Greek Symbols//EN" "ISOgrk3" PUBLIC "ISO 8879:1986//ENTITIES Alternative Greek Symbols//EN" "ISOgrk4" PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN" "ISOamsa" PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Binary Operators//EN" "ISOamsb" PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Delimiters//EN" "ISOamsc" PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Negated Relations//EN" "ISOamsn" PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Ordinary//EN" "ISOamso" PUBLIC "ISO 8879:1986//ENTITIES Added Math Symbols: Relations//EN" "ISOamsr" PUBLIC "ISO 8879:1986//ENTITIES Box and Line Drawing//EN" "ISObox" PUBLIC "ISO 8879:1986//ENTITIES Russian Cyrillic//EN" "ISOcyr1" PUBLIC "ISO 8879:1986//ENTITIES Non-Russian Cyrillic//EN" "ISOcyr2"
The above catalog entries assume isoent.cat is in
the directory containting the ISO entity sets. If this is not true,
the system identifiers (e.g. “ISOdia”) must be
changed (e.g. “/path/to/ISOdia”) appropriately.
The second catalog (“OpenJade” catalog) lists system identifiers of other catalog files needed by OpenJade, including the ISO entity set catalog. This catalog file can be located anywhere. It has the following content:
CATALOG /path/to/openjade/dsssl/catalog CATALOG /path/to/isoent.cat
where “/path/to/” is replaced by a real path. The first entry in this catalog references a file named “catalog” within the OpenJade distribution.
Six environment variables must be set before building documentation:
CLASSPATH is the path to the
file saxon.jar within the Saxon distribution.
STYLESHEET_XSL_HTML is the path of the
html directory within the DocBook
XSL stylesheet distribution.
STYLESHEET_DSSSL_PRINT is the path of the
print directory within the DocBook
DSSSL stylesheet distribution.
XML_DCL is the path to the file
xml.dcl within the DocBook
DSSSL stylesheet distribution.
CATALOG is the path to the “OpenJade”
catalog file.
WITH_CV should be set to the string “true”
if Doxygen is to build the C++ based documentation.
For instance (assuming a Bourne type shell):
export CLASSPATH=/usr/local/lib/Saxon/saxon.jar export STYLESHEET_XSL_HTML=/usr/local/xsl/docbook/html/ export STYLESHEET_DSSSL_PRINT=/usr/share/sgml/dsssl/docbook-dsssl-nwalsh/print export XML_DCL=/usr/share/sgml/dsssl/docbook-dsssl-nwalsh/dtds/decls/xml.dcl export CATALOG=~/Documents/sgml/catalog export WITH_CV=true
To make all docs cd to the toplevel
doc directory and type make.
To also make a doc tarball type:
cd doc # cd to toplevel doc directory make tarball
Build one particular doc or a particular set of docs by cd'ing to the directory of interest and typing make. For example:
cd doc/Developer # Make all developer docs. make
or
cd doc/Developer/Guide # Make just the developer's guide. make
To remove “incidental” files (but no products) from a directory (and its sub-directories) type:
make clean
To also remove products (generated files) type:
make veryclean
The script
doc/Utilities/Publish/publish.rb is used to
build SCIRun documentation. It can also deliver SCIRun documentation
to a local or remote site. Driven by configuration files, the script
can build the entire documentation tree or selected parts of
it.
The script is used as follows:
publish.rb config-file
where config-file is the name of a
configuration file.
Two configuration files can be found in
doc/Utilities/Publish. One,
template.conf builds all documentation. The
other, pwd.conf, builds documentation in the
current working directory. The configuration files should be copied elsewhere and
edited appropriately. Read the comments in each configuration file
for editing instructions.
Each document is composed in one (or more) of the following markup languages (ML):
Table 2, “Document Types” provides document specific details.
A number of DocBook, HTML, and LaTeX source documents contain
snippets of Ruby code. These “eruby” (embedded ruby)
source documents can be identified by their extensions:
.rxml for DocBook or other XML sources,
.rhtml for HTML sources, and
.rtex for LaTeX documents. Products
(.xml, .html, and
.tex files) are generated by replacing code
snippets with results of their execution—the eruby tool
executes this code and performs the replacement.
Be sure to edit the eruby version of a document (if it exists) rather than its product equivalent.
Table 2. Document Types
| Document(s) | ML(s) |
|---|---|
| Developer Guide | DocBook and HTML |
| FAQs | DocBook |
| Installation Guide | DocBook |
| Module Descriptions | SCIRun Component (or Module) ML and LaTeX |
| Tutorial | HTML |
| Users Guide | LaTeX |
| "Cover Pages" (index.html files) | HTML |
Later sections provide information on editing these documents.
The Component (or module) markup language was developed by
SCI. It is defined by its DTD which is the file
doc/Utilities/XML/component.dtd.
This document is composed in DocBook ML.
Table 3, “Stylesheet Usage” shows CSS stylesheets and the documents
that use them. Stylesheets can be found in
doc/Utilities/HTML
Table 3. Stylesheet Usage
| Stylesheet | Document(s) |
|---|---|
common.css | Included by all other stylesheets |
srdocbook.css | Docbook Documents including the FAQs |
srlatex2html.css | Latex Documents |
mainindex.css | doc/index.html |
subindex.css | Second level index files (e.g. doc/User/index.html) |
pkgindex.css | doc/Developer/Modules/index.html |
moduleindex.css | doc/Developer/Modules/SCIRun.html,
etc. (i.e. HTML files generated by the program
doc/Utilities/HTML/makepkgindex.rb) |
component.css | Module
descriptions generated by
doc/Utilities/XML/component.xsl. |
“Why so many bloody style sheets?”. Because it is too bloody hard to write, debug, and maintain a one-size-fits-all stylesheet!
My personal philosophy:
Avoid writing a "one-size-fits-all" stylesheet. Doing so creates a large stylesheet (filled with many classes) that is hard to understand and debug, which makes writing documents more difficult.
Associate 1 stylesheet per document class—which is why there are so many stylesheets above.
Write XHTML/HTML documents
using no presentational markup or inline
style attribute (although I sometimes use the<style> element).
Write stylesheets using the minimum number of style classes. This rule simplifies stylesheets and the documents that use them, although it increases the number of stylesheets needed.
This section discusses the use of emacs to edit XML documents.
It is easy to get lost in the noise of XML syntax. Therefore, it is best to use an XML DTD aware editor. This type of editor will help construct valid XML documents.
Emacs is one such editor. It supports an editing environment called XML mode, a derivative of PSGML mode. XML mode highlights XML syntax, indents nested elements and their content, and automatically inserts elements and attributes based on the position of the insertion point. It is still possible, however, to create invalid documents using Emacs XML mode.
Emacs XML mode can be used to edit XML based module descriptions, XHTML documents, DocBook documents, and any XML based language that is described by a DTD.
Recent versions of Emacs come with XML mode installed. Check to see if you have XML mode
by typing M-x xml-mode. You do not have
XML mode if you get the message
[No match]
in return. XML mode can be obtained online.
The following lisp code should be inserted into the .emacs
file:
; Tell emacs to use sgml/xml mode for the following file types.
(setq auto-mode-alist
(append
'(("\\.xml" . xml-mode)
("\\.xhtml" . xml-mode))
auto-mode-alist))
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
(autoload 'xml-mode "psgml" "Major mode to edit XML files." t)
; Create some faces for use with sgml/xml mode.
; Change colors to suite your fancy.
(make-face 'sgml-start-tag-face)
(set-face-foreground 'sgml-start-tag-face "MediumSeaGreen")
(make-face 'sgml-end-tag-face)
(set-face-foreground 'sgml-end-tag-face "SeaGreen")
(make-face 'sgml-entity-face)
(set-face-foreground 'sgml-entity-face "Red")
(make-face 'sgml-doctype-face)
(set-face-foreground 'sgml-doctype-face "firebrick")
(make-face 'sgml-comment-face)
(set-face-foreground 'sgml-comment-face "blue")
; Use faces defined above.
(setq sgml-set-face t)
(setq sgml-markup-faces
'((comment . sgml-comment-face)
(start-tag . sgml-start-tag-face)
(end-tag . sgml-end-tag-face)
(doctype . sgml-doctype-face)
(entity . sgml-entity-face)))
To start a new XML document:
Create a new file (C-x C-f) with a suffix of .xml
Insert a preamble. The following is a preamble for a DocBook document:
<?xml version="1.0"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD &dbk; XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">
Insert the following XML comment at the bottom of the file.
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-default-dtd-file:"top-of-cvs-tree/Utilities/XML/docbook.ced"
sgml-omittag:nil
sgml-shorttag:nil
End:
-->
Replace top-of-cvs-tree with the relative
path from the document to the doc directory of
the SCIRun CVS tree.
Note that the file docbook.ced is a precompiled
DTD for the docbook language. Replace
docbook.ced with
xhtml1-transitional.ced when creating a
XHTML document. Replace
docbook.ced with
component.ced when creating a
module description document.
Save the file, close it, and re-open it. Now begin editing the file using xml mode.
This section presents some of the most important XML-mode editing commands. See the online manual for complete documentation. FIX ME! The following is taken from the online manual. It should be replaced by original text.
C-c C-eInserts start and end-tags for an element (sgml-insert-element). The name of the element is read from the mini-buffer with completion on valid elements. If sgml-insert-end-tag-on-new-line is non-nil or the element has element content, the end-tag is inserted on a new line after the start-tag.
If sgml-omittag-transparent is nil, the list of valid elements only contain the elements that can be in the content of the current element.
Required elements in the content are automatically inserted if the option sgml-auto-insert-required-elements is non-nil. When the content model demands an element, but there is more than one to choose from, a comment can be inserted with the available choices if the option sgml-insert-missing-element-comment is non-nil.
C-c C-iInserts a new element in the current element where it is legal. Prompts for element name with completion. The completion list contains all elements that could be added to the current element, without making the content invalid. This assumes the content is valid to begin with. Currently, this list only has regular elements, not inclusions. The new element is inserted as late as possible in the current element (unless prefix argument is given, then as early as possible.)
C-c C-rMakes the region into a new element (sgml-tag-region). Reads element name from mini-buffer with completion as for C-c C-e.
C-c <Will ask, for the tag to insert, in the mini-buffer with completion on the tags that are valid at point (sgml-insert-tag).
If sgml-auto-insert-required-elements is non-nil, tags for elements required between the inserted tags will also be inserted.
The list of valid tags, computed for a position in the buffer, will contain:
The end-tag for the current element, if it can be ended at the position. It will contain end-tags for enclosing elements if the necessary omissible end-tag declarations have been made in the DTD.
The start-tags of all elements that could occur after point. If sgml-omittag-transparent is nil, the above will be limited to the elements that can occur within the current element.
C-c /Inserts an end-tag for the current element (sgml-insert-end-tag).
C-c RETSplits the current element at point. If repeated, the containing element is split before the beginning of then current element.
Typical use is to start a new paragraph element when inside a paragraph.
C-c C-a
C-c +Read attribute name and value from mini-buffer and insert attribute specification (sgml-insert-attribute). If point is immediately after a start-tag, this command operates on that start-tag. Otherwise, the command operates on the element after point.
The attribute name is read with completion. If the attribute has a token list as declared value, the attribute value also reads with completion. The prompt for attribute value typically looks like:
Value for attribute (type Default: current value):
Some characters or character combinations should not be used literally, because they will not typeset in an optimal way. Here is a list of things to watch for:
Enclose quotations in the quote element.
Rather than typing, say, "He said
thus and such", type <quote>He said
thus and such</quote>.
Use … to produce
ellipsis.
Rather than typing:
<quote>He said thus and such and ...</quote>
type: <quote>He said thus and such and …</quote>
Use ⋮ to produce
ellipsis.
Type:
<para>
⋮
Above me and below me there is stuff.
⋮
</para>
rather than:
<para>
.
.
.
Above me and below me there is stuff.
.
.
.
</para>
Use – to produce an en
dash.
Type “1–10” rather than
“1-10”
Use — to produce an em
dash.
Type “You stink!—Well, a little bit anyway” rather than
“You stink!---Well, a little bit anyway.”
DocBook is an XML based language for composing technical documents, specifically documents about computer software. The Installation Guide, Developers Guide, and this document are composed in the DocBook language.
It is beyond the scope of this article to introduce the DocBook language in detail. Read the online DocBook guide for an introduction to DocBook, and a complete reference to all DocBook's elements and attributes.
Peruse this document's XML source to get a feel for
the DocBook language. It is the file
doc/Documentum/documentum.xml
DocBook documents can be contained in one file, or segmented into several files. A multi-file document consists of a main file and one or more additional file.
A new single file document looks like this:
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE root-element PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" [
<!ENTITY sr "SCIRun">
]>
<!--
The contents of this file are subject to the University of Utah Public
License (the "License"); you may not use this file except in compliance
with the License.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
License for the specific language governing rights and limitations under
the License.
The Original Source Code is SCIRun, released March 12, 2001.
The Original Source Code was developed by the University of Utah.
Portions created by UNIVERSITY are Copyright (C) 2001, 1994
University of Utah. All Rights Reserved.
-->
<!-- Insert root element here. -->
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-default-dtd-file:"../../doc/Utilities/XML/docbook.ced"
sgml-omittag:nil
sgml-shorttag:nil
End:
-->
In the DOCTYPE declaration, root-element
should be replaced by the name of the document's root element, usually
book or article. The path to
docbook.ced should be altered appropriately.
A multi-file document consists of a main file that usually does nothing but “include” other files. Here is the main file for a book consisting of five chapters:
<?xml version="1.0"? encoding="iso-8859-1" >
<!--
The contents of this file are subject to the University of Utah Public
License (the "License"); you may not use this file except in compliance
with the License.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
License for the specific language governing rights and limitations under
the License.
The Original Source Code is SCIRun, released March 12, 2001.
The Original Source Code was developed by the University of Utah.
Portions created by UNIVERSITY are Copyright (C) 2001, 1994
University of Utah. All Rights Reserved.
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" [
<!ENTITY sr "SCIRun">
<!ENTITY chap1 SYSTEM "chap1.xml">
<!ENTITY chap2 SYSTEM "chap2.xml">
<!ENTITY chap3 SYSTEM "chap3.xml">
<!ENTITY chap4 SYSTEM "chap4.xml">
<!ENTITY chap5 SYSTEM "chap5.xml">
]>
<book id="main">
<title>My Great Book <title>
&chap1;
&chap2;
&chap3;
&chap4;
&chap5;
</book>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-default-dtd-file:"../../doc/Utilities/XML/docbook.ced"
sgml-omittag:nil
sgml-shorttag:nil
End:
-->
chap1.xml look like this:
<!-- The contents of this file are subject to the University of Utah Public License (the "License"); you may not use this file except in compliance with the License. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. The Original Source Code is SCIRun, released March 12, 2001. The Original Source Code was developed by the University of Utah. Portions created by UNIVERSITY are Copyright (C) 2001, 1994 University of Utah. All Rights Reserved. --> <chapter> <title>My First Chapter</title> <section> <title>First Section, First Chapter</title> <para>Blah, blah, blah</para> </section> </chapter> <!-- Keep this comment at the end of the file Local variables: mode: xml sgml-default-dtd-file:"../../doc/Utilities/XML/docbook.ced" sgml-omittag:nil sgml-shorttag:nil End: -->
Currently, there are three FAQs:
Installation FAQ - doc/Installation/FAQ/faq.rxml |
User FAQ - doc/User/FAQ/faq.rxml |
Developer FAQ - doc/Developer/FAQ/faq.rxml |
To add a new entry to a FAQs (using emacs/xemacs XML mode):
Open the appropriate file with emacs/xemacs (recommended)
Move point to just before the first
qandaentry element or just after the last
qandaentry element.
Insert the following template at point:
<qandaentry> <revhistory> <revision> <revnumber></revnumber> <date></date> </revision> </revhistory> <question> <para> </para> </question> <answer> <para> </para> </answer> </qandaentry>
Fill out the template (using additional DocBook markup if necessary).
See XML Module Descriptions (Explicated) for information on creating/editing XML based module descriptions.
See Latex Module Descriptions (Explicated) for information on creating/editing LaTeX based module descriptions.
Avoid HTML/XHTML. Use a higher-level markup language such as DocBook or LaTeX.
If HTML must be used, consider using XHTML instead. XHTML is an XML formulation of HTML. It is not yet possible or practical to write pure XHTML, but as much as possible, implement HTML-type documents using XHTML. The following rules for composing XHTML (and HTML) documents should be followed:
Use Emacs XML mode for composing XHTML documents.
Write tag and attribute names in lower case.
Enclose attribute values in quotes
(e.g. id="sec.edithtmldocs")
Close all elements.. I.e. never omit end tags. Empty
elements should be closed by an end tag or by ending the start tag
with />, e.g. the horizontal rule element should
be written as <hr/>
Nest elements properly.
… and in general try to produce valid XHTML/HTML documents.
Mind character entities (see Charater Literals—Do's and Dont's).
Avoid presentational markup (e.g. <font> elements) — Instead, use external CSS stylesheets
or the <style> element ,but avoid
the inline style attribute.
These rules are explained on the W3Schools.com web site.
Documents that live in the doc side of the tree
should be derived from
doc/Documentum/doc_template.html. Documents that live
in the src side of the tree should be based on
doc/Documentum/src_template.html.
SCIRun documentation is published to SCI's external web site.
Documentation for current SCIRun release is published at http://software.sci.utah.edu/doc.
Documentation under development is published at http://software.sci.utah.edu/future/doc.
Documentation being tested for release is published at http://software.sci.utah.edu/pre-release/doc.
The following sections describe (approximately) how to publish documentation to these sites.
Documentation for current SCIRun release (from the current release branch of the CVS tree) is published on SCI's external web site.
To publish docs on this web site:
Build a doc tarball from the sources on the release branch.
Rename the tarball:
docs-,
where d.d.d.tar.gzd.d.d is the version
number of the documentation set contained in the tarball.
Log on to virgil.sci.utah.edu. Cd to
/w01/docs/scirun-biopse.
Move the directory named present to the
past directory and rename it to reflect the
version of the docs contained therein, e.g.:
mv present past/1.6.1
Create a new present directory. Copy the new
doc tarball to the new directory.
Cd to present and unpack the
tarball using GNU tar.
The resulting directory contains doc and
src sub-directories. Move
doc and src up one level (so
they are children of present). Remove the
remaining empty directory from present.
The symbolic links /w01/sciweb/software/doc and
/w01/sciweb/software/src must exist and must
point to /w01/docs/scirun-biopse/present/doc and
/w01/docs/scirun-biopse/present/src
respectively. Verify that this is so.
Documentation under developement for a future SCIRun release, is derived from the trunk of the CVS tree and is published on SCI's external web site.
To publish docs on this web site:
Build a doc tarball from sources on the trunk.
Log on to virgil.sci.utah.edu. Cd to
/w01/docs/scirun-biopse.
Delete current contents of the directory named
future. Copy the new doc tarball to
future.
Cd to future and unpack the
tarball using GNU tar.
The resulting directory contains doc and
src sub-directories. Move
doc and src up one level (so
they are children of future). Remove the
remaining empty directory from future.
The symbolic link /w01/sciweb/software/future
must exist and must point to
/w01/docs/scirun-biopse/future.
Verify that this is so.
Pre-release documentation is documentation derived from a branch that has been created in anticipation of a new SCIRun release. It is published on the pre-release web site, so it can be tested and debugged prior to a release of SCIRun
To publish pre-release docs:
Build a doc tarball from sources on the newly created branch.
Rename the tarball:
docs-,
where d.d.d.tar.gzd.d.d is the version
number of the documentation set contained in the tarball.
Log on to virgil.sci.utah.edu. Cd to
/w01/docs/scirun-biopse.
Delete current contents of the directory named
pre-release. Copy the doc tarball to
pre-release.
Cd to pre-release and unpack the
tarball using GNU tar.
The resulting directory contains doc and
src sub-directories. Move
doc and src up one level (so
they are children of pre-release). Remove the
remaining empty directory from future.
The symbolic link /w01/sciweb/software/pre-release
must exist and must point to the directory
/w01/docs/scirun-biopse/pre-release.
Verify that this is so.
The pre-release site should be updated until the new
version of SCIRun is released. After release, the
pre-release directory should be emptied and the
present directory should be updated with
documentation for new release.
The following tools are needed to build SCIRun documentation:
GNU's version of the make utility. Makefiles in the doc tree are incompatible with other versions of the make utility.
GNU's version of tar. Tar is used to package the documentation into a single file (tarball) for distribution. GNU tar must be used to extract documentation from its tarball.
Saxon (see below) requires the Java runtime system and libraries.
Note that SGI systems ship with an ancient java distribution—newer distributions can be found on SGI's web site.
An XSLT processor that applies XSL stylesheets to XML sources to translate them to other forms (e.g. HTML). Saxon is written in Java. Saxon is used to translate the Developers guide, the Installation guide, the FAQs, and the XML based module descriptions to HTML and LaTeX.
A document markup language and typesetting system. The User's guide and some module descriptions require LaTeX.
A tool that translates LaTeX documents to HTML. Latex2html is used to translate the User's guide and latex module descriptions to HTML.
A TeX macro package for processing TeX output generated by OpenJade. See http://jadetex.sourceforge.net/ for installation instructions.
Converts dvi files to pdf. Dvipdf is part of modern LaTeX distributions.
An implementation of the DSSSL stylesheet language. OpenJade applies a DSSSL stylesheet to SGML/XML input to produce TeX output.
Needed Character entities sets.
A catalog file must that references these entity sets must be prepared. See Catalog Files for instructions.
The DocBook stylesheets translate DocBook XML documents (Developers Guide, Installation Guide, and FAQs) to HTML.
SCIRun specific stylesheets, which override templates in the DocBook
distribution, must be copied into the DocBook distribution. Copy the
files doc/Utilities/XML/srdocbook.xsl,
doc/Utilities/XML/srdocbook-common.xsl,
doc/Utilities/XML/srdocbook-chunk.xsl, and
doc/Utilities/XML/srqandaset.xsl to the
html directory of the DocBook distribution.
A documentation system for C++. Doxygen generates and extracts documentation from C++ source files.
A number of scripts in the doc tree are written in the programming language Ruby.
A number of XML, HTML, and LaTeX source documents contain snippets of Ruby code. ERuby is a tool that produces a new document by replacing the code with result of its execution. A modified version of eruby 0.9.8 is used. Contact me to get the sources. More information on these type of files can be found in Documents and Their Markup Languages
From the ImageMagick README file: ImageMagick
“...is a robust collection of tools and libraries to read, write, and
manipulate an image in any of the more popular image formats including GIF,
JPEG, PNG, PDF, and Photo CD...”
The convert utility from the ImageMagick package is used to translate jpg and gif files to eps for use in the printable version of the user's guide.