|
|
Noel Projects
Noel is used to translate a set of Noel template files into a set of output
HTML files. The simplest form of a project is a list of files provided to the Noel
command line. These templates are concatenated,
and the filename and subdirectory of the last template is used to determine
where the output HTML file goes.
When you are generating multiple output files, you can use a Noel
project file (or the -p command line tag) to tell Noel which
files to parse, in what order, and when to output a file.
Here is an example project file, which is actually the bulk of the Noel
project for kelek.com:
(vars tags nav template)
index.html contact.html resume.html links.html
{(sub=noel _template.html) *.html exclude=_*}
{(sub=mines _template.html) *.html exclude=_*}
{(sub=freelance _template.html) *.html exclude=_*}
|
Specifying Files
Noel source files can be listed as individual paths (e.g. "index.html"
or "foo/bar/index.html") and file globs (e.g. "foo/*.html"). Individual
files, directories, and globs can be excluded using the "exclude=" option.
Recursive globs are possible using '**' (e.g. "foo/**/*.html"). If just
a directory is listed (e.g. "foo/") all .html and .prj (Noel project) files
will be matched. "foo/" is different than "foo/*" which matches all
files in foo.
When given a filename without an extension, Noel will also look for
a matching .html or .prj file.
Resource vs. Leaf Files
Files that are within parenthesis are resource files. They are parsed
by Noel, but no output file is generated to match the file. Files that are
not contained within parenthesis are leaf files. Leaf files are parsed
by Noel, a matching output file is generated, and then the Noel parser
rolls back to where the last resource file left off.
Source and Destination Locations
By default, the relative path to a leaf source file (i.e. relative to the
'-s' source directory) is appended to the destination directory (specified
by the '-d' option) and that's where the file is output to. The 'current'
source and destination directories can be manipulated throughout the project
for simplicity in places and extra flexibility in others.
The 'src='
option sets a new source directory (relative to the current source directory).
The 'dest=' option sets new destination directory (relative to the current
destination directory). The 'sub=' option combines both 'src=' and 'dest='.
These options specify relative directories. To give a directory relative
to the default -s or -d directories, begin the path with the special
"$BASE" value (e.g. "src=$BASE/other/source/path"). It is not necessary
to put directory options in parenthesis, but since they are changes
and not specifying leaf files, I think it is clearer to do so.
Context Switching
Changes to Noel content are arranged into a large tree. Near the top of the
tree are usually global variables, global tags, and a skeletal
<TEMPLATE> tag. Branches of the tree contain
more tags, sub-section behavior, and eventually end in an individual leaf
file. Changes made down one branch do not effect other branches.
A variable set in a leaf file is only going to show up in that leaf file. If
one section overrides a global variable, that section sees the new value and
the rest of the content tree sees the old value. This goes for source and
destination directory changes, as well.
This context switching is controlled by braces { } in Noel
project files. Changes made within braces are limited to that branch of
the project. Branches can be nested, of course.
Projects within Projects
It is possible to include project files (files with a .prj extension)
within project files. This is the equivalent of 'including' the file into
the containing project file. The included project is implicitly placed
within its own context, as if the .prj file was surrounded by braces.
Project File Comments
Project files can contain both single-line and ranged comments.
Single-line comments begin with # and everything until the next newline is
ignored. Ranged comments begin with #* and end with *# and can span multiple
lines.
|
