Updated README

nigel.stanger / Handbook

Browse code Updated README • Cleaned up Markdown. • Added some introductory text. master
1 parent 18cda74 commit 90f84ac9beede224c2c6d4a053d50a8b93164211 Nigel Stanger authored on 25 Oct 2019

Patch

Showing 1 changed file

Ignore Space Show notes View README.md
# Handbook related infrastructure This repository contains various tools and infrastructure related to the production of teaching materials. The contents include: * Scripts to generate dates for lectures, etc. * Autoconf configuration scripts for required tools. * Various include files and templates for make. ## Required environment variables ### `TEACHING_SHARED` This variable specifies the path to the top level of the teaching shared directory hierarchy, wherever you happen to have put it (e.g., on my machine this is set to `/Users/nstanger/Documents/Teaching/Shared`). ### `ALL_PAPERS_ROOT` This variable specifies the path to the top level directory for all papers taught, i.e., the directory that contains the individual paper directory hierarchies. This assumes that you have all your current paper directories contained within a single hierarchy. If you don’t, you’re in trouble ☺. For example, on my machine this is set to `/Users/nstanger/Documents/Teaching` (which contains symbolic links to the current directories for INFO212, INFO321, ...). ### `HANDBOOK_INSTALL_ROOT` This variable specifies the path to the top level directory on the web/deployment server, under which the files for this paper will be installed (that is, the directory that contains the individual paper directory hierarchies). On my machine this is set to `/Volumes/SHARED/Teaching/DatabaseCourses/Web_Deployment`, as the share gets mounted under `/Volumes/SHARED`. Under Windows this will be a UNC path which may require munging. ### `DBCOURSES_WEB_ROOT` This variable specifies the path to the top level directory of the Web server (e.g. `/mnt/info-nts-12/dbcourses`) being used to serve dynamic content (e.g. PHP scripts). Currently this is limited to the timetable.php script. ### `XSLT` This variable specifies your preferred XSLT processor. Currently the valid options are `saxon` for SAXON 6.5.x, `saxon-b` for SAXON-B, `xalan-c` for the C++ implementation of Xalan and `xalan-j` for the Java implementation of Xalan (weirdly, the latter two have different command line options). For example, on my machine this is set to `saxon-b` (this is also the recommended setting, as the others don’t support XSLT 2.0 as well, if at all). ## Configuring Once the variables above have been defined: ```sh cd configuration make # assumes GNU make ./configure ``` Check for missing items in the configure script output. Some will raise a fatal error if missing, some won’t. Install any tools that are missing. Some will require a bit more work, especially the XML-related tools like the entity resolver. (This latter requires catalog and properties files to be set up—see the instructions in the XML repository.) If all looks OK, then everything should just work from this point on! (fingers crossed) ## Including content fragments (XML) Content fragment files can be included using XML includes. Source files are processed by `xmllint` (a utility that comes with libxml) to produce an intermediate XML file that contains all of the included fragments. This is then processed normally. Paths in XML includes should always be relative to the current directory, since we can’t predict where in the file system hierarchy the source will be. A typical include might looks something like this: ```xml <xi:include href="../../../Tutorials/Foo/Bar.xml" xpointer="xpointer(/document/)" /> ``` All fragments are represented by an XML document of class “fragment”. The outermost `<document>` element is stripped off by the XPath expression in the `xpointer` attribute. Required environment variables ============================== `TEACHING_SHARED` This variable specifies the path to the top level of the teaching shared directory hierarchy, wherever you happen to have put it (e.g., on my machine this is set to `/Users/nstanger/Documents/Teaching/Shared`). `ALL_PAPERS_ROOT` This variable specifies the path to the top level directory for all papers taught, i.e., the directory that contains the individual paper directory hierarchies. This assumes that you have all your current paper directories contained within a single hierarchy. If you don’t, you’re in trouble ☺. For example, on my machine this is set to `/Users/nstanger/Documents/Teaching` (which contains symbolic links to the current directories for INFO212, INFO321, ...). `HANDBOOK_INSTALL_ROOT` This variable specifies the path to the top level directory on the web/deployment server, under which the files for this paper will be installed (that is, the directory that contains the individual paper directory hierarchies). On my machine this is set to `/Volumes/SHARED/Teaching/DatabaseCourses/Web_Deployment`, as the share gets mounted under `/Volumes/SHARED`. Under Windows this will be a UNC path which may require munging. `DBCOURSES_WEB_ROOT` This variable specifies the path to the top level directory of the Web server (e.g. `/mnt/info-nts-12/dbcourses`) being used to serve dynamic content (e.g. PHP scripts). Currently this is limited to the timetable.php script. `XSLT` This variable specifies your preferred XSLT processor. Currently the valid options are `saxon` for SAXON 6.5.x, `saxon-b` for SAXON-B, `xalan-c` for the C++ implementation of Xalan and `xalan-j` for the Java implementation of Xalan (weirdly, the latter two have different command line options). For example, on my machine this is set to `saxon-b` (this is also the recommended setting, as the others don’t support XSLT 2.0 as well, if at all). Configuring =========== Once the variables above have been defined: % cd configuration % make % ./configure Check for missing items in the configure script output. Some will raise a fatal error if missing, some won’t. Install any tools that are missing. Some will require a bit more work, especially the XML-related tools like the entity resolver. (This latter requires catalog and properties files to be set up—see the instructions in the XML repository.) If all looks OK, then everything should just work from this point on! (fingers crossed) Including content files ======================= Content files can be included using XML includes. Source files are processed by `xmllint` (a utility that comes with libxml) to produce an intermediate XML file that contains all of the included fragments. This is then processed normally. Paths in XML includes should always be relative to the current directory, since we can’t predict where in the file system hierarchy the source will be. A typical include might looks something like this: <xi:include href="../../../Tutorials/Foo/Bar.xml" xpointer="xpointer(/document/)" /> All fragments are represented by an XML document of class “fragment”. The outermost `<document>` element is stripped off by the XPath expression in the `xpointer` attribute.

Ignore Space Show notes View

README.md

# Handbook related infrastructure

This repository contains various tools and infrastructure related to the production of teaching materials. The contents include:

* Scripts to generate dates for lectures, etc.
* Autoconf configuration scripts for required tools.
* Various include files and templates for make.

## Required environment variables

### `TEACHING_SHARED`

This variable specifies the path to the top level of the teaching shared directory hierarchy, wherever you happen to have put it (e.g., on my machine this is set to `/Users/nstanger/Documents/Teaching/Shared`).

### `ALL_PAPERS_ROOT`

This variable specifies the path to the top level directory for all papers taught, i.e., the directory that contains the individual paper directory hierarchies. This assumes that you have all your current paper directories contained within a single hierarchy. If you don’t, you’re in trouble ☺. For example, on my machine this is set to `/Users/nstanger/Documents/Teaching` (which contains symbolic links to the current directories for INFO212, INFO321, ...).

### `HANDBOOK_INSTALL_ROOT`

This variable specifies the path to the top level directory on the web/deployment server, under which the files for this paper will be installed (that is, the directory that contains the individual paper directory hierarchies). On my machine this is set to `/Volumes/SHARED/Teaching/DatabaseCourses/Web_Deployment`, as the share gets mounted under `/Volumes/SHARED`. Under Windows this will be a UNC path which may require munging.

### `DBCOURSES_WEB_ROOT`

This variable specifies the path to the top level directory of the Web server (e.g. `/mnt/info-nts-12/dbcourses`) being used to serve dynamic content (e.g. PHP scripts).  Currently this is limited to the timetable.php script.

### `XSLT`

This variable specifies your preferred XSLT processor. Currently the valid options are `saxon` for SAXON 6.5.x, `saxon-b` for SAXON-B, `xalan-c` for the C++ implementation of Xalan and `xalan-j` for the Java implementation of Xalan (weirdly, the latter two have different command line options). For example, on my machine this is set to `saxon-b` (this is also the recommended setting, as the others don’t support XSLT 2.0 as well, if at all).

## Configuring

Once the variables above have been defined:

```sh
cd configuration
make                # assumes GNU make
./configure
```

Check for missing items in the configure script output. Some will raise a fatal error if missing, some won’t. Install any tools that are missing. Some will require a bit more work, especially the XML-related tools like the entity resolver. (This latter requires catalog and properties files to be set up—see the instructions in the XML repository.)

If all looks OK, then everything should just work from this point on! (fingers crossed)

## Including content fragments (XML)

Content fragment files can be included using XML includes. Source files are processed by `xmllint` (a utility that comes with libxml) to produce an intermediate XML file that contains all of the included fragments. This is then processed normally. Paths in XML includes should always be relative to the current directory, since we can’t predict where in the file system hierarchy the source will be.

A typical include might looks something like this:

```xml
<xi:include href="../../../Tutorials/Foo/Bar.xml" xpointer="xpointer(/document/*)" />
```

All fragments are represented by an XML document of class “fragment”. The outermost `<document>` element is stripped off by the XPath expression in the `xpointer` attribute.

Required environment variables
==============================

`TEACHING_SHARED`
This variable specifies the path to the top level of the teaching shared directory hierarchy, wherever you happen to have put it (e.g., on my machine this is set to `/Users/nstanger/Documents/Teaching/Shared`).

`ALL_PAPERS_ROOT`
This variable specifies the path to the top level directory for all papers taught, i.e., the directory that contains the individual paper directory hierarchies. This assumes that you have all your current paper directories contained within a single hierarchy. If you don’t, you’re in trouble ☺. For example, on my machine this is set to `/Users/nstanger/Documents/Teaching` (which contains symbolic links to the current directories for INFO212, INFO321, ...).

`HANDBOOK_INSTALL_ROOT`
This variable specifies the path to the top level directory on the web/deployment server, under which the files for this paper will be installed (that is, the directory that contains the individual paper directory hierarchies). On my machine this is set to `/Volumes/SHARED/Teaching/DatabaseCourses/Web_Deployment`, as the share gets mounted under `/Volumes/SHARED`. Under Windows this will be a UNC path which may require munging.

`DBCOURSES_WEB_ROOT`
This variable specifies the path to the top level directory of the Web server (e.g. `/mnt/info-nts-12/dbcourses`) being used to serve dynamic content (e.g. PHP scripts).  Currently this is limited to the timetable.php script.

`XSLT`
This variable specifies your preferred XSLT processor. Currently the valid options are `saxon` for SAXON 6.5.x, `saxon-b` for SAXON-B, `xalan-c` for the C++ implementation of Xalan and `xalan-j` for the Java implementation of Xalan (weirdly, the latter two have different command line options). For example, on my machine this is set to `saxon-b` (this is also the recommended setting, as the others don’t support XSLT 2.0 as well, if at all).

Configuring
===========

Once the variables above have been defined:

% cd configuration
	% make
	% ./configure

If all looks OK, then everything should just work from this point on! (fingers crossed)

Including content files
=======================

Content files can be included using XML includes. Source files are processed by `xmllint` (a utility that comes with libxml) to produce an intermediate XML file that contains all of the included fragments. This is then processed normally. Paths in XML includes should always be relative to the current directory, since we can’t predict where in the file system hierarchy the source will be.

A typical include might looks something like this:

<xi:include href="../../../Tutorials/Foo/Bar.xml" xpointer="xpointer(/document/*)" />

All fragments are represented by an XML document of class “fragment”. The outermost `<document>` element is stripped off by the XPath expression in the `xpointer` attribute.

Show line notes below