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

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

home  |  acting  |  blog  |  consulting  |  noel  |  contact
© 2013 Michael McDonald, . All rights reserved.