erbook is an extensible document processor that emits HTML (web page), LaTeX (PDF), man (UNIX manual page), plain text, and any document format you can imagine from eRuby templates that allow scripting and dynamic content generation.
To get help or provide feedback, simply contact the author.
Node classNode#title()Node#id()Node#type_label()Node#type_atts()Node#title_atts()Node#title_html()Node#content_html()Node#title_link(aTitle = nil)Node#index_link()Node#number_link()Node#number_and_title_link()Node#index_and_title_link()Node#content_div()Node#here_frag()Node#list_frag()Icon#css_class()Icon#css_image()Hash#to_html_atts()String#to_html_entities()String#to_uri_fragment()String#to_inline_html()String#to_html(aInline = false)String#thru_maruku(aInline = false)String#thru_coderay()String#protect(aInput, aTags, aVerbatim) {|aInput| ... }erbook is an extensible document processor that emits HTML (web page), LaTeX (PDF), man (UNIX manual page), plain text, and any document format you can imagine from eRuby templates that allow scripting and dynamic content generation.
Note 1. See the source of this manual
Did you know that this manual was generated by erbook? Here is the source document to prove it!
You may notice that the source document is hierarchically indented. As a result, it must be processed with the --unindent option to produce proper output:
erbook --unindent html manual.erb
Unlike document processors such as DocBook, Deplate, and SiSU, erbook is:
Unlike the documents of raw text processors such as AsciiDoc, txt2tags, and Grutatxt, erbook documents are scriptable eRuby templates, which means that you can inject arbitrary Ruby code into your documents for dynamic content generation.
Vitor Peres in ruby-talk:
I actually felt like printing [this manual], because it’s just so well-thought typographically… Even if [erbook] weren’t great by itself, I’d feel good just looking at the manual.
Ara T. Howard in ruby-talk:
[this manual is] a insanely complete and nice looking bit of documentation [… erbook] looks like a great project
Martin DeMello in ruby-talk:
Very nice work indeed!
erbook is open source software so feel free to contribute your improvements and discuss your ideas with the author. You can obtain the source code from this source repository and monitor for changes by subscribing to this news feed.
The erbook logo, its image file “erbook.png”, and its source file “erbook.svg” make use of the “cartoon owl sitting on a book” graphic that was created and released into the public domain by Jens Vierbuchen on July 7, 2008.
Copyright 2006 Suraj N. Kurapati sunaku@gmail.com
Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
erbook releases are numbered in major.minor.patch form, according to the RubyGems rational versioning policy which can be summarized thus:
| What increased in the version number? | What does the increase signify about the release? | ||
| Backwards compatible? | New features? | Bug fixes? | |
|---|---|---|---|
| major | No | Yes | Yes |
| minor | Yes | Yes | Yes |
| patch | Yes | No | Yes |
Your system needs the following software to run erbook.
| Software | Notes |
|---|---|
| Ruby | Version 1.8.x is required. |
| Maruku | Required by the default HTML format. |
| CodeRay | Required by the default HTML format. |
If your system has RubyGems, then you can install Maruku and CodeRay by running the following command:
gem install maruku coderay
If your system has RubyGems, then you can install erbook by running the following commands:
gem install erbook erbook -v
Otherwise, follow these instructions:
Download the newest release package from the download area.
Extract the release package somewhere on your system.
Go inside the extracted directory and run the following command:
ruby bin/erbook -v
If the installation was successful, then you will see output like this:
project: erbook version: 4.0.0 release: 2008-11-15 website: http://snk.tuxfamily.org/lib/erbook install: /home/sun/src/erbook
Otherwise, you can contact the author for help.
You will see the following items inside erbook’s installation directory, whose path you can determine by running this command:
erbook -v
bin/ — contains executable programs.
fmt/ — contains the predefined set of format specification files. If you ever need to install your custom format specification file globally, then put it inside this directory.
latex.yaml — high-quality typesetting
html.yaml — web page for the Internet
man.yaml — manual page for UNIX
text.yaml — plain text, nothing fancy
lib/ — erbook automatically adds this directory to Ruby’s load path.
erbook.rb — project version information.
erbook/
html.rb — provides methods (see Section 5.1.1. Text to HTML conversion) for the Chapter 5.1. HTML format.
rdoc.rb — provides RDoc parse trees to Ruby code.
doc/ — contains this manual and other documentation.
erbook.svg — source file of the erbook logo.
manual.erb — source file of this manual.
api/ — contains API reference documentation for the provided Ruby code.
LICENSE — project license and copyright notice.
When you run erbook, it does the following:
Loads the format specification file.
Creates an input document by:
Reading the input (the content of either the input file or the standard input stream) into memory.
Evaluating include directives in the input.
Transforms the input document into a processed document by:
Building a document tree data structure from nodes present in the input document.
Replacing every node in the input document with the result of its node output template.
Transforms the processed document into an output document according to the document output template.
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.
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, ... %>
Technically, nodes are Ruby method invocations composed of the following:
| Component | Description |
|---|---|
node_type | name of the method being invoked |
node_argument1, node_argument2, ... | arguments for the method invocation |
node_content | a block argument being passed to the method invocation |
node_object | a Node object (see Section 3.1.1. The Node class) representing this method invocation |
A format specification file defines what types of nodes an input document may use.
Node class
When erbook builds a document tree from the nodes in an input document, it stores information about these nodes into Node objects. A Node object has the following properties (methods):
| Property | Type | Description |
|---|---|---|
| type | String | Name of the type of this node. |
| args | Array | Arguments passed to this node. |
| content | String | The block of text passed to this node. |
| output | String | Result of the node output template for the content of this node. |
| digest | String | A unique identifier for the content of this node. |
| trace | Array | A stack trace describing the location of this node in the input document. |
| index | String | A LaTeX-style section number for this node. This property is only present if the index parameter is enabled in the definition of this type of node. |
| number | Integer | An order-of-occurrence number for this node. This property is only present if the number parameter is enabled in the definition of this type of node. |
| depth | Integer | Distance from the root of the document tree to this node. |
| parent | Node | The 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 Node | List of child nodes from the document tree. |
Furthermore, the Node class is derived from Ruby’s OpenStruct class, so you can define new properties for Node objects dynamically.
A format specification file is a plain-text file marked up in YAML syntax. 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. |
| code | String | Ruby code that will be loaded before the input document is processed. This source code will be evaluated inside the main erbook executable, so any file-system or path-dependent portions of this source code should take appropriate precautions. |
| nodes | Hash | A listing of node definitions. |
| output | String | An eRuby template for the final output document. See Section 3.2.2. Document output template. |
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? |
| number | Boolean | Assign an order-of-occurrence number to this node? |
| silent | Boolean | Suppress the output of this node? |
| output | String | An eRuby template for the content of this node. See Section 3.2.1.1. Node output template. |
You may define additional parameters in a node definition if you want.
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, erbook 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 |
|---|---|---|
@node | Node | the node for which this template is being evaluated |
@roots | Array of Node | All root nodes in the document tree. |
@nodes | Array of Node | All nodes in the document tree. |
@types | Hash | Mapping from node type (String) to array of Node objects having that type. |
@spec | Hash | Data from the format specification file. |
erbook also provides the following mappings inside the @spec variable:
| Expression | Type | Description |
|---|---|---|
@spec[:name] | String | Short-hand name of the current format. |
@spec[:file] | String | Path of the current format specification file. |
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. |
@roots | Array of Node | All root nodes in the document tree. |
@nodes | Array of Node | All nodes in the document tree. |
@types | Hash | Mapping from node type (String) to array of Node objects having that type. |
@spec | Hash | Data from the format specification file. |
erbook also provides the following mappings inside the @spec variable:
| Expression | Type | Description |
|---|---|---|
@spec[:name] | String | Short-hand name of the current format. |
@spec[:file] | String | Path of the current format specification file. |
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 Example 1. HelloWorld format specification file and make use of it in the Example 2. Input document for HelloWorld format. This shows how to provide format-specific functionality to an input document.
We define a $style variable in Example 2. Input document for HelloWorld format and make use of it in Example 1. HelloWorld format specification file. This shows how to pass parameters from an input document to your format specification file.
To run this example:
Save the code shown in Example 1. HelloWorld format specification file to a file named HelloWorld.spec
Save the text shown in Example 2. Input document for HelloWorld format to a file named HelloWorld.input
Run this command:
erbook HelloWorld.spec HelloWorld.input > HelloWorld.output
Examine the HelloWorld.output file to your satisfaction!
Example 1. HelloWorld format specification file
desc: An example format.
code: |
# Returns a random, yet pronounceable, name.
def generate_name
letters = ('a'..'z').to_a - %w[ c q w x ] # redundant sounds
vowels = %w[a e i o u]
consonants = letters - vowels
sets = [consonants, vowels]
length = 3 + rand(5)
name = (0...length).map do |i|
# alternate between consonants and vowels
set = sets[i % sets.length]
# choose a random letter from the set
set[rand(set.length)]
end.join
name
end
class Node
def name
# dynamically compute (and store)
# the name of this node on demand
@name ||= generate_name
end
end
nodes:
hello:
index: true
number: true
silent: false
output: |
<h3><%= @node.type %> #<%= @node.index %>: <%= @node.name.inspect %></h3>
My name is <%= @node.name.inspect %> and these are my properties:
<dl style="<%= $style %>">
<dt>args</dt>
<dd><code><%= @node.args.inspect %></code></dd>
<dt>index</dt>
<dd><code><%= @node.index.inspect %></code></dd>
<dt>number</dt>
<dd><code><%= @node.number.inspect %></code></dd>
<dt>trace</dt>
<dd><pre><%= @node.trace.join("\n") %></pre></dd>
<dt>content</dt>
<dd><%= @node.content %></dd>
</dl>
output: |
Welcome to the "<%= @spec[:name] %>" format.
<%= @content %>
That's all folks!
Example 2. Input document for HelloWorld format
<% $style = "border-left: thick dotted LightGrey; padding-left: 1em;" %>
<% hello "Pretentious", 1, 2, 3 do %>
<big>I'm</big> the very first node, oh _yes_ I am! *sneer*
<% hello "Bashful", 4, 5, 6 do %>
Hi, I... *hide*
<% hello "Hopeful", rand do %>
*sigh*
<% hello "Confused", (rand * rand) do %>
Huh?
<% end %>
<% end %>
<% hello "Raving", __FILE__ do %>
Oh it's *on* now! You're going *down*!
<% end %>
<% end %>
<% hello "Sleepy", Time.now do %>
*yawn* Just five more minutes...
<% hello "Peaceful", Dir.pwd do %>
So _be_ happy my friend, *happy*!
<%= hello "Lonely (as you can see, I have no block)" %>
<% end %>
<% end %>
<% end %>
<% hello "Snappy" do %>
Zip! Zap! Wake up, you sap!
_Whoo I'm wild!_ ;-)
<% end %>
<%= hello "Independent (no block, no parents, I am _free_!)" %>Example 3. Output of HelloWorld format
Welcome to the “HelloWorld” format.
My name is “yezulu” and these are my properties:
["Pretentious", 1, 2, 3]"1"1INPUT:1 bin/erbook:278 bin/erbook:278:in `instance_eval' bin/erbook:278
["Bashful", 4, 5, 6]"1.1"2INPUT:3 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:1 bin/erbook:278 bin/erbook:278:in `instance_eval' bin/erbook:278
["Hopeful", 0.626416670548946]"1.1.1"3INPUT:5 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:3 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:1 bin/erbook:278 bin/erbook:278:in `instance_eval' bin/erbook:278
["Confused", 0.0687952044306042]"1.1.1.1"4INPUT:7 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:5 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:3 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:1 bin/erbook:278 bin/erbook:278:in `instance_eval' bin/erbook:278
["Raving", "INPUT"]"1.1.2"5INPUT:9 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:3 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:1 bin/erbook:278 bin/erbook:278:in `instance_eval' bin/erbook:278
["Sleepy", Sat Nov 15 18:25:08 -0800 2008]"1.2"6INPUT:11 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:1 bin/erbook:278 bin/erbook:278:in `instance_eval' bin/erbook:278
["Peaceful", "/home/sun/src/erbook"]"1.2.1"7INPUT:13 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:11 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:1 bin/erbook:278 bin/erbook:278:in `instance_eval' bin/erbook:278
["Lonely (as you can see, I have no block)"]"1.2.1.1"8INPUT:15 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:13 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:11 bin/erbook:80:in `content_from_block' bin/erbook:259:in `hello' INPUT:1 bin/erbook:278 bin/erbook:278:in `instance_eval' bin/erbook:278
My name is “pomit” and these are my properties:
["Snappy"]"2"9INPUT:17 bin/erbook:278 bin/erbook:278:in `instance_eval' bin/erbook:278
My name is “faz” and these are my properties:
["Independent (no block, no parents, I am _free_!)"]"3"10INPUT:20 bin/erbook:278 bin/erbook:278:in `instance_eval' bin/erbook:278
That’s all folks!
erbook is an extensible document processor based on eRuby.
STDIN will be read if no input files are specified.
If an error occurs, the input document will be printed to STDOUT so you can investigate line numbers in the error’s stack trace. Otherwise, the final output document will be printed to STDOUT.
erbook [Option...] {Format|SpecFile} [InputFile...]
Option:
As the {Format|SpecFile} token in the usage syntax above denotes, erbook requires its first command-line argument to be either (1) the name of a predefined format or (2) the path to a format specification file.
Predefined formats are simply short-hand names of format specification files located in the fmt/ subdirectory of the erbook installation directory (see Section 2.3. Manifest).
The include directive allows you to insert the content of an arbitrary file at a certain place in the input document. It is written like this:
<%# include YOUR_PATH_HERE #%>
In the above example, YOUR_PATH_HERE is the path of the file whose content you wish to insert into the input document.
You can divide a large document into separate files for easier editing and stitch them together, dynamically, into a single document using the include directive.
When writing erbook documents, I prefer to indent the content of nodes according to their depth (as can be seen in the source of this manual) because my text editor of choice automatically folds blocks of text based on indentation.
If you also prefer to write documents in this way, be sure to pass the --unindent option to erbook so that the indentation will not affect the resulting output.
This part describes the default formats provided along with erbook. The format specification files for these formats can be found in the fmt/ directory of the erbook installation directory (see Section 2.3. Manifest).
These formats are meant to serve as working examples. If you require more functionality from one of these formats, simply make a copy of the corresponding format specification file and edit the copy to suit your needs. If you would like to contribute or discuss your enhancements to these default formats, you can contact the author.
This format generates a monolithic HTML document that allows users to easily search for a particular topic using nothing more than their web browser’s built-in text search mechanism. This facilitates offline reading, where an Internet search engine is not available.
In the HTML document, you will notice that the numbers of chapters, sections, figures, admonitions, etc. are hyperlinks that take you back to the corresponding place in the table of contents. These links make it easy to navigate the HTML document, especially for users of text-only web browsers.
Furthermore, the HTML document comes equipped with a stylesheet that makes it suitable for printing. In particular, users of the Mozilla and Opera family of web browsers will be pleasantly surprised to notice that all hyperlinks have been expanded to include their target URL next to the link text. So try using the “print preview” function of a graphical web browser to see how the HTML document will appear when printed.
Inside the fmt/ subdirectory of the erbook installation directory (see Section 2.3. Manifest), you will see a html.rb file. This file defines methods that transform text in an input document into HTML:
String#to_html - Transforms this string into HTML while ensuring that the result contains one or more block-level elements at the root.
String.to_inline_html - Transforms this string into an inline HTML string (one that does not contain any block-level HTML elements at the root).
The default implementation of the String#to_html method employs the Markdown markup system. If you do not like Markdown or wish to use a different markup system for text in your documents, then simply edit the html.rb file and adjust the source code of the default String#to_html and String.to_inline_html methods accordingly.
For example, if you replace the entire html.rb file with the following code, then the output of all nodes will appear within red boxes in the final output document.
class String # Transforms this string into HTML while ensuring that the # result contains one or more block-level elements at the root. def to_html '<p style="border: thin solid red">' + self + '</p>' end # Transforms this string into an *inline* HTML string (one that # does not contain any block-level HTML elements at the root). def to_inline_html self end end
In addition to supporting Markdown syntax, the default implementation has some additional features which are described in the following subsections.
Syntax coloring is automatically added to source code found inside the <code> and </code> HTML tags. The syntax coloring library, CodeRay, currently supports the following programming languages:
Because different programming languages have different syntax coloring schemes, you can specify the language of your source code using the lang attribute to ensure that only the appropriate coloring scheme is used. Note that unless the lang attribute is specified, Ruby is assumed to be the programming language of all source code by default.
For example, here is some source code without the lang attribute:
# Ruby ########################### def hello puts "Hello world!" end /* C ****************************/ #include <stdio.h> int main(int argc, char **argv) { printf("Hello world!\n"); return 0; } <!-- HTML -----------------------> <html> <body> Hello world! <body> </html>
And here is the same source code with a lang="c" attribute:
# Ruby ###########################
def hello
puts "Hello world!"
end
/* C ****************************/
#include <stdio.h>
int main(int argc, char **argv) {
printf("Hello world!\n");
return 0;
}
<!-- HTML ----------------------->
<html>
<body>
Hello world!
<body>
</html>
And here is the same source code with a lang="html" attribute:
# Ruby ###########################
def hello
puts "Hello world!"
end
/* C ****************************/
#include <stdio.h>
int main(int argc, char **argv) {
printf("Hello world!\n");
return 0;
}
<!-- HTML ----------------------->
<html>
<body>
Hello world!
<body>
</html>
Source code is automatically sized to be displayed as either a line or paragraph of text, depending on whether it contains line breaks.
For example, here is a single line life = true or false of code. And here is a paragraph
life = true or falseof code.
Sometimes you just need to protect some text from being mangled by the text-to-HTML conversion process . In such cases, you can wrap the text you want to proctect within <noformat> and </noformat> tags.
The HTML format accepts the following document parameters.
| Parameter | Type | Default value | Description |
|---|---|---|---|
$title | String | "$title" | Title of the document. |
$authors | Hash | {"$authors" => nil} | A mapping of author name to author URL. You can obfuscate e-mail addresses using the provided String#to_html_entities method like this: { "Y. Matsumoto" => "mailto:matz@ruby.invalid".to_html_entities } |
$date | String | Time.now.strftime("%d %B %Y") | Date when the document was written. |
$logo | String | nil | Arbitrary content that goes above the document title in the default header. |
$feeds | Hash | nil | A mapping of feed URL to feed format. Here is an example: $feeds = { "my_rss_feed.xml" => "rss", "my_atom_feed.xml" => "atom" } |
$use_icons | Boolean | true | Use Tango icons in admonitions (see Section 5.1.4.3. Admonition nodes)? |
The HTML format provides the following methods. In the method declarations shown below,
Node#title()
Returns the user-defined title for this node‘s content.
Node#here_frag()
Returns a unique URI fragment for this node.
Node#list_frag()
Returns the URI fragment for the location in the table of contents / list of figures that points this node.
Icon#css_class()
Returns the CSS class for this icon.
Icon#css_image()
Returns a CSS url() containing embedded image data.
Hash#to_html_atts()
Transforms this hash into a string of HTML attribute key=value pairs.
String#to_html_entities()
Transforms this UTF-8 string into HTML entities.
String#to_uri_fragment()
Transforms this string into a valid URI fragment. See www.nmt.edu/tcc/help/pubs/xhtml/id-type.html
String#to_inline_html()
Transforms this string into an inline HTML string (one that does not contain any block-level HTML elements at the root).
String#to_html(aInline = false)
Transforms this string into HTML while ensuring that the result contains one or more block-level elements at the root.
If aInline is true, then the resulting HTML will be an inline string.
String#thru_maruku(aInline = false)
Returns the result of running this string through Maruku.
If aInline is true, then the resulting HTML will not be wrapped in a HTML paragraph element.
String#thru_coderay()
Adds syntax coloring to <code> elements in the given text. If the <code> tag has an attribute lang="…", then that is considered the programming language for which appropriate syntax coloring should be applied. Otherwise, the programming language is assumed to be ruby.
String#protect(aInput, aTags, aVerbatim) {|aInput| ... }
Protects the given tags in the given input, passes that protected input to the given block, restores the given tags in the result of the block and returns it.
If aVerbatim is true, the content of the elments having the given tags will not be temporarily altered so that process nested elements can be processed.
Unless otherwise noted, all nodes defined by the HTML format accept two arguments, in this order:
The second argument is used by the cross-referencing nodes (see Section 5.1.4.1.4. xref and Section 5.1.4.5.2. cite), which allow you to refer to another node in the document by its unique identifier.
Furthermore, node definitions in the HTML format have two additional parameters:
| Parameter | Type | Description |
|---|---|---|
| toc | Boolean | Include this node in the Table of Contents (TOC)? |
| lof | Boolean | Include this node in the List of Figures (LOF)? |
The nodes described in this section form the overall structure of the output document.
This node overrides the logo, title, list of authors, and date when the document was written, all of which are shown at the top of the document.
This node overrides (1) the date when this document was generated and (2) the hyperlink to the erbook website, shown at the bottom of the document. The hyperlink is there as a way of saying thanks for erbook, the wonderful little utility you have grown so fond of! ;-)
A summary of the entire document. This is what most readers will skim through, if you are lucky. Alas, nobody reads entire documents these days! :-(
A cross-reference; a hyperlink that takes you to any node in the document.
The first argument of this node is either the unique identifier or the user-defined title of the node you wish to cross-reference. If no nodes in the document have the given identifier or user-defined title, then an error will be raised.
The second argument of this node overrides the default link text of the cross-reference.
For example, this node in the input document:
<%= xref "SpecFile" %>
appears in the output document like this: Section 3.2. Format specification file.
As another example, this node in the input document:
<%= xref "SpecFile", "custom link text" %>
appears in the output document like this: custom link text.
The nodes described in this section are meant to help organize the document’s content logically. Based on how deeply these nodes are nested in the document, their heading will be larger (shallow depth) or smaller (deep depth).
A collection of chapters.
This is how a part node appears.
A collection of sections.
This is how a chapter node appears.
A collection of paragraphs about a particular topic.
This is how a section node appears.
An admonition is basically a box that is indented more deeply than the text surrounding it. It is typically used to convey extraneous or pertinent information about the application of ideas discussed in the surrounding text.
I like to follow the KDE guidelines[1] when determining which admonition to use in my documents.
Use a warning node when “data loss could occur if you follow the procedure being described.” [1]
This is how a warning node appears.
bq. A note of caution. Use this for example when the reader may lose easily recovered or replaceable information (e.g. user settings), or when they could cause data loss if they don’t correctly follow the procedure being outlined. [1]
This is how a caution node appears.
Use an important node when:
bq. When there is no danger of data loss, but you wish to make clear to the reader a consequence that isn’t immediately obvious (e.g. when changing the font for one instance of a program also changes the default setting, and this isn’t clear from the GUI.) [1]
This is how a important node appears.
Use a note node to convey:
bq. Information the user should be aware of, but is peripheral to the actual task being described. [1]
This is how a note node appears.
A diagram, sketch, image, or illustration; something that visually depicts an idea or thought.
This is how a figure node appears.
Information (typically measurement data) represented in tabular form for easy reading, comparison, and analysis.
This is how a table node appears.
The nodes in this section deal with attribution of ideas—an important weapon against plagiarism.
This node stores bibliography information about an information source that is relevant to your document.
If you wish to cite a certain source in several places in your document, start by creating a reference node first and then use a cite node (see Section 5.1.4.5.2. cite) to perform the citation.
See Reference 2 for an example of how a reference node appears.
A citation to a reference node (see Section 5.1.4.5.1. reference) in the document’s bibliography.
The first argument of this node is the unique identifier of the reference node you wish to cite. You can specify additional arguments to give more detail about the citation.
For example, this node in the input document:
<%= cite "html.nodes.reference.example" %>
appears in the output document like this: [2]
As another example, this node in the input document:
<%= cite "html.nodes.reference.example", "chapter 10", "page 53", "..." %>
appears in the output document like this: [2, chapter 10, page 53, ...]
L. Watts, “Admonitions: Tips, hints, and Warnings”, in The KDE DocBook Authors guide, Chapter 13, [Online document], 22 September 2004 (Revision 1.00.00), [cited 8 December 2007], Available at http://l10n.kde.org/docs/markup/tips-hints-etc.html
This is how a reference node appears.