AsciiDoc Architecture
=====================
Stuart Rackham <srackham@methods.co.nz>
December 2004


Just a few notes describing how AsciiDoc is put together.


Overveiw
--------
AsciiDoc is comprised of the following entities:

- Configuration files
- Document Attributes
- Document translator


Reimplementation in Ruby
------------------------
- Long term goal.
- Built with unit test framework.
- Combine global reader, config, document services using Dependency
  Injection containers (see Chad Fowler's  'Dependency Injection in
  Ruby' paper).
- Study the ERB class source code for ideas on parsing.
- Don't try to incorporate ERB type substitutions -- it's quite
  different in intent and usage, besides it's easy to implement a
  stand-alone ERB preprocessor.


Vocabulary
----------
Document Title::
  Document header title.

Section Title::
  Section or subsection title.

Block Title::
  Block element title.

List::
  There are four list types:
  - Itemized
  - Ordered
  - Labeled (horizontal and vertical).
  - Callout

Paragraph::

Delimited Block::

Variant Delimited Block:
  
Attribute::
  A name and a textual value.

Atrribute Reference::
  An attribute name or expression enclosed by braces.
  Simple, Calculated and Executable.

Attribute Value::
  The text resulting from evaluating an attribute reference.

Attribute List::
  List of attributes enclosed in square brackets. The listed
  attributes are available for substitution in the markup templates of
  associated macro and block elements.

Macro::
  Inline and block. Macros are characterized by a name, a syntax, a
  single target argument and an attribute list.
+
  The default syntax for a inline and block macros is
  `<name>:<target><attributelist>` and
  `<name>::<target><attributelist>` respectively.

Configuration files::
  A set of cascading INI format footnote:[See p.119 taoup] text files
  which (among other things) define the AsciiDoc source and target
  (backend) syntaxes.  At runtime The AsciiDoc default global
  configuration files are combined with optional document and user
  specific configuration files.

Document Attributes::
  A set of key-value pairs used for textual substitution in
  configuration and document files.

Document translator::
  This is the asciidoc(1) program which reads AsciiDoc source and
  outputs the corresponding backend formatted text (normally DocBook
  or HTML).

Markup Template::
  Configuration file section containing multi-line backend markup for
  a document element.  Markup templates can contain substitutable
  attribute references.

Markup Tag::
  Configuration file `[Tags]` section entry defining document element
  start and end markup tags. Markup tags can contain substitutable
  attribute references.

Element Definition::
  Configuration file section defining an AsciiDoc block element.
  Section entries are specific to the type of element being defined
  (Paragraph, List, Table, DelimitedBlock).

Special Words::


Block Element::

Inline Element::


