From dustman at cvrti.utah.edu Sun Feb 26 16:50:17 2017
Content-Type: multipart/mixed; boundary="===============2454175560488037418=="
MIME-Version: 1.0
From: Ted Dustman <dustman at cvrti.utah.edu>
To: xemacs-beta at xemacs.org
Subject: sgml-mode related crash
Date: 2003-01-31 11:30:53 -0700
Message-ID: <200301311830.h0VIUr9T002584@eegah.cvrti.utah.edu>

--===============2454175560488037418==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

This bug report will be sent to the XEmacs Development Team,
 not to your local site managers!!
Please write in English, because the XEmacs maintainers do not have
translators to read other languages for them.


Please describe as succinctly as possible:
	- What happened.
	- What you thought should have happened.
	- Precisely what you were doing at the time.

Please also include any C or lisp back-traces that you may have.
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
Dear Bug Team!

Xemacs crashes when the following file is opened.  I'm sorry I've included
so much of this file but I couldn't create a shorter version that would
cause the crash.  I believe the crash is related to this piece of text
occuring multiplie times:

<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-default-dtd-file:"<top-of-cvs-tree>/doc/Utilities/XML/docbook.ced"
sgml-omittag:nil
sgml-shorttag:nil
End:
-->

This text occurs once at the end of the file for the purpose of configuring
sgml-mode and other times in the text as examples of its usage.

Start of file:

<?xml version=3D"1.0" encoding=3D"UTF-8" ?>

<!--
  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 article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"../Utilities/XML/Docbook_dtd/docbookx.dtd" [
<!ENTITY ltx "LaTeX">
<!ENTITY sr "SCIRun">
<!ENTITY dbk "DocBook">
]>

<article class=3D"techreport">
<title>&sr; Documentum</title>
<subtitle>&sr; Documentation (Explicated)</subtitle>

<articleinfo>
<author>
<firstname>Ted</firstname>
<surname>Dustman</surname>
<affiliation>
<orgname>Scientific Computing and Imaging Institute</orgname>
<address>
<street>50 S. Central Campus Dr.</street>
<city>Salt Lake City</city>
<state>UT</state>
<postcode>84112</postcode>
<email>dustman(a)cvrti.utah.edu</email>
<phone>801-587-9513</phone>
</address>
</affiliation>
</author>
</articleinfo>

<section id=3D"sec.intro">
<title>Introduction</title>

<para>This document is for those who wish to write or build (or
both) &sr; documentation.</para>

<para>It describes:

<itemizedlist>
<listitem>
<para>The organization of the documentation tree.</para>
</listitem>
<listitem>
<para>The types of documents in the tree.</para >
</listitem>
<listitem>
<para>How to build document products from their
sources (and the tools needed to do this).</para>
</listitem>
<listitem>
<para>How to edit documents.</para>
</listitem>
</itemizedlist>

</para>

</section>

<section id=3D"sec.overview">
<title>Doc Tree Organization</title>

<para><xref linkend=3D"tbl.doc-tree"/> 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 a <link linkend=3D"sec.srcsprds">later</link> section.
</para>

<para>

<table id=3D"tbl.doc-tree">
<title>Doc Tree Organization</title>
<tgroup cols=3D"2">
<thead>
<row>
<entry>Directory</entry>
<entry>Description and Important Files</entry>
</row>
</thead>
<tbody>
<row>
<entry><filename>doc</filename></entry>
<entry><para>Root of doc tree.  <filename>Index.rhtml</filename> is the main
cover page for the documentation tree.  This directory's Makefile
initiates the building of the entire doc tree.</para></entry>
</row>
<row>
<entry><filename>doc/Documentum</filename></entry>
<entry><para><quote>Document documentation</quote>.  Document
templates for XHTML and DocBook documents.</para></entry>
</row>
<row>
<entry><filename>doc/Utilities/XML</filename></entry>
<entry>
<para>XSL style files, DTDs and CEDs (precompiled dtds for use with Emacs P=
SGML
mode), and XML related scripts.</para>
</entry>
</row>
<row>
<entry><filename>doc/Utilities/TeX</filename></entry>
<entry>
<para>&ltx; related style files, macros files, and scripts.
</para>
</entry>
</row>
<row>
<entry><filename>doc/Utilities/HTML</filename></entry>
<entry><para>CSS style files, javascript sources, and HTML related
scripts.</para></entry>
</row>
<row>
<entry><filename>doc/Utilities/Figures</filename></entry>
<entry><para>Shared figures (e.g. page header and footer banners).</para></=
entry>
</row>
<row>
<entry><filename>doc/User</filename></entry>
<entry>
<para>User documentation root.  <filename>Index.rhtml</filename> is the
cover page for &sr; user documentation.  This directory's Makefile
initiates the building of the user documentation set.
</para>
</entry>
</row>
<row>
<entry><filename>doc/User/Tutorial</filename></entry>
<entry><para>HTML sources and figures for the &sr; Tutorial</para></entry>
</row>
<row>
<entry><filename>doc/User/Guide</filename></entry>
<entry><para>&ltx; sources for the &sr; users guide.
<filename>Makefile</filename> is responsible for building web and print
versions of the guide.
</para></entry>
</row>
<row>
<entry><filename>doc/User/FAQ</filename></entry>
<entry><para>XML sources for the user FAQ.</para></entry>
</row>
<row>
<entry><filename>doc/Developer/</filename></entry>
<entry>
<para>
Developer documentation root. <filename>Index.rhtml</filename> is the cover
page for &sr; developer documentation.  This directory's Makefile
initiates the building of the developer documentation set.
</para>
</entry>
</row>
<row>
<entry><filename>doc/Developer/Guide</filename></entry>
<entry>
<para>XML and HTML sources for the &sr; developers
guide.  <filename>Makefile</filename> builds the HTML version of the
guide.</para>
</entry>
</row>
<row>
<entry><filename>doc/Developer/FAQ</filename></entry>
<entry>
<para>XML sources for developer FAQ.</para>
</entry>
</row>
<row>
<entry><filename>doc/Developer/CodeViews</filename></entry>
<entry>
<para>Tools (Makefile, configuration file, and script) for building source
code (C++) based documentation using Doxygen.
</para>
</entry>
</row>
<row>
<entry><filename>doc/Developer/Modules</filename></entry>
<entry>
<para>
<filename>Makefile</filename> builds HTML versions of the module
descriptions.  <filename>Index.rhtml</filename> is cover page for module
descriptions. Note that module descriptionn sources live in the
<filename>XML</filename> and <filename>TeX</filename> directories on the
<filename>src</filename> side of the tree.
</para>
</entry>
</row>
<row>
<entry><filename>doc/Installation/</filename></entry>
<entry>
<para>Installation documentation root.  <filename>Makefile</filename>
invokes sub-makes.  <filename>Index.rhtml</filename> is the cover page for
&sr; installation documentation.</para>
</entry>
</row>

<row>
<entry><filename>doc/Installation/Guide</filename></entry>
<entry>
<para>XML sources for installation guide and
<filename>Makefile</filename> for generating the guide.</para>
</entry>
</row>
<row>
<entry><filename>doc/Installation/FAQ</filename></entry>
<entry>
<para>XML sources for installation FAQ.</para>
</entry>
</row>
<row>
<entry><filename>doc/FAQBook</filename></entry>
<entry>
<para>XML source (<filename>faqbook.xml</filename>) for the &sr; FAQ book
(it merely assembles FAQ sources into book form).</para>
<para><filename>Makefile</filename> generates the FAQ book.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>

</para>

</section>

<section id=3D"sec.builddocs">
<title>Building Docs</title>

<para>&sr; documents are written in number of <firstterm><link
linkend=3D"sec.docmls">markup</link></firstterm> languages: XML, &ltx;,
and HTML (plus their <firstterm>eruby</firstterm>
equivalents&mdash;see <xref endterm=3D"sec.docmls.title"
linkend=3D"sec.docmls"/> for more information).  XML and &ltx; document
sources must be <quote>built</quote> or transformed into other forms
(e.g. HTML) for presentation.  This section shows how to invoke the
build system.</para>

<para>This section assumes that all necessary
<link linkend=3D"sec.tools">tools</link> have been installed.</para>

<para>Three environment variables must be set before building
the documentation:
<simplelist>
<member><envar>CLASSPATH</envar> must contain the path of the
file <filename>saxon.jar</filename> within the Saxon distribution.
</member>
<member><envar>STYLESHEET_PATH</envar> must point to the location of the
<filename>html</filename> directory within the &dbk; stylesheet
distribution.
</member>
<member>
<envar>WITH_CV</envar> should be set to the string <quote>true</quote>
if you want Doxygen to build the C++ based documentation.
</member>
</simplelist>
For instance (assuming a Bourne type shell):
<programlisting>
export CLASSPATH=3D/usr/local/lib/Saxon/saxon.jar
export STYLESHEET_PATH=3D/usr/local/xsl/docbook/html/
export WITH_CV=3Dtrue
</programlisting>

</para>

<para>Now to make (all) docs <command>cd</command> to the toplevel
<filename>doc</filename> directory and type <command>make</command>.
</para>

<para>To also make a doc tarball type this:
<programlisting>
cd doc                  # cd to topleve doc directory
make tarball
</programlisting>
</para>

<para>You may want to build one particular doc or a particular set of docs.
You can do =

so by <command>cd</command>'ing to the directory of interest and typing
<command>make</command>.  For example:
<programlisting>
cd doc/Developer        # Make all developer docs.
make
</programlisting> or
<programlisting>
cd doc/Developer/Guide  # Make just the developer's guide.
make
</programlisting>
</para>

<para>To remove <quote>incidental</quote> files (but
no products) from a directory (and its sub-directories) type:
<programlisting>make clean</programlisting> =

</para>

<para>To also remove products (generated files) type:
<programlisting>make veryclean</programlisting>
</para>
</section>

<section id=3D"sec.srcsprds">
<title>Sources, Makefiles, and Products</title>

<para>The term <firstterm>sources</firstterm> refers to
files that are created and edited manually.  The term
<firstterm>products</firstterm> refers to files that are generated from sou=
rces by a
tool of some sort.  Sources are always part of the CVS repository and
products never are.</para>

<para>
Makefiles are responsible for generating products from sources.
<xref linkend=3D"tbl.srcprd"/> shows sources, corresponding Makefiles, and
the products they generate.  Products that are not explicit targets of
<filename>Makefile</filename> are not shown.</para>

<para>The doc tree uses a conventional recursive makefile =

approach to building documentation.  Some Makefiles generate products (see
<xref linkend=3D"tbl.srcprd"/>) while others
(<filename>doc/Developer/Makefile</filename>,
<filename>doc/Installation/Makefile</filename>,
<filename>doc/User/Makefile</filename>) merely invoke sub-make processes.
The topmost Makefile (<filename>doc/Makefile</filename> initiates the build
of the entire documentation set.  Its other important function is to make
a documentation tarball</para>

<para>The doc tree and its build system were designed so that anyone with
the proper <link linkend=3D"sec.tools">tools</link> can build documentation.
This facilitates the edit/compile/test/debug cycle.  The doc developer need
not wait for the doc tree to be published on the internal web site before
discovering bugs and errors.  The doc developer can edit sources, invoke
make to build products, test and debug the docs with his web browser, and
correct problems all before committing his changes to the CVS
repository.</para>

<para>Note that Makefiles are written in the GNU make dialect.</para>

<para>Below you will notice files with extensions
<filename>.rxml</filename>, <filename>.rhtml</filename>, and
<filename>.rtex</filename>.  These are <firstterm>eruby</firstterm>
sources.  Information on these type of files can be found in <xref
endterm=3D"sec.docmls.title" linkend=3D"sec.docmls"/>.</para>

<para>
<table id=3D"tbl.srcprd">
<title>Sources, Makefiles, and Products</title>
<tgroup cols=3D"3">
<thead>
<row>
<entry>Source(s)</entry>
<entry>Makefile</entry>
<entry>Product(s)</entry>
</row>
</thead>
<tbody>
<row>
<entry><para><filename>doc/index.rhtml</filename></para></entry>
<entry><para><filename>doc/Makefile</filename></para></entry>
<entry><para><filename>doc/index.html</filename></para></entry>
</row>
<row>
<entry><para><filename>doc/Developer/index.rhtml</filename></para></entry>
<entry><para><filename>doc/Developer/Makefile</filename></para></entry>
<entry><para><filename>doc/Developer/index.html</filename></para></entry>
</row>
<row>
<entry><para>C++ sources in the src side of the tree</para></entry>
<entry><para><filename>doc/Developer/CodeViews/Makefile</filename></para></=
entry>
<entry><para><filename>doc/Developer/CodeViews/html/*.html</filename></para=
></entry>
</row>
<row>
<entry>
<para><filename>doc/Developer/Guide/main.rxml</filename>,
<filename>doc/Developer/Guide/dev/*.xml</filename>, and
<filename>doc/Developer/Guide/src/*.xml</filename></para>
</entry>
<entry><para><filename>doc/Developer/Guide/Makefile</filename></para></entr=
y>
<entry><para><filename>doc/Developer/Guide/*.html</filename></para></entry>
</row>
<row>
<entry>
<para><filename>src/Dataflow/XML/*.xml</filename> and
<filename>src/Packages/*/Dataflow/XML/*.xml</filename></para>
</entry>
<entry><para><filename>doc/Developer/Modules/Makefile</filename></para></en=
try>
<entry>
<para><filename>src/Dataflow/XML/*.html</filename> and
<filename>src/Packages/*/Dataflow/XML/*.html</filename></para>
</entry>
</row>
<row>
<entry><para><filename>doc/FAQBook/faqbook.xml</filename>,
<filename>doc/Developer/FAQ/faq.xml</filename>,
<filename>doc/Installation/FAQ/faq.xml</filename>, and
<filename>doc/User/FAQ/faq.xml</filename></para></entry> =

<entry><para><filename>doc/FAQBook/Makefile</filename></para></entry>
<entry><para><filename>doc/FAQBook/*.html</filename></para></entry>
</row>
<row>
<entry><para><filename>doc/Installation/index.rhtml</filename></para></entr=
y>
<entry><para><filename>doc/Installation/Makefile</filename></para></entry>
<entry><para><filename>doc/Installation/index.html</filename></para></entry>
</row>
<row>
<entry><para><filename>doc/Installation/Guide/*.[r]xml</filename></para></e=
ntry>
<entry><para><filename>doc/Installation/Guide/Makefile</filename></para></e=
ntry>
<entry><para><filename>doc/Installation/Guide/*.html</filename></para></ent=
ry>
</row>
<row>
<entry><para><filename>doc/User/index.rhtml</filename></para></entry>
<entry><para><filename>doc/User/Makefile</filename></para></entry>
<entry><para><filename>doc/User/index.html</filename></para></entry>
</row>
<row>
<entry>
<para><filename>doc/User/Guide/*.[r]tex</filename>,
<filename>src/Dataflow/XML/*.xml</filename>,
<filename>src/Dataflow/Modules/*/doc/*.jpg</filename>,
<filename>src/Dataflow/Modules/*/doc/*.gif</filename>,
<filename>src/Dataflow/TeX/*/*.tex</filename>,
<filename>src/Dataflow/TeX/*/*.jpg</filename>,
<filename>src/Dataflow/TeX/*/*.gif</filename>,
<filename>src/Packages/*/Dataflow/XML/*.xml</filename>,
<filename>src/Packages/*/Dataflow/Modules/*/doc/*.jpg</filename>,
<filename>src/Packages/*/Dataflow/Modules/*/doc/*.gif</filename>,
<filename>src/Packages/*/Dataflow/TeX/*.tex</filename>,
<filename>src/Packages/*/Dataflow/TeX/*/*.jpg</filename>,
<filename>src/Packages/*/Dataflow/TeX/*/*.gif</filename>.</para>
</entry>
<entry><para><filename>doc/User/Guide/Makefile</filename></para></entry>
<entry>
<para>
<filename>doc/User/Guide/usersguide.ps</filename> and
<filename>doc/User/Guide/usersguide/</filename>.  =

</para> =

<para>Intermediate products
<filename>doc/User/Guide/userguide.dvi</filename>, <filename>*_modules.tex<=
/filename> and
<filename>srugmacros.sty</filename> are generated.
</para>
<para>EPS files on
the <filename>src</filename> side of the tree generated from JPEG
and GIF files.</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>

</section>


<section id=3D"sec.docmls">
<title id=3D"sec.docmls.title">Documents and Their Markup Languages</title> =


<para>Each document is composed in one (or more) of the following markup
languages (ML): =

<itemizedlist>
<listitem>
<para><ulink url=3D"http://www.latex.org">&ltx;</ulink></para></listitem>
<listitem>
<para><ulink
url=3D"http://docbook.org/tdg/en/html/docbook.html">&dbk;</ulink></para></l=
istitem>
<listitem>
<para>The (home grown) Component (or module) ML</para></listitem>
<listitem>
<para>The (home grown) FAQ ML</para></listitem>
<listitem>
<para>HTML</para></listitem>
</itemizedlist>
<xref linkend=3D"tbl.mls"/> provides document specific details.
</para>

<para>A number of &dbk;, HTML, and &ltx; source documents contain
snippets of Ruby code.  These <quote>eruby</quote> (embedded ruby)
source documents may be identified by their extensions:
<filename>.rxml</filename> for &dbk; (or other XML) sources,
<filename>.rhtml</filename> for HTML sources, and
<filename>.rtex</filename> for &ltx; documents.  Products
(<filename>.xml</filename>, <filename>.html</filename>, and
<filename>.tex</filename> files) are generated by replacing the code
snippets with the results of their execution&mdash;the eruby tool
executes this code and performs the replacement.  <note> <para>Be sure
to edit the eruby version of a document (if it exists) rather than its
product equivalent.</para></note></para>

<para>

<table id=3D"tbl.mls">
<title>Document Types</title>
<tgroup cols=3D"2">
<thead>
<row>
<entry>Document(s)</entry>
<entry>ML(s)</entry>
</row>
</thead>
<tbody>
<row>
<entry>Developer Guide</entry>
<entry>&dbk; and HTML</entry>
</row>
<row>
<entry>FAQs</entry>
<entry>&sr; FAQ ML</entry>
</row>
<row>
<entry>Installation Guide</entry>
<entry>&dbk;</entry>
</row>
<row>
<entry>Module Descriptions</entry>
<entry>&sr; Component (or Module) ML and &ltx;</entry>
</row>
<row>
<entry>Tutorial</entry>
<entry>HTML</entry>
</row>
<row>
<entry>Users Guide</entry>
<entry>&ltx;</entry>
</row>
<row>
<entry>"Cover Pages" (index.html files)</entry>
<entry>HTML</entry>
</row>
</tbody>
</tgroup>
</table>
</para>

<para>Later sections provide information on editing these documents.</para>

<para>The Component (or module) and FAQ markup languages were developed by
SCI.  The former is defined by its DTD which is in the file
<filename>doc/Utilities/XML/component.dtd</filename>. The latter is defined
by its DTD - <filename>doc/Utilities/XML/faq.dtd</filename>.</para>

<para>This document (the one you are reading) is composed in the &dbk;
ML.</para>


</section>

<section>
<title>Documents and Their CSS Stylesheets</title>

<para>
<xref linkend=3D"cssusage"/> shows CSS stylesheets and the documents
that use them.  Stylesheets can be found in
<filename>doc/Utilities/HTML</filename>
</para>

<para>
<table id=3D"cssusage">
<title id=3D"cssusagetitle">Stylesheet Usage</title>
<tgroup cols=3D"2">
<thead>
<row>
<entry>Stylesheet</entry>
<entry>Document(s)</entry>
</row>
</thead>
<tbody>
<row>
<entry><filename>srdocbook.css</filename></entry>
<entry>Docbook Documents</entry>
</row>
<row>
<entry><filename>srlatex2html.css</filename></entry>
<entry>Latex Documents</entry>
</row>
<row>
<entry><filename>mainindex.css</filename></entry>
<entry>doc/index.html</entry>
</row>
<row>
<entry><filename>subindex.css</filename></entry>
<entry>Second level index files (e.g. <filename>doc/User/index.html</filena=
me>)</entry>
</row>
<row>
<entry><filename>pkgindex.css</filename></entry>
<entry><filename>doc/Developer/Modules/index.html</filename></entry>
</row>
<row>
<entry><filename>moduleindex.css</filename></entry>
<entry><filename>doc/Developer/Modules/SCIRun.html</filename>,
etc. (i.e. HTML files generated by the program
<filename>doc/Utilities/HTML/makepkgindex.rb)</filename></entry>
</row>
<row>
<entry><filename>faq.css</filename></entry>
<entry>FAQ documents.</entry>
</row>
<row>
<entry><filename>component.css</filename></entry> <entry>Module
descriptions generated by
<filename>doc/Utilities/XML/component.xsl</filename>.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>

<para><quote>Why so many bloody style sheets?</quote> you may
ask. Because its too bloody hard to write, debug, and maintain a
one-size-fits-all stylesheet!</para>

<note>
<title>A Philosophical Note</title> =


<para>My personal philosophy is to:
<itemizedlist>
<listitem>
<para>Avoid writing a "one-size-fits-all" stylesheet.  Doing so
creates a large stylesheet (filled with lots of classes) which is hard
to understand and debug and which makes writing documents more
difficult.</para>
</listitem>
<listitem>
<para>Associate 1 stylesheet per  document class&mdash;which is why there a=
re
so many stylesheets above.</para>
</listitem>
<listitem>
<para>Write XHTML/HTML documents
using no presentational markup nor using the inline
<literal>style</literal> attribute (although I sometimes use the<sgmltag
class=3D"starttag">style</sgmltag> element).</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
</itemizedlist>
</para>
</note>
</section>

<section>
<title>Editing Documents</title>

<section id=3D"sec.xmlmode">
<title>Editing XML Documents</title>
<para>This section discusses the use of emacs to edit XML documents.</para>
<para>
An ordinary text editor may be used to edit XML document content.  However,
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 you
construct valid XML documents.
</para>

<para>Emacs is one such editor.  It supports an editing environment called
XML mode (which is really 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, though, to create invalid documents using
Emacs XML mode.
</para>

<para>Emacs XML mode can be used to edit XML based module descriptions,
XHTML documents, &dbk; documents, and any XML based language which is
described by a DTD.</para>

<para>
Recent versions of Emacs come with XML mode installed.  You can check
if yours does by typing <userinput>M-x xml-mode</userinput>.  You don't have
XML mode if you get the message
<screen>[No match]</screen> in return.
If you don't have XML mode you may get it
<ulink url=3D"http://www.lysator.liu.se/~lenst/about_psgml/psgml.html">onli=
ne</ulink>.
</para>

<section id=3D"sec.dotemacs">
<title>Emacs Initialization (.emacs)</title>
<para>The following lisp code should be inserted into your <filename>.emacs=
</filename>
file:
<programlisting>
<![CDATA[
; 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))) =

]]>
</programlisting>
</para>
</section>

<section id=3D"sec.createxmldoc">
<title>Creating an XML Document </title>
<para>
To start a new XML document do this:
<itemizedlist>
<listitem>
<para>Create a new file (<userinput>C-x C-f</userinput>) with a suffix of <=
filename>.xml</filename></para>
</listitem>
<listitem>
<para>Insert a preamble. The following is a preamble for a  &dbk; document:
<programlisting>
<![CDATA[
<?xml version=3D"1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD &dbk; XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">
]]>
</programlisting>
</para>
</listitem>
<listitem>
<para>Insert the following XML comment at the bottom of the file.
<programlisting>
<![CDATA[
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-default-dtd-file:"<top-of-cvs-tree>/doc/Utilities/XML/docbook.ced"
sgml-omittag:nil
sgml-shorttag:nil
End:
-->
]]>
</programlisting>
Where <quote>&lt;top-of-cvs-tree&gt;</quote> is a relative path from your
document to the root of your &sr; CVS tree.
</para>
<para>Note that the file <filename>docbook.ced</filename> is a precompiled
DTD for the docbook language.  You will find a 2 other
<filename>.ced</filename> files in <filename>doc/Utilities/XML/</filename>.
These are <filename>component.ced</filename>, for module descriptions, and
<filename>xhtml1-transitional.ced</filename> for XHTML.</para>
</listitem>
<listitem>
<para>
Save your file, close it, and re-open it.  Now you may begin editing your
file using xml mode.
</para>
</listitem>
</itemizedlist>
</para>
</section>

<section>
<title>XML-Mode Survival</title>
<para>This section presents a few of the most important XML-mode editing
commands.  See the =

<ulink url=3D"http://www.lysator.liu.se/~lenst/about_psgml/psgml.html">onli=
ne
manual</ulink> =

for complete documentation.  Note that the remainder of this section has be=
en
lifted from =

<ulink url=3D"http://www.lysator.liu.se/~lenst/about_psgml/psgml.html#Edit"=
>this section</ulink> of the  online manual.

<variablelist>
<varlistentry>
<term><userinput>C-c &lt;</userinput></term>
<listitem>
<para>Will ask, for the tag to insert, in the mini-buffer with completion
on the tags that are valid at point (sgml-insert-tag).</para> <para>If
sgml-auto-insert-required-elements is non-nil, tags for elements required
between the inserted tags will also be inserted.
</para>
<para>The list of valid tags, computed for a position in the buffer, will
contain:
<orderedlist>
<listitem>
<para>The end-tag for the current element, if it can be ended at the
position. Furthermore it will contain end-tags for enclosing elements if
the necessary omissible end-tag declarations have been made in the DTD.
</para>
</listitem>
<listitem>
<para>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.</para> </listitem></orderedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><userinput>C-c C-e</userinput></term>
<listitem>
<para>Insert 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 will be inserted on a new line after the
start-tag.
</para>
<para>If sgml-omittag-transparent is nil, the list of valid elements will
only contain the elements that can be in the content of the current
element.</para> <para>Required elements in the content will be
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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><userinput>C-c C-i</userinput></term>
<listitem>
<para>Inserts 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 somewhere,
without making the content invalid. This assumes that the content is valid
to begin with. Currently this list only has regular elements, not
inclusions. The new element will be inserted as late as possible in the
current element (unless prefix argument is given, then as early as
possible.)  </para></listitem>
</varlistentry>
<varlistentry>
<term><userinput>C-c C-r</userinput></term>
<listitem>
<para>Makes the region into a new element (sgml-tag-region). Reads element
name from mini-buffer with completion as for C-c C-e.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><userinput>C-c /</userinput></term>
<listitem>
<para>Inserts an end-tag for the current element (sgml-insert-end-tag).</pa=
ra>
</listitem>
</varlistentry>
<varlistentry>
<term><userinput>C-c RET</userinput></term>
<listitem>
<para>Split the current element at point. If repeated, the containing
element will be split before the beginning of then current element.</para>
<para>Typical use is to start a new paragraph element when inside a
paragraph.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><userinput>C-c +</userinput></term>
<listitem>
<para>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
will operate on the element after point.
</para>
<para>The attribute name will be read with completion. If the attribute has=
 a
token list as declared value the attribute value will also be read with
completion. The prompt for attribute value will typically look like:</para>
<screen>Value for attribute (type Default: current value):</screen>
</listitem>
</varlistentry>
</variablelist>
</para> =

</section>

<section id=3D"charent">
<title id=3D"charenttitle">Charater Literals&mdash;Do's and Dont's</title>

<para>Some characters or character combinations should not be used
literally.  This is because they will not be typeset in an optimal
way.  Here is a list of things to watch for:
<variablelist>
<varlistentry>
<term>Quotations</term>
<listitem>
<para>Enclose quotations in the <sgmltag
class=3D"element">quote</sgmltag> element.</para>

<para>Rather than typing, say, "He said
thus and such", type <sgmltag class=3D"starttag">quote</sgmltag>He said
thus and such<sgmltag class=3D"endtag">quote</sgmltag>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Horizontal Ellipsis</term>
<listitem>
<para>Use <sgmltag class=3D"genentity">hellip</sgmltag> to produce
ellipsis.</para> =


<para>Rather than typing:
<literallayout> =

<![CDATA[
<quote>He said thus and such and ...</quote>
]]>
</literallayout>
type:
<![CDATA[
<quote>He said thus and such and &hellip;</quote>
]]>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Vertical Ellipsis</term>
<listitem>
<para>Use <sgmltag class=3D"genentity">vellip</sgmltag> to produce
ellipsis.</para> =


<para>Type:
<literallayout>
<![CDATA[
<para>
&vellip;
Above me and below me there is stuff.
&vellip;
</para>
]]>
</literallayout>
rather than:
<literallayout>
<![CDATA[
<para>
.
.
.
Above me and below me there is stuff.
.
.
.
</para>
]]>
</literallayout>
</para>

</listitem>
</varlistentry>
<varlistentry>
<term>En Dash</term>
<listitem>
<para>Use <sgmltag class=3D"genentity">ndash</sgmltag> to produce an en
dash.</para> =


<para>Type <quote>1<sgmltag
class=3D"genentity">ndash</sgmltag>10</quote> rather than
<quote>1-10</quote></para>
</listitem>
</varlistentry>
<varlistentry>
<term>Em Dash</term>
<listitem>
<para>Use <sgmltag class=3D"genentity">mdash</sgmltag> to produce an em
dash.</para> =


<para>Type <quote>You stink!<sgmltag
class=3D"genentity">mdash</sgmltag>Well, a little bit anyway</quote> rather=
 than
<quote>You stink!---Well, a little bit anyway.</quote></para>
</listitem>
</varlistentry>
</variablelist>
</para>

</section>

</section>

<section id=3D"sec.editdocbkdocs">
<title>Editing &dbk; Documents</title> <para>&dbk; is an XML based
language for composing techical documents.  Especially documents about
computer software.  The <citetitle>Installation Guide</citetitle>,
<citetitle>Developers Guide</citetitle>, and this document are
composed in the &dbk; language.</para>

<para>It is beyond the scope of this article to introduce the &dbk;
language in any detail.  Please read the <ulink
url=3D"http://docbook.org/tdg/en/html/docbook.html">online &dbk;
guide</ulink> for an introduction to &dbk;.  It also provides a complete
reference to all &dbk;'s elements and attributes.  =

</para>

<para>You may want to peruse this document's XML source to get a feel for
the &dbk; language.  It is the file
<filename>doc/Documentum/documentum.xml</filename>
</para>

<section>
<title>Single File Document</title>

<para>&dbk; documents may be contained in one file or may be segmented into
several files.  A multi-file document will consist of a
<firstterm>main</firstterm> file and one or more additional file.</para>

<para>
A new single file document will look like this:
<programlisting>
<![CDATA[
<?xml version=3D"1.0" encoding=3D"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:
-->
]]>
</programlisting>
Where <quote>root-element</quote> should be replaced by your document's root
element, usually <sgmltag>book</sgmltag> or <sgmltag>article</sgmltag>.  And
the path to <filename>docbook.ced</filename> should be altered appropriatel=
y.
</para>

</section>

<section>
<title>Multi-file Document</title>

<para>A multi-file document will consist of a main file which usually does
nothing more than <quote>include</quote> other files.  Here is the main
file for a book consisting of five chapters:
<programlisting>
<![CDATA[
<?xml version=3D"1.0"? encoding=3D"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=3D"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:
-->
]]>
</programlisting>
And <filename>chap1.xml</filename> would look like this:
<programlisting>
<![CDATA[
<!--
  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:
-->
]]>
</programlisting>
</para>

</section>

</section>

<section id=3D"sec.editfaqdocs">
<title>Editing FAQ Documents</title>
<para>There are currently three FAQs:
<simplelist>
<member>Installation FAQ - <filename>doc/Installation/FAQ/faq.rxml</filenam=
e></member>
<member>User FAQ - <filename>doc/User/FAQ/faq.rxml</filename></member>
<member>Developer FAQ - <filename>doc/Developer/FAQ/faq.rxml</filename></me=
mber>
</simplelist>
</para>
<para>To add a new entry to one of these FAQs (using emacs/xemacs XML mode)
do this:
<orderedlist>
<listitem>
<para>Open the appropriate file with emacs/xemacs (recommended)</para>
</listitem>
<listitem>
<para>Move point to just before the first
<sgmltag>qandaentry</sgmltag> element or just after the last
<sgmltag>qandaentry</sgmltag> element.</para>
</listitem>
<listitem>
<para>
Insert the following template at point: =

<programlisting>
<![CDATA[
<qandaentry>
<revhistory>
<revision>
<revnumber></revnumber>
<date></date>
</revision>
</revhistory>
<question>
<para>
</para>
</question>
<answer>
<para>
</para>
</answer>
</qandaentry>
]]>
</programlisting>
Fill out the template (using additional DocBook markup if necessary).
</para>
</listitem>
</orderedlist>
</para>
</section>

<section id=3D"sec.editxmlmoddocs">
<title>Editing XML Module Descriptions</title>
<para>See <ulink url=3D"module-xml/index.html"><citetitle>XML Module
Descriptions (Explicated)</citetitle></ulink> for information on
creating/editing XML based module descriptions.</para>
</section>

<section id=3D"sec.editltxmoddocs">
<title>Editing &ltx; Module Descriptions</title>
<para>See <ulink url=3D"module-latex/index.html"><citetitle>Latex Module
Descriptions (Explicated)</citetitle></ulink> for information on
creating/editing &ltx; based module descriptions.</para>
</section>

<section id=3D"sec.edithtmldocs">
<title>Editing HTML and XHTML Documents</title> =

<para>First of all you
should try to avoid HTML/XHTML altogether.  Try using a higher-level markup
language like &dbk; or &ltx;.</para> =

<para>Secondly, if you must use HTML
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
we should be implementing our HTML-type documents using XHTML.  The
following rules for composing XHTML (and HTML) documents should be
followed:
<itemizedlist>
<listitem>
<para>Use Emacs XML mode for composing XHTML documents.</para>
</listitem>
<listitem>
<para>Write tag and attribute names in lower case.</para>
</listitem>
<listitem>
<para>Enclose attribute values in quotes
(e.g. <userinput>id=3D"sec.edithtmldocs"</userinput>)</para>
</listitem>
<listitem>
<para>Close all elements..  I.e. never omit end tags.  Empty
elements should be closed by either an end tag or by ending the start tag
with <userinput>/&gt;</userinput>, e.g. the horizontal rule element should
be written as <userinput>&lt;hr/&gt;</userinput></para>
</listitem>
<listitem>
<para>Nest elements properly.</para>
</listitem>
<listitem>
<para>&hellip; and in general try to produce valid XHTML/HTML
documents.</para>
</listitem>
<listitem>
<para>Mind your character entities (see <xref endterm=3D"charenttitle"
linkend=3D"charent"/>).</para>
</listitem>
<listitem>
<para>Avoid presentational markup (e.g. <sgmltag
class=3D"starttag">font</sgmltag> elements) &mdash;Use external CSS stylesh=
eets
or the <sgmltag class=3D"starttag">style</sgmltag> element (but avoid
the inline <literal>style</literal> attribute) instead.</para>
</listitem>
</itemizedlist>
These rules are explained more fully on the <ulink
url=3D"http://www.w3schools.com/xhtml/xhtml_html.asp">W3Schools.com</ulink>
web site. </para>

<para>Documents which live in the <filename>doc</filename> side of the tree
should be derived from
<filename>doc/Documentum/doc_template.html</filename> and those that live
in the <filename>src</filename> side of the tree should be based on
<filename>doc/Documentum/src_template.html</filename>.</para>
</section>

<section id=3D"sec.editltxdocs">
<title>Editing &ltx; Documents</title>
<para>&vellip;</para>
<para>Some day I need to put something here.</para>
<para>&vellip;</para>
 </section>

</section>

<section>
<title>Publishing to SCI Web Sites</title>

<para>&sr; documentation is published to 3 SCI web sites.  Each web site
serves a different purpose.</para>

<para>Documentation under development is
published on the <ulink
url=3D"http://internal.sci.utah.edu/developer/SCIRun/doc">internal</ulink>
site.
Documentation being tested for release is published on the
<ulink url=3D"http://software2.sci.utah.edu/doc">test</ulink> site.
Documentation for the current &sr; release is published on the
<ulink url=3D"http://software.sci.utah.edu/doc">external</ulink>
site.
</para>

<para>The following sections describe (approximately) how to publish
documentation to these sites.</para>

<section>
<title>Publishing to SCI's Internal Web Site</title>
<para>&sr; documentation which is under development (from the
trunk of the CVS tree) is published on
SCI's internal web site.  To publish docs on the internal web site do
this:
<orderedlist>
<listitem>
<para>Update your &sr; CVS tree.</para>
</listitem>
<listitem>
<para>Build the docs and create a doc tarball.</para>
</listitem>
<listitem>
<para>Copy the tarball to
<filename>/usr/sci/projects/SCIRun/docs</filename> and unpack it using
GNU tar (<command>tar zxf &lt;tarball&gt;</command>).</para>
</listitem>
<listitem>
<para><command>Cd</command> to
<filename>/usr/sci/projects/SCIRun/docs</filename> and remove the
<filename>doc</filename> and <filename>src</filename> directories if
they exist.</para>
</listitem>
<listitem>
<para>Move the <filename>doc</filename> and <filename>src</filename>
directories from inside the directory created by unpacking the tarball
to <filename>/usr/sci/projects/SCIRun/docs</filename>.</para>
</listitem>
</orderedlist>
</para>
</section>

<section>
<title>Publishing to SCI's Test Web Site</title> =


<para>SCI's test web
site is <filename>http://software2.sci.utah.edu</filename>.  Use this
site to test documentation (from the release branch of the CVS tree)
prior to a software release.</para> =


<para>To publish the docs on SCI's external web site do this:
<orderedlist>
<listitem>
<para>Build a doc tarball from the sources on the release branch.
Rename the tarball to reflect its release number,
e.g. <filename>SCIRunDocs-1.6.1.tar.gz</filename>.</para> =

</listitem>
<listitem>
<para>Copy the doc tarball to the directory
<filename>/w01/docs/scirun-biopse</filename> on
<filename>dante.sci.utah.edu</filename>.</para>
</listitem>
<listitem>
<para>Unpack the tarball using GNU tar.</para>
</listitem>
<listitem>
<para>Rename the resulting directory to match the name of the tarball,
e.g. <filename>SCIRunDocs-1.6.1</filename>.</para>
</listitem>
<listitem>
<para><command>cd</command> to
<filename>/w01/sciweb/software</filename>.</para>
</listitem>
<listitem>
<para>Remove the symbolic links <filename>doc</filename> and <filename>src<=
/filename>.</para>
</listitem>
<listitem>
<para>Create new symbolic links.  The <filename>doc</filename> link
should point to
<filename>../../docs/scirun-biopse/&lt;doc-directory&gt;/doc</filename>
and the <filename>src</filename> link should point to
<filename>../../docs/scirun-biopse/&lt;doc-directory&gt;/src</filename>
where <filename>&lt;doc-directory&gt;</filename> is the name of
directory created (and renamed) previously.  For example:</para>
<literallayout class=3D"monospaced">
ln -s ../../docs/scirun-biopse/1.6.1/doc doc
ln -s ../../docs/scirun-biopse/1.6.1/src src
</literallayout>
</listitem>
</orderedlist>
</para>

</section>

<section>
<title>Publishing to SCI's External Web Site.</title>

<para>&sr; documentation for the current &sr; release (from the
current release branch of the CVS tree) is published to the external
web site.</para>

<para>To publish the docs on SCI's external web site do this:
<orderedlist>
<listitem>
<para>Build a doc tarball from the sources on the release branch.
Rename the tarball to as follows:
<filename>docs-<replaceable>d.d.d</replaceable>.tar.gz</filename>,
where <replaceable>d.d.d</replaceable> is the documentation version
number.</para>
</listitem>
<listitem>
<para>Copy the doc tarball to the directory
<filename>/w01/docs/scirun-biopse/present</filename> on
<filename>virgil.sci.utah.edu</filename>.</para>
</listitem>
<listitem>
<para>Unpack the tarball using GNU tar.</para>
</listitem>
<listitem>
<para>The resulting directory will contain <filename>doc</filename>
and <filename>src</filename> sub-directories.  Move these
sub-directories up one level.  Remove the =

</listitem>
<listitem>
<para><command>Cd</command> to
<filename>/w01/sciweb/software</filename>.</para>
</listitem>
<listitem>
<para>Remove the symbolic links <filename>doc</filename> and <filename>src<=
/filename>.</para>
</listitem>
<listitem>
<para>Create new symbolic links.  The <filename>doc</filename> link
should point to
<filename>../../docs/scirun-biopse/present/doc</filename>
and the <filename>src</filename> link should point to
<filename>../../docs/scirun-biopse/present/src</filename>
For
example:</para>
<literallayout class=3D"monospaced">
ln -s ../../docs/scirun-biopse/1.8.1/doc doc
ln -s ../../docs/scirun-biopse/1.8.1/src src
</literallayout>
</listitem>
</orderedlist>
</para>

</section>

</section>

<section id=3D"sec.tools">
<title>Tools</title>

<para>
The following tools are
needed to build &sr; documentation:
<variablelist>
<varlistentry>
<term><ulink url=3D"http://www.gnu.org/software/make/make.html">GNU
Make</ulink> (3.79 or later)</term>
<listitem>
<para>GNU's version of the make utility.  Makefiles in the doc tree are
incompatible with other versions of the make utility.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url=3D"http://www.gnu.org/software/tar/tar.html">GNU
Tar</ulink> (1.12 or later)</term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Java (1.3 or later)</term>
<listitem>
<para>Saxon (see below) requires the Java runtime system and libraries.</pa=
ra>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url=3D"http://saxon.sourceforge.net/">Saxon</ulink> (6.5.2 or =
later)</term>
<listitem>
<para>Saxon is an XSLT processor which 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 FAQ book, and the XML based module descriptions to HTML and &ltx=
;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url=3D"http://www.latex-project.org/">&ltx;</ulink></term>
<listitem>
<para>&ltx; is a document markup language and typesetting system.  The Users
guide and some module descriptions require &ltx;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url=3D"http://www.latex2html.org">Latex2html</ulink></term>
<listitem>
<para>The latex2html tool translates &ltx; documents to HTML.  It is used to
translate the Users guide and latex module descriptions to HTML.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url=3D"http://www.stack.nl/~dimitri/doxygen/">Doxygen</ulink><=
/term>
<listitem>
<para>Doxygen is a documentation system for C++.  It both generates and ext=
racts
documentation from C++ source files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url=3D"http://docbook.sourceforge.net/">&dbk; Style
Sheets</ulink> (1.51.1)</term>
<listitem>
<para>The &dbk; stylesheets translate &dbk; XML documents (Developers
guide and Installation guide) to HTML.</para> =

<para>There are 3 &sr;
specific stylesheets that must be copied into the &dbk; distribution. The
files <filename>doc/Utilities/XML/srdocbook.xsl</filename>,
<filename>doc/Utilities/XML/srdocbook-common.xsl</filename>, and
<filename>doc/Utilities/XML/srdocbook-chunk.xsl</filename> must be copied
to the <filename>html</filename> directory of the &dbk;
distribution.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url=3D"http://www.pragmaticprogrammer.com/ruby/">Ruby</ulink> =
(1.6
or later)</term>
<listitem>
<para>A number of scripts in the doc tree are written in the programming la=
nguage Ruby.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ERuby (a modified version of eruby 0.9.8)</term>
<listitem>
<para>A number of XML, HTML, and &ltx; 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.  <ulink
url=3D"mailto:dustman(a)cvrti.utah.edu">Contact me</ulink> to get the
sources. More information on these type of files can be found in <xref
endterm=3D"sec.docmls.title" linkend=3D"sec.docmls"/></para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url=3D"http://www.imagemagick.org">ImageMagick</ulink></term>
<listitem>
<para>From the ImageMagick <filename>README</filename> file: ImageMagick
<quote>...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...</quote></para> =

<para>The <command>convert</command> utility from the ImageMagick package
is being used to translate jpg and gif files to eps for use in the
printable version of the users guide.</para>
</listitem>

</varlistentry>
</variablelist>
</para>

</section>

<section id=3D"to-do">
<title>To Do</title>
<para>The following sections present a never ending list of things to
be done.</para>

<section>
<title>User Docs</title>
<itemizedlist>
<listitem>
<para>Partially revised for &sr; 1.8.  More work needed</para>
</listitem>
</itemizedlist>
</section>

<section>
<title>Developer Docs</title>
<itemizedlist>
<listitem>
<para>Needs update.</para>
</listitem>
<listitem>
<para>Convert remaining html docs to xml.</para>
</listitem>
<listitem>
<para>Get missing figures for a few xml module descriptions.</para>
</listitem>
</itemizedlist>
</section>

<section>
<title>FAQs</title>
<itemizedlist>
<listitem>
<para>FAQs are out of date.  Need a volunteer to cull out the cruft.</para>
</listitem>
</itemizedlist>
</section>

<section>
<title>General</title>

<itemizedlist>

<listitem>
<para>Produce truly printable Installation and Developer Guides (how
good are the FOPs these days?).  We can always use jade and jadetex.
This would require the installation of jade and the DocBook DSSSL
stylesheets.</para>
</listitem>
<listitem>
<para>Generate Makefiles via configure script.  Need to check that
 the proper tools are installed, etc.</para>
</listitem>
<listitem>
<para>Add section to this document on editing latex documents.</para>
</listitem>
</itemizedlist>

</section>

<section>
<title>Changes to <filename>component.dtd</filename></title>
<para>
Modify <filename>component.dtd</filename> in the following ways:
<itemizedlist>
<listitem>
<para>Replace <sgmltag class=3D"starttag">examplesr</sgmltag> element
with the <sgmltag class=3D"starttag">docnet</sgmltag> element as
proposed by Marty.</para>
</listitem>
<listitem>
<para>Enhance <sgmltag class=3D"starttag">description</sgmltag> element
to allow the <sgmltag class=3D"starttag">img</sgmltag> element.</para>
</listitem>
<listitem>
<para>Don't require that the basic flow patterns start with a <sgmltag
class=3D"starttag">p</sgmltag> element.</para>
</listitem>
<listitem>
<para>Add <quote>id</quote> attribute to all
elements and then:</para>

<para>Replace <sgmltag class=3D"starttag">slink</sgmltag> and <sgmltag
class=3D"starttag">rlink</sgmltag> elements with <sgmltag
class=3D"starttag">ulink</sgmltag> (for url style links) and <sgmltag
class=3D"starttag">link</sgmltag> (for intra document
links).</para>
</listitem>
</itemizedlist>
</para>
</section>

</section>

</article>

<!-- 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:
-->


=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

System Info to help track down your bug:
---------------------------------------

uname -a: Darwin mainserver.cvrti.utah.edu 6.2 Darwin Kernel Version 6.2: T=
ue Nov  5 22:00:03 PST 2002; root:xnu/xnu-344.12.2.obj~1/RELEASE_PPC  Power=
 Macintosh powerpc

./configure  '--prefix=3D/sw' '--with-dialogs=3Dathena' '--with-widgets=3Da=
thena' '--with-sound=3Dnone' '--with-database=3Dno' '--without-ldap' '--wit=
hout-postgresql' '--with-athena=3D3d'


XEmacs 21.5-b9 "brussels sprouts"  configured for `powerpc-apple-darwin6.2'.


Compilation / Installation:
  Source code location:              /sw/src/xemacs-21.5.9-3/xemacs-21.5.9
  Installation prefix:               /sw
  Operating system description file: `s/darwin.h'
  Machine description file:          `m/powerpc.h'
  Compiler:                          gcc -g -O3 -Wall -Wno-switch -Winline =
-Wmissing-prototypes -Wsign-compare -Wshadow -Wpointer-arith
  Relocating allocator for buffers:  no
  GNU version of malloc:             no
    - The GNU allocators don't work with this system configuration.

Window System:
  Compiling in support for the X window system:
    - X Windows headers location:                 /usr/X11R6/include
    - X Windows libraries location:               /usr/X11R6/lib
    - Handling WM_COMMAND properly.
  Compiling in support for the Athena widget set:
    - Athena headers location:                    X11/Xaw3d
    - Athena library to link:                     Xaw3d
  Using Lucid menubars.
  Using Lucid scrollbars.
  Using Athena dialog boxes.
  Using Athena native widgets.

TTY:
  Compiling in support for ncurses.

Images:
  Compiling in support for GIF  images (builtin).
  Compiling in support for XPM  images.
  Compiling in support for PNG  images.
  Compiling in support for JPEG images.
  Compiling in support for TIFF images.

Sound:

Databases:

Internationalization:

Mail:
  Compiling in support for "dot-locking" mail spool file locking method.

Other Features:
  Inhibiting IPv6 canonicalization at startup.
  Compiling in support for dynamic shared object modules.
  Using the new portable dumper.
  Compiling in support for extra debugging code.
  WARNING: ---------------------------------------------------------
  WARNING: Compiling in support for runtime error checking.
  WARNING: XEmacs will run noticeably more slowly as a result.
  WARNING: Error checking is on by default for XEmacs beta releases.
  WARNING: ---------------------------------------------------------



Load-Path Lisp Shadows:
----------------------
(/sw/lib/xemacs/xemacs-packages/lisp/ecrypto/md5
/sw/lib/xemacs/xemacs-packages/lisp/gnus/md5)


Installed XEmacs Packages:
-------------------------

((zenirc:version 1.13 :type regular)
 (xslt-process :version 1.1 :type regular)
 (xslide :version 1.03 :type regular)
 (xemacs-devel :version 1.48 :type single-file)
 (xemacs-base :version 1.68 :type regular)
 (w3 :version 1.25 :type regular)
 (vm :version 7.07 :type regular)
 (viper :version 1.34 :type regular)
 (view-process :version 1.12 :type regular)
 (vhdl :version 1.15 :type regular)
 (vc-cc :version 1.21 :type regular)
 (vc :version 1.33 :type regular)
 (tramp :version 1.08 :type regular)
 (tpu :version 1.12 :type regular)
 (tooltalk :version 1.13 :type regular)
 (tm :version 1.34 :type regular)
 (time :version 1.12 :type regular)
 (textools :version 1.12 :type regular)
 (text-modes :version 1.52 :type single-file)
 (texinfo :version 1.2 :type regular)
 (supercite :version 1.19 :type regular)
 (strokes :version 1.08 :type regular)
 (speedbar :version 1.24 :type regular)
 (sounds-wav :version 1.1 :type regular)
 (sounds-au :version 1.1 :type regular)
 (sml-mode :version 0.03 :type regular)
 (slider :version 1.13 :type regular)
 (sieve :version 1.09 :type regular)
 (sh-script :version 1.15 :type regular)
 (sgml :version 1.08 :type regular)
 (semantic :version 1.14 :type regular)
 (scheme :version 1.11 :type regular)
 (sasl :version 1.12 :type regular)
 (rmail :version 1.13 :type regular)
 (reftex :version 1.28 :type regular)
 (psgml-dtds :version 1.02 :type regular)
 (psgml :version 1.33 :type regular)
 (ps-print :version 1.08 :type regular)
 (prog-modes
  :version
   1
   .65
    :type
     single-file)
 (pcomplete :version 1.01 :type regular)
 (pcl-cvs :version 1.64 :type regular)
 (pc :version 1.25 :type single-file)
 (os-utils :version 1.28 :type single-file)
 (ocaml :version 0.03 :type regular)
 (net-utils :version 1.28 :type single-file)
 (mmm-mode :version 1.0 :type regular)
 (misc-games :version 1.15 :type single-file)
 (mine :version 1.14 :type regular)
 (mh-e :version 1.15 :type regular)
 (mew :version 1.17 :type regular)
 (mailcrypt :version 2.11 :type regular)
 (mail-lib :version 1.49 :type regular)
 (liece :version 1.07 :type regular)
 (jde :version 1.35 :type regular)
 (ispell :version 1.24 :type regular)
 (ilisp :version 1.28 :type regular)
 (igrep :version 1.09 :type regular)
 (idlwave :version 1.25 :type regular)
 (ibuffer :version 1.08 :type regular)
 (hm--html-menus :version 1.18 :type regular)
 (haskell-mode :version 1.03 :type regular)
 (gnus :version 1.62 :type regular)
 (gnats :version 1.15 :type regular)
 (games :version 1.13 :type regular)
 (fsf-compat :version 1.11 :type single-file)
 (frame-icon :version 1.09 :type regular)
 (forms :version 1.14 :type regular)
 (footnote :version 1.15 :type regular)
 (eudc :version 1.36 :type regular)
 (eterm :version 1.13 :type regular)
 (ess :version 1.02 :type regular)
 (eshell :version 1.03 :type regular)
 (emerge :version 1.09 :type regular)
 (elib :version 1.1 :type single-file)
 (eieio :version 1.03 :type regular)
 (efs :version 1.29 :type regular)
 (edt :version 1.12 :type regular)
 (edit-utils :version 1.93 :type single-file)
 (ediff :version 1.41 :type regular)
 (edebug :version 1.14 :type regular)
 (ecrypto :version 0.11 :type regular)
 (docbookide :version 0.05 :type regular)
 (dired :version 1.12 :type regular)
 (dictionary :version 1.11 :type regular)
 (debug :version 1.15 :type regular)
 (crisp :version 1.12 :type regular)
 (cookie :version 1.14 :type regular)
 (clearcase :version 1.04 :type regular)
 (cc-mode :version 1.3 :type regular)
 (calendar :version 1.18 :type regular)
 (calc :version 1.23 :type regular)
 (c-support :version 1.16 :type single-file)
 (build :version 1.07 :type regular)
 (bbdb :version 1.21 :type regular)
 (auctex :version 1.32 :type regular)
 (apel :version 1.25 :type regular)
 (ada :version 1.1 :type regular))


Features:
--------

(mail-abbrevs xemacsbug shadow sendmail rfc822 font disp-table paren
blink-paren pending-del func-menu view-less view efs-ovwrt default-dir
gnuserv mwheel tex-site font-lock cus-face tramp regexp-opt advice
advice-preload shell comint ring format-spec timer zenirc-autoloads
xslt-process-autoloads xslide-autoloads xemacs-devel-autoloads
xemacs-base-autoloads w3-autoloads vm-autoloads viper-autoloads
view-process-autoloads vhdl-autoloads vc-cc-autoloads vc-autoloads
tramp-autoloads tpu-autoloads tooltalk-autoloads tm-autoloads
time-autoloads textools-autoloads text-modes-autoloads texinfo-autoloads
supercite-autoloads strokes-autoloads speedbar-autoloads
sounds-wav-autoloads sounds-au-autoloads sml-mode-autoloads
slider-autoloads sieve-autoloads sh-script-autoloads sgml-autoloads
semantic-autoloads scheme-autoloads sasl-autoloads rmail-autoloads
reftex-autoloads psgml-dtds-autoloads psgml-autoloads ps-print-autoloads
prog-modes-autoloads pcomplete-autoloads pcl-cvs-autoloads pc-autoloads
os-utils-autoloads ocaml-autoloads net-utils-autoloads mmm-mode-autoloads
misc-games-autoloads mine-autoloads mh-e-autoloads mew-autoloads
mailcrypt-autoloads mail-lib-autoloads liece-autoloads jde-autoloads
ispell-autoloads ilisp-autoloads igrep-autoloads idlwave-autoloads
ibuffer-autoloads hm--html-menus-autoloads haskell-mode-autoloads
gnus-autoloads gnats-autoloads games-autoloads fsf-compat-autoloads
frame-icon-autoloads forms-autoloads footnote-autoloads eudc-autoloads
eterm-autoloads ess-autoloads eshell-autoloads emerge-autoloads
elib-autoloads eieio-autoloads efs-autoloads edt-autoloads
edit-utils-autoloads ediff-autoloads edebug-autoloads ecrypto-autoloads
docbookide-autoloads dired-autoloads dictionary-autoloads debug-autoloads
crisp-autoloads cookie-autoloads clearcase-autoloads cc-mode-autoloads
calendar-autoloads calc-autoloads c-support-autoloads build-autoloads
bbdb-autoloads auctex-autoloads apel-autoloads ada-autoloads src-autoloads
loadhist rsz-minibuf auto-show fontl-hooks x-iso8859-1 code-cmds
gutter-items menubar-items x-menubar mode-motion mouse behavior itimer
auto-save lisp-mode easymenu iso8859-1 page buff-menu lib-complete cus-file
derived env text-props frame obsolete cus-start custom widget cl-extra
mini-cl cl cl-19 packages backquote very-early-lisp unicode
lucid-scrollbars cut-buffer lucid-menubars athena-dialogs x c-balloon-help
tty-frames tty toolbar scrollbar unix-processes multicast network-streams
subprocesses modules menu-accelerator-support menubar md5 xemacs gutter
tiff png gif jpeg xpm xbm lisp-float-type file-coding darwin dialog devices
window-system base64)


Recent keystrokes:
-----------------

button1 button1up C-x 1 M-x v e r TAB button2 button2up =

C-n ( v e r s i o n ) C-j misc-user


Recent messages (most recent first):
-----------------------------------

Loading xemacsbug...done (file xemacsbug.el is newer)
Loading xemacsbug... (file xemacsbug.el is newer)
XEmacs 21.5  (beta9) "brussels sprouts" [Lucid] (powerpc-apple-darwin6.2) o=
f Fri Nov 29 2002 on mainserver.cvrti.utah.edu
Making completion list...
Warning: XEmacs:  Mod1 is being used for both Mode_switch and Alt.
Warning: =

	Two distinct modifier keys (such as Meta and Hyper) cannot generate
	the same modifier bit, because Emacs won't be able to tell which
	modifier was actually held down when some other key is pressed.  It
	won't be able to tell Meta-x and Hyper-x apart, for example.  Change
	one of these keys to use some other modifier bit.  If you intend for
	these keys to have the same behavior, then change them to have the
	same keysym as well as the same modifier bit.
Warning: =

	The meanings of the modifier bits Mod1 through Mod5 are determined
	by the keysyms used to control those bits.  Mod1 does NOT always
	mean Meta, although some non-ICCCM-compliant programs assume that.
Loading font...done
Loading font...
Paren mode is paren
Loading paren...done
Loading paren...
Loading /private/var/netboot/Users/dustman/.emacs.d/rgstrs.el...done
Loading /private/var/netboot/Users/dustman/.emacs.d/rgstrs.el...
Loading gnuserv...done
Loading gnuserv...
Loading mwheel...done
Loading mwheel...
Loading /sw/lib/xemacs/xemacs-packages/lisp/auctex/tex-site.el...done
Loading /sw/lib/xemacs/xemacs-packages/lisp/auctex/tex-site.el...




--===============2454175560488037418==--