doc/theory.erb in erbook-7.0.0 vs doc/theory.erb in erbook-7.1.0

- old
+ new

@@ -1,11 +1,12 @@ %#-- -%# Copyright 2007 Suraj N. Kurapati -%# See the LICENSE file for details. +%# Copyright protects this work. +%# See LICENSE file for details. %#++ -%|chapter "Theory of operation" +%|chapter "Theory" + When you run <%= $project %>, it does the following: 1. Loads the <%= xref "SpecFile", "format specification file" %>. 2. Creates an *input document* by: @@ -22,11 +23,13 @@ 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 %> @@ -66,11 +69,13 @@ | `node_content` | a block argument being passed to the method invocation | | `node_object` | 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): | Property | Type | Description | | -------- | ---- | ----------- | | type | `String` | Name of the type of this node. | @@ -85,11 +90,13 @@ | parent | `ERBook::Document::Node` | 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. | | children | `Array` of `ERBook::Document::Node` | List of child nodes from the document tree. | 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 new 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. | Parameter | Type | Description | | --------- | ---- | ----------- | | desc | `String` | A short description of the output format. | @@ -102,11 +109,13 @@ # scope) because it is initialized and used in two # different child scopes that exist at different depths common_template_vars = nil %> + %|section "Node definition", "SpecFile.nodes" + A node definition is a mapping from a name (the "node type") to the following set of parameters: | Parameter | Type | Description | | --------- | ---- | ----------- | | index | Boolean | Assign a LaTeX-style section number to this node? | @@ -116,11 +125,13 @@ | inline | Boolean | Is node's output an in-line string of text that can be embedded anywhere in the document? | | bypass | Boolean | Is node simply a wrapper (of negligible depth) for content? | 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: | Variable | Type | Description | @@ -139,21 +150,25 @@ | `@format[:name]` | `String` | Short-hand name of the current format. | | `@format[:file]` | `String` | Path of the current format specification file. | }.lstrip.gsub(/^ +/, '') %> + %|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: | Variable | Type | Description | | -------- | ---- | ----------- | | `@content` | `String` | Content of the processed document. | <%= common_template_vars %> + %|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. @@ -168,13 +183,19 @@ <%= $program %> HelloWorld.spec HelloWorld.input > HelloWorld.output 4. Examine the <tt>HelloWorld.output</tt> file to your satisfaction! + %|example "HelloWorld format specification file", "HelloWorld.spec" + <code lang="rhtml"><%= verbatim File.read('doc/HelloWorld.spec') %></code> + %|example "Input document for HelloWorld format", "HelloWorld.input" + <code lang="rhtml"><%= verbatim File.read('doc/HelloWorld.input') %></code> + %|example "Output of HelloWorld format", "HelloWorld.output" + %= `ruby bin/#{PROGRAM} -u doc/HelloWorld.spec doc/HelloWorld.input`