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 <osspkg@gmail.com>

COPYRIGHT

       Copyright X 2003-2008 Brendt Wohlberg <osspkg@gmail.com>

       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-09                                            XNAV(1)