Chapter 32. Block Element Definitions

The syntax and behavior of Paragraph, DelimitedBlock, List and Table block elements is determined by block definitions contained in AsciiDoc configuration file sections.

Each definition consists of a section title followed by one or more section entries. Each entry defines a block parameter controlling some aspect of the block’s behavior. Here’s an example:

[blockdef-listing]
delimiter=^-{4,}$
template=listingblock
presubs=specialcharacters,callouts

Configuration file block definition sections are processed incrementally after each configuration file is loaded. Block definition section entries are merged into the block definition, this allows block parameters to be overridden and extended by later loading configuration files.

AsciiDoc Paragraph, DelimitedBlock, List and Table block elements share a common subset of configuration file parameters:

delimiter

A Python regular expression that matches the first line of a block element — in the case of DelimitedBlocks and Tables it also matches the last line.

template

The name of the configuration file markup template section that will envelope the block contents. The pipe (|) character is substituted for the block contents. List elements use a set of (list specific) tag parameters instead of a single template. The template name can contain attribute references allowing dynamic template selection a the time of template substitution.

options

A comma delimited list of element specific option names. In addition to being used internally, options are available during markup tag and template substitution as attributes with an empty string value named like <option>-option (where <option> is the option name). See attribute options for a complete list of available options.

subs, presubs, postsubs

presubs and postsubs are lists of comma separated substitutions that are performed on the block contents. presubs is applied first, postsubs (if specified) second.
subs is an alias for presubs.
If a filter is allowed (Paragraphs, DelimitedBlocks and Tables) and has been specified then presubs and postsubs substitutions are performed before and after the filter is run respectively.
Allowed values: specialcharacters, quotes, specialwords, replacements, macros, attributes, callouts.
The following composite values are also allowed:
none
No substitutions.
normal
The following substitutions in the following order: specialcharacters, quotes, attributes, specialwords, replacements, macros, replacements2.
verbatim
The following substitutions in the following order: specialcharacters and callouts.
normal and verbatim substitutions can be redefined by with subsnormal and subsverbatim entries in a configuration file [miscellaneous] section.
The substitutions are processed in the order in which they are listed and can appear more than once.

filter

This optional entry specifies an executable shell command for processing block content (Paragraphs, DelimitedBlocks and Tables). The filter command can contain attribute references.

posattrs

Optional comma separated list of positional attribute names. This list maps positional attributes (in the block’s attribute list) to named block attributes. The following example, from the QuoteBlock definition, maps the first and section positional attributes:

posattrs=attribution,citetitle

style

This optional parameter specifies the default style name.

<stylename>-style

Optional style definition (see Styles below).

The following block parameters behave like document attributes and can be set in block attribute lists and style definitions: template, options, subs, presubs, postsubs, filter.

32.1. Styles

A style is a set of block parameter bundled as a single named parameter. The following example defines a style named verbatim:

verbatim-style=template="literalblock",subs="verbatim"

If a block’s attribute list contains a style attribute then the corresponding style parameters are be merged into the default block definition parameters.

All style parameter names must be suffixed with -style and the style parameter value is in the form of a list of named attributes.
The template style parameter is mandatory, other parameters can be omitted in which case they inherit their values from the default block definition parameters.
Multi-item style parameters (subs,presubs,postsubs,posattrs) must be specified using Python tuple syntax (rather than a simple list of values as they in separate entries) e.g. postsubs=("callouts",) not postsubs="callouts".

32.2. Paragraphs

Paragraph translation is controlled by [paradef-*] configuration file section entries. Users can define new types of paragraphs and modify the behavior of existing types by editing AsciiDoc configuration files.

Here is the shipped Default paragraph definition:

[paradef-default]
delimiter=(?P<text>\S.*)
template=paragraph

The normal paragraph definition has a couple of special properties:

It must exist and be defined in a configuration file section named [paradef-default].
Irrespective of its position in the configuration files default paragraph document matches are attempted only after trying all other paragraph types.

Paragraph specific block parameter notes:

delimiter: This regular expression must contain the named group text which matches the text on the first line. Paragraphs are terminated by a blank line, the end of file, or the start of a DelimitedBlock.
options: The listelement option specifies that paragraphs of this type will automatically be considered part of immediately preceding list items. The skip option causes the paragraph to be treated as a comment (see CommentBlocks).

Paragraph processing proceeds as follows:

The paragraph text is aligned to the left margin.
Optional presubs inline substitutions are performed on the paragraph text.
If a filter command is specified it is executed and the paragraph text piped to its standard input; the filter output replaces the paragraph text.
Optional postsubs inline substitutions are performed on the paragraph text.
The paragraph text is enveloped by the paragraph’s markup template and written to the output file.

32.3. Delimited Blocks

DelimitedBlock options values are:

sectionbody: The block contents are processed as a SectionBody.
skip: The block is treated as a comment (see CommentBlocks). Preceding attribute lists and block titles are not consumed.

presubs, postsubs and filter entries are ignored when sectionbody or skip options are set.

DelimitedBlock processing proceeds as follows:

Optional presubs substitutions are performed on the block contents.
If a filter is specified it is executed and the block’s contents piped to its standard input. The filter output replaces the block contents.
Optional postsubs substitutions are performed on the block contents.
The block contents is enveloped by the block’s markup template and written to the output file.


	Attribute expansion is performed on the block filter command before it is executed, this is useful for passing arguments to the filter.

32.4. Lists

List behavior and syntax is determined by [listdef-*] configuration file sections. The user can change existing list behavior and add new list types by editing configuration files.

List specific block definition notes:

type: This is either bulleted,numbered,labeled or callout.
delimiter: A Python regular expression that matches the first line of a list element entry. This expression can contain the named groups text (bulleted groups), index and text (numbered lists), label and text (labeled lists).
tags: The <name> of the [listtags-<name>] configuration file section containing list markup tag definitions. The tag entries (list, entry, label, term, text) map the AsciiDoc list structure to backend markup; see the listtags sections in the AsciiDoc distributed backend .conf configuration files for examples.

32.5. Tables

Table behavior and syntax is determined by [tabledef-*] and [tabletags-*] configuration file sections. The user can change existing table behavior and add new table types by editing configuration files. The following [tabledef-*] section entries generate table output markup elements:

colspec: The table colspec tag definition.
headrow, footrow, bodyrow: Table header, footer and body row tag definitions. headrow and footrow table definition entries default to bodyrow if they are undefined.
headdata, footdata, bodydata: Table header, footer and body data tag definitions. headdata and footdata table definition entries default to bodydata if they are undefined.
paragraph: If the paragraph tag is specified then blank lines in the cell data are treated as paragraph delimiters and marked up using this tag.

Table behavior is also influenced by the following [miscellaneous] configuration file entries:

pagewidth: This integer value is the printable width of the output media. See table attributes.
pageunits: The units of width in output markup width attribute values.

Table definition behavior

The output markup generation is specifically designed to work with the HTML and CALS (DocBook) table models, but should be adaptable to most XML table schema.
Table definitions can be “mixed in” from multiple cascading configuration files.
New table definitions inherit the default table and table tags definitions ([tabledef-default] and [tabletags-default]) so you only need to override those conf file entries that require modification.