A brief note on the development of Topics in Molecular Quantum Mechanics.

Brian J. Keay

The homepage for this document is currently http://www.scienceelearning.org.

Temporary mailing address:
2664 Benton Street
Santa ClaraCA

See also the revision notes.


This brief technical note is intended to provide information on the software tools used to create the tutorial Topics in Molecular Quantum Mechanics.

Table of Contents

1. How to view the Web pages.
2. Software tools.

1. How to view the Web pages.

As mentioned elsewhere, the equations in Topics in Molecular Quantum Mechanics are encoded in MathML, which can be viewed with a MathML enabled Web browser, such as Mozilla. Those using Internet Explorer can choose a plug-in from a list. One version of this document has been formatted for IE 5.5 with MathPlayer 1.0, but those using IE 6.0 should consider upgrading to MathPlayer 2.0, which can now use the same formatting of the MathML Web pages as the Mozilla browsers. Those using Mozilla Firefox 1.0 may need to download fonts from http://www.mozilla.org/projects/mathml/fonts. The character encoding of the Web pages with MathML content is Unicode (UTF-8). If the Web pages don't appear to render correctly after you install the correct browser or plug-in, go to your browser's menu bar and select "View", "Encoding", "Unicode (UTF-8)".

[Caution]Viewing the tutorial from your local hard drive.

If you download the tutorial to your hard drive, be sure that that the Cascading Style Sheet freedom.css is available in the same directory as the HTML or XTML files. You should also have directories called images and MQM_graphics, which, at the moment, just contains nine graphics files all together. If you use Internet Explorer there may also be problems using the XTML version of the tutorial from your local hard drive. If this is the case, then try using the HTML version, or download a Mozilla browser.

2. Software tools.

Topics in Molecular Quantum Mechanics is being written using the DocBook document type definition (DTD), and processed using the command line Extensible Stylesheet Language Transformation (XSLT) processor xsltproc. An excellent place to begin learning how to use DocBook is DocBook: The Definitive Guide, by Norman Walsh and Leonard Muellner, with contributions from Bob Stayton. It can be read online at http://www.docbook.org/tdg/en/html/docbook.html. Those using DocBook will also need to know how to process the documents using an Extensible Stylesheet Language Transformation (XSLT) processor, such as xsltproc. There are a couple excellent tutorials available via the Internet on how to process DocBook documents. One is Bob Stayton's DocBook XSL: The Complete Guide, which is also available via the Internet at http://www.sagehill.net/docbookxsl/index.html. Ashley J.S Mills also has a nice tutorial at http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/docbooksys/docbooksyshome.html.

For now, we will only mention that the command line parameters in Example 1 were executed with xsltproc within a Python script.

Example 1. xsltproc command line parameters.

xsltproc -stringparam base.dir ./FREEDOM/ --stringparam  bibliography.numbered 1 \
--stringparam  section.label.includes.component.label 1 \
-stringparam admon.graphics 1 -stringparam  navig.graphics 1 \
--stringparam chunker.output.doctype-public "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" \
--stringparam chunker.output.doctype-system "http://www.w3.org/TR/MathML2/dtd/xhtml-math11-f.dtd" \
--stringparam  section.autolabel 1 \
--stringparam  html.stylesheet freedom.css \
--stringparam  chunk.section.depth 0 \
--stringparam  xref.with.number.and.title 0 \
--stringparam  formal.title.placement "equation before" \
--stringparam  table.borders.with.css 1 \
--stringparam  table.cell.border.thickness 0.1pt \
--stringparam  table.frame.border.thickness "0.1pt" \
--stringparam  table.cell.border.color "#dbd0ff" \
 freedom.xsl out2.xml' % vars() )

The formatting of the equation numbers was accomplished with a customization layer in the file freedom.xsl, and the alignment of the equation numbers is done with the Cascading Style Sheet (CSS) freedom.css. The contents of freedom.xsl are shown in Example 2.

Example 2. The style sheet customization layer in freedom.xsl.

<?xml version='1.0'?>
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

<xsl:import href="/usr/share/sgml/docbook/xsl-stylesheets-1.65.1-2/xhtml/docbook.xsl"/>

<xsl:param name="html.stylesheet" select="'freedom.css'"/>
<xsl:param name="shade.verbatim" select="1"/>

<xsl:param name="local.l10n.xml" select="document('')"/>
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
  <l:l10n language="en">
	<l:context name="title">
      		<l:template name="equation" text="(%n)"/>

	<l:context name="xref-number">
      		<l:template name="equation" text="(%n)"/>

<xsl:param name="generate.toc">
appendix  toc,title
article/appendix  nop
article   toc,title
book      toc,title,figure,table,example
chapter   toc,title
part      toc,title
preface   toc,title
qandadiv  toc
qandaset  toc
reference toc,title
sect1     toc
sect2     toc
sect3     toc
sect4     toc
sect5     toc
section   toc
set       toc,title