NAME
xnav - Construct navigation top and sidebars for a collection of web
pages
SYNOPSIS
xnav [ -V ] [ -h ] [ -v ] [ -c (all | (title | base | script | style |
meta | link | object)[,(title | base | script | style | meta | link |
object)][,...])] [ -b (rmv | div) ] [ -i ] [ init | make | valid |
clean ] path
DESCRIPTION
XNav adds a wrapper with CSS style and top and side navigation bars to
a directory tree of XHTML documents. It also provides a mechanism for
automatic construction of XHTML documents from user defined XML
document types, using user suplied XSL.
OPTIONS
init path
Initialise directory path as an XNav website.
make path
Construct the XNav website in directory path.
valid path
Validate XML and XHTML in directory path.
clean path
Clean auto-generated files in directory path.
-V Display version.
-h Display usage information.
-v Verbose operation.
-c Specify the html/head children to include in the output documents.
Allowed values are ’all’ (the default), ’none’, or a comma
separated list of element names ’title’, ’base’, ’script’, ’style’,
’meta’, ’link’, and ’object’.
-b Select handling of the body specification in CSS within a
html/head/style element. Valid values are ’rmv’, requesting removal
of any body definitions, and ’div’, requesting replacement by a top
level div element with the same style.
-i Append ’index.html’ to top and side navigation directory paths.
Primarily useful for constructing a set of pages that may be
navigated as files accessed directly by a web browser, rather than
through a web server.
USAGE
Start by setting up the desired directory structure of the collection
of web pages. All HTML documents should be valid XHTML 1.0 Strict, and
should have extension .xml rather than the usual .html. Each directory
should have, at least, an index document called index.xml, and a
configuration file called xnav.xml.
The configuration file format is defined in the file xnav.dtd. The top
level element is xnav, with optional child elements directory and file.
The label for a specific directory is usually provided by the label in
the referencing directory element in the parent directory, but may be
specified by using the label attribute in the top level directory. If
the index.xml file is not HTML, the type attribute should be set to the
name of the document format, and an XSL template should be provided for
handling that type.
A directory element represents a navigation link to a subdirectory, the
actual directory name being specified by the href attribute, and the
directory label used in the navigation bars being specified as the
element content. If a directory element points to a directory not
managed by XNav (i.e. into which the build script should not recurse),
the enter attribute value should be ’no’. If the directory is managed
by XNav, but is for some reason desired to be excluded from the side
navigation bar, the sidenav attribute value should be ’no’.
A file element represents a link to a file within the same directory as
the xnav.xml file, and has similar usage to the directory element. If
the file is not HTML, the type attribute should be set to the name of
the document format, and an XSL template should be provided for
handling that type. If the file is desired to be excluded from the side
navigation bar, the sidenav attribute value should be ’no’.
Initialise the directory structure at path using the command
xnav init path
creating a directory XNAV in path, containing configuration files which
may be edited by the user. The files head.xml and foot.xml define
header and footer HTML added to every page generated by XNav. The
catalog.xml file allows the XML processing utilities used by XNav to
locate the DTD for the xnav.xml configuration files. If the user adds
additional document types for processing by XNav, references to the
relevant DTDs should be added to the catalog file. Finally, the
xnavinc.xsl file includes the main XSL stylesheet xnav.xsl responsible
for the majority of XNav processing.
XNav can be extended to process arbitrary XML document types by
including additional XSL stylesheets within the xnavinc.xsl file. If a
non-HTML document types is referred to as newtype in the type
attribute, the user should define an XSL template with name newtype and
mode dynamic-template-select. Within this template, the content of the
document to be processed is available at XPath src/newtype.
Once initialisation is complete, and whenever source XML documents are
edited, the output HTML files may be generated using the command
xnav make path
The command
xnav valid path
validates source XML files which contain a DOCTYPE specification. Files
that do not contain such a specification are checked to determine
whether they are well formed.
AUTHOR
Brendt Wohlberg <software@wohlberg.net>
COPYRIGHT
Copyright AX 2003-2008 Brendt Wohlberg <software@wohlberg.net>
This program is free software; you can redistribute it and/or modify it
under the terms of version 2 of the GNU General Public License
<http://www.gnu.org/licenses/gpl-2.0.txt>.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
AVAILABILITY
Available from <http://www.wohlberg.net/public/software/xml/xnav/>
2008-01-29