- Added documentation on including content files.

nigel.stanger / Handbook

Browse code - Added documentation on including content files. master
1 parent d1485e6 commit 2332cb7ae204bf95c885b38dce912b71e28e29a3 nstanger authored on 21 Jan 2005

Patch

Showing 1 changed file

Ignore Space Show notes View README.txt
Required environment variables ============================== TEACHING_SHARED This variable specifies the path to the top level of the teaching shared directory hierarchy, whereever 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/2005" (which contains directories INFO212, INFO321, ...). HANDBOOK_INSTALL_ROOT This variable specifies the path to the top level directory on the web server, under which the files for this paper will be installed (that is, the directory that contains the individual paper directory hierarchies). Under Windows this would typically point to "\\INFO-NTS-12\DBCourses$" (but this may require munging depending on how UNC paths are dealt with). On my machine this is set to "/Volumes/DBCOURSES$", because this is where the share gets mounted. XSLT This variable specifies your preferred XSLT processor. Currently the valid options are "saxon" for SAXON 6.5.x, "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". Including content files ======================= To simulate the effect of XML fragment inclusion (which isn't supported in any software yet), we use ASP like tags in the document files to mark where content files should be inserted. These tags look something like this: <@INC[DBMS/Q_What_is_a_DBMS.xml]@> What the makefile does is run a Perl script to replace each of these tags with the content of the file specified by the include path (this path is relative to the root directory of the paper + the section name, e.g., $(ALL_PAPERS_ROOT)/INFO212/Tutorials). A problem can arise if one of these tags occurs inside an XML comment, e.g.: <!-- <@INC[DBMS/Q_What_is_a_DBMS.xml]@> --> This is a problem if the content file Q_What_is_a_DBMS.xml also contains XML comments. Comments cannot be nested in XML, and the XSLT processor will complain bitterly. The solution is to "neuter" the include tag, by changing it in such a way that the Perl script will no longer recognise it, e.g.: <!-- <@IN[DBMS/Q_What_is_a_DBMS.xml]@> --> Just remember to change it back when you un-comment the inclusion, or the XSLT processor will complain about malformed XML tags :) SETUP Required environment variables: TEACHING_SHARED This variable specifies the path to the top level of the teaching shared directory hierarchy, whereever 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/2005" (which contains directories INFO212, INFO321, ...). HANDBOOK_INSTALL_ROOT This variable specifies the path to the top level directory on the web server, under which the files for this paper will be installed (that is, the directory that contains the individual paper directory hierarchies). Under Windows this would typically point to \\INFO-NTS-12\DBCourses$ (but this may require munging depending on how UNC paths are dealt with). On my machine this is set to "/Volumes/DBCOURSES$", because this is where the share gets mounted. XSLT This variable specifies your preferred XSLT processor. Currently the valid options are "saxon" for SAXON 6.5.x, "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".

Ignore Space Show notes View

README.txt

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

TEACHING_SHARED
This variable specifies the path to the top level of the teaching shared
directory hierarchy, whereever 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/2005" (which contains directories
INFO212, INFO321, ...).

HANDBOOK_INSTALL_ROOT
This variable specifies the path to the top level directory on the web
server, under which the files for this paper will be installed (that is,
the directory that contains the individual paper directory hierarchies).
Under Windows this would typically point to "\\INFO-NTS-12\DBCourses$"
(but this may require munging depending on how UNC paths are dealt
with). On my machine this is set to "/Volumes/DBCOURSES$", because this
is where the share gets mounted.

XSLT
This variable specifies your preferred XSLT processor. Currently the
valid options are "saxon" for SAXON 6.5.x, "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".

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

To simulate the effect of XML fragment inclusion (which isn't supported
in any software yet), we use ASP like tags in the document files to mark where content
files should be inserted. These tags look something like this:

<@INC[DBMS/Q_What_is_a_DBMS.xml]@>

What the makefile does is run a Perl script to replace each of these
tags with the content of the file specified by the include path (this
path is relative to the root directory of the paper + the section name,
e.g., $(ALL_PAPERS_ROOT)/INFO212/Tutorials).

A problem can arise if one of these tags occurs inside an XML comment, e.g.:

This is a problem if the content file Q_What_is_a_DBMS.xml also contains
XML comments. Comments cannot be nested in XML, and the XSLT processor
will complain bitterly. The solution is to "neuter" the include tag, by
changing it in such a way that the Perl script will no longer recognise
it, e.g.:

Just remember to change it back when you un-comment the inclusion, or
the XSLT processor will complain about malformed XML tags :)

SETUP

Required environment variables:

HANDBOOK_INSTALL_ROOT
This variable specifies the path to the top level directory on the web
server, under which the files for this paper will be installed (that is,
the directory that contains the individual paper directory hierarchies).
Under Windows this would typically point to \\INFO-NTS-12\DBCourses$
(but this may require munging depending on how UNC paths are dealt
with). On my machine this is set to "/Volumes/DBCOURSES$", because this
is where the share gets mounted.

Show line notes below