40
AsciiDoc User Guide
80 / 88
36.11 Creating stand-alone HTML documents
If you’ve ever tried to send someone an HTML document that includes stylesheets and images you’ll know that it’s not as
straight-forward as exchanging asingle file. AsciiDochas options tocreate stand-alone documents containingembedded images,
stylesheets and scripts. The following AsciiDoc command creates a single file containingembeddedimages, CSS stylesheets,
and JavaScript (for table of contents and footnotes):
$ asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt
You can view the HTML file here:http://asciidoc.org/article-standalone.html
36.12 Shipping stand-alone AsciiDoc source
Reproducingpresentation documents from someone else’s source has one major problem: unless your configuration files are the
same as the creator’s you won’t get the same output.
The solution is to create a single backend specific configuration file using the asciidoc(1) -c (--dump-conf) command-
line option. You then ship this file along with the AsciiDoc source document plus the asciidoc.py script. The only end user
requirement is that they have Python installed (and that they consider you a trusted source). This example creates a composite
HTML configuration file for mydoc.txt:
$ asciidoc -cb xhtml11 mydoc.txt > mydoc-xhtml11.conf
Ship mydoc.txt, mydoc-html.conf, and asciidoc.py. With these three files (and a Python interpreter) the recipient
can regenerate the HMTL output:
$ ./asciidoc.py -eb xhtml11 mydoc.txt
The -e(--no-conf) optionexcludes theuse of implicitconfigurationfiles, ensuringthatonlyentriesfrom themydoc-html.conf
configuration are used.
36.13 Inserting blank space
Adjust your style sheets to add the correct separation between block elements. Inserting blank paragraphs containing a single
non-breaking space character {nbsp} works but is an ad hoc solution compared to using style sheets.
36.14 Closing open sections
You can close off section tags up to level N by calling the eval::[Section.setlevel(N)] system macro. This is useful
if you want to include a section composed of raw markup. The following example includes a DocBook glossary division at the
top section level (level 0):
ifdef::basebackend-docbook[]
eval::[Section.setlevel(0)]
+++++++++++++++++++++++++++++++
<glossary>
<title>Glossary</title>
<glossdiv>
...
</glossdiv>
</glossary>
+++++++++++++++++++++++++++++++
endif::basebackend-docbook[]