XNAV(1)

📦 version 0.05, in ubuntu jammy

🌸 XNAV(1) — the manual page, but make it a group chat 🌸

okay bestie, sit down, hydrate, because we're about to talk about xnav — yes, that's the XNAV command from section 1 of the manual, and she's literally the friend who builds your whole website's navigation for you. no cap. 🫶

✨ NAME ✨

xnav — constructs 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

she's giving "one command, many moods". iconic. 👑

✨ DESCRIPTION ✨

so XNav wraps your directory tree of XHTML documents in a whole wrapper with CSS style plus top and side navigation bars. like, she dresses your plain little docs up for the function. 🎀

and she ALSO gives you a mechanism for automatic construction of XHTML documents from user defined XML document types, using user suplied XSL. (yes, "suplied" — that's how the original spells it, and we respect the original's spelling, periodt. 😌)

✨ OPTIONS ✨

  • init path — initialise directory path as an XNav website. it's giving "setting up the group chat". 💖
  • make path — construct the XNav website in directory path. the actual glow-up moment. ✨
  • valid path — validate XML and XHTML in directory path. vibe check for your markup. 🧚
  • clean path — clean auto-generated files in directory path. the "decluttering my room at 2am" energy. 🌸
  • -V — display version. tell me who you are, bestie. 💅
  • -h — display usage information. help me help you. 🙈
  • -v — verbose operation. she's not being quiet about it. 😭
  • -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. pick your faves, queen. 🍓
  • -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. choose your fighter. 🔥
  • -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. the "double-click the file, it just works" special. 🌈

✨ USAGE ✨

🌟 setting the scene

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. no, bestie, not .html. i said what i said. 😤

each directory should have, at least:

  • an index document called index.xml, and
  • a configuration file called xnav.xml.

🌟 the config file, aka the lore

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 is specified by the href attribute, and
  • the directory label used in the navigation bars is 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.

🌟 init: the beginning of the era

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. let's meet the cast: 💖

  • head.xml and foot.xml define header and footer HTML added to every page generated by XNav.
  • catalog.xml 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, xnavinc.xsl includes the main XSL stylesheet xnav.xsl responsible for the majority of XNav processing.

🌟 extending her, because she can do anything

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 type 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.

🌟 make: the glow up

once initialisation is complete, and whenever source XML documents are edited, the output HTML files may be generated using the command

xnav make path

🌟 valid: the vibe check

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 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.

okay but fr fr, the "no warranty" bit is real and it means what it says. she's free, she's open, she's not promising you anything legally. respect it. 🙏

✨ AVAILABILITY ✨

available from <http://www.wohlberg.net/public/software/xml/xnav/> 🌈

and that's the whole page, bestie — sourced from the XNAV(1) manual page, dated 2014-03-09, and she's still serving. go build something iconic. mwah. 💅✨🎀

📦 where this page comes from