diff options
Diffstat (limited to 'source-builder/sb/asciidoc/doc/faq.txt')
| -rw-r--r-- | source-builder/sb/asciidoc/doc/faq.txt | 1358 |
1 files changed, 0 insertions, 1358 deletions
diff --git a/source-builder/sb/asciidoc/doc/faq.txt b/source-builder/sb/asciidoc/doc/faq.txt deleted file mode 100644 index 2723f20..0000000 --- a/source-builder/sb/asciidoc/doc/faq.txt +++ /dev/null @@ -1,1358 +0,0 @@ -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 http://www.methods.co.nz/asciidoc/userguide.html#X27 -for ways to include such a file): - ---------------------------------------------------------------------- -[paragraph] -<formalpara{id? id="{id}"}{role? role="{role}"}{id? xreflabel="{paracounter}"}><title>{title}</title><para> -{title%}<simpara{id? id="{id}"}{role? role="{role}"}{id? xreflabel="{paracounter}"}> -{paracounter} | -{title%}</simpara> -{title#}</para></formalpara> -{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: - ------------------------------ -<<some_label_you_understand>> ------------------------------ - -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 (<<X4,see - also>>): - - 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 -http://docbook.sourceforge.net/release/xsl/current/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 <<X3>> (this link displays the text 'A titled paragraph'). - -[id="X2",reftext="2nd section"] -Section Two ------------ -See also <<X1>> (this link displays the text 'Section One'). - -[[X3]] -.A titled paragraph -Lorem ipsum dolor sit amet, consectetuer adipiscing elit. - -See also <<X2>> (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=<td style="background-color:red;">|</td> -......................................... - -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` http://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 -http://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] - <anchor id="{1}" xreflabel="[{counter:bibliography1}]"/>[{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 -`<?dblatex bgcolor="#cceeff"?>` into the DocBook output generated by -AsciiDoc: - - pass::[<?dblatex bgcolor="#cceeff"?>] - -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 -http://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 -http://www.methods.co.nz/asciidoc/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 -http://home.gna.org/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 http://home.gna.org/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 -# retrive 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] -<div class="paragraph"{id? id="{id}"} style="text-indent:3em;">{title?<div class="title">{title}</div>}<p> -| -</p></div> ---------------------------------------------------------------------- - -. 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*| -\srackham@methods.co.nz -<\srackham@methods.co.nz> -\mailto:[\srackham@methods.co.nz] - -2*| -\http://www.foo1.co.nz -\\http://www.foobar.com[] -\\http://www.foobar.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? - -http://live.gnome.org/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 <simpara> element instead of <para>? - -`<simpara>` is really the same as `<para>` 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 - `<emphasis>` elements inside `<screen>` 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 <<X1,replace spaces with -'%20'>>. - -For example, the following call won't work: - - mailto:jb@foobar.com,jd@acme.co.nz?subject=New foofoo release[New foofoo release] - -Use this instead: - - mailto:jb%40foobar.com,jd%40acme.co.nz?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: - ---------------------------------------------------------------- -<xsl:stylesheet version="1.0" - xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - xmlns:fo="http://www.w3.org/1999/XSL/Format"> - <xsl:import href="/etc/asciidoc/docbook-xsl/fo.xsl"/> - <xsl:template match="phrase[@role='f2']"> - <fo:inline font-family="the font for f2"> - <xsl:apply-templates/> - </fo:inline> - </xsl:template> -</xsl:stylesheet> ---------------------------------------------------------------- - -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...] - |