AsciiDoc User Guide
33 / 88
The footnote text can span multiple lines.
The xhtml11 and html5 backends render footnotes dynamically using JavaScript; html4 outputs do not use JavaScript and leave
the footnotes inline; docbook footnotes are processed by the downstream DocBook toolchain.
Example footnotes:
A footnote footnote:[An example footnote.];
a second footnote with a reference ID footnoteref:[note2,Second footnote.];
finally a reference to the second footnote footnoteref:[note2].
Renders:
Afootnote
2
;a second footnote with a reference ID
3
;finally a reference to the second footnote
3
.
19 Indexes
The shipped AsciiDoc configuration includes the inline macros for generatingDocBook index entries.
indexterm:[<primary>,<secondary>,<tertiary>] , (((<primary>,<secondary>,<tertiary>)))
This inline macro generates an index term (the <secondary> and <tertiary> positional attributes are optional).
Example: indexterm:[Tigers,Big cats] (or, usingthe alternative syntax (((Tigers,Big cats))). Index
terms thathave secondary and tertiaryentries also generate separate index terms for the secondary andtertiary entries. The
index terms appear in the index, not the primary text flow.
indexterm2:[<primary>] , ((<primary>))
This inline macro generates an index term that appears in both the index and the primary text flow. The <primary>
should not be padded to the left or right with white space characters.
For working examples see the article.txt and book.txt documents in the AsciiDoc ./doc distribution directory.
Note
Index entries only really make sense if you are generating DocBook markup—DocBook conversion programs automatically
generate an index at the point an Index section appears in source document.
20 Callouts
Callouts are a mechanism for annotating verbatim text (for example: source code, computer output and user input). Callout
markers are placed inside the annotated text while the actual annotations are presented in a callout list after the annotated text.
Here’s an example:
.MS-DOS directory listing
-----------------------------------------------------
10/17/97
9:04
<DIR>
bin
10/16/97
14:11
<DIR>
DOS
<1>
10/16/97
14:40
<DIR>
Program Files
10/16/97
14:46
<DIR>
TEMP
10/17/97
9:04
<DIR>
tmp
10/16/97
14:37
<DIR>
WINNT
10/16/97
14:25
119
AUTOEXEC.BAT
<2>
2/13/94
6:21
54,619
COMMAND.COM
<2>
10/16/97
14:25
115
CONFIG.SYS
<2>
2
An example footnote.
3
Second footnote.
Create bookmark pdf - add, remove, update PDF bookmarks in C#.net, ASP.NET, MVC, Ajax, WinForms, WPF
Empower Your C# Project with Rapid PDF Internal Navigation Via Bookmark and Outline
export pdf bookmarks to excel; bookmarks pdf reader
Create bookmark pdf - VB.NET PDF bookmark library: add, remove, update PDF bookmarks in vb.net, ASP.NET, MVC, Ajax, WinForms, WPF
Empower Your VB.NET Project with Rapid PDF Internal Navigation Via Bookmark and Outline
bookmark pdf reader; create bookmarks pdf files
AsciiDoc User Guide
34 / 88
11/16/97
17:17
61,865,984
pagefile.sys
2/13/94
6:21
9,349
WINA20.386
<3>
-----------------------------------------------------
<1> This directory holds MS-DOS.
<2> System startup code for DOS.
<3> Some sort of Windows 3.1 hack.
Which renders:
MS-DOS directory listing
10/17/97
9:04
<DIR>
bin
10/16/97
14:11
<DIR>
DOS
v
1
10/16/97
14:40
<DIR>
Program Files
10/16/97
14:46
<DIR>
TEMP
10/17/97
9:04
<DIR>
tmp
10/16/97
14:37
<DIR>
WINNT
10/16/97
14:25
119
AUTOEXEC.BAT
v
2
2/13/94
6:21
54,619
COMMAND.COM
v
3
10/16/97
14:25
115
CONFIG.SYS
v
4
11/16/97
17:17
61,865,984
pagefile.sys
2/13/94
6:21
9,349
WINA20.386
v
5
v
1
This directory holds MS-DOS.
v
2
,
v
3
,
v
4
System startup code for DOS.
v
5
Some sort of Windows 3.1 hack.
E
XPLANATION
• The callout marks are whole numbers enclosed in angle brackets— they refer to the correspondingly numbered item in the
following callout list.
• By default callout marks are confined to LiteralParagraphs, LiteralBlocks and ListingBlocks (although this is a configuration
file option and can be changed).
• Callout list item numbering is fairly relaxed—list items can start with <n>, n> or > where n is the optional list item number
(in the latter case list items starting with a single > character are implicitly numbered starting at one).
• Callout lists should not be nested.
• Callout lists cannot be used within tables.
• Callout lists start list items hard against the left margin.
• If you want to present a number inside angle brackets you’ll need to escape it with a backslash to prevent it being interpreted
as a callout mark.
Note
Define the AsciiDoc icons attribute (for example using the
-a icons
command-line option) to display callout icons.
VB.NET Create PDF from Excel Library to convert xlsx, xls to PDF
C#, C#.NET PDF Reading, C#.NET Annotate PDF in WPF, C#.NET PDF Create, C#.NET NET rotate PDF pages, C#.NET search text in PDF, C#.NET edit PDF bookmark, C#.NET
how to bookmark a pdf document; how to add bookmarks to pdf files
VB.NET Create PDF from Word Library to convert docx, doc to PDF in
Easy to create searchable and scanned PDF files from Word. Ability to get word count of PDF pages. Change Word hyperlink to PDF hyperlink and bookmark.
export pdf bookmarks to text file; bookmarks in pdf reader
AsciiDoc User Guide
35 / 88
20.1 Implementation Notes
Callout marks are generated by the callout inline macro while callout lists are generated using the callout list definition. The
callout macro and callout list are special in that theyworktogether. The callout inline macro is notenabled by the normalmacros
substitutions option, instead it has its own callouts substitution option.
The following attributes are available during inline callout macro substitution:
{index}
The callout list item index inside the angle brackets.
{coid}
An identifier formattedlike CO<listnumber>-<index> thatuniquelyidentifies the calloutmark. For exampleCO2-4
identifies the fourth callout mark in the second set of callout marks.
The {coids} attribute can be used during callout list item substitution—it is a space delimited list of callout IDs that refer to
the explanatory list item.
20.2 Including callouts in included code
You can annotate working code examples with callouts— just remember to put the callouts inside source code comments. This
example displays the test.py source file (containing a single callout) using the source (code highlighter) filter:
AsciiDoc source
[source,python]
-------------------------------------------
\include::test.py[]
-------------------------------------------
<1> Print statement.
Included test.py source
print ’Hello World!’
# <1>
21 Macros
Macros are a mechanism for substitutingparametrized 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:
http://www.docbook.org/[DocBook.org]
include::chapt1.txt[tabsize=2]
mailto:srackham@gmail.com[]
M
ACRO BEHAVIOR
• <name> is the macro name. It can only contain letters, digits or dash characters and cannot start with a dash.
• The optional <target> cannot contain white space characters.
• <attrlist> is alistofattributes enclosed in square brackets.
• ] characters inside attribute lists must be escaped with a backslash.
C# Create PDF from Word Library to convert docx, doc to PDF in C#.
Easy to create searchable and scanned PDF files from Word. Able to get word count in PDF pages. Change Word hyperlink to PDF hyperlink and bookmark.
how to add bookmarks to pdf document; adding bookmarks to a pdf
VB.NET PDF Convert to Tiff SDK: Convert PDF to tiff images in vb.
Qualified Tiff files are exported with high resolution in VB.NET. Create multipage Tiff image files from PDF in VB.NET project. Support
add bookmark to pdf reader; bookmarks pdf file
AsciiDoc User Guide
36 / 88
• Expansion of macroreferences can normallybe escapedbyprefixinga backslashcharacter (seetheAsciiDocFAQ for examples
of exceptions to this rule).
• Attribute references in block macros are expanded.
• The substitutions performed prior to Inline macro macro expansion are determined by the inline context.
• Macros are processed in the order they appear in the configuration file(s).
• Calls to inline macros can be nested inside different inline macros (an inline macro call cannot contain a nested call to itself).
• In addition to <name>, <target> and <attrlist> the <passtext> and <subslist> named groups are available to
passthrough macros.Amacroisapassthroughmacroifthedefinitionincludesa<passtext>namedgroup.
21.1 Inline Macros
Inline Macros occur in an inline element context. Predefined Inline macros include URLs, image and link macros.
21.1.1 URLs
http, https, ftp, file, mailto and callto URLs are rendered using predefined inline macros.
• If you don’t need a custom link caption you can enter the http, https, ftp, file URLs and email addresses without any special
macro syntax.
• If the <attrlist> is empty the URL is displayed.
Here are some examples:
http://www.docbook.org/[DocBook.org]
http://www.docbook.org/
mailto:joe.bloggs@foobar.com[email Joe Bloggs]
joe.bloggs@foobar.com
Which are rendered:
DocBook.org
http://www.docbook.org/
email Joe Bloggs
joe.bloggs@foobar.com
If the <target> necessitates space characters use %20, for example large%20image.png.
21.1.2 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.
C# Create PDF from Tiff Library to convert tif images to PDF in C#
Create PDF from Tiff. |. Home ›› XDoc.PDF ›› C# PDF: Create PDF from Tiff. Create PDF from Tiff in both .NET WinForms and ASP.NET application.
copy bookmarks from one pdf to another; how to create bookmark in pdf with
C# Create PDF from Excel Library to convert xlsx, xls to PDF in C#
C#.NET PDF SDK- Create PDF from Word in Visual C#. Online C#.NET Tutorial for Create PDF from Microsoft Office Excel Spreadsheet Using .NET XDoc.PDF Library.
add bookmarks pdf; add bookmark pdf
AsciiDoc User Guide
37 / 88
anchor
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
displayedbycaptionless xref macros that refer tothis anchor. The optional<xreflabel> is onlyreallyusefulwhen generating
DocBook output. Example anchor:
[[X1]]
You mayhave noticed thatthesyntax of this inlineelementis the same asthatof theBlockIdblockelement, this isnocoincidence
since they are functionally equivalent.
xref
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:
• The AsciiDoc xhtml11and html5 backends display the <id> enclosed in square brackets.
• If DocBook is produced the DocBook toolchain is responsible for the displayed text which will normally be the referenced
figure, table or section title number followed by the element’s title text.
Here is an example:
[[tiger_image]]
.Tyger tyger
image::tiger.png[]
This can be seen in <<tiger_image>>.
21.1.3 Linking to Local Documents
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 (relativeto the file system location of
the referringdocument). The optional <caption> is the link’s displayed text. If <caption> is not specifiedthen<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.
C# Create PDF from PowerPoint Library to convert pptx, ppt to PDF
C#.NET PDF SDK- Create PDF from PowerPoint in C#. How to Use C#.NET PDF Control to Create PDF from Microsoft PowerPoint Presentation in .NET Project.
export excel to pdf with bookmarks; bookmark pdf acrobat
VB.NET PDF - Create PDF Online with VB.NET HTML5 PDF Viewer
C#, C#.NET PDF Reading, C#.NET Annotate PDF in WPF, C#.NET PDF Create, C#.NET NET rotate PDF pages, C#.NET search text in PDF, C#.NET edit PDF bookmark, C#.NET
how to add bookmarks to a pdf; pdf export bookmarks
AsciiDoc User Guide
38 / 88
21.1.4 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 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.
I
MAGE 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 alsoUseofALTtextsinIMGs). For example:
image:images/logo.png[Company Logo]
• The optional title attribute provides a title for the image. Theblockimagemacro renders the title alongside the image. The
inline image macro displays the title as a popup “tooltip” in visual browsers (AsciiDoc HTML outputs only).
• 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 32pixels:
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"]
• Theoptional scaledwidth attribute is onlyusedinDocBookblockimages (specificallyfor PDF documents). The following
example scales the images to 75% of the available print width:
image::images/logo.png[scaledwidth="75%",alt="Company Logo"]
• The image 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"]
• The optional 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.
21.1.5 Comment Lines
Seecommentblockmacro.
21.2 Block Macros
ABlock 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:
• They occur in a block context.
• The default syntax is <name>::<target>[<attrlist>] (two colons, not one).
• Markup template section names end in -blockmacro instead of -inlinemacro.
AsciiDoc User Guide
39 / 88
21.2.1 Block Identifier
The Block Identifier macro sets the id attribute and has the same syntax as theanchorinlinemacro 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"]AttributeListelement).
21.2.2 Images
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 samemacroattributesas it’sinlineimagemacro counterpart.
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"]
Atitle 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 thedataURIscheme.
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
• All current popular browsers support data URIs, although versions of Internet Explorer prior to version 8 do not.
• Some browsers limit the size of data URIs.
AsciiDoc User Guide
40 / 88
21.2.3 Comment Lines
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 thatsupportinline macro expansion.
Example comment line:
// This is a comment.
If the showcomments attribute is defined comment lines are written to the output:
• In DocBook the comment lines are enclosed by the remark element (which may or may not be rendered by your toolchain).
• The showcomments attribute does not exposeCommentBlocks. Comment Blocks are never passedto the output.
21.3 System Macros
System macros are block macros that perform a predefined task and are hardwired into the asciidoc(1) program.
• You can escape system macros with a leading backslash character (as you can with other macros).
• Thesyntaxandtasks performed bysystem macros is builtinto asciidoc(1)sothey don’t appear inconfiguration files. You
can however customize the syntax by adding entries to a configuration file [macros] section.
21.3.1 Include Macros
The include and include1 system macros to include the contents of a named file into the source document.
The include macroincludes 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
substitutionsperformed. Theinclude1 macro’sintendeduseis to includeverbatim embeddedCSS or scripts intoconfiguration
file headers. Example:
include::chapter1.txt[tabsize=4]
I
NCLUDE MACRO BEHAVIOR
• If the included file name is specified with a relative path then the path is relative to the location of the referring document.
• Include macros canappear inside configuration files.
• Files included from within DelimitedBlocks are read to completion to avoid false end-of-block underline termination.
• Attribute references areexpanded inside the include target;if an attribute is undefinedthenthe includedfile is silentlyskipped.
• The tabsize macro attribute sets the number of space characters tobe usedfor tabexpansion in the included file (notapplicable
to include1 macro).
• The depth macro attribute sets the maximum permitted number of subsequent nested includes (not applicable to 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.
• If the he warnings attribute is set toFalse (or any other Python literalthat evaluates to boolean false) then no warning message
is printed if the included file does not exist. Bydefault warnings are enabled.
• Internally the include1 macrois 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.
AsciiDoc User Guide
41 / 88
21.3.2 Conditional Inclusion Macros
Lines of text in the source document can be selectively included or excluded from processing based on the existence (or not) of
adocument 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 includedif a document attribute is defined:
ifndef::<attribute>[]
:
endif::<attribute>[]
<attribute> is an attribute name which is optional in the trailing endif macro.
If you onlywant to process a single line of textthenthe text can be put inside the square brackets andthe 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:
• Multiple , separated attribute names evaluate to defined if one or more of the attributes is defined, otherwise it’s value is
undefined.
• Multiple + separated attribute names evaluate to defined if all of the attributes is defined, otherwise it’s value is undefined.
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::[]
• Document attribute references are expanded before the expression is evaluated.
• If an attribute reference is undefined then the expression is considered false.
Take a look at the
*
.conf configuration files in the AsciiDoc distribution for examples of conditional inclusion macro usage.
AsciiDoc User Guide
42 / 88
21.3.3 Executable system macros
The eval, sys and sys2 block macros exhibit the same behavior as their same namedsystemattributereferences. 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]
------------------
Note
There are no block macro versions of the eval3 and sys3 system attributes.
21.3.4 Template System Macro
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]
T
EMPLATE MACRO BEHAVIOR
• The 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.
21.4 Passthrough macros
Passthrough macros are analogous topassthroughblocks 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.
pass
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>]
asciimath, latexmath
Inline and block. Passes text unmodified. Used formathematicalformulas.
+++
Inline and block. The triple-plus passthrough is functionally identical to the pass macro but you don’t have to escape ]
characters and you canprefix with quoted attributes in the inline version. Example:
Red [red]+++‘sum_(i=1)\^n i=(n(n+1))/2‘$+++ AsciiMathML formula
Documents you may be interested
Documents you may be interested