| User Guide |
Before you install Yggdrasil, you must have a working installation of Perl version 5.8.0. You can download Perl from one of the following locations:
Unzip and extract the distribution to the desired directory. All files are in a directory named yggdrasil. After extracting the files, you can run Yggdrasil with
perl y.pl [OPTIONS]
or
./y.pl [OPTIONS]
depending on your OS and system setup. Run
perl y.pl --help
to display a description of the available commandline options.
Yggdrasil uses a couple of modules which are not included in the standard Perl distribution. Use the CPAN shell (Linux) or PPM (Windows) to install the modules on your system:
Using CPAN:
perl -MCPAN -eshell
install AppConfig
install Date::Format
install Text::Template
Using PPM:
ppm install AppConfig
ppm install TimeDate
ppm install Text-Template
AppConfig is not available from the default ActiveState repository. Use http://theoryx5.uwinnipeg.ca/ppms/ instead.
If you want to validate your HTML documents as they are being built, you need to install the SP SGML System:
SP comes with Document Type Definitions (DTD) for HTML versions up to 4.0. If you want to validate XHTML documents you need to download the correct DTD’s from the World Wide Web Consortium:
Unzip the file you downloaded and copy the DTD’s to SP’s pubtext/ directory.
See the Quick Start Guide.
Yggdrasil handles most of the intersite navigation automatically. Use the following features to take advantage of this.
Links to all subpages of the current page are placed in the @navigation template variable. The array contains reference to hashes with the following keys: name and href. Name is the title of the page and href is the relative path from the current page to the subpage.
The array is sorted alphabetically on the value of the name key, but you can use a snippet of code in your template to sort it any way you like.
Whether a page shows up in the @navigation variable depends on your settings for the include and exclude configuration variables.
Links to all index pages in the path from the current page to the root page are placed in the @trail template variable. The array contains references to hashes with the same keys as those in the @navigation template variable.
In the default configuration, all links in the breadcrumb trail are relative with no file names (e.g. ../../). This means that for the trail to work you must have HTML index files (as determined by the html_indices configuration variable) in all directories of the site.
Links to all files in the current directory are placed in the @siblings template variable. The array contains references to hashes with the same keys as those in @navigation template variable. For non-HTML files the filename is used in the name field.
Content spanning multiple pages is handled by the numbered subpages feature. This feature requires that you use a specific directory layout for your content. E.g. for content spanning three pages you must use the following directory structure:
somedir/
index.html First page
2/
index.thml Second page
3/
index.html Third page
On pages 2 and 3 the page number is appended to the breadcrumb trail (in the form ‘Page n’). Yggdrasil doesn’t create links to the numbered subpages, you have to create your own ‘next/previous page’ links.
Use this feature when you have set up your source with a base template for one target but you need to override this for a different target without having to maintain duplicate source directories. This can also be useful when you need to publish a subdirectory of your main source directory to a different target.
FIXME: description of template override syntax
Misc. features.
Yggdrasil can upload all processed files via FTP. You need to set a hostname, a username nad a password for this feature to work (an optional remote path can also be set).
Yggdrasil can delete remote files that are no longer in use, but it has no support for deleting empty directories.
FIXME: config file syntax
If you have installed the SP SGML System, you can have Yggdrasil validate your output files as they are being generated. Any errors found will be reported when all files have been processed.
You must define the full commandline needed to start nsgmls in the sp_command_line configuration variable (an example is included in conf/default.cfg. The variable $filename will be replaced with the name of the file being processed.
Enable validation with the --validate commandline option or by setting validate=1 in the configuration file.
The default navigation generated by Yggdrasil is only suitable for use on a properly configured webserver. To prepare your site for offline use you need to inlcude filenames in all navigation links.
Set include_index=1 in the configuration file to include filenames in all links.
When preparing alternate versions of your site you might need to perform some kind of postprocessing on the output files.
To use the postprocessing feature, you must create a file containing an anonymous subroutine. This file must be named according to your configuration file. If you are using default.cfg, the file containing the subroutine must be named default.sub and be placed in the conf/ directory.
FIXME: text about input/output of postprocessing sub.
If you need to process the files with other tools, you can use a log file to get a list of all the processed files.
FIXME: text about headers, footers and line templates.
The examples below use the configuration file syntax.
input_dir = /home/me/site/source
output_dir = /home/me/www
data_dir = data
dir_mode = 0755
include = \.html$
include = \.shtml$
exclude = ^_
exclude = \.tmpl$
exclude = ~$
@navigation array.
skip = ^img
skip = ^index$
base_url = http://www.mysite.com
base_template = base.tmpl
template_extension = .tmpl
template_override beta = /home/me/site/template.tmpl
timestamp_format = %a %b %e %Y (%T)
html_indices = index.html
html_indices = index.shtml
html_only = 0
FIXME: note on how this is usually not necessary because of global site navigation already in place.
front_page_navigation = 0
include_index = 0
siblings_include_index = 0
home_label = Home
title_tag = h1
default_title = No Title
subpages = 1
pagination = Page
ftp_host = ftp.mysite.com
ftp_username = me
ftp_password = secret
ftp_path = /www
line(s) of the log file.
log_file_header = # Yggdrasil log file
line(s) of the log file.
log_file_footer = # end of log file
log_file_format = {$fullname}
release_file = .release
sp_command_line = /usr/bin/nsgmls {$filename}
forcecache = 0
help = 0
log_file = mysite.log
update = 0
upload = 0
release = 0
sp_command_line.
validate = 0
verbose = 1
The following functions are available in the templates:
include($filename)include_text($filename)The following variables are available in the templates:
<h1> tags in the file). If no title can be found in the document, a default title is used.Morten Wulff, <wulff@psyke.org>
Copyright 2003, Morten Wulff
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the file “FDL”.
| User Guide |