Macros

Prev		Next

Macros are a mechanism for substituting parameterized text into output documents.

Macros have a name, a single target argument and an attribute list. The default syntax is <name>:<target>[<attributelist>] (for inline macros) and <name>::<target>[<attributelist>] (for block macros). Here are some examples:

http://www.methods.co.nz/asciidoc/index.html[Asciidoc home page]
include::chapt1.txt[tabsize=2]
mailto:srackham@methods.co.nz[]

Inline Macros

Inline Macros occur in an inline element context. Predefined Inline macros include URLs, image and link macros.

URLs

Standard http, https, ftp, file and mailto URLs are rendered using predefined inline macros.

The default AsciiDoc inline macro syntax is very similar to a URL: all you need to do is append an attribute list containing an optional caption immediately following the URL. If no caption text is provided the URL itself is displayed.

Here are some examples:

http://www.methods.co.nz/asciidoc/[The AsciiDoc home page]
mailto:joe.bloggs@foobar.com[email Joe Bloggs]
mailto:joe.bloggs@foobar.com[]

Which are rendered:

The AsciiDoc home page

email Joe Bloggs

joe.bloggs@foobar.com


	If the `<target>` necessitates space characters they should be replaced by `%20`. For example `large%20image.png`.

Internal Cross References

Two AsciiDoc inline macros are provided for creating hypertext links within an AsciiDoc document. You can use either the standard macro syntax or the (preferred) alternative.

anchor

Used to specify hypertext link targets:

[[<id>,<xreflabel>]]
anchor:<id>[<xreflabel>]

The <id> is a unique identifier that must begin with a letter. The optional <xreflabel> is the text to be displayed by captionless xref macros that refer to this anchor. The optional <xreflabel> is only really useful when generating DocBook output. Example anchor:

[[X1]]

You may have noticed that the syntax of this inline element is the same as that of the BlockId block element, this is no coincidence since they are functionally equivalent.

xref

Creates a hypertext link to a document anchor.

<<<id>,<caption>>>
xref:<id>[<caption>]

The <id> refers to an existing anchor <id>. The optional <caption> is the link's displayed text. If <caption> is not specified then the <id>, enclosed in square brackets, is displayed. Example:

<<X15,attribute lists>>

Linking to Local Documents

Hypertext links to files on the local filesystem are specified using the link inline macro.

link:<target>[<caption>]

The link macro generates relative URLs. The link macro <target> is the target file name (relative to the file system location of the referring document). The optional <caption> is the link's displayed text. If <caption> is not specified then <target> is displayed. Example:

link:downloads/foo.zip[download foo.zip]

You can use the <filename>#<id> syntax to refer to an anchor within a target document but this usually only makes sense when targeting HTML documents.

Images can serve as hyperlinks using the image macro.

Images

Inline images are inserted into the output document using the image macro. The inline syntax is:

image:<target>[<attributes>]

The contents of the image file <target> is displayed. To display the image it's file format must be supported by the target backend application. HTML and DocBook applications normally support PNG or JPG files.

<target> file name paths are relative to the location of the referring document.

Image macro attributes

The optional first positional attribute list entry specifies the alternative text which is displayed if the output application is unable to process the image file. For example:
```
image:images/logo.png[Company Logo]
```
The optional width and height named attributes scale the image size and can be used in any combination. The following example scales the previous example to a height of 32 pixels:
```
image:images/logo.png["Company Logo",height=32]
```
The optional link named attribute is used to link the image to an external document. The following example links a screenshot thumbnail to a full size version:
```
image:screen-thumbnail.png[height=32,link="screen.png"]
```

Include Macros

These system macros include the contents of a named file in the source document; it's as if the included file were part of the parent document.

There are two include macros: include which allows nested include macros and include1 which does not allow nested includes.

Example 1. Include macro examples

 include::chapter1.txt[tabsize=4]

 +++++++++++++++++++++++
 include1::table6.html[]
 +++++++++++++++++++++++

chapter1.txt is processed exactly as if its text were part of the parent document except that tabs are expanded to 4 characters.
Since it is enclosed in a BackendBlock the text from table6.html is included and written to the output without any further processing.