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 X 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/>

                                            2014-03-06                                    XNAV(1)