asciidoc-py3-9.0.0rc1/ 0000755 0001750 0001750 00000000000 13570064211 013756 5 ustar joseph joseph asciidoc-py3-9.0.0rc1/configure.ac 0000644 0001750 0001750 00000000236 13570064211 016245 0 ustar joseph joseph AC_INIT(asciidoc, 9.0.0rc1)
AC_SUBST([PACKAGE_DATE], ['27 November 2019'])
AC_CONFIG_FILES(Makefile)
AC_PROG_SED
AC_PROG_LN_S
AC_PROG_INSTALL
AC_OUTPUT
asciidoc-py3-9.0.0rc1/asciidocapi.py 0000644 0001750 0001750 00000023152 13570064211 016603 0 ustar joseph joseph #!/usr/bin/env python3
"""
asciidocapi - AsciiDoc API wrapper class.
The AsciiDocAPI class provides an API for executing asciidoc. Minimal example
compiles `mydoc.txt` to `mydoc.html`:
import asciidocapi
asciidoc = asciidocapi.AsciiDocAPI()
asciidoc.execute('mydoc.txt')
- Full documentation in asciidocapi.txt.
- See the doctests below for more examples.
Doctests:
1. Check execution:
>>> import io
>>> infile = io.StringIO('Hello *{author}*')
>>> outfile = io.StringIO()
>>> asciidoc = AsciiDocAPI()
>>> asciidoc.options('--no-header-footer')
>>> asciidoc.attributes['author'] = 'Joe Bloggs'
>>> asciidoc.execute(infile, outfile, backend='html4')
>>> print(outfile.getvalue())
Hello Joe Bloggs
>>> asciidoc.attributes['author'] = 'Bill Smith'
>>> infile = io.StringIO('Hello _{author}_')
>>> outfile = io.StringIO()
>>> asciidoc.execute(infile, outfile, backend='docbook')
>>> print(outfile.getvalue())
Hello Bill Smith
2. Check error handling:
>>> import io
>>> asciidoc = AsciiDocAPI()
>>> infile = io.StringIO('---------')
>>> outfile = io.StringIO()
>>> asciidoc.execute(infile, outfile)
Traceback (most recent call last):
File "", line 1, in
File "asciidocapi.py", line 189, in execute
raise AsciiDocError(self.messages[-1])
AsciiDocError: ERROR: : line 1: [blockdef-listing] missing closing delimiter
Copyright (C) 2009 Stuart Rackham. Free use of this software is granted
under the terms of the GNU General Public License (GPL).
"""
import sys,os,re
API_VERSION = '0.1.2'
MIN_ASCIIDOC_VERSION = '8.4.1' # Minimum acceptable AsciiDoc version.
def find_in_path(fname, path=None):
"""
Find file fname in paths. Return None if not found.
"""
if path is None:
path = os.environ.get('PATH', '')
for dir in path.split(os.pathsep):
fpath = os.path.join(dir, fname)
if os.path.isfile(fpath):
return fpath
else:
return None
class AsciiDocError(Exception):
pass
class Options(object):
"""
Stores asciidoc(1) command options.
"""
def __init__(self, values=[]):
self.values = values[:]
def __call__(self, name, value=None):
"""Shortcut for append method."""
self.append(name, value)
def append(self, name, value=None):
if type(value) in (int,float):
value = str(value)
self.values.append((name,value))
class Version(object):
"""
Parse and compare AsciiDoc version numbers. Instance attributes:
string: String version number '.[.][suffix]'.
major: Integer major version number.
minor: Integer minor version number.
micro: Integer micro version number.
suffix: Suffix (begins with non-numeric character) is ignored when
comparing.
Doctest examples:
>>> Version('8.2.5') < Version('8.3 beta 1')
True
>>> Version('8.3.0') == Version('8.3. beta 1')
True
>>> Version('8.2.0') < Version('8.20')
True
>>> Version('8.20').major
8
>>> Version('8.20').minor
20
>>> Version('8.20').micro
0
>>> Version('8.20').suffix
''
>>> Version('8.20 beta 1').suffix
'beta 1'
"""
def __init__(self, version):
self.string = version
reo = re.match(r'^(\d+)\.(\d+)(\.(\d+))?\s*(.*?)\s*$', self.string)
if not reo:
raise ValueError('invalid version number: %s' % self.string)
groups = reo.groups()
self.major = int(groups[0])
self.minor = int(groups[1])
self.micro = int(groups[3] or '0')
self.suffix = groups[4] or ''
def __lt__(self, other):
if self.major < other.major:
return True
elif self.major == other.major:
if self.minor < other.minor:
return True
elif self.minor == other.minor:
if self.micro < other.micro:
return True
return False
# (sigh). Copy-paste
def __le__(self, other):
if self.major > other.major:
return False
elif self.major <= other.major:
if self.minor > other.minor:
return False
elif self.minor <= other.minor:
if self.micro > other.micro:
return False
return True
def __eq__(self, other):
if self.major == other.major and self.minor == other.minor and self.micro == other.micro:
return True
return False
class AsciiDocAPI(object):
"""
AsciiDoc API class.
"""
def __init__(self, asciidoc_py=None):
"""
Locate and import asciidoc.py.
Initialize instance attributes.
"""
self.options = Options()
self.attributes = {}
self.messages = []
# Search for the asciidoc command file in that order :
# - ASCIIDOC_PY environment variable
# - asciidoc_py function argument
# - sibling (preferred to shell search paths, to ensure version matching)
# - shell search paths
cmd = os.environ.get('ASCIIDOC_PY')
if cmd:
if not os.path.isfile(cmd):
raise AsciiDocError('missing ASCIIDOC_PY file: %s' % cmd)
elif asciidoc_py:
# Next try path specified by caller.
cmd = asciidoc_py
if not os.path.isfile(cmd):
raise AsciiDocError('missing file: %s' % cmd)
else:
# try to find sibling paths
this_path = os.path.dirname(os.path.realpath(__file__))
for fname in ['asciidoc.py','asciidoc.pyc','asciidoc']:
cmd = find_in_path(fname, path=this_path)
if cmd: break
else:
# Try shell search paths.
for fname in ['asciidoc.py','asciidoc.pyc','asciidoc']:
cmd = find_in_path(fname)
if cmd: break
else:
# Finally try current working directory.
for cmd in ['asciidoc.py','asciidoc.pyc','asciidoc']:
if os.path.isfile(cmd): break
else:
raise AsciiDocError('failed to locate asciidoc')
self.cmd = os.path.realpath(cmd)
self.__import_asciidoc()
def __import_asciidoc(self, reload=False):
'''
Import asciidoc module (script or compiled .pyc).
See
http://groups.google.com/group/asciidoc/browse_frm/thread/66e7b59d12cd2f91
for an explanation of why a seemingly straight-forward job turned out
quite complicated.
'''
if os.path.splitext(self.cmd)[1] in ['.py','.pyc']:
sys.path.insert(0, os.path.dirname(self.cmd))
try:
try:
if reload:
import importlib # Because reload() is shadowed.
importlib.reload(self.asciidoc)
else:
import asciidoc
self.asciidoc = asciidoc
except ImportError:
raise AsciiDocError('failed to import ' + self.cmd)
finally:
del sys.path[0]
else:
# The import statement can only handle .py or .pyc files, have to
# use importlib for scripts with other names.
try:
from importlib.util import spec_from_loader, module_from_spec
from importlib.machinery import SourceFileLoader
loader = SourceFileLoader('asciidoc', self.cmd)
spec = spec_from_loader('asciidoc', loader)
module = module_from_spec(spec)
spec.loader.exec_module(module)
self.asciidoc = module
except ImportError:
raise AsciiDocError('failed to import ' + self.cmd)
if Version(self.asciidoc.VERSION) < Version(MIN_ASCIIDOC_VERSION):
raise AsciiDocError(
'asciidocapi %s requires asciidoc %s or better'
% (API_VERSION, MIN_ASCIIDOC_VERSION))
def execute(self, infile, outfile=None, backend=None):
"""
Compile infile to outfile using backend format.
infile can outfile can be file path strings or file like objects.
"""
self.messages = []
opts = Options(self.options.values)
if outfile is not None:
opts('--out-file', outfile)
if backend is not None:
opts('--backend', backend)
for k, v in self.attributes.items():
if v == '' or k[-1] in '!@':
s = k
elif v is None: # A None value undefines the attribute.
s = k + '!'
else:
s = '%s=%s' % (k, v)
opts('--attribute', s)
args = [infile]
# The AsciiDoc command was designed to process source text then
# exit, there are globals and statics in asciidoc.py that have
# to be reinitialized before each run -- hence the reload.
self.__import_asciidoc(reload=True)
try:
try:
self.asciidoc.execute(self.cmd, opts.values, args)
finally:
self.messages = self.asciidoc.messages[:]
except SystemExit as e:
if e.code:
raise AsciiDocError(self.messages[-1])
if __name__ == "__main__":
"""
Run module doctests.
"""
import doctest
options = doctest.NORMALIZE_WHITESPACE + doctest.ELLIPSIS
test_result = doctest.testmod(optionflags=options)
print(test_result)
sys.exit(test_result.failed > 0)
asciidoc-py3-9.0.0rc1/.gitignore 0000644 0001750 0001750 00000000502 13570064211 015743 0 ustar joseph joseph .idea/
.DS_Store
*.pyc
# ignore test products
#tests/data/*.html
#tests/data/*.xml
#tests/data/*.ly
#tests/data/*.abc
#tests/data/*.md5
#tests/data/*.png
# ignore doc products
doc/*.md5
doc/*.ly
doc/*.svg
doc/*.png
doc/*.1
doc/*.html
# ignore the configure/make products
/autom4te.cache/
/config.*
/configure
Makefile
asciidoc-py3-9.0.0rc1/doc/ 0000755 0001750 0001750 00000000000 13570064211 014523 5 ustar joseph joseph asciidoc-py3-9.0.0rc1/doc/latex-filter.txt 0000644 0001750 0001750 00000017055 13570064211 017674 0 ustar joseph joseph LaTeX Filter
============
:blogpost-status: published
:blogpost-doctype: article
:blogpost-posttype: page
:blogpost-categories: AsciiDoc,LaTeX,python
The AsciiDoc distribution includes a LaTeX filter that translates LaTeX source
to an image which is automatically inserted into the AsciiDoc output document.
Although it can accept any LaTeX source, the primary use is to render
mathematical formulae (see the examples below). The filter implements the
'latex' Listing block and Paragraph styles.
Two image formats are supported; PNG and SVG. PNG is the default since that
was the first format that this filter supported. However, SVG is a better
format since it's scalable. Using SVG make formulas look good in both PDFs
and on web pages. SVG will also scale well when zooming in on a web page for
example. It is recommended to always use the SVG format. This can be done by
setting the 'imgfmt' parameter to 'svg', as is done below. An even better way
is to set the global attribute 'latex-imgfmt' to 'svg'. Then SVG will be used
for all formulas.
This LaTeX paragraph:
[listing]
.....................................................................
["latex", imgfmt="svg"]
---------------------------------------------------------------------
\begin{equation*}
y = \int_0^\infty \gamma^2 \cos(x) dx
\end{equation*}
---------------------------------------------------------------------
.....................................................................
Renders:
["latex", imgfmt="svg"]
---------------------------------------------------------------------
\begin{equation*}
y = \int_0^\infty \gamma^2 \cos(x) dx
\end{equation*}
---------------------------------------------------------------------
Compare the formula above, which is rendered as an SVG image, to the formula
below which has been rendered as a PNG image. The difference will be most
notable if zooming in on a web page, printing the web page or when rendering
the document as a PDF.
[listing]
.....................................................................
["latex", "latex2.png", 140, imgfmt="png"]
---------------------------------------------------------------------
\begin{equation*}
y = \int_0^\infty \gamma^2 \cos(x) dx
\end{equation*}
---------------------------------------------------------------------
.....................................................................
Renders:
["latex", "latex2.png", 140, imgfmt="png"]
---------------------------------------------------------------------
\begin{equation*}
y = \int_0^\infty \gamma^2 \cos(x) dx
\end{equation*}
---------------------------------------------------------------------
This LaTeX block:
[listing]
.....................................................................
["latex","latex1.svg",imgfmt="svg",align="center"]
---------------------------------------------------------------------
\begin{equation*}
\displaystyle{ V_i = C_0 - C_3
\frac{C_1\cos(\theta_i+C_3)}{C_4+C_1\cos(\theta_i+C_2)} }
\end{equation*}
---------------------------------------------------------------------
.....................................................................
Renders:
["latex","latex1.svg",imgfmt="svg",align="center"]
---------------------------------------------------------------------
\begin{equation*}
\displaystyle{ V_i = C_0 - C_3
\frac{C_1\cos(\theta_i+C_3)}{C_4+C_1\cos(\theta_i+C_2)} }
\end{equation*}
---------------------------------------------------------------------
This LaTeX block:
[listing]
.....................................................................
.LaTeX filter example
[latex]
["latex","latex3.svg",imgfmt="svg"]
---------------------------------------------------------------------
\begin{equation}
\Re{z} =\frac{n\pi \dfrac{\theta +\psi}{2}}{
\left(\dfrac{\theta +\psi}{2}\right)^2 + \left( \dfrac{1}{2}
\log \left\lvert\dfrac{B}{A}\right\rvert\right)^2}.
\end{equation}
\begin{equation}
\boxed{\eta \leq C(\delta(\eta) +\Lambda_M(0,\delta))}
\end{equation}
\begin{equation}\label{first}
a=b+c
\end{equation}
\begin{subequations}\label{grp}
\begin{align}
a&=b+c\label{second}\\
d&=e+f+g\label{third}\\
h&=i+j\label{fourth}
\end{align}
\end{subequations}
---------------------------------------------------------------------
.....................................................................
Renders:
.LaTeX filter example
[latex]
["latex","latex3.svg",imgfmt="svg"]
---------------------------------------------------------------------
\begin{equation}
\Re{z} =\frac{n\pi \dfrac{\theta +\psi}{2}}{
\left(\dfrac{\theta +\psi}{2}\right)^2 + \left( \dfrac{1}{2}
\log \left\lvert\dfrac{B}{A}\right\rvert\right)^2}.
\end{equation}
\begin{equation}
\boxed{\eta \leq C(\delta(\eta) +\Lambda_M(0,\delta))}
\end{equation}
\begin{equation}\label{first}
a=b+c
\end{equation}
\begin{subequations}\label{grp}
\begin{align}
a&=b+c\label{second}\\
d&=e+f+g\label{third}\\
h&=i+j\label{fourth}
\end{align}
\end{subequations}
---------------------------------------------------------------------
This LaTeX paragraph:
[listing]
.....................................................................
.A LaTeX table
["latex",imgfmt="svg"]
\begin{tabular}{c r @{.} l}
Pi expression &
\multicolumn{2}{c}{Value} \\
\hline
$\pi$ & 3&1416 \\
$\pi^{\pi}$ & 36&46 \\
$(\pi^{\pi})^{\pi}$ & 80662&7 \\
\end{tabular}
.....................................................................
Renders:
.A LaTeX table
["latex",imgfmt="svg"]
\begin{tabular}{c r @{.} l}
Pi expression &
\multicolumn{2}{c}{Value} \\
\hline
$\pi$ & 3&1416 \\
$\pi^{\pi}$ & 36&46 \\
$(\pi^{\pi})^{\pi}$ & 80662&7 \\
\end{tabular}
Using the Filter
----------------
- The LaTeX filter is invoked by setting the Listing block or
Paragraph style (the first positional block attribute) to 'latex'.
- The second positional attribute (named 'target' is optional, it sets
the name of the generated image file. If this is not supplied a
file name like `{docname}__{target-number}.{imgfmt}` is synthesised
(where `{docname}` is the document file name, `{target-number}`
is an integer number and `{imgfmt}` is the image format (png or svg).
- The third positional attribute, named 'dpi', is also optional; it is
an integer number that sets the output resolution in dots per inch
for a PNG image. It is ignored for an SVG image.
- The image format to use can be selected by setting the 'imgfmt'
parameter or by globally setting the 'latex-imgfmt' attribute.
Setting it to 'svg' will render SVG images and setting it to 'png'
will render PNG images. The default is 'png'.
Because the LaTeX images are rendered using the image block templates
you can also use the optional named image block attributes (see
link:userguide.html#X55[Image macro attributes] in the AsciiDoc User
Guide).
[TIP]
=====================================================================
You can also change the image size using the following LaTeX commands:
\tiny
\scriptsize
\footnotesize
\small
\normalsize
\large
\Large
\LARGE
\huge
For example:
[latex]
\Large $y = \int_0^\infty \gamma^2 \cos(x) dx$
The `\Large` command is outside the `$` math delimiters.
=====================================================================
The filter (`./filters/latex/latex2img.py`) can be used outside
AsciiDoc to convert LaTeX source to images.
Execute the following command to see how to use it:
$ ./filters/latex/latex2img.py --help
Limitations
-----------
- The `asciidoc(1)` input and output files cannot both be `-` (stdin
and stdout), either the input or output files (or both) must be a
named file.
Installation
------------
In addition to AsciiDoc you will need to have `latex(1)`,
`dvipng(1)` (for PNG) and/or `dvisvgm(1)` (for SVG) installed.
asciidoc-py3-9.0.0rc1/doc/faq.txt 0000644 0001750 0001750 00000134634 13570064211 016046 0 ustar joseph joseph 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://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
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 <> (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` 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]
[{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
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://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
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]
---------------------------------------------------------------------
. 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?
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 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 http://johnmacfarlane.net/pandoc/[Pandoc] to convert
documents in http://daringfireball.net/projects/markdown/[markdown],
http://docutils.sourceforge.net/docs/ref/rst/introduction.html[reStructuredText],
http://redcloth.org/textile[textile],
http://www.w3.org/TR/html40/[HTML], http://www.docbook.org/[DocBook],
or http://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 inlcude 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
http://docbook.sourceforge.net/release/xsl/1.78.1/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].
asciidoc-py3-9.0.0rc1/doc/latexmath.txt 0000644 0001750 0001750 00000007240 13570064211 017256 0 ustar joseph joseph Embedding LaTeX Math in AsciiDoc dblatex documents
==================================================
You can include LaTeX math equations in AsciiDoc documents that are
processed by http://dblatex.sourceforge.net/[dblatex]. The AsciiDoc
'latexmath' macros and passthrough blocks generate DocBook
'inlineequation', 'informalequation' and 'equation' elements
containing the LaTeX markup which is processed by 'dblatex'.
Inline equations
----------------
This markup:
---------------------------------------------------------------------
An inline equation latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$]
using the 'latexmath' inline macro.
---------------------------------------------------------------------
Renders:
An inline equation latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$]
using the 'latexmath' inline macro.
Informal equations
------------------
Informal (untitled) equations are generated with a 'latexmath' style
passthrough delimited block. This markup:
---------------------------------------------------------------------
[latexmath]
++++++++++++++++++++++++++++++++++++++++++++
\[C = \alpha + \beta Y^{\gamma} + \epsilon\]
++++++++++++++++++++++++++++++++++++++++++++
---------------------------------------------------------------------
Renders:
[latexmath]
++++++++++++++++++++++++++++++++++++++++++++
\[C = \alpha + \beta Y^{\gamma} + \epsilon\]
++++++++++++++++++++++++++++++++++++++++++++
Functionally identical block macro syntax:
---------------------------------------------------------------------
latexmath::[\[C = \alpha + \beta Y^{\gamma} + \epsilon\]]
---------------------------------------------------------------------
Renders:
latexmath::[\[C = \alpha + \beta Y^{\gamma} + \epsilon\]]
Formal equations
----------------
Formal equations are titled and are generated with a 'latexmath' style
passthrough delimited block.
This markup:
---------------------------------------------------------------------
.First equation
[latexmath]
++++++++++++++++++++++++++++++++++++++++++++
\[C = \alpha + \beta Y^{\gamma} + \epsilon\]
++++++++++++++++++++++++++++++++++++++++++++
---------------------------------------------------------------------
Renders:
.First equation
[latexmath]
++++++++++++++++++++++++++++++++++++++++++++
\[C = \alpha + \beta Y^{\gamma} + \epsilon\]
++++++++++++++++++++++++++++++++++++++++++++
This markup:
---------------------------------------------------------------------
.Matrix
[latexmath]
++++++++++++++++++++++++++++++++++++++++++++
\[ P^{e \rightarrow c}= \left[
\begin{array}{*{3}{r@{}l}}
& \cos \theta & & \sin \theta \sin \varphi & & \sin \theta \cos \varphi\\
& \sin \theta \sin \psi
& & \cos \varphi \cos \psi - \cos \theta \sin \varphi \sin \psi
& - & \sin \varphi \cos \psi - \cos \theta \cos \varphi \sin \psi\\
- & \sin \theta \cos \psi
& & \cos \varphi \sin \psi + \cos \theta \sin \varphi \cos \psi
& - & \sin \varphi \sin \psi + \cos \theta \cos \varphi \cos \psi\\
\end{array}
\right] \]
++++++++++++++++++++++++++++++++++++++++++++
---------------------------------------------------------------------
Renders:
.Matrix
[latexmath]
++++++++++++++++++++++++++++++++++++++++++++
\[ P^{e \rightarrow c}= \left[
\begin{array}{*{3}{r@{}l}}
& \cos \theta & & \sin \theta \sin \varphi & & \sin \theta \cos \varphi\\
& \sin \theta \sin \psi
& & \cos \varphi \cos \psi - \cos \theta \sin \varphi \sin \psi
& - & \sin \varphi \cos \psi - \cos \theta \cos \varphi \sin \psi\\
- & \sin \theta \cos \psi
& & \cos \varphi \sin \psi + \cos \theta \sin \varphi \cos \psi
& - & \sin \varphi \sin \psi + \cos \theta \cos \varphi \cos \psi\\
\end{array}
\right] \]
++++++++++++++++++++++++++++++++++++++++++++
asciidoc-py3-9.0.0rc1/doc/music-filter.txt 0000644 0001750 0001750 00000012011 13570064211 017662 0 ustar joseph joseph Music Filter
============
The AsciiDoc distribution includes a Music Block filter that
translates music in http://lilypond.org/[LilyPond] or
http://abcnotation.org.uk/[ABC] notation to standard classical
notation in the form of a trimmed PNG image which is automatically
inserted into the AsciiDoc output document (see the examples below).
Actually the filter (`./filters/music/music2png.py`) can be used outside
AsciiDoc to convert LilyPond or ABC music files to PNG images.
Execute the following command to see how to use it:
$ ./filters/music/music2png.py --help
.Music Block containing ABC notation
=====================================================================
This Music Block:
[listing]
.....................................................................
["music","music1.png",scaledwidth="100%"]
---------------------------------------------------------------------
T:The Butterfly
R:slip jig
C:Tommy Potts
H:Fiddle player Tommy Potts made this tune from two older slip jigs,
H:one of which is called "Skin the Peelers" in Roche's collection.
H:This version by Peter Cooper.
D:Bothy Band: 1975.
M:9/8
K:Em
vB2(E G2)(E F3)|B2(E G2)(E F)ED|vB2(E G2)(E F3)|(B2d) d2(uB A)FD:|
|:(vB2c) (e2f) g3|(uB2d) (g2e) (dBA)|(B2c) (e2f) g2(ua|b2a) (g2e) (dBA):|
|:~B3 (B2A) G2A|~B3 BA(uB d)BA|~B3 (B2A) G2(A|B2d) (g2e) (dBA):|
---------------------------------------------------------------------
.....................................................................
Renders:
["music","music1.png",scaledwidth="100%"]
---------------------------------------------------------------------
T:The Butterfly
R:slip jig
C:Tommy Potts
H:Fiddle player Tommy Potts made this tune from two older slip jigs,
H:one of which is called "Skin the Peelers" in Roche's collection.
H:This version by Peter Cooper.
D:Bothy Band: 1975.
M:9/8
K:Em
vB2(E G2)(E F3)|B2(E G2)(E F)ED|vB2(E G2)(E F3)|(B2d) d2(uB A)FD:|
|:(vB2c) (e2f) g3|(uB2d) (g2e) (dBA)|(B2c) (e2f) g2(ua|b2a) (g2e) (dBA):|
|:~B3 (B2A) G2A|~B3 BA(uB d)BA|~B3 (B2A) G2(A|B2d) (g2e) (dBA):|
---------------------------------------------------------------------
=====================================================================
.Music Block containing LilyPond notation
=====================================================================
This example contains LilyPond musical markup.
[listing]
.....................................................................
[music]
---------------------------------------------------------------------
\version "2.14.2"
\paper {
ragged-right = ##t
}
{
\time 3/4
\clef bass
c2 e4 g2. f4 e d c2 r4
}
---------------------------------------------------------------------
.....................................................................
Renders:
[music]
---------------------------------------------------------------------
\version "2.14.2"
\paper {
ragged-right = ##t
}
{
\time 3/4
\clef bass
c2 e4 g2. f4 e d c2 r4
}
---------------------------------------------------------------------
=====================================================================
NOTE: If you get an error processing the above example it may be that
it is not compatible with your version of LilyPond. Use the LilyPond
`convert-ly(1)` utility to update the source to the version that you
are using.
Using the Filter
----------------
- The Music filter is invoked by setting the Listing block or
Paragraph style (the first positional block attribute) to 'music'.
- The second positional attribute (named 'target' is optional, it sets
the name of the generated PNG image file. If this is not supplied a
file name like `{docname}__{target-number}.png` is synthesised
(where `{docname}` is the document file name and `{target-number}`
is an integer number.
- The third positional attribute ('format') specifies the music input
format: either 'abc' for ABC or 'ly' for LilyPond. If the format is
omitted ABC notation is assumed unless the text starts with a
backslash character, in which case the format is set to 'ly'.
Because the LaTeX images are rendered using the image block templates
you can also use the optional named image block attributes (see
link:userguide.html#X55[Image macro attributes] in the AsciiDoc User
Guide).
Limitations
-----------
- The `asciidoc(1)` input and output files cannot both be `-` (stdin
and stdout), either the input or output files (or both) must be a
named file.
Installation
------------
In addition to AsciiDoc you will need to have installed:
- http://lilypond.org/web/[LilyPond] (most Linux distributions include
this package).
- http://www.imagemagick.org[ImageMagick] (most Linux distributions
include this package).
Test the music filter it by converting the test file to HTML with AsciiDoc:
$ asciidoc -v ./filters/music/music-filter-test.txt
$ firefox ./filters/music/music-filter-test.html &
The filter was developed and tested on Xubuntu Linux using LilyPond
2.10.5 and ImageMagick 6.2.4.
NOTE: The filter does not work with LilyPond 2.2.6 because it did not
generate the requested output file name correctly (2.6.3 does not have
a problem).
asciidoc-py3-9.0.0rc1/doc/customers.csv 0000644 0001750 0001750 00000001463 13570064211 017270 0 ustar joseph joseph "AROUT","Around the Horn","Thomas Hardy","120 Hanover Sq.
London","(171) 555-7788"
"BERGS","Berglunds snabbkop","Christina Berglund","Berguvsvagen 8
Lulea","0921-12 34 65"
"BLAUS","Blauer See Delikatessen","Hanna Moos","Forsterstr. 57
Mannheim","0621-08460"
"BLONP","Blondel pere et fils","Frederique Citeaux","24, place Kleber
Strasbourg","88.60.15.31"
"BOLID","Bolido Comidas preparadas","Martin Sommer","C/ Araquil, 67
Madrid","(91) 555 22 82"
"BONAP","Bon app'","Laurence Lebihan","12, rue des Bouchers
Marseille","91.24.45.40"
"BOTTM","Bottom-Dollar Markets","Elizabeth Lincoln","23 Tsawassen Blvd.
Tsawassen","(604) 555-4729"
"BSBEV","B's Beverages","Victoria Ashworth","Fauntleroy Circus
London","(171) 555-1212"
"CACTU","Cactus Comidas para llevar","Patricio Simpson","Cerrito 333
Buenos Aires","(1) 135-5555"
asciidoc-py3-9.0.0rc1/doc/publishing-ebooks-with-asciidoc.txt 0000644 0001750 0001750 00000032664 13570064211 023450 0 ustar joseph joseph Publishing eBooks with AsciiDoc
===============================
// Web page meta data.
:keywords: AsciiDoc, EPUB tools, EPUB, PDF, ebooks
:description: How to create EPUB and PDF ebooks using AsciiDoc.
ifdef::blogpost[]
// Use the same article for both a blog post and on the AsciiDoc
// website.
:blogpost-title: Publishing eBooks with AsciiDoc
:blogpost-status: published
:blogpost-doctype: article
:blogpost-posttype: post
:blogpost-categories: AsciiDoc,eBook,EPUB,DocBook
*Published*: 2010-08-23 +
*Updated*: 2010-05-08
endif::blogpost[]
It's easy to write and publish books in
http://en.wikipedia.org/wiki/EPUB[EPUB] and PDF formats using
http://asciidoc.org/[AsciiDoc].
ifdef::blogpost[]
This article was originally published on the
http://asciidoc.org/publishing-ebooks-with-asciidoc.html[AsciiDoc
website].
endif::blogpost[]
Here are three examples: The first is a <>
introducing the AsciiDoc format, the second <> is a rather long multi-part book and the third <> includes a front cover image and
customized page styling.
ifdef::blogpost[]
// Wordpress processing instruction.
pass::[]
endif::blogpost[]
The examples presented below were created on a PC running Xubuntu
Linux 10.04 but should be applicable to any UNIX-based operating
system.
NOTE: A number of 'asciidoc' and 'a2x' features used in this article
require newer versions of AsciiDoc -- version 8.6.5 or better is
recommended. The version of
http://wiki.docbook.org/topic/DocBookXslStylesheets[DocBook XSL
Stylesheets] used was 1.76.1.
TIP: If you are experiencing 'xsltproc' errors when you run 'a2x' take
a look at Francis Shanahan's
http://francisshanahan.com/index.php/2011/fixing-epub-problem-docbook-xsl-asciidoc-a2x/[Fixing
the ePub problem with Docbook-XSL/A2X/Asciidoc] blog post.
[[X1]]
Minimal Book
------------
This didactic example contains a title and two chapters. The AsciiDoc
source is a plain text file named `minimal-book.txt`:
---------------------------------------------------------------------
= The Book Title
== The first chapter
Nec vitae mus fringilla eu vel pede sed pellentesque. Nascetur fugiat
nobis. Eu felis id mauris sollicitudin ut. Sem volutpat feugiat.
Ornare convallis urna vitae.
Nec mauris sed aliquam nam mauris dolor lorem imperdiet.
== The second chapter
Ut suspendisse nulla. Auctor felis facilisis. Rutrum vivamus nec
lectus porttitor dui dapibus eu ridiculus tempor sodales et. Sit a
cras. Id tellus cubilia erat.
Quisque nullam et. Blandit dui tempor. Posuere in elit diam egestas
sem vivamus vel ac.
---------------------------------------------------------------------
To generate the EPUB formatted book file `minimal-book.epub` run
AsciiDoc's 'a2x' toolchain wrapper command from the command-line:
a2x -fepub -dbook minimal-book.txt
The `-f` option specifies the output format, the `-d` option specifies
the document type (book, article or manpage). The optional
`--epubcheck` option tells 'a2x' to validate the EPUB file using
http://code.google.com/p/epubcheck/[epubcheck]. To generate a PDF
version (`minimal-book.pdf`) with 'dblatex' run:
a2x -fpdf -dbook minimal-book.txt
The distributed example PDFs were built using FOP -- if you prefer
http://xmlgraphics.apache.org/fop/[FOP] over
http://dblatex.sourceforge.net/[dblatex] use:
a2x -fpdf -dbook --fop minimal-book.txt
You can also generate an HTML formatted book, either using DocBook XSL
Stylesheets:
a2x -fxhtml -dbook minimal-book.txt
or directly using the 'asciidoc' command:
asciidoc -dbook minimal-book.txt
[NOTE]
======
The http://asciidoc.org/a2x.1.html[a2x toolchain
wrapper] uses the following programs (most will be available
prepackaged for your Linux distribution):
- http://xmlsoft.org/XSLT/[xsltproc]
- http://docbook.sourceforge.net/projects/xsl/[DocBook XSL
Stylesheets]
- http://dblatex.sourceforge.net/[dblatex] (PDF file generator)
- http://xmlgraphics.apache.org/fop/[FOP] (alternative PDF file
generator)
- http://code.google.com/p/epubcheck/[epubcheck] (optional EPUB file
validator)
======
[[X2]]
The Brothers Karamazov
----------------------
'The Brothers Karamazov' is an example of a multi-part book. To
generate the AsciiDoc source I downloaded the
http://www.gutenberg.org[Project Gutenberg] plain text source and
edited it manually (this took around 15 minutes). To generate the
`brothers-karamazov.epub` EPUB file run this command:
a2x brothers-karamazov.txt
:examples-url: http://asciidoc.org/examples/books/
[frame="topbot",options="header",caption=""]
.Brothers Karamazov source files and eBooks
|====================================================================
|EPUB |PDF |AsciiDoc source |Project Gutenburg text
|{examples-url}brothers-karamazov.epub[brothers-karamazov.epub]
|{examples-url}brothers-karamazov.pdf[brothers-karamazov.pdf]
|{examples-url}brothers-karamazov.zip[brothers-karamazov.zip]
|http://www.gutenberg.org/etext/28054
|====================================================================
Here's the start of the AsciiDoc source file showing the AsciiDoc
specific meta-data:
---------------------------------------------------------------------
//
// Text from Project Gutenburg http://www.gutenberg.org/etext/28054
//
// Formatted for AsciiDoc by Stuart Rackham.
//
// a2x default options.
// a2x: -f epub -d book --epubcheck
// Suppress revision history in dblatex outputs.
// a2x: --dblatex-opts "-P latex.output.revhistory=0"
// Suppress book part, chapter and section numbering in DocBook XSL outputs.
// a2x: --xsltproc-opts
// a2x: "--stringparam part.autolabel 0
// a2x: --stringparam chapter.autolabel 0
// a2x: --stringparam section.autolabel.max.depth 0"
//
= The Brothers Karamazov
:author: Fyodor Dostoyevsky
:encoding: iso-8859-1
:plaintext:
..........................................................................
Translated from the Russian of Fyodor Dostoyevsky by Constance Garnett
The Lowell Press New York
:
:
***START OF THE PROJECT GUTENBERG EBOOK THE BROTHERS KARAMAZOV***
..........................................................................
= PART I
== The History Of A Family
=== Fyodor Pavlovitch Karamazov
Alexey Fyodorovitch Karamazov was the third son of Fyodor Pavlovitch
...
---------------------------------------------------------------------
- The book, book part and chapter titles have been edited to conform
to http://asciidoc.org/userguide.html#X17[AsciiDoc
title conventions].
- Book part titles must be level zero titles:
= Book title (level 0)
= Part one title (level 0)
== Chapter 1 title (level 1)
:
- Sub-chapter levels can be accommodated with `===`, `====` and
`=====` title prefixes.
- In this example the 'Project Gutenberg' front matter was put in the
untitled preface inside an AsciiDoc literal block.
- The comment lines starting with `// a2x:` contain 'a2x' command
options for this document (it's easier to put them in the document
once than type them every time on the command-line).
- A number of 'xsltproc' options are passed to 'a2x' to suppress book
part, chapter and section numbering.
- Setting the AsciiDoc 'plaintext' attribute suppresses most of
http://asciidoc.org/userguide.html#_text_formatting[AsciiDoc's
text formatting] and substitution conventions, this allows large
amounts of text to be imported with little or no manual editing.
* Once you have defined the AsciiDoc 'plaintext' attribute the only
requisite manual editing will be to format the titles and rectify
the odd paragraph being interpreted as some other AsciiDoc block
element.
* In the combined 49 thousand lines of imported 'Sherlock Holmes'
and 'Brothers Karamazov' text I only encountered two
misinterpreted list items, neither affected the rendered output or
necessitated editing.
* You can selectively enable and disable the 'plaintext' attribute
throughout your document using AsciiDoc
http://asciidoc.org/userguide.html#X18[attribute
entries].
[[X3]]
The Adventures of Sherlock Holmes
---------------------------------
This book includes a front cover image and a customized page design.
To generate the `adventures-of-sherlock-holmes.epub` EPUB file run
this command:
a2x adventures-of-sherlock-holmes.txt
[frame="topbot",options="header",caption=""]
.Sherlock Holmes source files and eBooks
|====================================================================
|EPUB |PDF |AsciiDoc source |Project Gutenburg text
|{examples-url}adventures-of-sherlock-holmes.epub[adventures-of-sherlock-holmes.epub]
|{examples-url}adventures-of-sherlock-holmes.pdf[adventures-of-sherlock-holmes.pdf]
|{examples-url}adventures-of-sherlock-holmes.zip[adventures-of-sherlock-holmes.zip]
|http://www.gutenberg.org/etext/1661
|====================================================================
Here's a screenshot of the first page of the first chapter (rendered
by the http://www.epubread.com/en/[Firefox EPUBReader addon]):
image::images/epub.png[]
The {examples-url}adventures-of-sherlock-holmes.zip[AsciiDoc source
Zip file] contains the following files:
`adventures-of-sherlock-holmes.txt`::
The AsciiDoc source (derived from the
http://www.gutenberg.org/etext/1661[Project Gutenberg plain text
source]).
`adventures-of-sherlock-holmes.jpg`::
The front cover image.
`adventures-of-sherlock-holmes-docinfo.xml`::
A http://asciidoc.org/userguide.html#X87[docinfo] file
containing DocBook markup for the front cover image and the Project
Gutenberg frontmatter. DocBook XSL Stylesheets identifies the book
cover image by the `role="cover"` attribute in the DocBook
`mediaobject` element.
`adventures-of-sherlock-holmes.css`::
CSS rules for styling the page layout. The design is based on the
http://epubzengarden.com[ePub Zen Garden] 'Gbs' style. Because this
file is not named `docbook-xsl.css` the name must be specified
explicitly using the 'a2x' `--stylesheet` option.
`underline.png`::
A title underline image that is used by the CSS stylesheet. This
resource has to be explicitly passed to 'a2x' because 'a2x' only
searches HTML files for resources.
Here's the start of the AsciiDoc source file showing the AsciiDoc
specific meta-data:
---------------------------------------------------------------------
//
// Text from Project Gutenburg http://www.gutenberg.org/etext/1661
//
// Formatted for AsciiDoc by Stuart Rackham.
//
// a2x default options.
// a2x: -f epub -d book -a docinfo --epubcheck
// a2x: --stylesheet adventures-of-sherlock-holmes.css
// Suppress revision history in dblatex outputs.
// a2x: --dblatex-opts "-P latex.output.revhistory=0"
// Suppress book part, chapter and section numbering in DocBook XSL outputs.
// a2x: --xsltproc-opts
// a2x: "--stringparam part.autolabel 0
// a2x: --stringparam chapter.autolabel 0
// a2x: --stringparam section.autolabel.max.depth 0"
// Additional resources.
// a2x: --resource underline.png
//
= The Adventures of Sherlock Holmes
:author: Sir Arthur Conan Doyle
:encoding: iso-8859-1
:plaintext:
== A Scandal in Bohemia
To Sherlock Holmes she is always THE woman. I have seldom heard
...
---------------------------------------------------------------------
The manual editing of imported plain text involves formatting the
title and chapter names as
http://asciidoc.org/userguide.html#X17[AsciiDoc titles]
(in this example we've used the 'single line' title format). Sherlock
Holmes only has two title levels:
---------------------------------------------------------------------
= The Adventures of Sherlock Holmes
== A Scandal in Bohemia
== The Red-Headed League
== A Case of Identity
== The Boscombe Valley Mystery
== The Five Orange Pips
== The Man with the Twisted Lip
== The Adventure of the Blue Carbuncle
== The Adventure of the Speckled Band
== The Adventure of the Engineer's Thumb
== The Adventure of the Noble Bachelor
== The Adventure of the Beryl Coronet
== The Adventure of the Copper Beeches
== Colophon
---------------------------------------------------------------------
Styling your books
------------------
You can customize the appearance of a document with CSS. CSS file.
Either create your own or copy and edit the existing default
`docbook-xsl.css` file (located in the AsciiDoc `stylesheets`
configuration directory) then place it in the same directory as your
AsciiDoc source file. Use the 'a2x' `--stylesheet` option if you want
to use a different stylesheet file. Take a look at the
`adventures-of-sherlock-holmes.css` CSS file.
There are some great examples of EPUB book styles at
http://epubzengarden.com/[ePub Zen Garden].
Including embedded fonts
------------------------
See http://asciidoc.org/faq.html#X5[this FAQ].
Reading EPUB documents
----------------------
My current favorite software epub reader is the
http://www.epubread.com/en/[Firefox EPUBReader addon]. EPUBReader
honors the book's CSS styling rules and renders the page as the author
intended (many EPUB readers only process a sub-set of CSS styling
rules).
Browsers are a natural fit for EPUB (EPUB is just a bunch of zipped
XHTML files) -- I'd love to see browsers support EPUB natively.
As of writing this article most eBook readers (with the notable
exception of Amazon's Kindle) support the EPUB format.
Non-fiction Books and Manuals
-----------------------------
AsciiDoc supports a rich set of markup conventions and can generate
reference works and technical manuals complete with tables,
illustrations, indexes, bibliographies and appendices. All the
examples on the http:///asciidoc.org/[AsciiDoc web site]
can be formatted as EPUB eBooks.
asciidoc-py3-9.0.0rc1/doc/book-multi.txt 0000644 0001750 0001750 00000011023 13570064211 017343 0 ustar joseph joseph Multi-Part Book Title Goes Here
===============================
Author's Name
v1.0, 2003-12
:doctype: book
[dedication]
Example Dedication
==================
The optional dedication goes here.
This document is an AsciiDoc multi-part book skeleton containing
briefly annotated element placeholders plus a couple of example index
entries and footnotes. Books are normally used to generate DocBook
markup and the preface, appendix, bibliography, glossary and index
section titles are significant ('specialsections').
NOTE: Multi-part books differ from all other AsciiDoc document formats
in that top level sections (dedication, preface, book parts,
appendices, bibliography, glossary, index) must be level zero headings
(not level one).
[preface]
Example Preface
================
The optional book preface goes here at section level zero.
Preface Sub-section
~~~~~~~~~~~~~~~~~~~
NOTE: Preface and appendix subsections start out of sequence at level
2 (level 1 is skipped). This only applies to multi-part book
documents.
The First Part of the Book
==========================
[partintro]
.Optional part introduction title
--
Optional part introduction goes here.
--
The First Chapter
-----------------
Chapters can be grouped by preceding them with a level 0 Book Part
title.
Book chapters are at level 1 and can contain sub-sections nested up to
three deep.
footnote:[An example footnote.]
indexterm:[Example index entry]
It's also worth noting that a book part can have it's own preface,
bibliography, glossary and index. Chapters can have their own
bibliography, glossary and index.
And now for something completely different: ((monkeys)), lions and
tigers (Bengal and Siberian) using the alternative syntax index
entries.
(((Big cats,Lions)))
(((Big cats,Tigers,Bengal Tiger)))
(((Big cats,Tigers,Siberian Tiger)))
Note that multi-entry terms generate separate index entries.
Here are a couple of image examples: an image:images/smallnew.png[]
example inline image followed by an example block image:
.Tiger block image
image::images/tiger.png[Tiger image]
Followed by an example table:
.An example table
[width="60%",options="header"]
|==============================================
| Option | Description
| -a 'USER GROUP' | Add 'USER' to 'GROUP'.
| -R 'GROUP' | Disables access to 'GROUP'.
|==============================================
.An example example
===============================================
Lorum ipum...
===============================================
[[X1]]
Sub-section with Anchor
~~~~~~~~~~~~~~~~~~~~~~~
Sub-section at level 2.
Chapter Sub-section
^^^^^^^^^^^^^^^^^^^
Sub-section at level 3.
Chapter Sub-section
+++++++++++++++++++
Sub-section at level 4.
This is the maximum sub-section depth supported by the distributed
AsciiDoc configuration.
footnote:[A second example footnote.]
The Second Chapter
------------------
An example link to anchor at start of the <>.
indexterm:[Second example index entry]
An example link to a bibliography entry <>.
The Second Part of the Book
===========================
The First Chapter of the Second Part
------------------------------------
Chapters grouped into book parts are at level 1 and can contain
sub-sections.
:numbered!:
[appendix]
Example Appendix
================
One or more optional appendixes go here at section level zero.
Appendix Sub-section
~~~~~~~~~~~~~~~~~~~
NOTE: Preface and appendix subsections start out of sequence at level
2 (level 1 is skipped). This only applies to multi-part book
documents.
[bibliography]
Example Bibliography
====================
The bibliography list is a style of AsciiDoc bulleted list.
[bibliography]
- [[[taoup]]] Eric Steven Raymond. 'The Art of Unix
Programming'. Addison-Wesley. ISBN 0-13-142901-9.
- [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
'DocBook - The Definitive Guide'. O'Reilly & Associates. 1999.
ISBN 1-56592-580-7.
[glossary]
Example Glossary
================
Glossaries are optional. Glossaries entries are an example of a style
of AsciiDoc labeled lists.
[glossary]
A glossary term::
The corresponding (indented) definition.
A second glossary term::
The corresponding (indented) definition.
[colophon]
Example Colophon
================
Text at the end of a book describing facts about its production.
[index]
Example Index
=============
////////////////////////////////////////////////////////////////
The index is normally left completely empty, it's contents are
generated automatically by the DocBook toolchain.
////////////////////////////////////////////////////////////////
asciidoc-py3-9.0.0rc1/doc/testasciidoc.txt 0000644 0001750 0001750 00000017703 13570064211 017752 0 ustar joseph joseph AsciiDoc Tests
==============
AsciiDoc includes 'testasciidoc', a Python script runs a set of
AsciiDoc conformance tests. 'testasciidoc' runs through a list of
AsciiDoc source files, generates backend outputs and then compares
them to expected result files. The whole process is driven by a
configuration file containing a list of user configurable test
specifications.
Rationale
---------
When modifying AsciiDoc configuration files or source code it's very
easy to introduce regression errors. 'testasciidoc' is a tool for
writing many and varied test cases that can be run after changes have
been made in order to verify that existing behavior has not been
broken.
The 'testasciidoc' 'update' command automates the (re)generation of
expected test result data. Result data regeneration has to be
performed after changes to test case source files or after legitimate
changes to the AsciiDoc output formats -- doing this manually is
prohibitively tedious.
Running testasciidoc
--------------------
The `testasciidoc.py` script and the default `testasciidoc.conf`
configuration file are located in the AsciiDoc distribution `tests`
directory.
To view the command usage run:
---------------------------------------------------------------------
$ python tests/testasciidoc.py
Usage: testasciidoc.py [OPTIONS] COMMAND
Run AsciiDoc conformance tests specified in configuration FILE.
Commands:
list List tests
run [NUMBER] [BACKEND] Execute tests
update [NUMBER] [BACKEND] Regenerate and update test data
Options:
-f, --conf-file=CONF_FILE
Use configuration file CONF_FILE (default configuration file is
testasciidoc.conf in testasciidoc.py directory)
--force
Update all test data overwriting existing data
---------------------------------------------------------------------
To view the list of tests in the default `testasciidoc.conf`
configuration file run the 'list' command:
---------------------------------------------------------------------
$ python tests/testasciidoc.py list
1: Test cases
2: Tables
3: Source highlighter
4: Example article
5: Example book
6: Example multi-part book
7: !User Guide
---------------------------------------------------------------------
The '!' prefix signals that a test is currently disabled.
Before running the tests you will need to regenerate the expected
outputs by running the 'update' command:
---------------------------------------------------------------------
$ python tests/testasciidoc.py update
WRITING: tests/data/testcases-html4.html
WRITING: tests/data/testcases-xhtml11.html
WRITING: tests/data/testcases-docbook.xml
:
WRITING: tests/data/book-multi-docbook.xml
---------------------------------------------------------------------
Now you can run the tests:
---------------------------------------------------------------------
$ python tests/testasciidoc.py run
1: Test cases
SOURCE: asciidoc: tests/data/testcases.txt
PASSED: html4: tests/data/testcases-html4.html
PASSED: xhtml11: tests/data/testcases-xhtml11.html
PASSED: docbook: tests/data/testcases-docbook.xml
:
6: Example multi-part book
SOURCE: asciidoc: doc/book-multi.txt
PASSED: html4: tests/data/book-multi-html4.html
PASSED: xhtml11: tests/data/book-multi-xhtml11.html
PASSED: docbook: tests/data/book-multi-docbook.xml
TOTAL PASSED: 18
---------------------------------------------------------------------
[NOTE]
=====================================================================
- 'testasciidoc' requires AsciiDoc is located in your environment
search path, if not you'll need to set the `ASCIIDOC_PY` environment
variable to point to `asciidoc.py`.
- If you don't have GNU source-highlight installed you should disable
the 'Tables' and 'Source highlighter' tests in the
`tests/testasciidoc.conf` configuration file.
=====================================================================
testasciidoc commands
---------------------
'list'::
List test numbers and titles. A '!' title prefix signals that a
test is currently disabled.
'run'::
Read and execute tests from the test configuration file. A test
specifies AsciiDoc test case source file and command options. The
test compares generated outputs to expected outputs and any
differences displayed as a diff. You can run selected tests by
specifying the test number and/or backend after the `run` command.
Examples:
python tests/testasciidoc.py run
python tests/testasciidoc.py run 3
python tests/testasciidoc.py run html4
python tests/testasciidoc.py run 3 html4
'update'::
Generates and updates missing and out of date test output data
files, this eliminates one of the most time consuming aspect of test
management. Use the `--force` option to force updates.
Examples:
python tests/testasciidoc.py update
python tests/testasciidoc.py --force update 4
NOTE: You can run or update disabled tests by explicitly specifying
the test number.
Test configuration file
-----------------------
The tests configuration file format consists of one or more test specs
separated by a line of one or more percent characters. Each test spec
consists of an optional test title and description followed by one or
more optional directives (a directive starts with a percent
character). A 'directive' consists begins with a line containing a '%'
character followed by a directive name followed by zero or more lines
of directive data.
Test spec format
~~~~~~~~~~~~~~~~
---------------------------------------------------------------------
Optional test title
Optional test description...
% name
Optional base output file name. Defaults to base source file name.
% source
AsciiDoc source file name.
% backends
Optional list of backends to be tested(default is all backends).
% options
Optional list of command-line option tuples.
% attributes
Optional dictionary of attribute values.
---------------------------------------------------------------------
Example test spec:
---------------------------------------------------------------------
Example book
% options
['--section-numbers',('--doctype','book')]
% attributes
# Exclude date from document footer.
{'docdate':None}
% source
../doc/book.txt
---------------------------------------------------------------------
TIP: Take a look at the default `tests/testasciidoc.conf`
configuration file that comes with AsciiDoc.
- Tests can be disabled by prefixing the test title with an
exclamation '!' character.
- All relative file names are relative to the configuration file
directory.
- Multiple tests must by separated by a `%` separator line (one or
more percent characters).
- Lines starting with a percent character specify a test 'directive'
and may be followed by zero or more lines of directive data.
- Directive data lines cannot start with a percent character.
- Lines starting with a `#` hash character are ignored.
- The 'source' directive data is a single line containing the
AsciiDoc source file name.
- The 'options' directive data is a Python list of `(name,value)`
tuples specifying AsciiDoc command-line options. A string item is
equivalent to a `(name,None)` tuple.
- The 'attributes' directive data specifies a Python dictionary
containing AsciiDoc attributes to be passed to AsciiDoc.
globals directive
~~~~~~~~~~~~~~~~~
An optional 'globals' directive can precede all test specs, the
globals directive data is a Python dictionary containing global
values. Currently the only global is 'datadir', the directory
containing expected output files (defaults to configuration file
directory). For example:
---------------------------------------------------------------------
% globals
{'datadir': 'data'}
---------------------------------------------------------------------
Expected output test data files are stored in the 'datadir' and are
named after the corresponding AsciiDoc input source file. For example
if the AsciiDoc file name is `article.txt` then the corresponding
backend output files will be `article-html4.html`,
`article-xhtml11.html`, `article-docbook.xml` (stored in the 'datadir'
directory).
asciidoc-py3-9.0.0rc1/doc/asciidoc.1.txt 0000644 0001750 0001750 00000015665 13570064211 017216 0 ustar joseph joseph ASCIIDOC(1)
===========
:doctype: manpage
NAME
----
asciidoc - converts an AsciiDoc text file to HTML or DocBook
SYNOPSIS
--------
*asciidoc* ['OPTIONS'] 'FILE'
DESCRIPTION
-----------
The asciidoc(1) command translates the AsciiDoc text file 'FILE' to
DocBook or HTML. If 'FILE' is '-' then the standard input is used.
OPTIONS
-------
*-a, --attribute*='ATTRIBUTE'::
Define or delete document attribute. 'ATTRIBUTE' is formatted like
'NAME=VALUE'. Command-line attributes take precedence over
document and configuration file attributes. Alternate acceptable
forms are 'NAME' (the 'VALUE' defaults to an empty string);
'NAME!' (delete the 'NAME' attribute); 'NAME=VALUE@' (do not override
document or configuration file attributes). Values containing
spaces should be enclosed in double-quote characters. This option
may be specified more than once. A special attribute named
'trace' controls the output of diagnostic information.
*-b, --backend*='BACKEND'::
Backend output file format: 'docbook45', 'docbook5', 'xhtml11', 'html4',
'html5', 'slidy', 'wordpress' or 'latex' (the 'latex' backend is
experimental). You can also use the backend alias names 'html'
(aliased to 'xhtml11') or 'docbook' (aliased to 'docbook45').
Defaults to 'html'. The *--backend* option is also used to manage
backend plugins (see <>).
*-f, --conf-file*='CONF_FILE'::
Use configuration file 'CONF_FILE'.Configuration files processed
in command-line order (after implicit configuration files). This
option may be specified more than once.
*--doctest*::
Run Python doctests in 'asciidoc' module.
*-d, --doctype*='DOCTYPE'::
Document type: 'article', 'manpage' or 'book'. The 'book' document
type is only supported by the 'docbook' backends. Default document
type is 'article'.
*-c, --dump-conf*::
Dump configuration to stdout.
*--filter*='FILTER'::
Specify the name of a filter to be loaded (used to load filters
that are not auto-loaded). This option may be specified more than
once. The *--filter* option is also used to manage filter plugins
(see <>).
*-h, --help* ['TOPIC']::
Print help TOPIC. *--help* 'topics' will print a list of help
topics, *--help* 'syntax' summarizes AsciiDoc syntax,
*--help* 'manpage' prints the AsciiDoc manpage.
*-e, --no-conf*::
Exclude implicitly loaded configuration files except for those
named like the input file ('infile.conf' and
'infile-backend.conf').
*-s, --no-header-footer*::
Suppress document header and footer output.
*-o, --out-file*='OUT_FILE'::
Write output to file 'OUT_FILE'. Defaults to the base name of
input file with 'backend' extension. If the input is stdin then
the outfile defaults to stdout. If 'OUT_FILE' is '-' then the
standard output is used.
*-n, --section-numbers*::
Auto-number HTML article section titles. Synonym for
*--attribute numbered*.
*--safe*::
Enable safe mode. Safe mode is disabled by default. AsciiDoc
'safe mode' skips potentially dangerous scripted sections in
AsciiDoc source files.
*--theme*='THEME'::
Specify a theme name. Synonym for *--attribute theme*='THEME'.
The *--theme* option is also used to manage theme plugins (see
<>).
*-v, --verbose*::
Verbosely print processing information and configuration file
checks to stderr.
*--version*::
Print program version number.
[[X1]]
PLUGIN COMMANDS
---------------
The asciidoc(1) *--filter*, *--backend* and *--theme* options are used
to install, remove and list AsciiDoc filter, backend and theme
plugins. Syntax:
asciidoc OPTION install ZIP_FILE [PLUGINS_DIR]
asciidoc OPTION remove PLUGIN_NAME [PLUGINS_DIR]
asciidoc OPTION list
asciidoc OPTION build ZIP_FILE PLUGIN_SOURCE
Where:
*OPTION*::
asciidoc(1) *--filter*, *--backend* or *--theme* option specifying
the type of plugin.
*PLUGIN_NAME*::
A unique plugin name containing only alphanumeric or underscore
characters.
*ZIP_FILE*::
A Zip file containing plugin resources, the name must start with the
plugin name e.g. `my_filter-1.0.zip` packages filter `my_filter`.
*PLUGINS_DIR*::
The directory containing installed plugins. Each plugin is contained
in its own separate subdirectory which has the same name as the
plugin.
*PLUGINS_DIR* defaults to the `$HOME/.asciidoc/filters` (for
filter plugins) or `$HOME/.asciidoc/backends` (for backend plugins) or
`$HOME/.asciidoc/themes` (for theme plugins).
*PLUGIN_SOURCE*::
The name of a directory containing the plugin source files or the
name of a single source file.
The plugin commands perform as follows:
*install*::
Create a subdirectory in *PLUGINS_DIR* with the same name as the
plugin then extract the *ZIP_FILE* into it.
*remove*::
Delete the *PLUGIN_NAME* plugin subdirectory and all its contents
from the *PLUGINS_DIR*.
*list*::
List the names and locations of all installed filter or theme
plugins (including standard plugins installed in the global
configuration directory).
*build*::
Create a plugin file named *ZIP_FILE* containing the files and
subdirectories specified by *PLUGIN_SOURCE*. File and directory
names starting with a period are skipped.
ENVIRONMENT VARIABLES
---------------------
*`SOURCE_DATE_EPOCH`*::
If the `SOURCE_DATE_EPOCH` environment variable is set to a UNIX
timestamp, then the `{docdate}`, `{doctime}`, `{localdate}`, and
`{localtime}` attributes are computed in the UTC time zone, with any
timestamps newer than `SOURCE_DATE_EPOCH` replaced by
`SOURCE_DATE_EPOCH`. (This helps software using AsciiDoc to build
reproducibly.)
EXAMPLES
--------
`asciidoc asciidoc_file_name.txt`::
Simply generate an html file from the asciidoc_file_name.txt that is in
current directory using asciidoc.
`asciidoc -b html5 asciidoc_file_name.txt`::
Use the `-b` switch to use one of the proposed backend or another one you
installed on your computer.
`asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt`::
Use the `-a` switch to set attributes from command-line. AsciiDoc generated
its stand-alone HTML user guide containing embedded CSS, JavaScript and
images from the AsciiDoc article template with this command.
`asciidoc -b html5 -d manpage asciidoc.1.txt`::
Generating the asciidoc manpage using the html5 backend.
EXIT STATUS
-----------
*0*::
Success
*1*::
Failure (syntax or usage error; configuration error; document
processing failure; unexpected error).
BUGS
----
See the AsciiDoc distribution BUGS file.
AUTHOR
------
AsciiDoc was originally written by Stuart Rackham. Many people have
contributed to it.
RESOURCES
---------
SourceForge:
Main web site:
SEE ALSO
--------
a2x(1)
COPYING
-------
Copyright \(C) 2002-2011 Stuart Rackham. Free use of this software is
granted under the terms of the GNU General Public License (GPL).
asciidoc-py3-9.0.0rc1/doc/latex-bugs.txt 0000644 0001750 0001750 00000010240 13570064211 017334 0 ustar joseph joseph Bugs in asciidoc latex backend
==============================
Geoff Eddy
Benjamin Klum was unable to maintain the LaTeX backend beyond version
8.2.7, and as a consequence the `latex.conf` file ceased to work with
`asciidoc` sometime after this. For version 8.4.3 I made some changes
to the file to get it working again. This document summarises the
remaining issues which I have found with generating LaTeX and thence
PDF output with `asciidoc`, which is done as follows:
- `asciidoc --backend=latex --unsafe FILE.txt`
- `latex FILE.tex`
- `kpdf FILE.pdf`
Many of these were found by processing the `asciidoc.txt` file and
comparing the HTML output with the PDF.
== Footnotes
Priority:: Low.
Problem:: References to footnotes, and a sensible value for the
`[footnoteref-inlinemacro]` section, don't seem to be possible.
Cause:: LaTeX doesn't support footnoting much beyond creating a
footnote at a certain point in text and displaying the footnote
itself.
Solution:: Unclear. How important or necessary is this, anyway?
== Spurious text at starts of paragraphs
Priority:: Medium
Problem:: It is necessary to insert spurious text in paragraphs.
Cause:: This `asciidoc` input:
+
-------------------------------------------------------------------
Text
-------------------------------------------------------------------
+
generates this LaTeX code:
+
\begin{lstlisting}
SPURIOUS TEXTText\end{lstlisting}
+
which should be:
+
\begin{lstlisting}[]
Text\end{lstlisting}
Solution:: Find out a way to generate the correct LaTeX output as
above. The obvious solution, as explained in `latet.conf`, doesn't
work.
== Tables
Priority:: Rather high.
Problem:: Not all of the table configuration options can be passed
through to the LaTeX backend. In particular, I've had to assume that
all tables will be fifteen or fewer left-justified columns wide.
Cause:: The table models in LaTeX and HTML are too dissimilar for one
`asciidoc` specification to generate valid output in both formats by
simple regexp replacement. Related to this is the unfortunate fact
that `` and related tags aren't a required part of HTML4,
and some broswers (at least Firefox and Konqueror) don't implement
them.
Solution:: Perhaps table processing could be handled by a Python
plugin, which would read in a table spec and generate the appropriate
text?
== Unicode escaping
Priority:: Rather high, to me at least.
Problem:: The commented-out section in `latex.conf`, if uncommented,
converts `π` to `\unichar{960}`, which then causes LaTeX to
complain that the resulting command is unavailable in encoding T1. The
more common non-ASCII characters, such as those in `félicité` and
`świeca`, are handled properly, but some - such as the IPA characters
in the `tipa` package - are not.
Cause:: The encodings in the LaTeX output are wrong.
Solution:: Correct the encodings.
== Text colours
Priority:: Probably low
Problem:: The text colour options are not processed by LaTeX; for
example `[#ff0000]#Red text#` is not rendered in red.
Cause:: LaTeX and HTML represent RGB triads differently: HTML is happy
with `#ff8000`, but LaTeX needs `[rgb]{1,0.5,0}`.
Solution:: Provide some sort of internal RGB conversion mechanism
which can convert RGB triads to different representations.
== Text sizes
Priority:: Probably low
Problem:: The text size options are not processed by LaTeX:
`[,,1]#text#` is rendered in the same size as normal text.
Cause:: HTML size tags - `h1` through `h7` - are directly derivable
from the size number, whereas LaTeX has a series of descriptive words
(`HUGE` through `normalsize` to `scriptsize`).
Solution:: Provide a way to treat the number as an index into an
array.
== Background colour in paragraphs
Priority:: Medium
Problem:: If the `backgroundcolor` attribute is specified in the
`lstset` command, all paragraphs are displayed as black rectangles by
`kpdf`, `xpdf`, and `evince`, although `kdvi` has no problems. I've
had to remove the attribute, and so paragraphs all appear on white
backgrounds. The PDF viewers also complain:
Error (NNNN): Unknown operator 'rgb'
Cause:: Apparently a known bug in the output of `pdflatex`. Not a bug
in `asciidoc`.
Solution:: Wait until this bug is fixed?
asciidoc-py3-9.0.0rc1/doc/latex-backend.txt 0000644 0001750 0001750 00000026424 13570064211 017776 0 ustar joseph joseph LaTeX backend for Asciidoc
==========================
Benjamin Klum
v1.0, June 2006
== Introduction
LaTeX backend is a configuration file for Stuart Rackham's http://asciidoc.org/[Asciidoc]. It generates high-level LaTeX markup from Asciidoc documents. LaTeX is a document preparation system for TeX which in turn is a popular typesetting system. It is well known for producing excellently typesetted high quality printouts, especially suited for scientific text.
== Tutorial
Getting a ready-to-print document from an Asciidoc document using the LaTeX backend involves at least two steps:
1. Conversion of the Asciidoc document into a LaTeX document (this is done by Asciidoc using the LaTeX backend)
2. Conversion of the LaTeX document into a PDF document (this is done by the TeX system)
Try to create a PDF document from the Asciidoc document `article.txt` which resides in the `doc` directory of Asciidoc:
.. Make a copy of `article.txt` in a directory of your choice, let's call it `latex-test`.
.. Make sure that all images referenced in `article.txt` exist in `latex-test`. Brute force approach: Copy the whole `images` directory from Asciidoc directory into `latex-test`.
.. Change directory to `latex-test` and type following commands:
+
asciidoc --unsafe --backend=latex article.txt
pdflatex article.tex
+
.. Now there should be a file `article.pdf` in the `latex-test` directory.
[IMPORTANT]
==============================
- Asciidoc has to be started in 'unsafe mode' when using LaTeX backend.
- Note that some special LaTeX packages are necessary, see <>.
==============================
== General notes
=== Quality of LaTeX output
High-level LaTeX is not very straightforward to generate. Therefore there's no guarantee that the generated output is valid and compiles successfully. At all, this backend should be considered as rather experimental. You should have been already in touch with LaTeX in order to use the backend effectively because LaTeX compilation errors can be really nasty.
Nevertheless good results can be achieved by using LaTeX backend. Try for example to compile Stuart Rackham's Asciidoc documentation, a rather large document. It should compile without problems. However, the code filter might have to be reconfigured for the code filter example to work.
=== Configuration file customization
Like every other Asciidoc backend the LaTeX backend can be customized easily to fit the user's needs. Actually it is very important to have this option since LaTeX doesn't have a companion language like CSS which allows to put styling information in a separate file. Read more about the LaTeX backend configuration file <>.
=== Output optimization
The LaTeX output is optimized for creating PDF documents using 'pdflatex'.
[[unicodeSupport]]
=== Unicode support
Unfortunately TeX/LaTeX does not have native unicode support. The package 'ucs' adds elementary unicode support by introducing UTF-8 input encoding recognition and by defining lookup tables which contain the corresponding LaTeX commands for unicode characters. But these lookup tables are far from being complete. When a unicode character is found which is not defined in the lookup tables an error is raised by the TeX/LaTeX compiler. Note that TeX/LaTeX compilation errors caused by missing unicode character definitions are not fatal, that means the result is probably readable but undefined unicode characters are replaced with `[U+...]`. You may (de)activate the recognition of escaped unicode characters. See the <> backend option.
== Backend specific features
=== Special sections
LaTeX backend supports the following special sections and replaces them with corresponding LaTeX commands or environments:
- Abstract (only for document type 'article')
- Dedication (only for document type 'book')
- Index
- Bibliography (only when the attribute 'latex-use-bibliography-environment' is set)
- Appendix
- Contents
[[internalCrossReferences]]
=== Internal cross references
Macros for internal cross references have been extended by the attribute 'style'.
xref:[, style=
endif::linkcss[]
ifndef::disable-javascript[]
ifdef::linkcss[]
endif::linkcss[]
ifndef::linkcss[]
endif::linkcss[]
endif::disable-javascript[]
ifdef::asciimath[]
ifdef::linkcss[]
endif::linkcss[]
ifndef::linkcss[]
endif::linkcss[]
endif::asciimath[]
ifdef::latexmath[]
ifdef::linkcss[]
endif::linkcss[]
ifndef::linkcss[]
endif::linkcss[]
endif::latexmath[]
ifdef::mathjax[]
endif::mathjax[]
{docinfo1,docinfo2#}{include:{docdir}/docinfo.html}
{docinfo,docinfo2#}{include:{docdir}/{docname}-docinfo.html}
template::[docinfo]
# Article, book header.
ifndef::doctype-manpage[]
endif::doctype-manpage[]
# Man page header.
ifdef::doctype-manpage[]
endif::doctype-manpage[]
[footer]
{disable-javascript%}
