%#--
%# Copyright protects this work.
%# See LICENSE file for details.
%#++
%|chapter "Theory"
When you run <%= $project %>, it does the following:
1. Loads the <%= xref "SpecFile", "format specification file" %>.
2. Creates an *input document* by:
* Reading the input (the content of either the input file or the standard input stream) into memory.
3. Transforms the input document into a *processed document* by:
* Building a *document tree* data structure from <%= xref "Nodes", "nodes" %> present in the input document.
* Replacing every node in the input document with the result of its <%= xref "SpecFile.nodes.output", "node output template" %>.
4. Transforms the processed document into an *output document* according to the <%= xref "SpecFile.output", "document output template" %>.
5. Prints the output document to the standard output stream.
Although there is only one document being processed here, we refer to it using three distinct terms: *input*, *processed*, and *output*; because the content of the document changes radically with every transformation.
%|section "Nodes"
A node is a block of text that appears like this:
<%% node_type node_argument1, node_argument2, ... do |node_object| %>
node_content
<%% end %>
Or like this:
<%% node_type node_argument1, node_argument2, ... do %>
node_content
<%% end %>
Or like this:
<%%= node_type node_argument1, node_argument2, ... %>
Alternatively, you may omit the leading "<" and trailing "%>" characters from an eRuby directive if the directive spans an _entire_ line. So, the above examples become:
%% node_type node_argument1, node_argument2, ... do |node_object|
node_content
%% end
And:
%% node_type node_argument1, node_argument2, ... do
node_content
%% end
And:
%%= node_type node_argument1, node_argument2, ...
Technically, nodes are Ruby method invocations composed of the following:
%|table
%|thead
%|tr
%|th
Component
%|th
Description
%|tbody
%|tr
%|td
`node_type`
%|td
Name of the method being invoked.
%|tr
%|td
`node_argument1, node_argument2, ...`
%|td
Arguments for the method invocation.
%|tr
%|td
`node_content`
%|td
A block argument being passed to the method invocation.
%|tr
%|td
`node_object`
%|td
A `ERBook::Document::Node` object (see <%= xref "Node.class" %>) representing this method invocation.
A <%= xref "SpecFile", "format specification file" %> defines what types of nodes an input document may use.
%|section "The `ERBook::Document::Node` class", "Node.class"
When <%= $project %> builds a document tree from the nodes in an input document, it stores information about these nodes into `ERBook::Document::Node` objects. A `ERBook::Document::Node` object has the following properties (methods):
%|table
%|thead
%|tr
%|th
Property
%|th
Type
%|th
Description
%|tbody
%|tr
%|td
type
%|td
`String`
%|td
Name of the type of this node.
%|tr
%|td
definition
%|td
`Hash`
%|td
The definition of this type of node, taken directly from the <%= xref "SpecFile", "format specification file" %>.
%|tr
%|td
arguments
%|td
`Array`
%|td
Arguments passed to this node.
%|tr
%|td
backtrace
%|td
`Array`
%|td
A stack trace describing the location of this node in the input document.
%|tr
%|td
parent
%|td
`ERBook::Document::Node`
%|td
The `ERBook::Document::Node` object which contains this node. The value of this property will be `nil` if this node is a root of the document tree.
%|tr
%|td
children
%|td
`Array` of `ERBook::Document::Node`
%|td
List of child nodes from the document tree.
%|tr
%|td
depth
%|td
`Integer`
%|td
Distance from the root of the document tree to this node.
%|tr
%|td
section_number
%|td
`String`
%|td
A LaTeX-style section number for this node. This property is only present if enabled in the **number** parameter in the definition of this type of node.
%|tr
%|td
ordinal_number
%|td
`Integer`
%|td
An order-of-occurrence number for this node. This property is only present if enabled in the **number** parameter in the definition of this type of node.
%|tr
%|td
content
%|td
`String`
%|td
The block of text passed to this node.
%|tr
%|td
output
%|td
`String`
%|td
Result of the node output template for the content of this node.
Furthermore, the `ERBook::Document::Node` class is derived from [Ruby's `OpenStruct` class](http://www.ruby-doc.org/stdlib/libdoc/ostruct/rdoc/classes/OpenStruct.html), so you can define _additional_ properties for `ERBook::Document::Node` objects dynamically.
%|section "Format specification file", "SpecFile"
A format specification file is a plain-text file marked up in [YAML syntax](http://yaml4r.sourceforge.net/cookbook/). Through the following parameters, it defines (1) what types of nodes an input document may contain, (2) how the content of those nodes is transformed into output, and (3) how the processed document is transformed into the output document.
%|table
%|thead
%|tr
%|th
Parameter
%|th
Type
%|th
Description
%|tbody
%|tr
%|td
desc
%|td
`String`
%|td
A short description of the output format.
%|tr
%|td
code
%|td
`String`
%|td
Ruby code that will be loaded before the input document is processed. This source code will be evaluated inside the main <%= $project %> executable, so any file-system or path-dependent portions of this source code should take appropriate precautions.
%|tr
%|td
nodes
%|td
Hash
%|td
A listing of <%= xref "SpecFile.nodes", "node definitions" %>.
%|tr
%|td
output
%|td
`String`
%|td
An eRuby template for the final output document. See <%= xref "SpecFile.output" %>.
<%
# XXX: "declare" this local variable here (in the parent
# scope) because it is initialized and used in two
# different child scopes that exist at different depths
output_template_table_builder = nil
%>
%|section "Node definition", "SpecFile.nodes"
A node definition is a mapping from a name (the "node type") to the following set of parameters:
%|table
%|thead
%|tr
%|th
Parameter
%|th
Type
%|th
Description
%|tbody
%|tr
%|td
params
%|td
`String` or `Array` thereof
%|td
List of parameters that are expected to be specified during an instantiation of node. Any additional arguments passed during instantiation are stored in the `arguments` attribute of the resulting `ERBook::Document::Node` object.
%|tr
%|td
number
%|td
`String` or `Array` thereof
%|td
When "ordinal", assign an order of occurrence number to this node. When "section", assign a LaTeX-style section number to this node. Both choices can be specified simultaneously.
%|tr
%|td
inline
%|td
Boolean
%|td
Is node's output an in-line string of text that can be embedded anywhere in the document?
%|tr
%|td
silent
%|td
Boolean
%|td
Suppress the output of this node at the location it is instantiated?
%|tr
%|td
output
%|td
`String`
%|td
An eRuby template for the content of this node. See <%= xref "SpecFile.nodes.output" %>.
You may define additional parameters in a node definition if you want.
%|section "Node output template", "SpecFile.nodes.output"
A node output template (the **output** parameter in a node definition) is an eRuby template that transforms a node's content into output. During the processing stage, <%= $project %> replaces all nodes in the input document with the result of this template _unless_ the **silent** parameter is enabled in this node's definition.
The following variables are available for use in this template:
%|output_template_table_builder = lambda do |additional_rows|
%|table
%|thead
%|tr
%|th
Variable
%|th
Type
%|th
Description
%|tbody
% additional_rows.call
%|tr
%|td
`@roots`
%|td
`Array` of `ERBook::Document::Node`
%|td
All root nodes in the document tree.
%|tr
%|td
`@nodes`
%|td
`Array` of `ERBook::Document::Node`
%|td
All nodes in the document tree.
%|tr
%|td
`@nodes_by_type`
%|td
`Hash`
%|td
Mapping from node type (`String`) to array of `ERBook::Document::Node` objects having that type.
%|tr
%|td
`@format`
%|td
`Hash`
%|td
Data from the format specification file.
<%= PROJECT %> also provides the following mappings inside the `@format` variable:
%|table
%|thead
%|tr
%|th
Expression
%|th
Type
%|th
Description
%|tbody
%|tr
%|td
`@format[:name]`
%|td
`String`
%|td
Short-hand name of the current format.
%|tr
%|td
`@format[:file]`
%|td
`String`
%|td
Path of the current format specification file.
%|tr
% output_template_table_builder.call lambda {
%|tr
%|td
`@node`
%|td
`ERBook::Document::Node`
%|td
The node for which this template is being evaluated.
% }
%|section "Document output template", "SpecFile.output"
A document output template (the **output** parameter in a format specification file) is an eRuby template that transforms a processed document into the final output document.
The following variables are available for use in this template:
% output_template_table_builder.call lambda {
%|tr
%|td
`@content`
%|td
`String`
%|td
Content of the processed document.
% }
%|section "Creating your own document format", "HelloWorld"
Here is a working example to help you digest all that you've learned so far about format specification files. A few things to notice in this example are:
* We define a `generate_name()` method in <%= xref "HelloWorld.spec" %> and make use of it in the <%= xref "HelloWorld.input" %>. This shows how to provide format-specific functionality to an input document.
* We define a `$style` variable in <%= xref "HelloWorld.input" %> and make use of it in <%= xref "HelloWorld.spec" %>. This shows how to pass parameters from an input document to your format specification file.
To run this example:
1. Save the code shown in <%= xref "HelloWorld.spec" %> to a file named HelloWorld.spec
2. Save the text shown in <%= xref "HelloWorld.input" %> to a file named HelloWorld.input
3. Run this command:
<%= $program %> HelloWorld.spec HelloWorld.input > HelloWorld.output
4. Examine the HelloWorld.output file to your satisfaction!
%|example! "HelloWorld format specification file", "HelloWorld.spec"
<%= verbatim File.read('doc/HelloWorld.spec') %>
%|example! "Input document for HelloWorld format", "HelloWorld.input"
Note that this input document uses the [*shorthand* eRuby directive syntax](<%= Ember::WEBSITE %>#Directives) and the [implicit <%% end %> inference](<%= Ember::WEBSITE %>#Infer-block-endings) features of the [<%= Ember::PROJECT %>](<%= Ember::WEBSITE %>) <%= Ember::TAGLINE %>.
<%= verbatim File.read('doc/HelloWorld.input') %>
%|example! "Output of HelloWorld format", "HelloWorld.output"
%= `ruby bin/#{PROGRAM} -u doc/HelloWorld.spec doc/HelloWorld.input`