A scalar directive is a directive whose value is a “scalar”, a simple datatype such as a string or a number — as opposed to a directive object, which is a file or a folder in your source folder. RubyFrontier gathers scalar directives as part of the same process by which it gathers directive objects: as it begins to operate on a page object, it walks the hierarchy upwards from the page object, gathering directives (to construct the page table).
You can use any scalar directives for any purpose you like; but RubyFrontier also expects and hopes to find certain scalar directives defined for each page object that it renders, and you should be a little careful not to misuse these.
Your source folder supplies scalar directives to RubyFrontier in three places:
#prefs.yaml file. I already told you about this, but I’m going to tell you again here. As a page object is rendered, and RubyFrontier walks up the hierarchy looking for directives, it looks for files called
#prefs.yaml. If it encounters one, it loads it, expecting it to be a hash, and adds the elements of that hash into the list of directives, following the usual rules for folding. Keys in this hash are expected to be symbols.
So, for example, the source folder from which this Web page is rendered contains a
#prefs.yaml file that looks like this:
--- :bgcolor: FFFFEE :linkstylesheets: normal :markdown: true
These directives specify that by default a page should have a background color of
"#FFFFEE", should link to the stylesheet called
normal.css, and should be rendered through Markdown.
Scalar directives set through
#prefs.yaml files follow the rules of folding. This means that if there are multiple
#prefs.yaml files encountered as RubyFrontier walks up the hierarchy from the page object being rendered, all scalar directives in all
#prefs.yaml files encountered are obeyed, except that values encountered earlier in the walk (closer to the page object) override same-named values encountered later in the walk (higher up the hierarchy). So, for example, if the top-level
#prefs.yaml file sets
"#FFFFEE", then all page objects will have a
:bgcolor value of
"#FFFFEE", except that this value can be overridden for any group of files in a lower-level folder by giving a different value in a
#prefs.yaml file within that folder.
In the page object. As a page object is rendered, and RubyFrontier walks up the hierarchy looking for directives, it also looks in the page object itself. A directive in the page object must be one of the first lines of the page object, and it must begin with “#”. RubyFrontier looks through the lines of the page object file, and as soon as it encounters a line that does not begin with “#”, it breaks the page object file into two parts: everything that precedes that point is a series of scalar directives, everything after that point is the content of the page.
Following the “#”, with no space, is the name of the directive. This name will be translated into a symbol. So, for example, the word “#title” will be taken to define a
:title directive. Then there is a space. Then everything on the rest of the line will be evaluated (using
eval), and the result of this evaluation will be the value of the directive.
So, for example, the page object from which this Web page is generated starts like this:
#title "Scalar Directives"
RubyFrontier sees this and creates a
:title directive whose value is the string
A scalar directive supplied from the page object overrides a scalar directive with the same name supplied from a
#prefs.yaml file. So, for example, if the
#prefs.yaml file sets
"#FFFFEE", then all page objects “below” that file will have a
:bgcolor value of
"#FFFFEE", except that this value can be overridden for any particular file by giving a different value within that file, e.g.:
|Figure 1: Example of how scalar directives set in a top-level #prefs.yaml file are overridden through folding.|
The following scalar directives are “known” to RubyFrontier: they are meaningful to RubyFrontier out of the box, and will be obeyed if defined.
NOTE on capitalization of known scalar directive names: Frontier’s UserTalk is case-insensitive, but Ruby is not. Accordingly, I have had to pick a capitalization rule. The minimal simplest convention is all-lowercase, and this requires the least effort in migrating from Frontier (conversion to lowercase is a built-in TextMate command).
The pageheader is usually all the HTML up to and including the
<body> tag. It can be supplied in any of three different ways; one way is as the value of a :pageheader directive. This directive’s value can be the actual content of the pageheader (a string) or a Pathname for a text file to read and use as the content of the pageheader. The matter is discussed completely here.
The standard way of generating the pageheader involves inserting certain
<meta> tags into the
<head> region of the document, through the
metatags() standard macro. The following directives govern the behavior of this macro:
:includemetacharset. A boolean (the default is
true): should a
<meta> tag of the following form be inserted?
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
:charset. The charset value for the above
<meta> tag. The default is
:includemetagenerator. A boolean (the default is
true): should the following
<meta> tag be inserted?
<meta name="generator" content="RubyFrontier" />
<title>tag. Usually defined in the page object, since it is unusual for two pages to have the same title. The
:titlevalue is usable as an id for linking from one page to another within the site, so it’s a very good idea for every
:titleto be unique, and if two pages have the same
:title, you’ll get a warning. It is an error for a page to have no
:title(i.e. you must define this directive).
Body tag attributes are mostly superseded by CSS in good HTML practice, but they do still work.
:background. The name (with no extension) of a file in an
:bgcolor, :text, :link, :alink, :vlink. A color string; if hex, you may omit the initial “#”.
:topmargin, :leftmargin, :marginheight, :marginwidth.
If a page object file is a renderable, RubyFrontier uses the page object file’s name to derive the name for the Web page file that will be created. In doing this, it consults certain directives.
:fileextension. The suffix to be added to the name. This will replace the current suffix. The default is
:dropnonalphas. A boolean (default
true): Whether characters other than A through Z, 0 through 9, and underscore should be dropped from the name.
:lowercasefilenames. A boolean (default
true): Whether the name should be downcased.
:renderoutlinewith. The name of the outline renderer to be used if the page object is an outline (
.txt file will be treated as if it were an outline (
.opml), converting the text to XML in accordance with its indentation structure.
#template.txtwill be used. If defined, the file in question will be sought by appending “.txt” and looking in the source folder’s
#templatesfolder and in the user templates folder.
This documentation prepared
by Matt Neuburg, phd = matt at tidbits dot com
Download RubyFrontier from GitHub.