 |  |
| | |
Macros are a mechanism for substituting parametrized text into output documents.
Macros have a name, a single target argument and an attribute
list. The usual syntax is <name>:<target>[<attrlist>] (for
inline macros) and <name>::<target>[<attrlist>] (for block
macros). Here are some examples:
https://docbook.org/[DocBook.org] include::chapt1.txt[tabsize=2] mailto:srackham@gmail.com[]
Macro behavior
<name> is the macro name. It can only contain letters, digits or
dash characters and cannot start with a dash.
<target> cannot contain white space characters.
<attrlist> is a list of attributes enclosed in square
brackets.
] characters inside attribute lists must be escaped with a
backslash.
<name>, <target> and <attrlist> the
<passtext> and <subslist> named groups are available to
passthrough macros. A macro is a passthrough macro if the
definition includes a <passtext> named group.
Inline Macros occur in an inline element context. Predefined Inline macros include URLs, image and link macros.
http, https, ftp, file, mailto and callto URLs are rendered using predefined inline macros.
<attrlist> is empty the URL is displayed.
Here are some examples:
https://docbook.org/[DocBook.org] https://docbook.org/ mailto:joe.bloggs@foobar.com[email Joe Bloggs] joe.bloggs@foobar.com
Which are rendered:
If the <target> necessitates space characters use %20, for example
large%20image.png.
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.
Used to specify hypertext link targets:
[[<id>,<xreflabel>]] anchor:<id>[<xreflabel>]
The <id> is a unique string that conforms to the output markup’s
anchor syntax. 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.
Creates a hypertext link to a document anchor.
<<<id>,<caption>>> xref:<id>[<caption>]
The <id> refers to an anchor ID. The optional <caption> is the
link’s displayed text. Example:
<<X21,attribute lists>>
If <caption> is not specified then the displayed text is
auto-generated:
<id>
enclosed in square brackets.
Here is an example:
[[tiger_image]] .Tyger tyger image::tiger.png[] This can be seen in <<tiger_image>>.
Hypertext links to files on the local file system 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.
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 its 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 alt attribute is also the first positional attribute, it specifies alternative text which is displayed if the output application is unable to display the image file (see also Use of ALT texts in IMGs). For example:
image:images/logo.png[Company Logo]
The optional width and height attributes scale the image size
and can be used in any combination. The units are pixels. The
following example scales the previous example to a height of 32
pixels:
image:images/logo.png["Company Logo",height=32]
The optional link 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"]
The optional scaledwidth attribute is only used in DocBook block
images (specifically for PDF documents). The following example
scales the images to 75% of the available print width:
image::images/logo.png[scaledwidth="75%",alt="Company Logo"]
scale attribute sets the DocBook imagedata element
scale attribute.
The optional align attribute aligns block macro images
horizontally. Allowed values are center, left and right. For
example:
image::images/tiger.png["Tiger image",align="left"]
float attribute floats the image left or right on
the page (works with HTML outputs only, has no effect on DocBook
outputs). float and align attributes are mutually exclusive.
Use the unfloat::[] block macro to stop floating.
See comment block macro.
A Block macro reference must be contained in a single line separated either side by a blank line or a block delimiter.
Block macros behave just like Inline macros, with the following differences:
<name>::<target>[<attrlist>] (two
colons, not one).
-blockmacro instead of
-inlinemacro.
The Block Identifier macro sets the id attribute and has the same
syntax as the anchor inline macro since it performs
essentially the same function — block templates use the id
attribute as a block element ID. For example:
[[X30]]
This is equivalent to the [id="X30"] AttributeList element).
The image block macro is used to display images in a block context. The syntax is:
image::<target>[<attributes>]
The block image macro has the same macro attributes as it’s
inline image macro counterpart.
![[Warning]](images/icons/warning.png){kind=icon} | |
Unlike the inline |
Block images can be titled by preceding the image macro with a BlockTitle. DocBook toolchains normally number titled block images and optionally list them in an automatically generated List of Figures backmatter section.
This example:
.Main circuit board image::images/layout.png[J14P main circuit board]
is equivalent to:
image::images/layout.png["J14P main circuit board", title="Main circuit board"]
A title prefix that can be inserted with the caption attribute
(HTML backends). For example:
.Main circuit board [caption="Figure 2: "] image::images/layout.png[J14P main circuit board]
Embedding images in XHTML documents
If you define the data-uri attribute then images will be embedded in
XHTML outputs using the
data URI scheme. You
can use the data-uri attribute with the xhtml11 and html5
backends to produce single-file XHTML documents with embedded images
and CSS, for example:
$ asciidoc -a data-uri mydocument.txt
![[Note]](images/icons/note.png){kind=icon} | |
|
Single lines starting with two forward slashes hard up against the left margin are treated as comments. Comment lines do not appear in the output unless the showcomments attribute is defined. Comment lines have been implemented as both block and inline macros so a comment line can appear as a stand-alone block or within block elements that support inline macro expansion. Example comment line:
// This is a comment.
If the showcomments attribute is defined comment lines are written to the output:
System macros are block macros that perform a predefined task and are
hardwired into the asciidoc(1) program.
asciidoc(1) so they don’t appear in configuration files. You can
however customize the syntax by adding entries to a configuration
file [macros] section.
The include and include1 system macros to include the contents of
a named file into the source document.
The include macro includes a file as if it were part of the parent
document — tabs are expanded and system macros processed. The
contents of include1 files are not subject to tab expansion or
system macro processing nor are attribute or lower priority
substitutions performed. The include1 macro’s intended use is to
include verbatim embedded CSS or scripts into configuration file
headers. Example:
include::chapter1.txt[tabsize=4]
Include macro behavior
include1 macro).
include1 macro which
does not process nested includes). Setting depth to 1 disables
nesting inside the included file. By default, nesting is limited to
a depth of ten.
lines macro attribute can be used to include specific lines of
the file. You can specify a range of pages by using .. between
the two numbers, for example 1..10 would include the first 10
lines. You can include multiple ranges or invdividual pages by using
a comma or semi-colon, for example 1..10,45,50..60.
include1 macro is translated to the include1
system attribute which means it must be evaluated in a region where
attribute substitution is enabled. To inhibit nested substitution in
included files it is preferable to use the include macro and set
the attribute depth=1.
Lines of text in the source document can be selectively included or excluded from processing based on the existence (or not) of a document attribute.
Document text between the ifdef and endif macros is included if a
document attribute is defined:
ifdef::<attribute>[] : endif::<attribute>[]
Document text between the ifndef and endif macros is not included
if a document attribute is defined:
ifndef::<attribute>[] : endif::<attribute>[]
<attribute> is an attribute name which is optional in the trailing
endif macro.
If you only want to process a single line of text then the text can be
put inside the square brackets and the endif macro omitted, for
example:
ifdef::revnumber[Version number 42]
Is equivalent to:
ifdef::revnumber[] Version number 42 endif::revnumber[]
ifdef and ifndef macros also accept multiple attribute names:
Document text between the ifeval and endif macros is included if
the Python expression inside the square brackets is true. Example:
ifeval::[{rs458}==2]
:
endif::[]Take a look at the *.conf configuration files in the AsciiDoc
distribution for examples of conditional inclusion macro usage.
The eval, sys and sys2 block macros exhibit the same behavior as their same named system attribute references. The difference is that system macros occur in a block macro context whereas system attributes are confined to inline contexts where attribute substitution is enabled.
The following example displays a long directory listing inside a literal block:
------------------ sys::[ls -l *.txt] ------------------
| |
There are no block macro versions of the eval3 and sys3 system attributes. |
The template block macro allows the inclusion of one configuration
file template section within another. The following example includes
the [admonitionblock] section in the [admonitionparagraph]
section:
[admonitionparagraph] template::[admonitionblock]
Template macro behavior
template::[] macro is useful for factoring configuration file
markup.
template::[] macros cannot be nested.
template::[] macro expansion is applied after all configuration
files have been read.
Passthrough macros are analogous to passthrough blocks and are
used to pass text directly to the output. The substitution performed
on the text is determined by the macro definition but can be overridden
by the <subslist>. The usual syntax is
<name>:<subslist>[<passtext>] (for inline macros) and
<name>::<subslist>[<passtext>] (for block macros). Passthroughs, by
definition, take precedence over all other text substitutions.
Inline and block. Passes text unmodified (apart from explicitly specified substitutions). Examples:
pass:[<q>To be or not to be</q>]
pass:attributes,quotes[<u>the '{author}'</u>]
Inline and block. The triple-plus passthrough is functionally
identical to the pass macro but you don’t have to escape ]
characters and you can prefix with quoted attributes in the inline
version. Example:
Red [red]+++`sum_(i=1)\^n i=(n(n+1))/2`$+++ AsciiMath formula
Inline and block. The double-dollar passthrough is functionally identical to the triple-plus passthrough with one exception: special characters are escaped. Example:
$$`[[a,b],[c,d]]((n),(k))`$$
Each entry in the configuration [macros] section is a macro
definition which can take one of the following forms:
<pattern>=<name>[<subslist]
<pattern>=#<name>[<subslist]
<pattern>=+<name>[<subslist]
<pattern>
<pattern>.
<pattern> is a Python regular expression and <name> is the name of
a markup template. If <name> is omitted then it is the value of the
regular expression match group named name. The optional
[<subslist] is a comma-separated list of substitution names enclosed
in [] brackets, it sets the default substitutions for passthrough
text, if omitted then no passthrough substitutions are performed.
Pattern named groups. The following named groups can be used in macro <pattern> regular
expressions and are available as markup template attributes:
Here’s what happens during macro substitution
[macros]
section is matched against the input source line.
<name>-inlinemacro or <name>-blockmacro (depending on the macro
type).
| | | |
 |