AsciiDoc Frequently Asked Questions =================================== NOTE: New FAQs are appended to the bottom of this document. ///////////////////////////////////////////////////////////////// ADD NEW FAQS TO THE BOTTOM OF THIS DOCUMENT TO MAINTAIN NUMBERING ///////////////////////////////////////////////////////////////// == How do you handle spaces in included file names? Spaces are not allowed in macro targets so this include macro will not be processed: include::my document.txt[] The work-around is to replace the spaces with the `{sp}` (space character) attribute, for example: include::my{sp}document.txt[] == How do I number all paragraphs? Some documents such as specifications and legalese require all paragraphs to be sequentially numbered through the document, and to be able to reference these numbers. This can be achieved by using the DocBook toolchain but numbering the paragraphs with AsciiDoc using a custom config file containing the following (see https://asciidoc.org/userguide.html#X27 for ways to include such a file): --------------------------------------------------------------------- [paragraph] {title} {title%} {paracounter} | {title%} {title#} {counter2:paracounter} {empty} --------------------------------------------------------------------- References to the paragraphs operate in the normal way, you label the paragraph: ----------------------------- [[some_label_you_understand]] paragraph contents ----------------------------- and reference it in the normal manner: ----------------------------- <> ----------------------------- The text of the reference will be the paragraph number. For this to work for HTML you have to generate it via the DocBook toolchain. == Sources of information on configuring DocBook toolchains DocBook is a content and structure markup language, therefore AsciiDoc generated DocBook markup is also limited to content and structure. Layout and formatting definition is specific to the DocBook toolchain. The dblatex toolchain can be configured by setting parameters defined at http://dblatex.sourceforge.net/doc/manual/sec-params.html or for more complex styling by custom Latex stylesheets described at http://dblatex.sourceforge.net/doc/manual/sec-custom-latex.html. Similarly FOP can be configured by parameters described at http://sagehill.net/docbookxsl/OptionsPart.html and with custom xsl stylesheets generating formatting objects as described at http://sagehill.net/docbookxsl/CustomizingPart.html. [[X5]] == How can I include embedded fonts in an EPUB document? This is a two step process: 1. Declare the font files and their use in your document's CSS stylesheet. For example: + [listing] ......................................... @font-face { font-family : LiberationSerif-Regular; font-weight : normal; font-style: normal; src : url(LiberationSerif-Regular.ttf); } body { font-family: LiberationSerif-Regular, serif; } ......................................... 2. Declare the font file as resource when you use `a2x(1)` to compile the EPUB. For example: a2x -f epub -d book --epubcheck --stylesheet epubtest.css --resource .ttf=application/x-font-ttf --resource LiberationSerif-Regular.ttf epubtest.txt [NOTE] ====== - Requires AsciiDoc 8.6.5 or better. - The True Type Font mimetype had to be declared explicitly with the `--resource .ttf=application/x-font-ttf` option because it wasn't registered on my Linux system. - In the above example the font file is in the same directory as the AsciiDoc source file and is installed to the same relative location in the EPUB archive OEBPS directory -- if your font file resides in a different location you'll need to adjust the `--resource` option accordingly (see the 'RESOURCES' section in the `a2x(1)` man page for details). - The URL value of the CSS 'src' property is set to the destination font file relative to the CSS file. - The `--resource` option allows you to inject any file (not just font files) into the EPUB output document. - Using the CSS '@font-face' rule is a complex subject and is outside the scope of this FAQ. - Many EPUB readers do not process embedded fonts. ====== == What's the difference between + quoted text and ` quoted monospaced text? `+` (plus) quoted text is implemented as an AsciiDoc 'quotes' whereas +`+ (grave accent or backtick) quoted text is implemented as an AsciiDoc 'inline literal' passthrough macro. The semantics are different: 1. Inline passthrough macros are processed before any other inline substitutions e.g. all of the following line will be processed as a single inline passthrough and rendered as monospaced text (which is not the intended result): + -- `single quoted text' and `monospaced quoted text` This line works as expected: `single quoted text' and +monospaced quoted text+ -- 2. Backtick quoted text is rendered literally i.e. no substitutions are performed on the enclosed text. Here are some examples that would have to be escaped if plus quoting were used (<>): The `++i` and `++j` auto-increments. Paths `~/.vim` and `~/docs`. The `__init__` method. The `{id}` attribute. == Why is the generated HTML title element text invalid? Probably because your document title contains formatting that has generated HTML title markup. You can resolve this by explicitly defining the 'title' attribute in your document's header. == AsciiDoc sometimes generates invalid output markup, why? AsciiDoc is backend agnostic, the 'asciidoc' command has no knowledge of the syntax or structure of the backend format that it generates. Output document validation (syntactic and structural) should be performed separately by external validation tools. For example, AsciiDoc's 'a2x' toolchain command automatically performs validation checks using 'xmllint'. == The AsciiDoc toclevels attribute does not work with DocBook outputs, why? DocBook has no provision for specifying table of contents levels but you can set the TOC level further down the toolchain by passing the DocBook XSL Stylesheets https://cdn.docbook.org/release/xsl/snapshot/doc/html/toc.section.depth.html[toc.section.depth] parameter to 'dblatex' (using the `--param` option) or 'xsltproc' (using the `--stringparam` option). For example to show only chapter titles in the TOC of a 'book' document set 'toc.section.depth' to '0'. Increment the 'toc.section.depth' value to show more sub-section titles. If you are using 'a2x' you can set the options in the source file, for example: // a2x: --xsltproc-opts "--stringparam toc.section.depth 0" // a2x: --dblatex-opts "--param toc.section.depth=0" If the document is of type 'article' use the value '1' to show only top level section titles in the TOC, use the value '2' for two levels etc. == How can I include chapter and section tables of contents? DocBook outputs processed by DocBook XSL Stylesheets (either manually or via 'a2x') can generate additional separate section and chapter tables of contents using combinations of the http://www.sagehill.net/docbookxsl/TOCcontrol.html[TOC parameters]. Here are some examples using combinations of the `generate.section.toc.level` and `toc.section.depth` DocBook XSL Stylesheets parameters: [cols="2*l,4",width="90%",frame="topbot",options="header"] |====================================================== |generate.section.toc.level |toc.section.depth | |1 | |Single level book chapter TOCs or article section TOCs |1 | 3 |Article section TOCs with two levels |1 | 2 |Book chapter TOCs with two levels |====================================================== == How can I customize the appearance of XHTML and EPUB documents generated by a2x? You can customize the appearance of an EPUB document with CSS. See the link:publishing-ebooks-with-asciidoc.html[Sherlock Holmes eBook example] on the AsciiDoc website. == DocBook has many elements for document meta-data -- how can I use them from AsciiDoc? The 'docinfo', 'docinfo1' and 'docinfo2' attributes allow you include link:userguide.html#X97[document information files] containing DocBook XML into the header of the output file. == Do element titles automatically generate link captions? If you go the DocBook route then yes -- just omit the caption from the AsciiDoc 'xref' (`<<...>>`) macro. Both dblatex and DocBook XSL will use the target element's title text. Examples: [listing] .................................................................. [[X1]] Section One ----------- Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas ultrices justo porttitor augue. Vestibulum pretium. Donec porta See also <> (this link displays the text 'A titled paragraph'). [id="X2",reftext="2nd section"] Section Two ----------- See also <> (this link displays the text 'Section One'). [[X3]] .A titled paragraph Lorem ipsum dolor sit amet, consectetuer adipiscing elit. See also <> (this link displays the text '2nd section'). .................................................................. The AsciiDoc 'reftext' attribute has been used to explicitly set the link text to '2nd section' for 'Section Two'. == Can I define my own table styles? In addition to the built-in styles you can define your own. This (simplified) example for HTML backends defines a table style called 'red' which sets the background cell color to red. First put the definition in a configuration file: [listing] ......................................... [tabledef-default] red-style=tags="red" [tabletags-red] bodydata=| ......................................... Now you can use the style name to style cells or columns (in this example we use an unambiguous shortened abbreviation 'r'): [listing] ......................................... |================================== |Normal cell r|Red cell |================================== ......................................... == How can I add highlighted editorial comments to an AsciiDoc document? Both block and inline link:userguide.html#X25[comment lines] are displayed on the output if the 'showcomments' attribute is defined. Example: [listing] ......................................... :showcomments: // A block comment line. Qui in magna commodo, est labitur dolorum an. Est ne magna primis // An inline comment line. adolescens. ......................................... Is rendered as: :showcomments: // A block comment line. Qui in magna commodo, est labitur dolorum an. Est ne magna primis // An inline comment line. adolescens. NOTE: link:userguide.html#X26[Comment blocks] are never displayed. == What is the preferred file name extension for AsciiDoc files? The `.txt` https://en.wikipedia.org/wiki/Text_file[text file] extension is preferred, but it's just a convention and it's not enforced by the software. AsciiDoc source files are human readable https://en.wikipedia.org/wiki/Plain_text[plain text] files which is what the `.txt` extension is for. All text editors recognize and open files with a `.txt` extension. The `.txt` extension is universally recognized and unambiguous -- you are not left asking questions like ``What on earth is this file with the funny extension?'', ``How do I open it?'' and ``Is it safe to open?''. == How can I generate numbered bibliographic entries? If your outputs are DocBook generated then adding the following inline macro to a custom configuration file will result in auto-incrementing bibliography entry numbers (instead of displaying the bibliographic identifiers): [anchor3-inlinemacro] [{counter:bibliography2}] This FAQ submitted by Bela Hausmann. == How can I include lines of dashes inside a listing block? A line of four or more dashes will be mistaken for the ListingBlock terminator, one way round this problem is to use a LiteralBlock styled as a listing block. For example: [listing] ........................... Lorum ipsum ----------- ........................... == How can I customize PDF files generated by dblatex? There are a number of dblatex XSL parameters that can be used to customize PDF output. You can set them globally in the AsciiDoc `./dblatex/asciidoc-dblatex.xsl` configuration file or you can also pass them on the a2x(1) command-line. Here are some examples: The http://dblatex.sourceforge.net/doc/manual/latex.output.revhistory.html[latex.output.revhistory] parameter is used to suppress the revision history: a2x -f pdf --dblatex-opts "-P latex.output.revhistory=0" doc/article.txt The http://dblatex.sourceforge.net/doc/manual/doc.layout.html[doc.layout] parameter is used to include the cover page and document body (i.e. excludes table of contents and index), the http://dblatex.sourceforge.net/doc/manual/doc.publisher.show.html[doc.publisher.show] parameter is used to exclude the cover page logo: a2x -f pdf --dblatex-opts " -P doc.layout=\"coverpage mainmatter\" -P doc.publisher.show=0" doc/article.txt See also the http://dblatex.sourceforge.net/doc/manual/sec-params.html[dblatex XSL parameter reference]. == How can I add lists of figures and tables to PDFs created by dblatex? Set the http://dblatex.sourceforge.net/doc/sec-custom.html[doc.lot.show XSL parameter] -- you can set it using the dblatex `--param` command-line option, for example: a2x --dblatex-opts="--param=doc.lot.show=figure,table" doc/article.txt == How can I stop the document title being displayed? You could simply omit the document title, but this will result in a blank 'title' element in HTML outputs. If you want the HTML 'title' element to contain the document title then define the 'notitle' attribute (this will just suppress displaying the title), for example: My document title ================= :no title: == Why am I having trouble getting nested macros to work? The following example expands the 'image' inline macro, but the expansion contains double-quote characters which confuses the ensuing 'footnoteref' macro expansion: footnoteref:["F1","A footnote, with an image image:smallnew.png[]"] The solution is to use unquoted attribute values, replacing embedded commas with the comma character entity (`,`): footnoteref:[F1,A footnote, with an image image:smallnew.png[]] Similarly, you can embed double-quote characters in unquoted attribute values using the `"` character entity. == Why am I getting DocBook validation errors? Not all valid AsciiDoc source generates valid DocBook, for example 'special sections' (abstract, preface, colophon, dedication, bibliography, glossary, appendix, index, synopsis) have different DocBook schema's to normal document sections. For example, a paragraph is illegal in a bibliography. Don't forget if your document is a book you need to specify the asciidoc `-d book` command option, if you don't an article DocBook document will be generated, possibly containing book specific sections, resulting in validation errors. == How can I disable special section titles? For example, you want to use 'References' as a normal section name but AsciiDoc is auto-magically generating a DocBook 'bibliography' section. All you need to do is explicitly specify the section template name, for example: [sect1] References ---------- == How can I insert XML processing instructions into output documents? Use an inline or block passthrough macros. This example inserts `` into the DocBook output generated by AsciiDoc: pass::[] NOTE: XML processing instructions are specific to the application that processes the XML (the previous `dblatex` processing instruction is recognized by `dblatex(1)` when it processes the DocBook XML generated by Asciidoc). [[X4]] == How do I prevent double-quoted text being mistaken for an inline literal? Mixing doubled-quoted text with inline literal passthroughs can produce undesired results, for example, all of the following line is interpreted as an inline literal passthrough: ``XXX'' `YYY` In this case the solution is to use monospace quoting instead of the inline literal: ``XXX'' +YYY+ Use the +\pass:[]+ macro if it's necessary to suppress substitutions in the monospaced text, for example: ``XXX'' +pass:[don't `quote` me]+ == How can I generate a single HTML document file containing images and CSS styles? With the advent of Internet Explorer 8 all major web browsers now support the https://en.wikipedia.org/wiki/Data_URI_scheme[data URI scheme] for embedded images. The AsciiDoc 'xhtml11' and 'html5' backends supports the data URI scheme for embedded images and by default it embeds the CSS stylesheet. For example the following command will generate a single `article.html` file containing embedded images, admonition icons and the CSS stylesheet: asciidoc -a data-uri -a icons article.txt == Are there any tools to help me understand what's going on inside AsciiDoc? AsciiDoc has a built-in trace mechanism which is controlled by the 'trace' attribute; there is also the `--verbose` command-line option. These features are detailed in https://asciidoc.org/userguide.html#X82[Appendix G of the User Guide]. == One-liner ifdef::[]'s are disproportionately verbose can they shortened? This is the response to a question posted on the AsciiDoc discussion list, it illustrates a number of useful techniques. The question arose because the source highlight filter language identifier for the C++ language is `c++` when generating PDFs via dblatex (LaTeX listings package) or `cpp` when generating HTML (GNU source-highlight). Using straight `ifdef::[]` block macros we have: [listing] ......................................... \ifdef::basebackend-docbook[] [source,c++] \endif::basebackend-docbook[] \ifdef::basebackend-html[] [source,cpp] \endif::basebackend-html[] ----------------------------------------- class FooParser { public: virtual void startDocument() = 0; virtual void endDocument() = 0; }; ----------------------------------------- ......................................... This can be shortened using the short form of the `ifdef::[]` macro: [listing] ......................................... \ifdef::basebackend-docbook[[source,c++]] \ifdef::basebackend-html[[source,cpp]] ----------------------------------------- class FooParser { public: virtual void startDocument() = 0; virtual void endDocument() = 0; }; ----------------------------------------- ......................................... Using a conditional attribute instead of the `ifdef::[]` macro is even shorter: [listing] ......................................... [source,{basebackend@docbook:c++:cpp}] ----------------------------------------- class FooParser { public: virtual void startDocument() = 0; virtual void endDocument() = 0; }; ----------------------------------------- ......................................... If you have a number of listings it makes sense to factor the conditional attribute to a normal attribute: [listing] ......................................... :cpp: {basebackend@docbook:c++:cpp} [source,{cpp}] ----------------------------------------- class FooParser { public: virtual void startDocument() = 0; virtual void endDocument() = 0; }; ----------------------------------------- ......................................... Even shorter, set the default source highlight filter `language` attribute so you don't have to specify it every time: [listing] ......................................... :language: {basebackend@docbook:c++:cpp} [source] ----------------------------------------- class FooParser { public: virtual void startDocument() = 0; virtual void endDocument() = 0; }; ----------------------------------------- ......................................... == Some of my inline passthroughs are not passed through, why? Most likely the passthrough encloses another passthrough with a higher precedence. For example trying to render this +\pass:[]+ with this +\`\pass:[]`+ results in a blank string because the +\pass:[]+ passthrough evaluates first, instead use monospaced quoting and escape the passthrough i.e. ++ \+\\pass:[]+ ++ == How can I place an anchor (link target) on a list item? You can't use a 'BlockId' block element inside a list but you can use the syntactically identical 'anchor' inline macro. For example: --------------------- one:: Item one. [[X2]]two:: Item two. three:: Item three. --------------------- This *will not* work: --------------------- one:: Item one. [[X2]] two:: Item two. three:: Item three. --------------------- == How can I stop lists from nesting? If you place two lists with different syntax hard up against each other then the second list will be nested in the first. If you don't want the second list to be nested separate them with a comment line block macro. For example: ------------------- 1. List 1. 2. List 1. // a. List 2. b. List 2. ------------------- == Is it possible to include charts in AsciiDoc documents? There are a number of programs available that generate presentation charts from textual specification, for example https://pypi.org/project/PyChart/[Pychart] is a library for writing chart scripts in Python. Here's an example from the 'Pychart' documentation: .barchart.py --------------------------------------------------------------------- # # Example bar chart (from Pychart documentation https://pypi.org/project/PyChart/). # from pychart import * theme.get_options() data = [(10, 20, 30, 5), (20, 65, 33, 5), (30, 55, 30, 5), (40, 45, 51, 7), (50, 25, 27, 3), (60, 75, 30, 5), (70, 80, 42, 5), (80, 62, 32, 5), (90, 42, 39, 5), (100, 32, 39, 4)] # The attribute y_coord=... tells that the Y axis values # should be taken from samples. # In this example, Y values will be [40,50,60,70,80]. ar = area.T(y_coord = category_coord.T(data[3:8], 0), x_grid_style=line_style.gray50_dash1, x_grid_interval=20, x_range = (0,100), x_axis=axis.X(label="X label"), y_axis=axis.Y(label="Y label"), bg_style = fill_style.gray90, border_line_style = line_style.default, legend = legend.T(loc=(80,10))) # Below call sets the default attributes for all bar plots. chart_object.set_defaults(bar_plot.T, direction="horizontal", data=data) # Attribute cluster=(0,3) tells that you are going to draw three bar # plots side by side. The plot labeled "foo" will the leftmost (i.e., # 0th out of 3). Attribute hcol tells the column from which to # retrieve sample values from. It defaults to one. ar.add_plot(bar_plot.T(label="foo", cluster=(0,3))) ar.add_plot(bar_plot.T(label="bar", hcol=2, cluster=(1,3))) ar.add_plot(bar_plot.T(label="baz", hcol=3, cluster=(2,3))) ar.draw() --------------------------------------------------------------------- To execute the script and include the generated chart image in your document add the following lines to the AsciiDoc source: --------------------------------------------------------------------- // Generate chart image file. \sys2::[python "{indir}/barchart.py" --format=png --output="{outdir}/barchart.png" --scale=2] // Display chart image file. image::barchart.png[] --------------------------------------------------------------------- [NOTE] ===================================================================== - The `barchart.py` script is located in the same directory as the AsciiDoc source file (`{indir}`). - The generated chart image file (`barchart.png`) is written to the same directory as the output file (`{outdir}`). ===================================================================== == How can I render indented paragraphs? Styling is backend dependent: [float] ==== Create an indented paragraph style (xhtml11 and html5 backends) . Define an 'indented' paragraph style, for example, by putting this in a custom configuration file: + --------------------------------------------------------------------- [paradef-default] indented-style=template="indentedparagraph" [indentedparagraph]
{title?
{title}
}

|

--------------------------------------------------------------------- . Now apply the 'indented' style to normal paragraphs, for example: + --------------------------------------------------------------------- [indented] Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas ultrices justo porttitor augue. Vestibulum pretium. Donec porta vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed lacinia. Vivamus at lectus. --------------------------------------------------------------------- [float] ==== Use the role attribute (xhtml11 and html5 backends) . Add the following line to custom stylesheet: + --------------------------------------------------------------------- div.paragraph.indented p {text-indent: 3em;} --------------------------------------------------------------------- . Apply the 'role' attribute to indented paragraphs, for example: + --------------------------------------------------------------------- [role="indented"] Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas ultrices justo porttitor augue. Vestibulum pretium. Donec porta vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed lacinia. Vivamus at lectus. --------------------------------------------------------------------- . Include the custom stylesheet by setting the 'stylesheet' attribute (either from the command-line or with an attribute entry in the document header). [float] ==== Use the role attribute (docbook backend) . Add the following line to the distributed `docbook-xsl.css` stylesheet or include it in a custom stylesheet: + --------------------------------------------------------------------- p.indented {text-indent: 3em;} --------------------------------------------------------------------- . Apply the 'role' attribute to indented paragraphs, for example: + --------------------------------------------------------------------- [role="indented"] Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas ultrices justo porttitor augue. Vestibulum pretium. Donec porta vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed lacinia. Vivamus at lectus. --------------------------------------------------------------------- . If you have included the custom CSS in a separate stylesheet you will need to specify the stylesheet file name (along with the default `docbook-xsl.css` stylesheet file name) with the `html.stylesheet` XSL parameter. If you are using 'a2x(1)' use the `--stylesheet` option (it sets the `html.stylesheet` XSL parameter), for example: `--stylesheet "docbook-xsl.css mycss.css"`. NOTE: This applies to HTML outputs not PDF. To achieve the same results with PDF outputs you will need to customize the DocBook XSL Stylesheets to render indented paragraphs from DocBook `simpara` elements containing the the `role="indented"` attribute. == Is there a way to set default table grid and frame attributes? You can set the 'grid' and 'frame' attributes globally in your document header with Attribute Entries or from the command-line using the `--attribute` option. In the following example tables that don't explicitly set the 'grid' and 'frame' values will default to 'all' and 'topbot' respectively: --------------------------------------------------------------------- :grid: all :frame: topbot --------------------------------------------------------------------- TIP: This technique can be applied to any block element attribute (just beware of possible ambiguity, for example, table and image blocks both have a 'width' attribute). == How can I place a backslash character in front of an attribute reference without escaping the reference? Use the predefined `{backslash}` attribute reference instead of an actual backslash, for example if the `{projectname}` attribute has the value `foobar` then: d:\data{backslash}{projectname} would be rendered as: d:\data\foobar == How can I escape AsciiDoc markup? Most AsciiDoc inline elements can be suppressed by preceding them with a backslash character. These elements include: - Attribute references. - Text formatting. - Quoting, - Macros. - Replacements. - Special words. - Table cell separators. But there are exceptions -- see the next question. == Some elements can't be escaped with a single backslash There are a number of exceptions to the usual single backslash rule -- mostly relating to URL macros that have two syntaxes or quoting ambiguity. Here are some non-standard escape examples: [cols="l,v",width="40%",frame="topbot",options="header"] |======================================== |AsciiDoc | Renders 2*| \joe.bloggs@example.com <\joe.bloggs@example.com> \mailto:[\joe.bloggs@example.com] 2*| \http://www.example.com \\http://www.example.com[] \\http://www.example.com[Foobar Limited] 2*| A C\++ Library for C++ \\``double-quotes'' \*\*F**ile Open\... |======================================== The source of this problem is ambiguity across substitution types -- the first match unescapes allowing the second to substitute. A work-around for difficult cases is to side-step the problem using the +\pass:[]+ passthrough inline macro. NOTE: Escaping is unnecessary inside 'inline literal passthroughs' (backtick quoted text). == How can I escape a list? Here's how to handle situations where the first line of a paragraph is mistaken for a list item. [float] ==== Numbered and bulleted lists Precede the bullet or index of the first list item with an `{empty}` attribute, for example: {empty}- Qui in magna commodo est labitur dolorum an. Est ne magna primis adolescens. The predefined `{empty}` attribute is replaced by an empty string and ensures the first line is not mistaken for a bulleted list item. [float] ==== Labeled lists Two colons or semicolons in a paragraph may be confused with a labeled list entry. Use the predefined `{two-colons}` and `{two-semicolons}` attributes to suppress this behavior, for example: Qui in magna commodo{two-colons} est labitur dolorum an. Est ne magna primis adolescens. Will be rendered as: Qui in magna commodo{two-colons} est labitur dolorum an. Est ne magna primis adolescens. == How can I set default list and tables styles? You can set the element's 'style' entry in a global or custom configuration file. This example this will horizontally style all labeled lists that don't have an explicit style attribute: ---------------------------------- [listdef-labeled] style=horizontal [listdef-labeled2] style=horizontal ---------------------------------- This example will put a top and bottom border on all tables that don't already have an explicit style attribute: ---------------------------------- [tabledef-default] style=topbot topbot-style=frame="topbot" ---------------------------------- Alternatively you can set the configuration entries from inside your document, the above examples are equivalent to: ---------------------------------- :listdef-labeled.style: horizontal :listdef-labeled2.style: horizontal :tabledef-default.topbot-style: frame="topbot" :tabledef-default.style: topbot ---------------------------------- == Why do I get a filter non-zero exit code error? An error was returned when AsciiDoc tried to execute an external filter command. The most common reason for this is that the filter command could not be found by the command shell. To figure out what the problem is run AsciiDoc with the `--verbose` option to determine the command that is failing and then try to run the command manually from the command-line. == Are there any DocBook viewers? https://wiki.gnome.org/action/show/Apps/Yelp[Yelp], the GNOME help viewer, does a creditable job of displaying DocBook XML files directly. == Can you create ODF and PDF files using LibreOffice? https://www.libreoffice.org/[LibreOffice] can convert HTML produced by AsciiDoc to ODF text format and PDF format (I used LibreOffice 3.5 at the time of writing, the fidelity is very good but it's not perfect): . Create the HTML file using AsciiDoc, for example: asciidoc -a icons -a numbered -a disable-javascript article.txt + JavaScript is disabled because LibreOffice does not execute JavaScript, this means that AsciiDoc table of contents and footnotes will not be rendered into ODF (if you want the table of contents and footnotes you could manually cut and paste them from a Web browser). . Convert the HTML file to an ODF text file using LibreOffice: lowriter --invisible --convert-to odt article.html + -- The images imported from an HTML file will be linked, if your document contains images you should convert them to embedded images: [lowerroman] . Open the document in LibreOffice Writer. . Run the 'Edit->Links...' menu command. . Select all links and press the 'Break Link' button. Some images may also have been resized. To restore an image to its original size: [lowerroman] . Right-click on the image and select the 'Picture...' menu item. . Click on the 'Crop' tab. . Press the 'Original Size' button. -- . Convert the ODF file to an PDF text file using LibreOffice: lowriter --invisible --convert-to pdf article.odt + A PDF index is automatically created using the section headings. Alternatively you could manually copy-and-paste the entire document from a Web browser into a blank ODF document in LibreOffice -- this technique will bring through the table of contents and footnotes. This tip was originally contributed by Bernard Amade. == How can I suppress cell separators in included table data files? Use the `{include:}` system attribute instead of the `include::[]` macro (the former is not expanded until after the table data has been parsed into cells, whereas the latter is included before the table is processed. == How can I preserve paragraph line boundaries? Apply the The 'verse' paragraph style, the rendered text preserves line boundaries and is useful for lyrics and poems. For example: --------------------------------------------------------------------- [verse] Consul *necessitatibus* per id, consetetur, eu pro everti postulant homero verear ea mea, qui. --------------------------------------------------------------------- Alternatively, if you are generating PDF files, you can use line breaks. For example: --------------------------------------------------------------------- Consul *necessitatibus* per id, + consetetur, eu pro everti postulant + homero verear ea mea, qui. --------------------------------------------------------------------- == How can I include non-breaking space characters? Use the non-breaking space character entity reference ` ` (see the next question). You could also use the predefined `{nbsp}` attribute reference. == Can I include HTML and XML character entity references in my document? Yes, just enter the reference in your document. For example `β` will print a Greek small beta character β [[X1]] == How do I include spaces in URLs? URL inline macro targets (addresses) cannot contain white space characters. If you need spaces encode them as `%20`. For example: image:large%20image.png[] http://www.foo.bar.com/an%20example%20document.html == How can I get AsciiDoc to assign the correct DocBook language attribute? Set the AsciiDoc 'lang' attribute to the appropriate language code. For example: a2x -a lang=es doc/article.txt This will ensure that downstream DocBook processing will generate the correct language specific document headings (things like table of contents, revision history, figure and table captions, admonition captions). == How can I turn off table and image title numbering? For HTML outputs set the 'caption' attribute to an empty string, either globally: ------------------------- :caption: ------------------------- or on an element by element basis, for example: ------------------------- .Tiger [caption=""] image::images/tiger.png[] ------------------------- == How can I assign multiple author names? A quick way to do this is put both authors in a single first name, for example: --------------------------------------- My Document =========== :Author: Bill_and_Ben_the_Flowerpot_Men :Author Initials: BB & BC --------------------------------------- asciidoc(1) replaces the underscores with spaces. If you are generating DocBook then a more flexible approach is to create a 'docinfo' file containing a DocBook 'authorgroup' element (search the 'User Guide' for 'docinfo' for more details). == How can I selectively disable a quoted text substitution? Omitting the tag name will disable quoting. For example, if you don't want superscripts or subscripts then put the following in a custom configuration file or edit the global `asciidoc.conf` configuration file: ------------------- [quotes] ^= ~= ------------------- Alternatively you can set the configuration entries from within your document, the above examples are equivalent to: ------------------- :quotes.^: :quotes.~: ------------------- == How can I customize the \{localdate} format? The default format for the `{localdate}` attribute is the ISO 8601 `yyyy-mm-dd` format. You can change this format by explicitly setting the `{localdate}` attribute. For example by setting it using the asciidoc(1) `-a` command-line option: asciidoc -a localdate=`date +%d-%m-%Y` mydoc.txt You could also set it by adding an Attribute Entry to your source document, for example: :localdate: {sys: date +%Y-%m-%d} == Where can I find examples of commands used to build output documents? The User Guide has some. You could also look at `./doc/main.aap` and `./examples/website/main.aap` in the AsciiDoc distribution, they have all the commands used to build the AsciiDoc documentation and the AsciiDoc website (even if you don't use A-A-P you'll still find it useful). == Why have you used the DocBook element instead of ? `` is really the same as `` except it can't contain block elements -- this matches, more closely, the AsciiDoc paragraph semantics. == How can I format text inside a listing block? By default only 'specialcharacters' and 'callouts' are substituted in listing blocks; you can add quotes substitutions by explicitly setting the block 'subs' attribute, for example: [listing] .......................................... [subs="quotes"] ------------------------------------------ $ ls *-al* ------------------------------------------ .......................................... The `-al` will rendered bold. Note that: - You would need to explicitly escape text you didn't want quoted. - Don't do this in source code listing blocks because it modifies the source code which confuses the syntax highlighter. - This only works if your DocBook processor recognizes DocBook `` elements inside `` elements. Alternative, if the lines are contiguous, you could use the 'literal' paragraph style: ------------------------------------------ ["literal",subs="quotes"] $ ls *-al* ------------------------------------------ == Why doesn't the include1::[] macro work? Internally the `include1` macro is translated to the `include1` system attribute which means it must be evaluated in a region where attribute substitution is enabled. `include1` won't work, for example, in a ListingBlock (unless attribute substitution is enabled). `include1` is intended for use in configuration files, use the `include` macro and set the attribute `depth=1` instead, for example: [listing] ................................................ ------------------------------------------------ \include::blogpost_media_processing.txt[depth=1] ------------------------------------------------ ................................................ == How can I make the mailto macro work with multiple email addresses? For the AsciiDoc 'mailto' macro to work with multiple email addresses (as per RFC2368) you need to URL encode the '@' characters (replace them with '%40'), if you don't the individual addresses will be rendered as separate links. You also need to <>. For example, the following call won't work: mailto:jb@example.com,jd@example.com?subject=New foofoo release[New foofoo release] Use this instead: mailto:jb%40example.com,jd%40example.com?subject=New%20foofoo%20release[New foofoo release] == How can a replacement have a trailing backslash? Quote the entry name -- this nonsensical example replaces `x\` with `y`: "x\\"=y If quoting were omitted the equals character (separating the entry name `x` from the value `y`) would be escaped. == How can I control page breaks when printing HTML outputs? Here are some techniques you can use to control page breaks in HTML outputs produced by the 'xhtml11' and 'html5' backends: - You can generate a page break with the '<<<' block macro. The following example prints the 'Rats and Mice' section on a new page: + ---------------- <<< == Rats and Mice Lorum ipsum ... ---------------- - You can use the 'unbreakable' option to instruct the browser not to break a block element. The following image and it's caption will be kept together the printed page: + ------------------------------------ [options="unbreakable"] .Tiger block image image::images/tiger.png[Tiger image] ------------------------------------ - You can apply the 'unbreakable' option globally to all block elements by defining the 'unbreakable-option' attribute in your document header. - Finally, the most powerful technique is to create custom CSS containing paged media properties. For example this asciidoc(1) command: + -- asciidoc --attribute stylesheet=article.css article.txt Will include the following `article.css` file in the output document: ------------------------------------------------- div#toc, div.sect1 { page-break-before: always; } ------------------------------------------------- Which will ensure the table of contents and all top level sections start on a new printed page. -- == Is it possible to reposition the Table of Contents in HTML outputs? By default the 'xhtml11' and 'html5' backends auto-position the TOC after the header. You can manually position the TOC by setting the 'toc-placement' attribute value to 'manual' and then inserting the `toc::[]` block macro where you want the TOC to appear. For example, put this in the document header: ---------------------- :toc: :toc-placement: manual ---------------------- The put this where you want the TOC to appear: ------- toc::[] ------- == HTML generated by AsciiDoc fills the width of the browser, how can I limit it to a more readable book width? You can set the maximum with for outputs generated by 'html5', 'xhtml11' and 'slidy' backends by assigning the link:userguide.html#X103[max-width] attribute (either from the command-line or with an attribute entry in the document header). For example: asciidoc -a max-width=55em article.txt == Using roles to select fonts for PDF Some applications require mixing fonts beyond the set of faces normally provided by default (normal, monospace, italic etc.) for example mixed language text where the font used for the majority of text does not contain suitable glyphs in the minority language. As AsciiDoc can not provide presentation markup since it is not provided by Docbook this is achieved by marking text which should use a different font with a custom role which can be rendered by the the docbook toolchain. NOTE: For XHTML outputs AsciiDoc translates the role attribute to a class which can be selected and styled by CSS as described in the AsciiDoc users guide. The Docbook toolchains will have to be configured to render the text that you mark with the custom role. For FOP a small XSL wrapper is needed, say a file called `my_fo.xsl` containing: --------------------------------------------------------------- --------------------------------------------------------------- This is used with `a2x` by: a2x -f pdf --fop --xsl-file=my_fo.xsl input.txt and the AsciiDoc source marked by: normal text [f2]#special font is like this# and back to normal Thanks to Antonio Borneo for this answer. == How can I place a footnote immediately following quoted text? A closing quote is not recognised if it is immediately followed by a letter (the 'f' in 'footnote' in the following example): ``Double-quoted text''footnote:[Lorum ipsum...] A workaround is to put a word-joiner between the trailing quote and the footnote (the `{empty}` attribute would also work), for example: ``Double-quoted text''{wj}footnote:[Lorum ipsum...] == How can I convert documents from other formats to AsciiDoc? You can use https://pandoc.org/[Pandoc] to convert documents in https://daringfireball.net/projects/markdown/[markdown], https://docutils.sourceforge.io/rst.html[reStructuredText], https://www.promptworks.com/textile/[textile], https://html.spec.whatwg.org/[HTML], https://docbook.org/[DocBook], or https://www.latex-project.org/[LaTeX] to AsciiDoc. == How can I insert raw HTML in a document processed by a2x? `a2x` generates HTML via DocBook (DocBook XSL Stylesheets) so if you use a passthrough block it must contain DocBook (not HTML). Fortunately DocBook XSL Stylesheets has a http://www.sagehill.net/docbookxsl/InsertExtHtml.html[dbhtml-include processing instruction] which will include a file containing raw HTML into the generated HTML output. For example: --------------------------------------------------------------- ++++ ++++ --------------------------------------------------------------- == Why is there a period after the block title in the PDF output? If your document has blocks that have block titles, you may notice in the PDF output (generated by `a2x(1)` using the `--fop` flag) that a period gets added to the end of the block title. You will not see the period in the intermediary DocBook XML that’s generated when creating a PDF -- it’s added by the DocBook XSL templates when the DocBook XML is converted to FO XML. The DocBook XSL attribute that controls what character is added after a block title is https://cdn.docbook.org/release/xsl/snapshot/doc/html/runinhead.default.title.end.punct.html[ runinhead.default.title.end.punct]. You can override it and eliminate the default period value by adding the following line to the `./docbook-xsl/common.xsl` file that ships with AsciiDoc: This FAQ was https://groups.google.com/group/asciidoc/browse_thread/thread/19dda8807fa7c3f2[contributed by Dan Allen].