From bba578e8ac7462d87c350ef458da4aac4f21db28 Mon Sep 17 00:00:00 2001 From: Matthew Peveler Date: Sat, 25 Dec 2021 00:56:51 -0500 Subject: Isolate test inputs to own folder (#231) --- tests/data/ascii-ids1.txt | 9 - tests/data/barchart.py | 4 - tests/data/deprecated-quotes.txt | 12 - tests/data/dummy_file.py | 470 --- tests/data/filters-test.txt | 90 - tests/data/include-lines-test.txt | 23 - tests/data/lang-cs-man-test.txt | 21 - tests/data/lang-cs-test.txt | 106 - tests/data/lang-de-man-test.txt | 21 - tests/data/lang-de-test.txt | 106 - tests/data/lang-en-man-test.txt | 21 - tests/data/lang-en-test.txt | 114 - tests/data/lang-es-man-test.txt | 21 - tests/data/lang-es-test.txt | 106 - tests/data/lang-fr-man-test.txt | 21 - tests/data/lang-fr-test.txt | 106 - tests/data/lang-hu-man-test.txt | 21 - tests/data/lang-hu-test.txt | 106 - tests/data/lang-it-man-test.txt | 21 - tests/data/lang-it-test.txt | 106 - tests/data/lang-ja-man-test.txt | 18 - tests/data/lang-ja-test.txt | 94 - tests/data/lang-nl-man-test.txt | 21 - tests/data/lang-nl-test.txt | 94 - tests/data/lang-pt-BR-man-test.txt | 21 - tests/data/lang-pt-BR-test.txt | 106 - tests/data/lang-ro-man-test.txt | 21 - tests/data/lang-ro-test.txt | 106 - tests/data/lang-ru-man-test.txt | 21 - tests/data/lang-ru-test.txt | 106 - tests/data/lang-sv-man-test.txt | 21 - tests/data/lang-sv-test.txt | 114 - tests/data/lang-uk-man-test.txt | 21 - tests/data/lang-uk-test.txt | 106 - tests/data/newline.txt | 17 - tests/data/oldtables.txt | 64 - tests/data/open-block-test.txt | 117 - tests/data/rcs-id-marker-test.txt | 6 - tests/data/slidy-example.txt | 174 - tests/data/testcases.conf | 12 - tests/data/testcases.txt | 817 ---- tests/data/utf8-bom-test.txt | 9 - tests/data/utf8-examples.txt | 217 -- tests/inputs/article-docinfo.xml | 87 + tests/inputs/article.txt | 139 + tests/inputs/ascii-ids1.txt | 9 + tests/inputs/asciidoc.1.txt | 237 ++ tests/inputs/asciidoc.conf | 7 + tests/inputs/asciidoc.txt | 6096 ++++++++++++++++++++++++++++++ tests/inputs/asciimath.txt | 59 + tests/inputs/barchart.py | 4 + tests/inputs/book-multi.txt | 181 + tests/inputs/book.txt | 156 + tests/inputs/customers.csv | 18 + tests/inputs/deprecated-quotes.txt | 12 + tests/inputs/dummy_file.py | 470 +++ tests/inputs/filters-test.txt | 90 + tests/inputs/include-lines-test.txt | 23 + tests/inputs/lang-cs-man-test.txt | 21 + tests/inputs/lang-cs-test.txt | 106 + tests/inputs/lang-de-man-test.txt | 21 + tests/inputs/lang-de-test.txt | 106 + tests/inputs/lang-en-man-test.txt | 21 + tests/inputs/lang-en-test.txt | 114 + tests/inputs/lang-es-man-test.txt | 21 + tests/inputs/lang-es-test.txt | 106 + tests/inputs/lang-fr-man-test.txt | 21 + tests/inputs/lang-fr-test.txt | 106 + tests/inputs/lang-hu-man-test.txt | 21 + tests/inputs/lang-hu-test.txt | 106 + tests/inputs/lang-it-man-test.txt | 21 + tests/inputs/lang-it-test.txt | 106 + tests/inputs/lang-ja-man-test.txt | 18 + tests/inputs/lang-ja-test.txt | 94 + tests/inputs/lang-nl-man-test.txt | 21 + tests/inputs/lang-nl-test.txt | 94 + tests/inputs/lang-pt-BR-man-test.txt | 21 + tests/inputs/lang-pt-BR-test.txt | 106 + tests/inputs/lang-ro-man-test.txt | 21 + tests/inputs/lang-ro-test.txt | 106 + tests/inputs/lang-ru-man-test.txt | 21 + tests/inputs/lang-ru-test.txt | 106 + tests/inputs/lang-sv-man-test.txt | 21 + tests/inputs/lang-sv-test.txt | 114 + tests/inputs/lang-uk-man-test.txt | 21 + tests/inputs/lang-uk-test.txt | 106 + tests/inputs/latex-filter.txt | 246 ++ tests/inputs/latexmath.txt | 121 + tests/inputs/latexmathml.txt | 41 + tests/inputs/newline.txt | 17 + tests/inputs/newtables.txt | 743 ++++ tests/inputs/oldtables.txt | 64 + tests/inputs/open-block-test.txt | 117 + tests/inputs/rcs-id-marker-test.txt | 6 + tests/inputs/slidy-example.txt | 174 + tests/inputs/source-highlight-filter.txt | 275 ++ tests/inputs/testcases.conf | 12 + tests/inputs/testcases.txt | 817 ++++ tests/inputs/utf8-bom-test.txt | 9 + tests/inputs/utf8-examples.txt | 217 ++ tests/testasciidoc.conf | 150 +- 101 files changed, 12289 insertions(+), 3883 deletions(-) delete mode 100644 tests/data/ascii-ids1.txt delete mode 100644 tests/data/barchart.py delete mode 100644 tests/data/deprecated-quotes.txt delete mode 100644 tests/data/dummy_file.py delete mode 100644 tests/data/filters-test.txt delete mode 100644 tests/data/include-lines-test.txt delete mode 100644 tests/data/lang-cs-man-test.txt delete mode 100644 tests/data/lang-cs-test.txt delete mode 100644 tests/data/lang-de-man-test.txt delete mode 100644 tests/data/lang-de-test.txt delete mode 100644 tests/data/lang-en-man-test.txt delete mode 100644 tests/data/lang-en-test.txt delete mode 100644 tests/data/lang-es-man-test.txt delete mode 100644 tests/data/lang-es-test.txt delete mode 100644 tests/data/lang-fr-man-test.txt delete mode 100644 tests/data/lang-fr-test.txt delete mode 100644 tests/data/lang-hu-man-test.txt delete mode 100644 tests/data/lang-hu-test.txt delete mode 100644 tests/data/lang-it-man-test.txt delete mode 100644 tests/data/lang-it-test.txt delete mode 100644 tests/data/lang-ja-man-test.txt delete mode 100644 tests/data/lang-ja-test.txt delete mode 100644 tests/data/lang-nl-man-test.txt delete mode 100644 tests/data/lang-nl-test.txt delete mode 100644 tests/data/lang-pt-BR-man-test.txt delete mode 100644 tests/data/lang-pt-BR-test.txt delete mode 100644 tests/data/lang-ro-man-test.txt delete mode 100644 tests/data/lang-ro-test.txt delete mode 100644 tests/data/lang-ru-man-test.txt delete mode 100644 tests/data/lang-ru-test.txt delete mode 100644 tests/data/lang-sv-man-test.txt delete mode 100644 tests/data/lang-sv-test.txt delete mode 100644 tests/data/lang-uk-man-test.txt delete mode 100644 tests/data/lang-uk-test.txt delete mode 100644 tests/data/newline.txt delete mode 100644 tests/data/oldtables.txt delete mode 100644 tests/data/open-block-test.txt delete mode 100644 tests/data/rcs-id-marker-test.txt delete mode 100644 tests/data/slidy-example.txt delete mode 100644 tests/data/testcases.conf delete mode 100644 tests/data/testcases.txt delete mode 100644 tests/data/utf8-bom-test.txt delete mode 100644 tests/data/utf8-examples.txt create mode 100644 tests/inputs/article-docinfo.xml create mode 100644 tests/inputs/article.txt create mode 100644 tests/inputs/ascii-ids1.txt create mode 100644 tests/inputs/asciidoc.1.txt create mode 100644 tests/inputs/asciidoc.conf create mode 100644 tests/inputs/asciidoc.txt create mode 100644 tests/inputs/asciimath.txt create mode 100644 tests/inputs/barchart.py create mode 100644 tests/inputs/book-multi.txt create mode 100644 tests/inputs/book.txt create mode 100644 tests/inputs/customers.csv create mode 100644 tests/inputs/deprecated-quotes.txt create mode 100644 tests/inputs/dummy_file.py create mode 100644 tests/inputs/filters-test.txt create mode 100644 tests/inputs/include-lines-test.txt create mode 100644 tests/inputs/lang-cs-man-test.txt create mode 100644 tests/inputs/lang-cs-test.txt create mode 100644 tests/inputs/lang-de-man-test.txt create mode 100644 tests/inputs/lang-de-test.txt create mode 100644 tests/inputs/lang-en-man-test.txt create mode 100644 tests/inputs/lang-en-test.txt create mode 100644 tests/inputs/lang-es-man-test.txt create mode 100644 tests/inputs/lang-es-test.txt create mode 100644 tests/inputs/lang-fr-man-test.txt create mode 100644 tests/inputs/lang-fr-test.txt create mode 100644 tests/inputs/lang-hu-man-test.txt create mode 100644 tests/inputs/lang-hu-test.txt create mode 100644 tests/inputs/lang-it-man-test.txt create mode 100644 tests/inputs/lang-it-test.txt create mode 100644 tests/inputs/lang-ja-man-test.txt create mode 100644 tests/inputs/lang-ja-test.txt create mode 100644 tests/inputs/lang-nl-man-test.txt create mode 100644 tests/inputs/lang-nl-test.txt create mode 100644 tests/inputs/lang-pt-BR-man-test.txt create mode 100644 tests/inputs/lang-pt-BR-test.txt create mode 100644 tests/inputs/lang-ro-man-test.txt create mode 100644 tests/inputs/lang-ro-test.txt create mode 100644 tests/inputs/lang-ru-man-test.txt create mode 100644 tests/inputs/lang-ru-test.txt create mode 100644 tests/inputs/lang-sv-man-test.txt create mode 100644 tests/inputs/lang-sv-test.txt create mode 100644 tests/inputs/lang-uk-man-test.txt create mode 100644 tests/inputs/lang-uk-test.txt create mode 100644 tests/inputs/latex-filter.txt create mode 100644 tests/inputs/latexmath.txt create mode 100644 tests/inputs/latexmathml.txt create mode 100644 tests/inputs/newline.txt create mode 100644 tests/inputs/newtables.txt create mode 100644 tests/inputs/oldtables.txt create mode 100644 tests/inputs/open-block-test.txt create mode 100644 tests/inputs/rcs-id-marker-test.txt create mode 100644 tests/inputs/slidy-example.txt create mode 100644 tests/inputs/source-highlight-filter.txt create mode 100644 tests/inputs/testcases.conf create mode 100644 tests/inputs/testcases.txt create mode 100644 tests/inputs/utf8-bom-test.txt create mode 100644 tests/inputs/utf8-examples.txt diff --git a/tests/data/ascii-ids1.txt b/tests/data/ascii-ids1.txt deleted file mode 100644 index 67958c4..0000000 --- a/tests/data/ascii-ids1.txt +++ /dev/null @@ -1,9 +0,0 @@ -// Test of generated chapter ID normalized to ASCII -:ascii-ids: 1 - -== Wstęp żółtej łąki - -== schön Grüßen - -== Белые Мотыль - diff --git a/tests/data/barchart.py b/tests/data/barchart.py deleted file mode 100644 index c79a514..0000000 --- a/tests/data/barchart.py +++ /dev/null @@ -1,4 +0,0 @@ -print( - "No barchart to avoid depending on Pychart for the tests.\n" - "See also: https://asciidoc.org/faq.html#_is_it_possible_to_include_charts_in_asciidoc_documents" # noqa: E501 -) diff --git a/tests/data/deprecated-quotes.txt b/tests/data/deprecated-quotes.txt deleted file mode 100644 index 2f44edf..0000000 --- a/tests/data/deprecated-quotes.txt +++ /dev/null @@ -1,12 +0,0 @@ -// Deprecated quote attributes. -[role="foo"]##fun with text##. -["green","yellow",2,role="foo"]##fun with text##. -[green,yellow,2]##fun with text##. -More [red,black,4]*fun with text*. -Yet more [red,,1.5]**fun with text**. -Yet more [red,,1.5]+fun with text+. -Yet more [red,,1.5]'fun with text'. - -Yet more [red,,1.5]_fun with text_. - -Yet more [orange]'fun with text'. diff --git a/tests/data/dummy_file.py b/tests/data/dummy_file.py deleted file mode 100644 index aec34aa..0000000 --- a/tests/data/dummy_file.py +++ /dev/null @@ -1,470 +0,0 @@ -#!/usr/bin/env python3 - -__version__ = '0.4.0' - - -import difflib -import io -import os -from pathlib import Path -import re -import shutil -import sys - -sys.path.append(str(Path(__file__).resolve().parent.parent)) -from asciidoc import asciidoc # noqa: E402 - -# Default backends. -BACKENDS = ('html4', 'xhtml11', 'docbook', 'docbook5', 'html5') -BACKEND_EXT = { - 'html4': '.html', - 'xhtml11': '.html', - 'docbook': '.xml', - 'docbook5': '.xml', - 'slidy': '.html', - 'html5': '.html' -} - - -def iif(condition, iftrue, iffalse=None): - """ - Immediate if c.f. ternary ?: operator. - False value defaults to '' if the true value is a string. - False value defaults to 0 if the true value is a number. - """ - if iffalse is None: - if isinstance(iftrue, str): - iffalse = '' - if type(iftrue) in (int, float): - iffalse = 0 - if condition: - return iftrue - else: - return iffalse - - -def message(msg=''): - print(msg, file=sys.stderr) - - -def strip_end(lines): - """ - Strip blank strings from the end of list of strings. - """ - for i in range(len(lines) - 1, -1, -1): - if not lines[i]: - del lines[i] - else: - break - - -def normalize_data(lines): - """ - Strip comments and trailing blank strings from lines. - """ - result = [s for s in lines if not s.startswith('#')] - strip_end(result) - return result - - -class AsciiDocTest(object): - def __init__(self): - self.number = None # Test number (1..). - self.name = '' # Optional test name. - self.title = '' # Optional test name. - self.description = [] # List of lines followoing title. - self.source = None # AsciiDoc test source file name. - self.options = [] - self.attributes = {'asciidoc-version': 'test'} - self.backends = BACKENDS - self.artifacts = [] # list of generated artifacts to delete - self.requires = [] # list of dependencies to check for for the test - self.confdir = None - self.datadir = None # Where output files are stored. - self.disabled = False - self.passed = self.skipped = self.failed = 0 - - def backend_filename(self, backend): - """ - Return the path name of the backend output file that is generated from - the test name and output file type. - """ - return '%s-%s%s' % ( - os.path.normpath(os.path.join(self.datadir, self.name)), - backend, - BACKEND_EXT[backend] - ) - - def parse(self, lines, confdir, datadir): - """ - Parse conf file test section from list of text lines. - """ - self.__init__() - self.confdir = confdir - self.datadir = datadir - lines = Lines(lines) - while not lines.eol(): - text = lines.read_until(r'^%') - if text: - if not text[0].startswith('%'): - if text[0][0] == '!': - self.disabled = True - self.title = text[0][1:] - else: - self.title = text[0] - self.description = text[1:] - continue - reo = re.match(r'^%\s*(?P[\w_-]+)', text[0]) - if not reo: - raise ValueError - directive = reo.groupdict()['directive'] - data = normalize_data(text[1:]) - if directive == 'source': - if data: - self.source = os.path.normpath(os.path.join( - self.confdir, os.path.normpath(data[0]) - )) - elif directive == 'options': - self.options = eval(' '.join(data)) - for i, v in enumerate(self.options): - if isinstance(v, str): - self.options[i] = (v, None) - elif directive == 'attributes': - self.attributes.update(eval(' '.join(data))) - elif directive == 'backends': - self.backends = eval(' '.join(data)) - elif directive == 'name': - self.name = data[0].strip() - elif directive == 'requires': - self.requires = eval(' '.join(data)) - elif directive == 'artifacts': - self.artifacts = eval(' '.join(data)) - else: - raise ValueError - if not self.title: - self.title = self.source - if not self.name: - self.name = os.path.basename(os.path.splitext(self.source)[0]) - - def is_missing(self, backend): - """ - Returns True if there is no output test data file for backend. - """ - return not os.path.isfile(self.backend_filename(backend)) - - def is_missing_or_outdated(self, backend): - """ - Returns True if the output test data file is missing or out of date. - """ - return self.is_missing(backend) or ( - os.path.getmtime(self.source) - > os.path.getmtime(self.backend_filename(backend)) - ) - - def clean_artifacts(self): - for artifact in self.artifacts: - loc = os.path.join(self.confdir, artifact) - if os.path.exists(loc): - os.unlink(loc) - - def get_expected(self, backend): - """ - Return expected test data output for backend. - """ - with open( - self.backend_filename(backend), - encoding='utf-8', - newline='' - ) as open_file: - return open_file.readlines() - - def generate_expected(self, backend): - """ - Generate and return test data output for backend. - """ - asciidoc.reset_asciidoc() - outfile = io.StringIO() - options = self.options[:] - options.append(('--out-file', outfile)) - options.append(('--backend', backend)) - for k, v in self.attributes.items(): - if v == '' or k[-1] in '!@': - s = str(k) - elif v is None: - s = k + '!' - else: - s = '%s=%s' % (k, v) - options.append(('--attribute', s)) - asciidoc.execute('asciidoc', options, [self.source]) - return outfile.getvalue().splitlines(keepends=True) - - def update_expected(self, backend): - """ - Generate and write backend data. - """ - lines = self.generate_expected(backend) - if not os.path.isdir(self.datadir): - print('CREATING: %s' % self.datadir) - os.mkdir(self.datadir) - with open( - self.backend_filename(backend), - 'w+', - encoding='utf-8', - newline='' - ) as open_file: - print('WRITING: %s' % open_file.name) - open_file.writelines(lines) - - def update(self, backend=None, force=False): - """ - Regenerate and update expected test data outputs. - """ - if backend is None: - backends = self.backends - else: - backends = [backend] - - print('SOURCE: asciidoc: %s' % self.source) - for backend in backends: - if force or self.is_missing_or_outdated(backend): - self.update_expected(backend) - print() - - self.clean_artifacts() - - def run(self, backend=None): - """ - Execute test. - Return True if test passes. - """ - if backend is None: - backends = self.backends - else: - backends = [backend] - result = True # Assume success. - self.passed = self.failed = self.skipped = 0 - print('%d: %s' % (self.number, self.title)) - if self.source and os.path.isfile(self.source): - print('SOURCE: asciidoc: %s' % self.source) - for backend in backends: - fromfile = self.backend_filename(backend) - skip = False - for require in self.requires: - if shutil.which(require) is None: - skip = True - break - if not skip and not self.is_missing(backend): - expected = self.get_expected(backend) - strip_end(expected) - got = self.generate_expected(backend) - strip_end(got) - lines = [] - for line in difflib.unified_diff(got, expected, n=0): - lines.append(line) - if lines: - result = False - self.failed += 1 - lines = lines[3:] - print('FAILED: %s: %s' % (backend, fromfile)) - message('+++ %s' % fromfile) - message('--- got') - for line in lines: - message(line) - message() - else: - self.passed += 1 - print('PASSED: %s: %s' % (backend, fromfile)) - else: - self.skipped += 1 - print('SKIPPED: %s: %s' % (backend, fromfile)) - self.clean_artifacts() - else: - self.skipped += len(backends) - if self.source: - msg = 'MISSING: %s' % self.source - else: - msg = 'NO ASCIIDOC SOURCE FILE SPECIFIED' - print(msg) - print('') - return result - - -class AsciiDocTests(object): - def __init__(self, conffile): - """ - Parse configuration file - :param conffile: - """ - self.conffile = conffile - self.passed = self.failed = self.skipped = 0 - # All file names are relative to configuration file directory. - self.confdir = os.path.dirname(self.conffile) - self.datadir = self.confdir # Default expected files directory. - self.tests = [] # List of parsed AsciiDocTest objects. - self.globals = {} - with open(self.conffile, encoding='utf-8') as open_file: - lines = Lines(open_file.readlines()) - first = True - while not lines.eol(): - s = lines.read_until(r'^%+$') - s = [line for line in s if len(line) > 0] # Drop blank lines. - # Must be at least one non-blank line in addition to delimiter. - if len(s) > 1: - # Optional globals precede all tests. - if first and re.match(r'^%\s*globals$', s[0]): - self.globals = eval(' '.join(normalize_data(s[1:]))) - if 'datadir' in self.globals: - self.datadir = os.path.join( - self.confdir, - os.path.normpath(self.globals['datadir']) - ) - else: - test = AsciiDocTest() - test.parse(s[1:], self.confdir, self.datadir) - self.tests.append(test) - test.number = len(self.tests) - first = False - - def run(self, number=None, backend=None): - """ - Run all tests. - If number is specified run test number (1..). - """ - self.passed = self.failed = self.skipped = 0 - for test in self.tests: - if ( - (not test.disabled or number) - and (not number or number == test.number) - and (not backend or backend in test.backends) - ): - test.run(backend) - self.passed += test.passed - self.failed += test.failed - self.skipped += test.skipped - if self.passed > 0: - print('TOTAL PASSED: %s' % self.passed) - if self.failed > 0: - print('TOTAL FAILED: %s' % self.failed) - if self.skipped > 0: - print('TOTAL SKIPPED: %s' % self.skipped) - - def update(self, number=None, backend=None, force=False): - """ - Regenerate expected test data and update configuratio file. - """ - for test in self.tests: - if (not test.disabled or number) and (not number or number == test.number): - test.update(backend, force=force) - - def list(self): - """ - Lists tests to stdout. - """ - for test in self.tests: - print('%d: %s%s' % (test.number, iif(test.disabled, '!'), test.title)) - - -class Lines(list): - """ - A list of strings. - Adds eol() and read_until() to list type. - """ - - def __init__(self, lines): - super(Lines, self).__init__() - self.extend([s.rstrip() for s in lines]) - self.pos = 0 - - def eol(self): - return self.pos >= len(self) - - def read_until(self, regexp): - """ - Return a list of lines from current position up until the next line - matching regexp. - Advance position to matching line. - """ - result = [] - if not self.eol(): - result.append(self[self.pos]) - self.pos += 1 - while not self.eol(): - if re.match(regexp, self[self.pos]): - break - result.append(self[self.pos]) - self.pos += 1 - return result - - -if __name__ == '__main__': - # guarantee a stable timestamp matching the test fixtures - os.environ['SOURCE_DATE_EPOCH'] = '1038184662' - # Process command line options. - from argparse import ArgumentParser - parser = ArgumentParser( - description='Run AsciiDoc conformance tests specified in configuration' - 'FILE.' - ) - msg = 'Use configuration file CONF_FILE (default configuration file is '\ - 'testasciidoc.conf in testasciidoc.py directory)' - parser.add_argument( - '-v', - '--version', - action='version', - version='%(prog)s {}'.format(__version__) - ) - parser.add_argument('-f', '--conf-file', help=msg) - - subparsers = parser.add_subparsers(metavar='command', dest='command') - subparsers.required = True - - subparsers.add_parser('list', help='List tests') - - options = ArgumentParser(add_help=False) - options.add_argument('-n', '--number', type=int, help='Test number to run') - options.add_argument('-b', '--backend', type=str, help='Backend to run') - - subparsers.add_parser('run', help='Execute tests', parents=[options]) - - subparser = subparsers.add_parser( - 'update', - help='Regenerate and update test data', - parents=[options] - ) - subparser.add_argument( - '--force', - action='store_true', - help='Update all test data overwriting existing data' - ) - - args = parser.parse_args() - - conffile = os.path.join(os.path.dirname(sys.argv[0]), 'testasciidoc.conf') - force = 'force' in args and args.force is True - if args.conf_file is not None: - conffile = args.conf_file - if not os.path.isfile(conffile): - message('missing CONF_FILE: %s' % conffile) - sys.exit(1) - tests = AsciiDocTests(conffile) - cmd = args.command - number = None - backend = None - if 'number' in args: - number = args.number - if 'backend' in args: - backend = args.backend - if backend and backend not in BACKENDS: - message('illegal BACKEND: {:s}'.format(backend)) - sys.exit(1) - if number is not None and (number < 1 or number > len(tests.tests)): - message('illegal test NUMBER: {:d}'.format(number)) - sys.exit(1) - if cmd == 'run': - tests.run(number, backend) - if tests.failed: - sys.exit(1) - elif cmd == 'update': - tests.update(number, backend, force=force) - elif cmd == 'list': - tests.list() diff --git a/tests/data/filters-test.txt b/tests/data/filters-test.txt deleted file mode 100644 index a8b051e..0000000 --- a/tests/data/filters-test.txt +++ /dev/null @@ -1,90 +0,0 @@ -Filter Tests -============ - - -== Toy filter example from User Guide - -[code,python] ----------------------------------------------- -''' A multi-line - comment.''' -def sub_word(mo): - ''' Single line comment.''' - word = mo.group('word') # Inline comment - if word in keywords[language]: - return quote + word + quote - else: - return word ----------------------------------------------- - - -== Pychart Chart generations from FAQ - -// Generate chart image file. -sys2::[python "{indir}/barchart.py" --format=png --output="{outdir={indir}}/{imagesdir=}{imagesdir?/}barchart.png" --scale=2] - -// Display chart image file. -image::barchart.png[] - - -== Graphviz Graphs - -.Simple graph -["graphviz", "graphviz1.png", alt="Graphviz->AsciiDoc->HTML"] ---------------------------------------------------------------------- -digraph G { rankdir=LR; Graphviz->AsciiDoc->HTML} ---------------------------------------------------------------------- - -.Not so simple graph -["graphviz", "graphviz2.png"] ---------------------------------------------------------------------- -digraph automata_0 { - size ="8.5, 11"; - node [shape = circle]; - 0 [ style = filled, color=lightgrey ]; - 2 [ shape = doublecircle ]; - 0 -> 2 [ label = "a " ]; - 0 -> 1 [ label = "other " ]; - 1 -> 2 [ label = "a " ]; - 1 -> 1 [ label = "other " ]; - 2 -> 2 [ label = "a " ]; - 2 -> 1 [ label = "other " ]; - "Machine: a" [ shape = plaintext ]; -} ---------------------------------------------------------------------- - - -== Music filter - -.A tune generated from ABC notation -[music,music1.png] ---------------------------------------------------------------------- -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. -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):| ---------------------------------------------------------------------- - -<>. - -[[X1]] -.A fragment generated from LilyPond source -["music", "music2.png", "ly", link="music2.ly"] ---------------------------------------------------------------------- -\version "2.10.0" -\paper { - ragged-right = ##t -} -{ - \time 3/4 - \clef bass - c2 e4 g2. f4 e d c2 r4 -} ---------------------------------------------------------------------- diff --git a/tests/data/include-lines-test.txt b/tests/data/include-lines-test.txt deleted file mode 100644 index 6f0fd2c..0000000 --- a/tests/data/include-lines-test.txt +++ /dev/null @@ -1,23 +0,0 @@ -include line test -================= - -The imports: - -[source,python] ----- -include::./dummy_file.py[lines="6..15"] ----- - -Some random ranges: - -[source,python] ----- -include::./dummy_file.py[lines="29..44,61..68,70,398..-1"] ----- - -Using ; as separator: - -[source,python] ----- -include::./dummy_file.py[lines="29..44;61..68"] ----- diff --git a/tests/data/lang-cs-man-test.txt b/tests/data/lang-cs-man-test.txt deleted file mode 100644 index 9c3726a..0000000 --- a/tests/data/lang-cs-man-test.txt +++ /dev/null @@ -1,21 +0,0 @@ -// Test for lang-it.conf language file. -:lang: cs - -ASCIIDOC(1) -=========== -:doctype: manpage - -NAME ----- -asciidoc - converts an AsciiDoc text file to HTML or DocBook - -SINOSSI -------- -*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. - -... diff --git a/tests/data/lang-cs-test.txt b/tests/data/lang-cs-test.txt deleted file mode 100644 index f960fb7..0000000 --- a/tests/data/lang-cs-test.txt +++ /dev/null @@ -1,106 +0,0 @@ -// Test for lang-cs.conf language file. -:lang: cs - -Languages Test -============== -:revnumber: v1.0 -:revdate: 2003-12-21 - -ifdef::doctype-article[] -Abstract --------- -Abstract special section. - -endif::doctype-article[] - - -ifdef::doctype-book[] -Dedica ------- -Dedication special section. - - -Prefazione ----------- -Preface special section. - - -Colofone --------- -Colophon special section. - -endif::doctype-book[] - - -The First Section ------------------ -Admonishments -~~~~~~~~~~~~~ -Do not translate in the source file -- they are translated to the -output file - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[Tiger image] - -Followed by an example table: - -.Table -[width="60%",options="header"] -|============================================== -| Option | Description -| -a 'USER GROUP' | Add 'USER' to 'GROUP'. -| -R 'GROUP' | Disables access to 'GROUP'. -|============================================== - -And now for something completely different: ((monkeys)), lions and -tigers. - - -Appendice A: Example Appendix ------------------------------ -Appendix special section. - - -Bibliografia ------------- -Bibliography special section. - -[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. - - -Glossario ---------- -Glossary special section. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - - -ifdef::basebackend-docbook[] -Index ------ -//////////////////////////////////////////////////////////////// -Index special section. -The index is normally left completely empty, it's contents being -generated automatically by the DocBook toolchain. -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/lang-de-man-test.txt b/tests/data/lang-de-man-test.txt deleted file mode 100644 index f1806d4..0000000 --- a/tests/data/lang-de-man-test.txt +++ /dev/null @@ -1,21 +0,0 @@ -// Test for lang-de.conf language file. -:lang: de - -ASCIIDOC(1) -=========== -:doctype: manpage - -NAME ----- -asciidoc - converts an AsciiDoc text file to HTML or DocBook - -ÜBERSICHT ---------- -*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. - -... diff --git a/tests/data/lang-de-test.txt b/tests/data/lang-de-test.txt deleted file mode 100644 index ebddb62..0000000 --- a/tests/data/lang-de-test.txt +++ /dev/null @@ -1,106 +0,0 @@ -// Test for lang-de.conf language file. -:lang: de - -Languages Test -============== -:revnumber: v1.0 -:revdate: 2003-12-21 - -ifdef::doctype-article[] -Zusammenfassung ---------------- -Abstract special section. - -endif::doctype-article[] - - -ifdef::doctype-book[] -Widmung -------- -Dedication special section. - - -Vorwort -------- -Preface special section. - - -Kolophon --------- -Colophon special section. - -endif::doctype-book[] - - -The First Section ------------------ -Admonishments -~~~~~~~~~~~~~ -Do not translate in the source file -- they are translated to the -output file - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[Tiger image] - -Followed by an example table: - -.Table -[width="60%",options="header"] -|============================================== -| Option | Description -| -a 'USER GROUP' | Add 'USER' to 'GROUP'. -| -R 'GROUP' | Disables access to 'GROUP'. -|============================================== - -And now for something completely different: ((monkeys)), lions and -tigers. - - -Anhang A: Example Appendix --------------------------- -Appendix special section. - - -Literaturverzeichnis --------------------- -Bibliography special section. - -[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. - - -Glossar -------- -Glossary special section. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - - -ifdef::basebackend-docbook[] -Stichwortverzeichnis --------------------- -//////////////////////////////////////////////////////////////// -Index special section. -The index is normally left completely empty, it's contents being -generated automatically by the DocBook toolchain. -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/lang-en-man-test.txt b/tests/data/lang-en-man-test.txt deleted file mode 100644 index 0dec04a..0000000 --- a/tests/data/lang-en-man-test.txt +++ /dev/null @@ -1,21 +0,0 @@ -// Test for lang-en.conf language file. -:lang: en - -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. - -... diff --git a/tests/data/lang-en-test.txt b/tests/data/lang-en-test.txt deleted file mode 100644 index a312458..0000000 --- a/tests/data/lang-en-test.txt +++ /dev/null @@ -1,114 +0,0 @@ -// Test for lang-en.conf language file. -:lang: en - -Languages Test -============== -:revnumber: v1.0 -:revdate: 2003-12-21 - -ifdef::doctype-article[] -// Translate title. -Abstract --------- -Abstract special section. - -endif::doctype-article[] - - -ifdef::doctype-book[] -// Translate title. -Dedication ----------- -Dedication special section. - - -// Translate title. -Preface -------- -Preface special section. - - -// Translate title. -Colophon --------- -Colophon special section. - -endif::doctype-book[] - - -The First Section ------------------ -Admonishments -~~~~~~~~~~~~~ -Do not translate in the source file -- they are translated to the -output file - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[Tiger image] - -Followed by an example table: - -.Table -[width="60%",options="header"] -|============================================== -| Option | Description -| -a 'USER GROUP' | Add 'USER' to 'GROUP'. -| -R 'GROUP' | Disables access to 'GROUP'. -|============================================== - -And now for something completely different: ((monkeys)), lions and -tigers. - - -// Translate title. -Appendix A: Example Appendix ----------------------------- -Appendix special section. - - -// Translate title. -Bibliography ------------- -Bibliography special section. - -[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. - - -// Translate title. -Glossary --------- -Glossary special section. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - - -ifdef::basebackend-docbook[] -// Translate title. -Index ------ -//////////////////////////////////////////////////////////////// -Index special section. -The index is normally left completely empty, it's contents being -generated automatically by the DocBook toolchain. -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/lang-es-man-test.txt b/tests/data/lang-es-man-test.txt deleted file mode 100644 index cb95b70..0000000 --- a/tests/data/lang-es-man-test.txt +++ /dev/null @@ -1,21 +0,0 @@ -// Test for lang-es.conf language file. -:lang: es - -ASCIIDOC(1) -=========== -:doctype: manpage - -NAME ----- -asciidoc - converts an AsciiDoc text file to HTML or DocBook - -SINOPSIS --------- -*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. - -... diff --git a/tests/data/lang-es-test.txt b/tests/data/lang-es-test.txt deleted file mode 100644 index 97eca94..0000000 --- a/tests/data/lang-es-test.txt +++ /dev/null @@ -1,106 +0,0 @@ -// Test for lang-es.conf language file. -:lang: es - -Languages Test -============== -:revnumber: v1.0 -:revdate: 2003-12-21 - -ifdef::doctype-article[] -Resumen -------- -Abstract special section. - -endif::doctype-article[] - - -ifdef::doctype-book[] -Dedicación ----------- -Dedication special section. - - -Prefacio --------- -Preface special section. - - -Colofón -------- -Colophon special section. - -endif::doctype-book[] - - -The First Section ------------------ -Admonishments -~~~~~~~~~~~~~ -Do not translate in the source file -- they are translated to the -output file - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[Tiger image] - -Followed by an example table: - -.Table -[width="60%",options="header"] -|============================================== -| Option | Description -| -a 'USER GROUP' | Add 'USER' to 'GROUP'. -| -R 'GROUP' | Disables access to 'GROUP'. -|============================================== - -And now for something completely different: ((monkeys)), lions and -tigers. - - -Apéndice A: Example Appendix ----------------------------- -Appendix special section. - - -Bibliografía ------------- -Bibliography special section. - -[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. - - -Glosario --------- -Glossary special section. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - - -ifdef::basebackend-docbook[] -Índice ------- -//////////////////////////////////////////////////////////////// -Index special section. -The index is normally left completely empty, it's contents being -generated automatically by the DocBook toolchain. -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/lang-fr-man-test.txt b/tests/data/lang-fr-man-test.txt deleted file mode 100644 index edb681f..0000000 --- a/tests/data/lang-fr-man-test.txt +++ /dev/null @@ -1,21 +0,0 @@ -// Test for lang-fr.conf language file. -:lang: fr - -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. - -... diff --git a/tests/data/lang-fr-test.txt b/tests/data/lang-fr-test.txt deleted file mode 100644 index 84c25fa..0000000 --- a/tests/data/lang-fr-test.txt +++ /dev/null @@ -1,106 +0,0 @@ -// Test for lang-fr.conf language file. -:lang: fr - -Languages Test -============== -:revnumber: v1.0 -:revdate: 2003-12-21 - -ifdef::doctype-article[] -Résumé ------- -Abstract special section. - -endif::doctype-article[] - - -ifdef::doctype-book[] -Dédicace --------- -Dedication special section. - - -Préface -------- -Preface special section. - - -Colophon --------- -Colophon special section. - -endif::doctype-book[] - - -The First Section ------------------ -Admonishments -~~~~~~~~~~~~~ -Do not translate in the source file -- they are translated to the -output file - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[Tiger image] - -Followed by an example table: - -.Table -[width="60%",options="header"] -|============================================== -| Option | Description -| -a 'USER GROUP' | Add 'USER' to 'GROUP'. -| -R 'GROUP' | Disables access to 'GROUP'. -|============================================== - -And now for something completely different: ((monkeys)), lions and -tigers. - - -Appendice A: Example Appendix ------------------------------ -Appendix special section. - - -Bibliographie -------------- -Bibliography special section. - -[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. - - -Glossaire ---------- -Glossary special section. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - - -ifdef::basebackend-docbook[] -Index ------ -//////////////////////////////////////////////////////////////// -Index special section. -The index is normally left completely empty, it's contents being -generated automatically by the DocBook toolchain. -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/lang-hu-man-test.txt b/tests/data/lang-hu-man-test.txt deleted file mode 100644 index 7caf1ad..0000000 --- a/tests/data/lang-hu-man-test.txt +++ /dev/null @@ -1,21 +0,0 @@ -// Test for lang-hu.conf language file. -:lang: hu - -ASCIIDOC(1) -=========== -:doctype: manpage - -NAME ----- -asciidoc - converts an AsciiDoc text file to HTML or DocBook - -ÁTTEKINTÉS ----------- -*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. - -... diff --git a/tests/data/lang-hu-test.txt b/tests/data/lang-hu-test.txt deleted file mode 100644 index cf873c2..0000000 --- a/tests/data/lang-hu-test.txt +++ /dev/null @@ -1,106 +0,0 @@ -// Test for lang-hu.conf language file. -:lang: hu - -Languages Test -============== -:revnumber: v1.0 -:revdate: 2003-12-21 - -ifdef::doctype-article[] -Kivonat -------- -Abstract special section. - -endif::doctype-article[] - - -ifdef::doctype-book[] -Ajánlás --------- -Dedication special section. - - -Előszó ------- -Preface special section. - - -Utószó ------- -Colophon special section. - -endif::doctype-book[] - - -The First Section ------------------ -Admonishments -~~~~~~~~~~~~~ -Do not translate in the source file -- they are translated to the -output file - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[Tiger image] - -Followed by an example table: - -.Table -[width="60%",options="header"] -|============================================== -| Option | Description -| -a 'USER GROUP' | Add 'USER' to 'GROUP'. -| -R 'GROUP' | Disables access to 'GROUP'. -|============================================== - -And now for something completely different: ((monkeys)), lions and -tigers. - - -A függelék: Example Appendix ----------------------------- -Appendix special section. - - -Bibliográfia ------------- -Bibliography special section. - -[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. - - -Szójegyzék ----------- -Glossary special section. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - - -ifdef::basebackend-docbook[] -Index ------ -//////////////////////////////////////////////////////////////// -Index special section. -The index is normally left completely empty, it's contents being -generated automatically by the DocBook toolchain. -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/lang-it-man-test.txt b/tests/data/lang-it-man-test.txt deleted file mode 100644 index 7309a0c..0000000 --- a/tests/data/lang-it-man-test.txt +++ /dev/null @@ -1,21 +0,0 @@ -// Test for lang-it.conf language file. -:lang: it - -ASCIIDOC(1) -=========== -:doctype: manpage - -NAME ----- -asciidoc - converts an AsciiDoc text file to HTML or DocBook - -SINOSSI -------- -*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. - -... diff --git a/tests/data/lang-it-test.txt b/tests/data/lang-it-test.txt deleted file mode 100644 index 790a57e..0000000 --- a/tests/data/lang-it-test.txt +++ /dev/null @@ -1,106 +0,0 @@ -// Test for lang-it.conf language file. -:lang: it - -Languages Test -============== -:revnumber: v1.0 -:revdate: 2003-12-21 - -ifdef::doctype-article[] -Abstract --------- -Abstract special section. - -endif::doctype-article[] - - -ifdef::doctype-book[] -Dedica ------- -Dedication special section. - - -Prefazione ----------- -Preface special section. - - -Colofone --------- -Colophon special section. - -endif::doctype-book[] - - -The First Section ------------------ -Admonishments -~~~~~~~~~~~~~ -Do not translate in the source file -- they are translated to the -output file - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[Tiger image] - -Followed by an example table: - -.Table -[width="60%",options="header"] -|============================================== -| Option | Description -| -a 'USER GROUP' | Add 'USER' to 'GROUP'. -| -R 'GROUP' | Disables access to 'GROUP'. -|============================================== - -And now for something completely different: ((monkeys)), lions and -tigers. - - -Appendice A: Example Appendix ------------------------------ -Appendix special section. - - -Bibliografia ------------- -Bibliography special section. - -[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. - - -Glossario ---------- -Glossary special section. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - - -ifdef::basebackend-docbook[] -Index ------ -//////////////////////////////////////////////////////////////// -Index special section. -The index is normally left completely empty, it's contents being -generated automatically by the DocBook toolchain. -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/lang-ja-man-test.txt b/tests/data/lang-ja-man-test.txt deleted file mode 100644 index 2ecaa14..0000000 --- a/tests/data/lang-ja-man-test.txt +++ /dev/null @@ -1,18 +0,0 @@ -// Test for lang-ja.conf language file. -:lang: ja - -ASCIIDOC(1) -=========== -:doctype: manpage - -== 名前 -asciidoc - AsciiDoc テキストファイルを HTML や DocBook に変換する - -== 書式 -*asciidoc* ['OPTIONS'] 'FILE' - -== 説明 -asciidoc(1) コマンドは AsciiDoc テキストファイル 'FILE' を DocBook -や HTML に変換する。 'FILE' が '-' ならば標準入力を使用する。 - -... diff --git a/tests/data/lang-ja-test.txt b/tests/data/lang-ja-test.txt deleted file mode 100644 index 13bec4c..0000000 --- a/tests/data/lang-ja-test.txt +++ /dev/null @@ -1,94 +0,0 @@ -// Test for lang-ja.conf language file. -:lang: ja - -Languages Test -============== -:revnumber: v1.0 -:revdate: 2003-12-21 - -ifdef::doctype-article[] -== 概要 -概要セクション - -endif::doctype-article[] - - -ifdef::doctype-book[] -== 献辞 -献辞セクション - - -== 前書 -前書セクション - - -== 奥付 -奥付セクション - -endif::doctype-book[] - - -== 第一セクション -=== 警告 -以下は処理系が翻訳するのでこのソースでは翻訳しない。 - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[虎の絵] - -続いて表の例。 - -.Table -[width="60%",options="header"] -|================================================= -| オプション | 説明 -| -a 'USER GROUP' | 'USER' を 'GROUP' に追加する -| -R 'GROUP' | 'GROUP' へのアクセスを禁止する -|================================================= - -そしてまったく異なるものの例: ((猿))、ライオン、虎。 - - -== 付録 A: 付録の例 -付録セクション - - -== 参考文献 -参考文献セクション - -[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] -用語:: - （インデントされた）用語の定義 - -別の用語:: - （インデントされた）用語の定義 - - -ifdef::basebackend-docbook[] -== 索引 -//////////////////////////////////////////////////////////////// -索引セクション。 -内容は DocBook ツールチェーンが自動生成するので、 -通常このセクションは空である。 -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/lang-nl-man-test.txt b/tests/data/lang-nl-man-test.txt deleted file mode 100644 index 4844c17..0000000 --- a/tests/data/lang-nl-man-test.txt +++ /dev/null @@ -1,21 +0,0 @@ -// Test for lang-nl.conf language file. -:lang: nl - -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. - -... diff --git a/tests/data/lang-nl-test.txt b/tests/data/lang-nl-test.txt deleted file mode 100644 index 7e6e823..0000000 --- a/tests/data/lang-nl-test.txt +++ /dev/null @@ -1,94 +0,0 @@ -// Test for lang-nl.conf language file. -:lang: nl - -= Languages Test -:revnumber: v1.0 -:revdate: 2003-12-21 - -ifdef::doctype-article[] -== Samenvatting -Bijzonder 'abstract' sectie. - -endif::doctype-article[] - - -ifdef::doctype-book[] -== Opdracht -Bijzonder 'dedication' sectie. - - -== Voorwoord -Bijzonder 'preface' sectie. - - -== Colofon -Bijzonder 'colophon' sectie. - -endif::doctype-book[] - - -== Het Eerste Hoofdstuk -=== Vermaningen -Vertaal ze niet in the broncode -- ze worden vanzelf vertaald in het -output bestand - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[Tiger image] - -Gevolgd door een voorbeeld tabel: - -.Table -[width="60%",options="header"] -|============================================== -| Optie | Beschrijving -| -a 'USER GROUP' | Voeg 'USER' toe aan 'GROUP'. -| -R 'GROUP' | Schakel toegang uit tot 'GROUP'. -|============================================== - -En nu iets totaal anders: ((apen)), leeuwen en tijgers. - - -== Bijlage A: Voorbeeld Bijlage -Bijzonder 'appendix' sectie. - - -== Literatuurlijst -Bijzonder 'bibliography' sectie. - -[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. - - -== Woordenlijst -Bijzonder 'glossary' sectie. - -[glossary] -Een woordenlijst term:: - De bijhorende (ingesprongen) definitie. - -Een tweede term:: - De bijhorende (ingesprongen) definitie. - - -ifdef::basebackend-docbook[] -== Register -//////////////////////////////////////////////////////////////// -Bijzonder 'index' sectie. -Het register wordt normaal leeg gehouden, de inhoud wordt -automatisch gegenereerd door de DocBook hulpmiddelen. -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/lang-pt-BR-man-test.txt b/tests/data/lang-pt-BR-man-test.txt deleted file mode 100644 index 0363ea6..0000000 --- a/tests/data/lang-pt-BR-man-test.txt +++ /dev/null @@ -1,21 +0,0 @@ -// Test for lang-pt-BR.conf language file. -:lang: pt-BR - -ASCIIDOC(1) -=========== -:doctype: manpage - -NAME ----- -asciidoc - converts an AsciiDoc text file to HTML or DocBook - -SINOPSE -------- -*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. - -... diff --git a/tests/data/lang-pt-BR-test.txt b/tests/data/lang-pt-BR-test.txt deleted file mode 100644 index daaff18..0000000 --- a/tests/data/lang-pt-BR-test.txt +++ /dev/null @@ -1,106 +0,0 @@ -// Test for lang-pt-BR.conf language file. -:lang: pt-BR - -Languages Test -============== -:revnumber: v1.0 -:revdate: 2003-12-21 - -ifdef::doctype-article[] -Resumo ------- -Abstract special section. - -endif::doctype-article[] - - -ifdef::doctype-book[] -Dedicação ---------- -Dedication special section. - - -Prefácio --------- -Preface special section. - - -Cólofon -------- -Colophon special section. - -endif::doctype-book[] - - -The First Section ------------------ -Admonishments -~~~~~~~~~~~~~ -Do not translate in the source file -- they are translated to the -output file - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[Tiger image] - -Followed by an example table: - -.Table -[width="60%",options="header"] -|============================================== -| Option | Description -| -a 'USER GROUP' | Add 'USER' to 'GROUP'. -| -R 'GROUP' | Disables access to 'GROUP'. -|============================================== - -And now for something completely different: ((monkeys)), lions and -tigers. - - -Appêndice A: Example Appendix ------------------------------ -Appendix special section. - - -Bibliografia ------------- -Bibliography special section. - -[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. - - -Glossário ---------- -Glossary special section. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - - -ifdef::basebackend-docbook[] -Índice ------- -//////////////////////////////////////////////////////////////// -Index special section. -The index is normally left completely empty, it's contents being -generated automatically by the DocBook toolchain. -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/lang-ro-man-test.txt b/tests/data/lang-ro-man-test.txt deleted file mode 100644 index 7309a0c..0000000 --- a/tests/data/lang-ro-man-test.txt +++ /dev/null @@ -1,21 +0,0 @@ -// Test for lang-it.conf language file. -:lang: it - -ASCIIDOC(1) -=========== -:doctype: manpage - -NAME ----- -asciidoc - converts an AsciiDoc text file to HTML or DocBook - -SINOSSI -------- -*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. - -... diff --git a/tests/data/lang-ro-test.txt b/tests/data/lang-ro-test.txt deleted file mode 100644 index 790a57e..0000000 --- a/tests/data/lang-ro-test.txt +++ /dev/null @@ -1,106 +0,0 @@ -// Test for lang-it.conf language file. -:lang: it - -Languages Test -============== -:revnumber: v1.0 -:revdate: 2003-12-21 - -ifdef::doctype-article[] -Abstract --------- -Abstract special section. - -endif::doctype-article[] - - -ifdef::doctype-book[] -Dedica ------- -Dedication special section. - - -Prefazione ----------- -Preface special section. - - -Colofone --------- -Colophon special section. - -endif::doctype-book[] - - -The First Section ------------------ -Admonishments -~~~~~~~~~~~~~ -Do not translate in the source file -- they are translated to the -output file - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[Tiger image] - -Followed by an example table: - -.Table -[width="60%",options="header"] -|============================================== -| Option | Description -| -a 'USER GROUP' | Add 'USER' to 'GROUP'. -| -R 'GROUP' | Disables access to 'GROUP'. -|============================================== - -And now for something completely different: ((monkeys)), lions and -tigers. - - -Appendice A: Example Appendix ------------------------------ -Appendix special section. - - -Bibliografia ------------- -Bibliography special section. - -[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. - - -Glossario ---------- -Glossary special section. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - - -ifdef::basebackend-docbook[] -Index ------ -//////////////////////////////////////////////////////////////// -Index special section. -The index is normally left completely empty, it's contents being -generated automatically by the DocBook toolchain. -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/lang-ru-man-test.txt b/tests/data/lang-ru-man-test.txt deleted file mode 100644 index 3e50548..0000000 --- a/tests/data/lang-ru-man-test.txt +++ /dev/null @@ -1,21 +0,0 @@ -// Test for lang-ru.conf language file. -:lang: ru - -ASCIIDOC(1) -=========== -:doctype: manpage - -NAME ----- -asciidoc - converts an AsciiDoc text file to HTML or DocBook - -ОБЗОР ------ -*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. - -... diff --git a/tests/data/lang-ru-test.txt b/tests/data/lang-ru-test.txt deleted file mode 100644 index 51d9b60..0000000 --- a/tests/data/lang-ru-test.txt +++ /dev/null @@ -1,106 +0,0 @@ -// Test for lang-ru.conf language file. -:lang: ru - -Languages Test -============== -:revnumber: v1.0 -:revdate: 2003-12-21 - -ifdef::doctype-article[] -Аннотация ---------- -Abstract special section. - -endif::doctype-article[] - - -ifdef::doctype-book[] -Посвящение ----------- -Dedication special section. - - -Введение --------- -Preface special section. - - -Колофон -------- -Colophon special section. - -endif::doctype-book[] - - -The First Section ------------------ -Admonishments -~~~~~~~~~~~~~ -Do not translate in the source file -- they are translated to the -output file - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[Tiger image] - -Followed by an example table: - -.Table -[width="60%",options="header"] -|============================================== -| Option | Description -| -a 'USER GROUP' | Add 'USER' to 'GROUP'. -| -R 'GROUP' | Disables access to 'GROUP'. -|============================================== - -And now for something completely different: ((monkeys)), lions and -tigers. - - -Приложение A: Example Appendix ------------------------------- -Appendix special section. - - -Библиография ------------- -Bibliography special section. - -[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 special section. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - - -ifdef::basebackend-docbook[] -Предметный указатель --------------------- -//////////////////////////////////////////////////////////////// -Index special section. -The index is normally left completely empty, it's contents being -generated automatically by the DocBook toolchain. -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/lang-sv-man-test.txt b/tests/data/lang-sv-man-test.txt deleted file mode 100644 index af82d8a..0000000 --- a/tests/data/lang-sv-man-test.txt +++ /dev/null @@ -1,21 +0,0 @@ -// Test for lang-sv.conf language file. -:lang: sv - -ASCIIDOC(1) -=========== -:doctype: manpage - -NAMN ----- -asciidoc - converts an AsciiDoc text file to HTML or DocBook - -ÖVERSIKT --------- -*asciidoc* ['OPTIONS'] 'FILE' - -BESKRIVNING ------------ -The asciidoc(1) command translates the AsciiDoc text file 'FILE' to -DocBook or HTML. If 'FILE' is '-' then the standard input is used. - -... diff --git a/tests/data/lang-sv-test.txt b/tests/data/lang-sv-test.txt deleted file mode 100644 index 1e64e3c..0000000 --- a/tests/data/lang-sv-test.txt +++ /dev/null @@ -1,114 +0,0 @@ -// Test for lang-sv.conf language file. -:lang: sv - -Languages Test -============== -:revnumber: v1.0 -:revdate: 2003-12-21 - -ifdef::doctype-article[] -// Translate title. -Sammanfattning --------------- -Abstract special section. - -endif::doctype-article[] - - -ifdef::doctype-book[] -// Translate title. -Dedikation ----------- -Dedication special section. - - -// Translate title. -Förord ------- -Preface special section. - - -// Translate title. -Kolofon -------- -Colophon special section. - -endif::doctype-book[] - - -The First Section ------------------ -Admonishments -~~~~~~~~~~~~~ -Do not translate in the source file -- they are translated to the -output file - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[Tiger image] - -Followed by an example table: - -.Table -[width="60%",options="header"] -|============================================== -| Option | Description -| -a 'USER GROUP' | Add 'USER' to 'GROUP'. -| -R 'GROUP' | Disables access to 'GROUP'. -|============================================== - -And now for something completely different: ((monkeys)), lions and -tigers. - - -// Translate title. -Appendix A: Exempel-appendix ----------------------------- -Appendix special section. - - -// Translate title. -Referenser ----------- -Bibliography special section. - -[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. - - -// Translate title. -Ordlista --------- -Glossary special section. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - - -ifdef::basebackend-docbook[] -// Translate title. -Sakregister ------------ -//////////////////////////////////////////////////////////////// -Index special section. -The index is normally left completely empty, it's contents being -generated automatically by the DocBook toolchain. -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/lang-uk-man-test.txt b/tests/data/lang-uk-man-test.txt deleted file mode 100644 index 8212e4c..0000000 --- a/tests/data/lang-uk-man-test.txt +++ /dev/null @@ -1,21 +0,0 @@ -// Test for lang-uk.conf language file. -:lang: uk - -ASCIIDOC(1) -=========== -:doctype: manpage - -NAME ----- -asciidoc - converts an AsciiDoc text file to HTML or DocBook - -ОГЛЯД ------ -*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. - -... diff --git a/tests/data/lang-uk-test.txt b/tests/data/lang-uk-test.txt deleted file mode 100644 index 76c58eb..0000000 --- a/tests/data/lang-uk-test.txt +++ /dev/null @@ -1,106 +0,0 @@ -// Test for lang-uk.conf language file. -:lang: uk - -Languages Test -============== -:revnumber: v1.0 -:revdate: 2011-01-30 - -ifdef::doctype-article[] -Анотація --------- -Abstract special section. - -endif::doctype-article[] - - -ifdef::doctype-book[] -Присвячення ------------ -Dedication special section. - - -Вступ ------ -Preface special section. - - -Колофон -------- -Colophon special section. - -endif::doctype-book[] - - -The First Section ------------------ -Admonishments -~~~~~~~~~~~~~ -Do not translate in the source file -- they are translated to the -output file - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -.Tiger -image::../../images/tiger.png[Tiger image] - -Followed by an example table: - -.Table -[width="60%",options="header"] -|============================================== -| Option | Description -| -a 'USER GROUP' | Add 'USER' to 'GROUP'. -| -R 'GROUP' | Disables access to 'GROUP'. -|============================================== - -And now for something completely different: ((monkeys)), lions and -tigers. - - -Додаток A: Example Appendix ---------------------------- -Appendix special section. - - -Бібліографія ------------- -Bibliography special section. - -[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 special section. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - - -ifdef::basebackend-docbook[] -Предметний покажчик -------------------- -//////////////////////////////////////////////////////////////// -Index special section. -The index is normally left completely empty, it's contents being -generated automatically by the DocBook toolchain. -//////////////////////////////////////////////////////////////// -endif::basebackend-docbook[] diff --git a/tests/data/newline.txt b/tests/data/newline.txt deleted file mode 100644 index ceead4a..0000000 --- a/tests/data/newline.txt +++ /dev/null @@ -1,17 +0,0 @@ -= Newline Tests - -These are tests about newlines. -See https://en.wikipedia.org/wiki/Newline[details] on the history. - -NOTE: Each section in the source file has the newline style from the - description. - -== UNIX Newlines - -Uses \n. - -== DOS Newlines - -Uses \r\n. - -== MAC Newlines Uses \r. Only used prior to Mac OS X. \ No newline at end of file diff --git a/tests/data/oldtables.txt b/tests/data/oldtables.txt deleted file mode 100644 index f6e0706..0000000 --- a/tests/data/oldtables.txt +++ /dev/null @@ -1,64 +0,0 @@ -AsciiDoc Old Tables -=================== - -Examples of the AsciiDoc 'old tables' syntax. This syntax was used in -AsciiDoc versions up to 8.2.7 and has since been deprecated in favor -of the 'new tables' syntax. - -Simple table: - -`---`--- -1 2 -3 4 -5 6 --------- - -Table with title, header and footer: - -.An example table -[grid="all"] -`-----------.-------------- -Column 1 Column 2 ---------------------------- -1 Item 1 -2 Item 2 -3 Item 3 ---------------------------- -6 Three items ---------------------------- - -Four columns totaling 15% of the 'pagewidth', CSV data: - -[frame="all"] -````~15 -1,2,3,4 -a,b,c,d -A,B,C,D -~~~~~~~~ - -A table with a numeric ruler and externally sourced CSV data: - -[frame="all", grid="all"] -`15`20`25`20`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -ID,Customer Name,Contact Name,Customer Address,Phone -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -"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" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - diff --git a/tests/data/open-block-test.txt b/tests/data/open-block-test.txt deleted file mode 100644 index 4826c3a..0000000 --- a/tests/data/open-block-test.txt +++ /dev/null @@ -1,117 +0,0 @@ -= Additional Open Block and Paragraph styles - - -[comment] -Lorum ipsum... - -[comment] --- -Lorum ipsum... --- - -[example] -Lorum ipsum... - -[example] --- -Lorum ipsum... - -Lorum ipsum... --- - -[sidebar] -Lorum ipsum... - -[sidebar] -.A title --- -Lorum ipsum... - -Lorum ipsum... --- - -[NOTE] --- -Lorum ipsum... - -Lorum ipsum... --- - -[CAUTION] --- -Lorum ipsum... - -Lorum ipsum... --- - -[IMPORTANT] --- -Lorum ipsum... - -Lorum ipsum... --- - -[WARNING] --- -Lorum ipsum... - -Lorum ipsum... --- - -[TIP] --- -Lorum ipsum... - -Lorum ipsum... --- - -[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes] --- -As he spoke there was the sharp sound of horses' hoofs and -grating wheels against the curb, followed by a sharp pull at the -bell. Holmes whistled. - -"A pair, by the sound," said he. "Yes," he continued, glancing -out of the window. "A nice little brougham and a pair of -beauties. A hundred and fifty guineas apiece. There's money in -this case, Watson, if there is nothing else." --- - -[verse, William Blake, from Auguries of Innocence] --- -To see a world in a grain of sand, -And a heaven in a wild flower, -Hold infinity in the palm of your hand, -And eternity in an hour. --- - -[source,python] --- -y = 15 - -if y == 24: - x = 42 --- - -[latex] --- -$y = \int_0^\infty \gamma^2 \cos(x) dx$ --- - -[graphviz] --- -digraph G { rankdir=LR; Graphviz->AsciiDoc->HTML} --- - -[music] --- -\version "2.10.0" -\paper { - ragged-right = ##t -} -{ - \time 3/4 - \clef bass - c2 e4 g2. f4 e d c2 r4 -} --- diff --git a/tests/data/rcs-id-marker-test.txt b/tests/data/rcs-id-marker-test.txt deleted file mode 100644 index 55b0892..0000000 --- a/tests/data/rcs-id-marker-test.txt +++ /dev/null @@ -1,6 +0,0 @@ -RCS $Id$ Marker Test -==================== -$Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $ - - -Lorum ipsum... diff --git a/tests/data/slidy-example.txt b/tests/data/slidy-example.txt deleted file mode 100644 index f5d0363..0000000 --- a/tests/data/slidy-example.txt +++ /dev/null @@ -1,174 +0,0 @@ -Slidy Example Slideshow -======================= -:author: Joe Bloggs -:copyright: Foobar Inc. -:backend: slidy -:max-width: 45em -:data-uri: -:icons: - - -This preamble will appear on a separate slide. - - -AsciiDoc Elements ------------------ -Sagittis in vestibulum. Habitasse ante nulla enim bibendum nulla. Odio -sed pede litora. - -[float] -=== Titles inside delimited blocks must be floated -Porta nisl metus. Justo porttitor vel. Cras consequat tincidunt id sed -conubia. Feugiat felis justo. Nunc amet nulla. Eu ac orci mollis. - -.Tiger -image::images/tiger.png[] - - -Incremental Elements --------------------- -The remaining elements on this page are incremental, press the space -bar to reveal them. - -[role="incremental"] -- Rhoncus pede justo. -- Velit pede dolor. -- Iaculis commodo et. -- Volutpat tristique nec. - -[role="incremental"] --- -Sagittis in vestibulum. Habitasse ante nulla enim bibendum nulla. Odio -sed pede litora. --- - -[role="incremental"] -. Rhoncus pede justo. -. Velit pede dolor. -. Iaculis commodo et. -. Volutpat tristique nec. - - -Outline Elements ----------------- -The following list is a Slidy 'outline' list -- nested bulleted or -numbered lists are expanded when the enclosing list item (the ones -with blue bullet points or numbers) are clicked. - -[role="outline"] -- Rhoncus pede justo. - * Rhoncus pede justo. - * Velit pede dolor. - -- Velit pede dolor. - * Iaculis commodo et. -+ -NOTE: 'Note' admonition paragraph. - - * Volutpat tristique nec. -+ -image::images/tiger.png[] - * Iaculis commodo et. - * Volutpat tristique nec. - -- Iaculis commodo et. -[role="outline"] - . Rhoncus pede justo. - ** Velit pede dolor. - ** Iaculis commodo et. - . Volutpat tristique nec. - -- Volutpat tristique nec. - - -AsciiDoc Elements ------------------ -NOTE: 'Note' admonition paragraph. - -IMPORTANT: 'Important' admonition paragraph. - -.Sidebar -********************************************************************* -Faucibus sagittis commodo sed et eu. Quam nullam ornare. Sed vel est. -Mauris urna lobortis interdum placerat per id magnis enim. -********************************************************************* - - -AsciiDoc Elements ------------------ -A quote block: - -[quote, Bertrand Russell, The World of Mathematics (1956)] -____________________________________________________________________ -A good notation has subtlety and suggestiveness which at times makes -it almost seem like a live teacher. -____________________________________________________________________ - -A verse block: - -[verse, William Blake, from Auguries of Innocence] -__________________________________________________ -To see a world in a grain of sand, -And a heaven in a wild flower, -Hold infinity in the palm of your hand, -And eternity in an hour. -__________________________________________________ - - -AsciiDoc Elements ------------------ -.Horizontal and vertical source data -[width="80%",cols="3,^2,^2,10",options="header"] -|========================================================= -|Date |Duration |Avg HR |Notes - -|22-Aug-08 |10:24 | 157 | -Worked out MSHR (max sustainable heart rate) by going hard -for this interval. - -|22-Aug-08 |23:03 | 152 | -Back-to-back with previous interval. - -|24-Aug-08 |40:00 | 145 | -Moderately hard interspersed with 3x 3min intervals (2min -hard + 1min really hard taking the HR up to 160). - -|========================================================= - - -Filters -------- -[source,python] -.Python source ---------------------------------------------------------------------- -''' A multi-line - comment.''' -def sub_word(mo): - ''' Single line comment.''' - word = mo.group('word') # Inline comment - if word in keywords[language]: - return quote + word + quote - else: - return word ---------------------------------------------------------------------- - -//// -The music generation block is ignored for testing as it generates a PNG -that is unique to the combination of lilypond and libpng used, which is -easily different from environment to environment - -[music] -.Music ---------------------------------------------------------------------- -\version "2.10.0" -\paper { - ragged-right = ##t -} -{ - \time 3/4 - \clef bass - c2 e4 g2. f4 e d c2 r4 -} ---------------------------------------------------------------------- - -//// diff --git a/tests/data/testcases.conf b/tests/data/testcases.conf deleted file mode 100644 index 78517c8..0000000 --- a/tests/data/testcases.conf +++ /dev/null @@ -1,12 +0,0 @@ -[replacements] -test-replacement=TEST_REPLACEMENT - -[test-template] -This template is overridden and should not be displayed. - -[test-template] -Template line 1. - -[+test-template] -Template line 2. - diff --git a/tests/data/testcases.txt b/tests/data/testcases.txt deleted file mode 100644 index d7dda45..0000000 --- a/tests/data/testcases.txt +++ /dev/null @@ -1,817 +0,0 @@ -// -// A collection of AsciiDoc test cases. -// - -Test 'Cases' -============ -:author: Joe Bloggs -// Web page meta data. -:title: Test Cases -:keywords: AsciiDoc, DocBook, EPUB, slideshow -:description: AsciiDoc is a text document format for writing short documents, + - articles, books, slideshows and UNIX man pages. -:replacements.(\w)'(\w): \1’\2 -:test-attribute: TEST_ATTRIBUTE - - -== Passthrough attributes == -ifdef::basebackend-docbook[] -:passtest: pass:[*lorum ipsum*] -endif::basebackend-docbook[] -ifdef::basebackend-html[] -:passtest: pass:[*lorum ipsum*] -endif::basebackend-html[] -{passtest} - -ifdef::basebackend-docbook[] -:passtest: pass:specialcharacters,quotes[*lorum ipsum*] -endif::basebackend-docbook[] -ifdef::basebackend-html[] -:passtest: pass:specialcharacters,quotes[*lorum ipsum*] -endif::basebackend-html[] -{passtest} - - -== Author attributes == -\{eval:expression}, \{sys:command} and \{sys2:command}, \{counter:c1} - -Hello *{author}* ({firstname} {lastname}, {authorinitials}). - -{firstname,lastname,surname#}first name or last name or surname. - -{firstname+lastname+surname#}first name and last name and surname. - -{firstname+lastname#}first name and last name. - - -== System attributes == -{counter:c1} {counter:c2:99} {counter:c3:A} - -{c1} = 1, {c2} = 99, {c3} = A - -{counter:c1} {counter:c2:99} {counter:c3:A} -{c1} {c2} {c3} - -{c1} = 2, {c2} = 100, {c3} = B - -{set:y:Foobar} -y: {y} - -{set:y!} - -y: {y} - -:x: 3 -:y: {eval:{x}+4} - -{x}, {y} - -{set:y:{x}} - -{x}, {y} - - -== Quoted text attributes == - -A=_X_, (_X_), _X_, [_X_] _X_ - -A=*_X_*, (`_X_`), _`X`_, [*_X_*] +_X_+ _X_ - -// These two illustrate that nesting doesn't always work. -[_*X*_] _+X+_ - -[[_intro]] -<<_intro>> <<_intro,intro>> xref:_intro[] _intro_ - -// Quote attributes. -[foo]#fun with text#. -[foo bar]*fun with text*. -[foo]+fun with text+. -[foo]_fun with text_. -[foo]'fun with text'. -[foo]``fun with text''. -[foo]`fun with text'. - -[foo]$$fun with text$$. - -[foo]+++fun with text+++. - -[red]#Obvious# and [big red yellow-background]*very obvious*. - -[underline]#Underline text#, [overline]#overline text# -and [line-through]#line-through text#. - -[firstletter]##T##esting 123 ... - -(``+1\n+'') if (usually ``+-1\n+'') - -(``++1\n++'') if (usually ``++-1\n++'') - -(`{author}') and `{author}' - - -== Configuration attribute entries == - -:listdef-labeled.style: horizontal -term:: definition - -:listdef-labeled.style: vertical -term:: definition - -ifdef::backend-xhtml11[] -<> - -:xref2-inlinemacro.: {2?{2}} - -<> - -:xref2-inlinemacro.: {2=[{1}]} -endif::[] - - -== role attribute == - -[role="test"] -Paragraph with a role attribute. - -[role="test"] -- first -- second -- third - - -== Break list nesting == -1. List 1. -2. List 1. - -// New list. -a. List 2. -b. List 2. - - -== Listing Blocks == -[subs="quotes"] ------------------------------------------- -$ ls *-al* ------------------------------------------- - -[listing] -.......................................... -[subs="quotes"] ------------------------------------------- -$ ls *-al* ------------------------------------------- -.......................................... - -.Listing ------------------------------------------- -$ ls -al ------------------------------------------- - -.Listing example -========================================== ------------------------------------------- -$ ls -al ------------------------------------------- -========================================== - -.Python paragraph -[source,python] -if n < 0: print 'Hello World!' - -.Titled Python listing -[source,python] ------------------------------------------- -if n < 0: print 'Hello World!' ------------------------------------------- - -.Python listing example -========================================== -[source,python] ------------------------------------------- -if n < 0: print 'Hello World!' ------------------------------------------- -========================================== - - -[[X1,anchor reftext]] -== Links == -An [[X2]] inline anchor. -An [[X3, anchor reftext]] inline anchor with reftext. - -<>; captioned link to <>. - -<> link to inline anchor; captioned link to <>. - -Link to <> anchor. - -An example link to a bibliography entry <>. - -[horizontal] -[[[Test::Unit]]]:: http://ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit.html - - -== Titles == - -[float] -===== Level 4 ===== -[float] -==== Level 3 ==== -[float] -=== Level 2 === -[float] -== Level 1 == -[float] -Level 4 -+++++++ -[float] -Level 3 -^^^^^^^ -[float] -Level 2 -~~~~~~~ -[float] -Level 1 -------- - -.Block title -Lorum ipsum. - - -== Lists == - -Bulleted: - -- item text -* item text -** item text -*** item text -**** item text -***** item text - -Numbered: - -1. arabic (decimal) numbering -a. loweralpha numbering -A. upperalpha numbering -i) lowerroman numbering -I) upperroman numbering -. arabic (decimal) numbering -.. loweralpha numbering -... lowerroman numbering -.... upperalpha numbering -..... upperroman numbering - -Labeled: - -label:: item text -label;; item text -label::: item text -label:::: item text - -With item anchor: - -one:: Item one. -[[item_two]]two:: Item two. -three:: Item three. - - -== Inline passthroughs == - -- Test pass:[`ABC`]. -- Test `pass:[ABC]`. -- The `++i` and `++j` auto-increments. -- Paths `~/.vim` and `~/docs`. -- The `__init__` method. -- The `{id}` attribute. - -List start number test: - -// The ol start attribute is not valid XHTML 1.1 (but it works in all -// browsers). -ifndef::backend-xhtml11[] -[start=7] -. List item 7. -. List item 8. -endif::backend-xhtml11[] - -== Images - -=== Block images - -[[tiger_image]] -.Tyger tyger -image::../../images/tiger.png[Tyger tyger] - -:height: 250 -:width: 350 -.Tyger tyger two -image::../../images/tiger.png[caption="Figure 2: ", alt="Tiger", align="center"] -:height!: -:width!: - -// Images and icons directories. -:imagesdir: ../../doc -image::music2.png[] - -:icons: -:iconsdir: ../../images/icons -NOTE: Lorum ipsum. - -:icons!: - -ifdef::backend-xhtml11[] -:imagesdir: ../../images -:data-uri: -image:smallnew.png[NEW] 'testing' `123`. - -endif::[] - -:data-uri!: - -=== Inline images - -:imagesdir: ../../images - -Inline image image:smallnew.png[] - -Inline image image:smallnew.png[NEW!] - -Inline image image:smallnew.png["NEW!",title="Small new"] - - -== Admonishments - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -// With icon images. -:icons: -:iconsdir: ../../images/icons - -NOTE: Lorum ipsum. - -TIP: Lorum ipsum. - -WARNING: Lorum ipsum. - -CAUTION: Lorum ipsum. - -IMPORTANT: Lorum ipsum. - -:icons!: - -== Backslash escapes - -.Apostrophe -Don't vs don\'t. - -.Exceptions -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%",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\... -|======================================== - - -== Paragraphs - -.Normal paragraph -This is a *bold* a line -This is a 'strong' line -This is another _strong_ line - -.Literal paragraph -[literal] -This is a *bold* a line -This is a 'strong' line -This is another _strong_ line - -.Verse paragraph -[verse] -This is a *bold* a line -This is a 'strong' line -This is another _strong_ line - -.Indented (literal) paragraph - This is a *bold* a line - This is a 'strong' line - This is another _strong_ line - -.Indented with quotes substitution -[subs="quotes"] - This is a *bold* a line - This is a 'strong' line - This is another _strong_ line - -.Literal paragraph with quotes substitution -["literal",subs="quotes"] -This is a *bold* a line -This is a 'strong' line -This is another _strong_ line - -ifndef::basebackend-docbook[] -.Monospaced paragraph with line breaks -+This is a *bold* line+ + -+This is a 'strong' line+ + -+This is another _strong_ line+ - - -.Another monospaced paragraph with line breaks -+This is a *bold* a line + -This is a 'strong' line + -This is another _strong_ line+ - -endif::basebackend-docbook[] - -.Literal block with quotes substitution -[subs="quotes"] -............................. -This is a *bold* a line -This is a 'strong' line -This is another _strong_ line -............................. - -[verse, William Blake, from Auguries of Innocence] -To see a world in a grain of sand, -And a heaven in a wild flower, -Hold infinity in the palm of your hand, -And eternity in an hour. - -[quote, Bertrand Russell, The World of Mathematics (1956)] -A good notation has subtlety and suggestiveness which at times makes -it almost seem like a live teacher. - - -URLs ----- -Mail Addresses -~~~~~~~~~~~~~~ -joe_bloggs@mail_server.com_ - -joe-bloggs@mail-server.com. - -joe-bloggs@mail-server.com,joe-bloggs@mail-server.com, - -mailto:joe-bloggs@mail-server.com[Mail] - -mailto:joe_bloggs@mail_server.com[Mail] - -mailto:joe.bloggs@mail.server.com[Mail] - -joe.bloggs@mail.server.com + -lorum ipsum. - - -Comments --------- -///////////////////////////////////////////////////////////////////// -A comment -block. -///////////////////////////////////////////////////////////////////// - -// This is a comment line. - -Qui in magna commodo, est labitur dolorum an. Est ne magna primis. -// Inline comment line. -adolescens. Sit munere ponderum dignissim et. Minim luptatum et. - -:showcomments: -// This comment line will be displayed in the output. - -Qui in magna commodo, est labitur dolorum an. Est ne magna primis. -// Visible inline comment line. -adolescens. Sit munere ponderum dignissim et. Minim luptatum et. - -///////////////////////////////////////////////////////////////////// -Comment blocks are never displayed in the output. -///////////////////////////////////////////////////////////////////// - -:showcomments!: - -[[comment_macro]] -.Block title -// Block macro comment does not consume titles or attributes. -Lorum ipsum. - -[[comment_block]] -.Block title -///////////////////////////////////////////////////////////////////// -Delimited comment block does not consume titles or attributes. -///////////////////////////////////////////////////////////////////// -Lorum ipsum. - - -ifdef::basebackend-docbook[] -[glossary] -List of terms -------------- -Using positional attribute to specify section template. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - -[template="glossary"] -List of terms -------------- -Using named 'template' attribute to specify section template. - -[glossary] -A glossary term:: - The corresponding (indented) definition. - -A second glossary term:: - The corresponding (indented) definition. - -endif::basebackend-docbook[] - -Index Terms ------------ -Test 1 ((test1)). - -Test 2 (((test2))). - -Test 3 (((test3,secondary))). - -Test 4 (((test4,secondary,tertiary))). - -Test 5 indexterm2:[test5]. - -Test 6 indexterm:[test6]. - -Test 7 indexterm:[test7,secondary]. - -Test 8 indexterm:[test8,secondary,tertiary]. - -Multi-passthough substitution (see -http://groups.google.com/group/asciidoc/browse_frm/thread/1269dc2feb1a482c) -((`foo`)) -(((foo,`bar`))) -(((foo,`bar`,`two`))) - -Table with fractional column width units ----------------------------------------- -NOTE: 'pagewidth' and 'pageunits' only apply to DocBook outputs. - -:miscellaneous.pagewidth: 17.5 -:miscellaneous.pageunits: cm - -.Horizontal and vertical source data -[width="50%",cols="3,^2,^2,10",options="header"] -|========================================================= -|Date |Duration |Avg HR |Notes - -|22-Aug-08 |10:24 | 157 | -Worked out MSHR (max sustainable heart rate) by going hard -for this interval. - -|22-Aug-08 |23:03 | 152 | -Back-to-back with previous interval. - -|24-Aug-08 |40:00 | 145 | -Moderately hard interspersed with 3x 3min intervals (2min -hard + 1min really hard taking the HR up to 160). - -|========================================================= - -== Table with parent configuration file and header attribute entry - -[cols="asciidoc"] -|==== -| -- Attribute entry from header: {test-attribute} -- Replacement from `testcases.conf` configuration file: test-replacement -|==== - -== Table column specifiers with merged cells -See -http://groups.google.com/group/asciidoc/browse_thread/thread/c9238380a1f2507a - -[cols="<1m,>1,^1s, ^1e"] -|============================================ - .2+| .2+|1- A 2+|2- B - |i- a |ii- b - |Values 1 |v1 |v2 |v3 - |Values 2 |v4 |v5 |v6 -|============================================ - -Floating tables and images --------------------------- -.Simple table -[float="left",width="15%",floatstyle="[htbp]"] -|======= -|1 |2 |A -|3 |4 |B -|5 |6 |C -|======= - -.Tiger -[float="right",floatstyle="[htbp]"] -image::images/tiger.png["Tiger image"] - -unfloat::[] - -Section level offsets ---------------------- -At level 1 - -:leveloffset: -1 -Section title -^^^^^^^^^^^^^ -At level 2 - -:leveloffset: 0 -Section title -~~~~~~~~~~~~~ -At level 2 - -:leveloffset: 2 -Section title -------------- -At level 3 - -:leveloffset!: -:numbered!: - -Section level offsets ---------------------- -At level 1 - -Single-quoted attributes ------------------------- -[quote,'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]'] -_____________________________________________________________________ -Sir, a woman's preaching is like a dog's walking on his hind legs. It -is not done well; but you are surprised to find it done at all. -_____________________________________________________________________ - -["quote","'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]'"] -_____________________________________________________________________ -Sir, a woman's preaching is like a dog's walking on his hind legs. It -is not done well; but you are surprised to find it done at all. -_____________________________________________________________________ - -Footnotes ---------- -Qui in magna commodo, est labitur dolorum an. Est ne magna primis -adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. -footnote:[footnote one. -Qui in magna commodo, est labitur dolorum an. Est ne magna primis -adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. -Qui in magna commodo, est labitur dolorum an. Est ne magna primis -adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel.] -Qui in magna commodo, est labitur dolorum an. Est ne magna primis -adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. -footnoteref:["F2","footnote two. -Qui in magna commodo, est labitur dolorum an. Est ne magna primis -adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel."] -Qui in magna commodo, est labitur dolorum an. Est ne magna primis -adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel -footnoteref:[F2]. -Qui in magna commodo, est labitur dolorum an. Est ne magna primis -adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. -footnote:[https://asciidoc.org/ Qui in magna commodo, -est labitur dolorum an. Est ne magna primis adolescens. Sit munere -ponderum dignissim et. Minim luptatum et vel -image:images/smallnew.png[]] -Qui in magna commodo, est labitur dolorum an. Est ne magna primis -adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. -footnote:[https://asciidoc.org/] -Qui in magna commodo, est labitur dolorum an. Est ne magna primis -adolescens. Sit munere ponderum dignissim et. Minim luptatum et -vel footnote:[https://asciidoc.org/[AsciiDoc website].]. -Qui in magna commodo, est labitur dolorum an. Est ne magna primis -adolescens. Sit munere ponderum dignissim et. Minim luptatum et -footnoteref:[F3,A footnote, "with an image" -image:images/smallnew.png[]]. -footnote:[With [square brackets\]] Qui in magna commodo, est labitur -dolorum an. Est ne magna primis. - - -Rulers and page breaks ----------------------- - -Lorum ipsum... - -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -Lorum ipsum... - -<<< - -Lorum ipsum... - - -这是一个测试 ------------- -Double-with character titles. -<<_这是一个测试,link to auto-generated section ID>>. - - -ifdef::backend-html5[] -HTML 5 audio and video block macros ------------------------------------ -audio::images/example.ogg[] - -.Audio tag test -audio::images/example.ogg[] - -video::images/gizmo.ogv[width=200,options="nocontrols,autoplay"] - -.Example video -video::images/gizmo.ogv[] - -video::http://www.808.dk/pics/video/gizmo.ogv[] - -++++ - - - -++++ - -endif::backend-html5[] - - -== Block macros - -:rs458: 2 - -ifeval::[{rs458}==2] -RS458 is 2. -endif::[] -ifeval::[not ({rs458}==2)] -This will not be processed. -endif::[] - -// Test eval block macro. -eval::[Section.setlevel(1)] - -// Test template concatenation. -{template:test-template} - -// Test ascii-ids attribute. -:ascii-ids: -== àn îd without accénts -Lorum ipsum... - -:ascii-ids!: -== àn îd with accénts -Lorum ipsum... - - -== Inline macros -http://groups.google.com/group/asciidoc/[A URL with [square -brackets\]]. - -== Equation -.Equation -[latexmath] -[floatstyle="[htbp]"] -++++++++++++++++++++++++++++++++++++++++++++ -\[C = \alpha + \beta Y^{\gamma} + \epsilon\] -++++++++++++++++++++++++++++++++++++++++++++ - -== Example -.Example -[floatstyle="[htbp]"] -++++++++++++++++++++++++++++++++++++++++++++ -Formal figures, tables, equations and examples can float in docbook backend -++++++++++++++++++++++++++++++++++++++++++++ diff --git a/tests/data/utf8-bom-test.txt b/tests/data/utf8-bom-test.txt deleted file mode 100644 index 09da3a2..0000000 --- a/tests/data/utf8-bom-test.txt +++ /dev/null @@ -1,9 +0,0 @@ -UTF-8 BOM Test -============== - -Include file with UTF-8 BOM: - -:leveloffset: 1 -include::{docname}.txt[depth=1] - -Lorum ipsum... diff --git a/tests/data/utf8-examples.txt b/tests/data/utf8-examples.txt deleted file mode 100644 index 0358f24..0000000 --- a/tests/data/utf8-examples.txt +++ /dev/null @@ -1,217 +0,0 @@ -UTF-8 encoded sample plain-text file -==================================== - -Markus Kuhn [ˈmaʳkʊs kuːn] — 2002-07-25 - - -The ASCII compatible UTF-8 encoding used in this plain-text file -is defined in Unicode, ISO 10646-1, and RFC 2279. - - -Using Unicode/UTF-8, you can write in emails and source code things such as - -== Mathematics and sciences - - ∮ E⋅da = Q, n → ∞, ∑ f(i) = ∏ g(i), ⎧⎡⎛┌─────┐⎞⎤⎫ - ⎪⎢⎜│a²+b³ ⎟⎥⎪ - ∀x∈ℝ: ⌈x⌉ = −⌊−x⌋, α ∧ ¬β = ¬(¬α ∨ β), ⎪⎢⎜│───── ⎟⎥⎪ - ⎪⎢⎜⎷ c₈ ⎟⎥⎪ - ℕ ⊆ ℕ₀ ⊂ ℤ ⊂ ℚ ⊂ ℝ ⊂ ℂ, ⎨⎢⎜ ⎟⎥⎬ - ⎪⎢⎜ ∞ ⎟⎥⎪ - ⊥ < a ≠ b ≡ c ≤ d ≪ ⊤ ⇒ (⟦A⟧ ⇔ ⟪B⟫), ⎪⎢⎜ ⎲ ⎟⎥⎪ - ⎪⎢⎜ ⎳aⁱ-bⁱ⎟⎥⎪ - 2H₂ + O₂ ⇌ 2H₂O, R = 4.7 kΩ, ⌀ 200 mm ⎩⎣⎝i=1 ⎠⎦⎭ - - -== Linguistics and dictionaries - -ði ıntəˈnæʃənəl fəˈnɛtık əsoʊsiˈeıʃn + -Y [ˈʏpsilɔn], Yen [jɛn], Yoga [ˈjoːgɑ] - - -== APL - - ((V⍳V)=⍳⍴V)/V←,V ⌷←⍳→⍴∆∇⊃‾⍎⍕⌈ - - -== Nicer typography in plain text files - -- ‘single’ and “double” quotes -- Curly apostrophes: “We’ve been here” -- ‚deutsche‘ „Anführungszeichen“ -- †, ‡, ‰, •, 3–4, —, −5/+5, ™, … -- ASCII safety test: 1lI|, 0OD, 8B -- the euro symbol: 14.95 € - - -== Combining characters - -STARGΛ̊TE SG-1, a = v̇ = r̈, a⃑ ⊥ b⃑ - -== Greek (in Polytonic) - -[verse, The Greek anthem] -________________________________ -Σὲ γνωρίζω ἀπὸ τὴν κόψη -τοῦ σπαθιοῦ τὴν τρομερή, -σὲ γνωρίζω ἀπὸ τὴν ὄψη -ποὺ μὲ βία μετράει τὴ γῆ. - -᾿Απ᾿ τὰ κόκκαλα βγαλμένη -τῶν ῾Ελλήνων τὰ ἱερά -καὶ σὰν πρῶτα ἀνδρειωμένη -χαῖρε, ὦ χαῖρε, ᾿Ελευθεριά! -________________________________ - -[verse,From a speech of Demosthenes in the 4th century BC] -______________________________________________________________ -Οὐχὶ ταὐτὰ παρίσταταί μοι γιγνώσκειν, ὦ ἄνδρες ᾿Αθηναῖοι, -ὅταν τ᾿ εἰς τὰ πράγματα ἀποβλέψω καὶ ὅταν πρὸς τοὺς -λόγους οὓς ἀκούω· τοὺς μὲν γὰρ λόγους περὶ τοῦ -τιμωρήσασθαι Φίλιππον ὁρῶ γιγνομένους, τὰ δὲ πράγματ᾿ -εἰς τοῦτο προήκοντα, ὥσθ᾿ ὅπως μὴ πεισόμεθ᾿ αὐτοὶ -πρότερον κακῶς σκέψασθαι δέον. οὐδέν οὖν ἄλλο μοι δοκοῦσιν -οἱ τὰ τοιαῦτα λέγοντες ἢ τὴν ὑπόθεσιν, περὶ ἧς βουλεύεσθαι, -οὐχὶ τὴν οὖσαν παριστάντες ὑμῖν ἁμαρτάνειν. ἐγὼ δέ, ὅτι μέν -ποτ᾿ ἐξῆν τῇ πόλει καὶ τὰ αὑτῆς ἔχειν ἀσφαλῶς καὶ Φίλιππον -τιμωρήσασθαι, καὶ μάλ᾿ ἀκριβῶς οἶδα· ἐπ᾿ ἐμοῦ γάρ, οὐ πάλαι -γέγονεν ταῦτ᾿ ἀμφότερα· νῦν μέντοι πέπεισμαι τοῦθ᾿ ἱκανὸν -προλαβεῖν ἡμῖν εἶναι τὴν πρώτην, ὅπως τοὺς συμμάχους -σώσομεν. ἐὰν γὰρ τοῦτο βεβαίως ὑπάρξῃ, τότε καὶ περὶ τοῦ -τίνα τιμωρήσεταί τις καὶ ὃν τρόπον ἐξέσται σκοπεῖν· πρὶν δὲ -τὴν ἀρχὴν ὀρθῶς ὑποθέσθαι, μάταιον ἡγοῦμαι περὶ τῆς -τελευτῆς ὁντινοῦν ποιεῖσθαι λόγον. - -Δημοσθένους, Γ´ ᾿Ολυνθιακὸς -______________________________________________________________ - - -== Georgian: - -.From a Unicode conference invitation -გთხოვთ ახლავე გაიაროთ რეგისტრაცია Unicode-ის მეათე საერთაშორისო -კონფერენციაზე დასასწრებად, რომელიც გაიმართება 10-12 მარტს, -ქ. მაინცში, გერმანიაში. კონფერენცია შეჰკრებს ერთად მსოფლიოს -ექსპერტებს ისეთ დარგებში როგორიცაა ინტერნეტი და Unicode-ი, -ინტერნაციონალიზაცია და ლოკალიზაცია, Unicode-ის გამოყენება -ოპერაციულ სისტემებსა, და გამოყენებით პროგრამებში, შრიფტებში, -ტექსტების დამუშავებასა და მრავალენოვან კომპიუტერულ სისტემებში. - - -== Russian - -.From a Unicode conference invitation -Зарегистрируйтесь сейчас на Десятую Международную Конференцию по -Unicode, которая состоится 10-12 марта 1997 года в Майнце в Германии. -Конференция соберет широкий круг экспертов по вопросам глобального -Интернета и Unicode, локализации и интернационализации, воплощению и -применению Unicode в различных операционных системах и программных -приложениях, шрифтах, верстке и многоязычных компьютерных системах. - - -== Thai (UCS Level 2) - -Excerpt from a poetry on The Romance of The Three Kingdoms (a Chinese -classic 'San Gua'): - - [----------------------------|------------------------] - ๏ แผ่นดินฮั่นเสื่อมโทรมแสนสังเวช พระปกเกศกองบู๊กู้ขึ้นใหม่ - สิบสองกษัตริย์ก่อนหน้าแลถัดไป สององค์ไซร้โง่เขลาเบาปัญญา - ทรงนับถือขันทีเป็นที่พึ่ง บ้านเมืองจึงวิปริตเป็นนักหนา - โฮจิ๋นเรียกทัพทั่วหัวเมืองมา หมายจะฆ่ามดชั่วตัวสำคัญ - เหมือนขับไสไล่เสือจากเคหา รับหมาป่าเข้ามาเลยอาสัญ - ฝ่ายอ้องอุ้นยุแยกให้แตกกัน ใช้สาวนั้นเป็นชนวนชื่นชวนใจ - พลันลิฉุยกุยกีกลับก่อเหตุ ช่างอาเพศจริงหนาฟ้าร้องไห้ - ต้องรบราฆ่าฟันจนบรรลัย ฤๅหาใครค้ำชูกู้บรรลังก์ ฯ - -(The above is a two-column text. If combining characters are handled -correctly, the lines of the second column should be aligned with the -| character above.) - - -== Ethiopian - -.Proverbs in the Amharic language -[verse] -ሰማይ አይታረስ ንጉሥ አይከሰስ። -ብላ ካለኝ እንደአባቴ በቆመጠኝ። -ጌጥ ያለቤቱ ቁምጥና ነው። -ደሀ በሕልሙ ቅቤ ባይጠጣ ንጣት በገደለው። -የአፍ ወለምታ በቅቤ አይታሽም። -አይጥ በበላ ዳዋ ተመታ። -ሲተረጉሙ ይደረግሙ። -ቀስ በቀስ፥ ዕንቁላል በእግሩ ይሄዳል። -ድር ቢያብር አንበሳ ያስር። -ሰው እንደቤቱ እንጅ እንደ ጉረቤቱ አይተዳደርም። -እግዜር የከፈተውን ጉሮሮ ሳይዘጋው አይድርም። -የጎረቤት ሌባ፥ ቢያዩት ይስቅ ባያዩት ያጠልቅ። -ሥራ ከመፍታት ልጄን ላፋታት። -ዓባይ ማደሪያ የለው፥ ግንድ ይዞ ይዞራል። -የእስላም አገሩ መካ የአሞራ አገሩ ዋርካ። -ተንጋሎ ቢተፉ ተመልሶ ባፉ። -ወዳጅህ ማር ቢሆን ጨርስህ አትላሰው። -እግርህን በፍራሽህ ልክ ዘርጋ። - - -== Runes - -ᚻᛖ ᚳᚹᚫᚦ ᚦᚫᛏ ᚻᛖ ᛒᚢᛞᛖ ᚩᚾ ᚦᚫᛗ ᛚᚪᚾᛞᛖ ᚾᚩᚱᚦᚹᛖᚪᚱᛞᚢᛗ ᚹᛁᚦ ᚦᚪ ᚹᛖᛥᚫ - -(Old English, which transcribed into Latin reads ``He cwaeth that he -bude thaem lande northweardum with tha Westsae.'' and means ``He said -that he lived in the northern land near the Western Sea.'') - - -== Braille - - ⡌⠁⠧⠑ ⠼⠁⠒ ⡍⠜⠇⠑⠹⠰⠎ ⡣⠕⠌ - - ⡍⠜⠇⠑⠹ ⠺⠁⠎ ⠙⠑⠁⠙⠒ ⠞⠕ ⠃⠑⠛⠔ ⠺⠊⠹⠲ ⡹⠻⠑ ⠊⠎ ⠝⠕ ⠙⠳⠃⠞ - ⠱⠁⠞⠑⠧⠻ ⠁⠃⠳⠞ ⠹⠁⠞⠲ ⡹⠑ ⠗⠑⠛⠊⠌⠻ ⠕⠋ ⠙⠊⠎ ⠃⠥⠗⠊⠁⠇ ⠺⠁⠎ - ⠎⠊⠛⠝⠫ ⠃⠹ ⠹⠑ ⠊⠇⠻⠛⠹⠍⠁⠝⠂ ⠹⠑ ⠊⠇⠻⠅⠂ ⠹⠑ ⠥⠝⠙⠻⠞⠁⠅⠻⠂ - ⠁⠝⠙ ⠹⠑ ⠡⠊⠑⠋ ⠍⠳⠗⠝⠻⠲ ⡎⠊⠗⠕⠕⠛⠑ ⠎⠊⠛⠝⠫ ⠊⠞⠲ ⡁⠝⠙ - ⡎⠊⠗⠕⠕⠛⠑⠰⠎ ⠝⠁⠍⠑ ⠺⠁⠎ ⠛⠕⠕⠙ ⠥⠏⠕⠝ ⠰⡡⠁⠝⠛⠑⠂ ⠋⠕⠗ ⠁⠝⠹⠹⠔⠛ ⠙⠑ - ⠡⠕⠎⠑ ⠞⠕ ⠏⠥⠞ ⠙⠊⠎ ⠙⠁⠝⠙ ⠞⠕⠲ - - ⡕⠇⠙ ⡍⠜⠇⠑⠹ ⠺⠁⠎ ⠁⠎ ⠙⠑⠁⠙ ⠁⠎ ⠁ ⠙⠕⠕⠗⠤⠝⠁⠊⠇⠲ - - ⡍⠔⠙⠖ ⡊ ⠙⠕⠝⠰⠞ ⠍⠑⠁⠝ ⠞⠕ ⠎⠁⠹ ⠹⠁⠞ ⡊ ⠅⠝⠪⠂ ⠕⠋ ⠍⠹ - ⠪⠝ ⠅⠝⠪⠇⠫⠛⠑⠂ ⠱⠁⠞ ⠹⠻⠑ ⠊⠎ ⠏⠜⠞⠊⠊⠥⠇⠜⠇⠹ ⠙⠑⠁⠙ ⠁⠃⠳⠞ - ⠁ ⠙⠕⠕⠗⠤⠝⠁⠊⠇⠲ ⡊ ⠍⠊⠣⠞ ⠙⠁⠧⠑ ⠃⠑⠲ ⠔⠊⠇⠔⠫⠂ ⠍⠹⠎⠑⠇⠋⠂ ⠞⠕ - ⠗⠑⠛⠜⠙ ⠁ ⠊⠕⠋⠋⠔⠤⠝⠁⠊⠇ ⠁⠎ ⠹⠑ ⠙⠑⠁⠙⠑⠌ ⠏⠊⠑⠊⠑ ⠕⠋ ⠊⠗⠕⠝⠍⠕⠝⠛⠻⠹ - ⠔ ⠹⠑ ⠞⠗⠁⠙⠑⠲ ⡃⠥⠞ ⠹⠑ ⠺⠊⠎⠙⠕⠍ ⠕⠋ ⠳⠗ ⠁⠝⠊⠑⠌⠕⠗⠎ - ⠊⠎ ⠔ ⠹⠑ ⠎⠊⠍⠊⠇⠑⠆ ⠁⠝⠙ ⠍⠹ ⠥⠝⠙⠁⠇⠇⠪⠫ ⠙⠁⠝⠙⠎ - ⠩⠁⠇⠇ ⠝⠕⠞ ⠙⠊⠌⠥⠗⠃ ⠊⠞⠂ ⠕⠗ ⠹⠑ ⡊⠳⠝⠞⠗⠹⠰⠎ ⠙⠕⠝⠑ ⠋⠕⠗⠲ ⡹⠳ - ⠺⠊⠇⠇ ⠹⠻⠑⠋⠕⠗⠑ ⠏⠻⠍⠊⠞ ⠍⠑ ⠞⠕ ⠗⠑⠏⠑⠁⠞⠂ ⠑⠍⠏⠙⠁⠞⠊⠊⠁⠇⠇⠹⠂ ⠹⠁⠞ - ⡍⠜⠇⠑⠹ ⠺⠁⠎ ⠁⠎ ⠙⠑⠁⠙ ⠁⠎ ⠁ ⠙⠕⠕⠗⠤⠝⠁⠊⠇⠲ - -(The first couple of paragraphs of "A Christmas Carol" by Dickens) - - -== Compact font selection example text - - ABCDEFGHIJKLMNOPQRSTUVWXYZ /0123456789 - abcdefghijklmnopqrstuvwxyz £©µÀÆÖÞßéöÿ - –—‘“”„†•…‰™œŠŸž€ ΑΒΓΔΩαβγδω АБВГДабвгд - ∀∂∈ℝ∧∪≡∞ ↑↗↨↻⇣ ┐┼╔╘░►☺♀ fi�⑀₂ἠḂӥẄɐː⍎אԱა - - -== Greetings in various languages - -Hello world, Καλημέρα κόσμε, コンニチハ - - -== Box drawing alignment tests - ---------------------------------------------------------------------- - █ - ▉ - ╔══╦══╗ ┌──┬──┐ ╭──┬──╮ ╭──┬──╮ ┏━━┳━━┓ ┎┒┏┑ ╷ ╻ ┏┯┓ ┌┰┐ ▊ ╱╲╱╲╳╳╳ - ║┌─╨─┐║ │╔═╧═╗│ │╒═╪═╕│ │╓─╁─╖│ ┃┌─╂─┐┃ ┗╃╄┙ ╶┼╴╺╋╸┠┼┨ ┝╋┥ ▋ ╲╱╲╱╳╳╳ - ║│╲ ╱│║ │║ ║│ ││ │ ││ │║ ┃ ║│ ┃│ ╿ │┃ ┍╅╆┓ ╵ ╹ ┗┷┛ └┸┘ ▌ ╱╲╱╲╳╳╳ - ╠╡ ╳ ╞╣ ├╢ ╟┤ ├┼─┼─┼┤ ├╫─╂─╫┤ ┣┿╾┼╼┿┫ ┕┛┖┚ ┌┄┄┐ ╎ ┏┅┅┓ ┋ ▍ ╲╱╲╱╳╳╳ - ║│╱ ╲│║ │║ ║│ ││ │ ││ │║ ┃ ║│ ┃│ ╽ │┃ ░░▒▒▓▓██ ┊ ┆ ╎ ╏ ┇ ┋ ▎ - ║└─╥─┘║ │╚═╤═╝│ │╘═╪═╛│ │╙─╀─╜│ ┃└─╂─┘┃ ░░▒▒▓▓██ ┊ ┆ ╎ ╏ ┇ ┋ ▏ - ╚══╩══╝ └──┴──┘ ╰──┴──╯ ╰──┴──╯ ┗━━┻━━┛ ▗▄▖▛▀▜ └╌╌┘ ╎ ┗╍╍┛ ┋ ▁▂▃▄▅▆▇█ - ▝▀▘▙▄▟ ---------------------------------------------------------------------- diff --git a/tests/inputs/article-docinfo.xml b/tests/inputs/article-docinfo.xml new file mode 100644 index 0000000..b4f9d18 --- /dev/null +++ b/tests/inputs/article-docinfo.xml @@ -0,0 +1,87 @@ + + + + + Dr + Lois + Common-Denominator + + Director, M. Behn School of Coop. Eng. + Director of Cooperative Efforts + The Marguerite Behn International School of + Cooperative Engineering + + + + + Mr + Steven + Norman + T + + ATI + Senior Application Analyst + Foobar, Inc. + Application Development + + + + + Peter + Pan + Sr. + Spiderman + + + Peter's a super hero in his spare time. + + + + + + + 2009 + Behn International + + + + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + + + + + 1.1 + May 2009 + PP + + Updates. + + + + 1.0 + October 2003 + PP + + First release. + + + diff --git a/tests/inputs/article.txt b/tests/inputs/article.txt new file mode 100644 index 0000000..9a9cc50 --- /dev/null +++ b/tests/inputs/article.txt @@ -0,0 +1,139 @@ +The Article Title +================= +Author's Name +v1.0, 2003-12 + + +This is the optional preamble (an untitled section body). Useful for +writing simple sectionless documents consisting only of a preamble. + +NOTE: The abstract, preface, appendix, bibliography, glossary and +index section titles are significant ('specialsections'). + + +:numbered!: +[abstract] +Example Abstract +---------------- +The optional abstract (one or more paragraphs) goes here. + +This document is an AsciiDoc article skeleton containing briefly +annotated element placeholders plus a couple of example index entries +and footnotes. + +:numbered: + +The First Section +----------------- +Article sections start at level 1 and can be nested up to four levels +deep. +footnote:[An example footnote.] +indexterm:[Example index entry] + +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. + +A Nested Sub-section +^^^^^^^^^^^^^^^^^^^^ +Sub-section at level 3. + +Yet another nested 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 Section +------------------ +Article sections are at level 1 and can contain sub-sections nested up +to four deep. + +An example link to anchor at start of the <>. +indexterm:[Second example index entry] + +An example link to a bibliography entry <>. + + +:numbered!: + +[appendix] +Example Appendix +---------------- +AsciiDoc article appendices are just just article sections with +'specialsection' titles. + +Appendix Sub-section +~~~~~~~~~~~~~~~~~~~~ +Appendix sub-section at level 2. + + +[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. + + +ifdef::backend-docbook[] +[index] +Example Index +------------- +//////////////////////////////////////////////////////////////// +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::backend-docbook[] diff --git a/tests/inputs/ascii-ids1.txt b/tests/inputs/ascii-ids1.txt new file mode 100644 index 0000000..67958c4 --- /dev/null +++ b/tests/inputs/ascii-ids1.txt @@ -0,0 +1,9 @@ +// Test of generated chapter ID normalized to ASCII +:ascii-ids: 1 + +== Wstęp żółtej łąki + +== schön Grüßen + +== Белые Мотыль + diff --git a/tests/inputs/asciidoc.1.txt b/tests/inputs/asciidoc.1.txt new file mode 100644 index 0000000..8861151 --- /dev/null +++ b/tests/inputs/asciidoc.1.txt @@ -0,0 +1,237 @@ +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 +--------- +GitHub: + +Main web site: + + +SEE ALSO +-------- +a2x(1) + + +COPYING +------- +Copyright \(C) 2002-2013 Stuart Rackham. + +Copyright \(C) 2013-2020 AsciiDoc Contributors. + +Free use of this software is granted under the terms of the GNU General +Public License version 2 (GPLv2). + diff --git a/tests/inputs/asciidoc.conf b/tests/inputs/asciidoc.conf new file mode 100644 index 0000000..bf8b9ce --- /dev/null +++ b/tests/inputs/asciidoc.conf @@ -0,0 +1,7 @@ +# +# Customization for AsciiDoc documentation. +# +[specialwords] +ifndef::doctype-manpage[] +monospacedwords=\\?\basciidoc\(1\) \\?\ba2x\(1\) +endif::doctype-manpage[] diff --git a/tests/inputs/asciidoc.txt b/tests/inputs/asciidoc.txt new file mode 100644 index 0000000..0721022 --- /dev/null +++ b/tests/inputs/asciidoc.txt @@ -0,0 +1,6096 @@ +AsciiDoc User Guide +=================== +AsciiDoc.py Team +:toc: +:icons: +:numbered: +:website: https://asciidoc.org/ + +AsciiDoc is a text document format for writing notes, documentation, +articles, books, ebooks, slideshows, web pages, blogs and UNIX man +pages. AsciiDoc files can be translated to many formats including +HTML, PDF, EPUB, man page. AsciiDoc is highly configurable: both the +AsciiDoc source file syntax and the backend output markups (which can +be almost any type of SGML/XML markup) can be customized and extended +by the user. + +[WARNING] +This user guide is for AsciiDoc.py, which is a legacy processor for +this syntax, handling an older rendition of AsciiDoc. As such, this +will not properly handle the +https://projects.eclipse.org/projects/technology.asciidoc[current AsciiDoc specification]. +It is suggested that unless you specifically require the AsciiDoc.py +toolchain, you should find a processor that handles the modern +AsciiDoc syntax. + +.This document +********************************************************************** +This is an overly large document, it probably needs to be refactored +into a Tutorial, Quick Reference and Formal Reference. + +If you're new to AsciiDoc read this section and the <> section and take a look at the example AsciiDoc (`*.txt`) +source files in the distribution `doc` directory. +********************************************************************** + + +Introduction +------------ +AsciiDoc is a plain text human readable/writable document format that +can be translated to DocBook or HTML using the asciidoc(1) command. +You can then either use asciidoc(1) generated HTML directly or run +asciidoc(1) DocBook output through your favorite DocBook toolchain or +use the AsciiDoc a2x(1) toolchain wrapper to produce PDF, EPUB, DVI, +LaTeX, PostScript, man page, HTML and text formats. + +The AsciiDoc format is a useful presentation format in its own right: +AsciiDoc markup is simple, intuitive and as such is easily proofed and +edited. + +AsciiDoc is light weight: it consists of a single Python script and a +bunch of configuration files. Apart from asciidoc(1) and a Python +interpreter, no other programs are required to convert AsciiDoc text +files to DocBook or HTML. See <> +below. + +Text markup conventions tend to be a matter of (often strong) personal +preference: if the default syntax is not to your liking you can define +your own by editing the text based asciidoc(1) configuration files. +You can also create configuration files to translate AsciiDoc +documents to almost any SGML/XML markup. + +asciidoc(1) comes with a set of configuration files to translate +AsciiDoc articles, books and man pages to HTML or DocBook backend +formats. + +.My AsciiDoc Itch +********************************************************************** +DocBook has emerged as the de facto standard Open Source documentation +format. But DocBook is a complex language, the markup is difficult to +read and even more difficult to write directly -- I found I was +spending more time typing markup tags, consulting reference manuals +and fixing syntax errors, than I was writing the documentation. +********************************************************************** + + +[[X6]] +Getting Started +--------------- +Installing AsciiDoc +~~~~~~~~~~~~~~~~~~~ +See the `README` and `INSTALL` files for install prerequisites and +procedures. Packagers take a look at <>. + +[[X11]] +Example AsciiDoc Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~ +The best way to quickly get a feel for AsciiDoc is to view the +AsciiDoc web site and/or distributed examples: + +- Take a look at the linked examples on the AsciiDoc web site home + page {website}. Press the 'Page Source' sidebar menu item to view + corresponding AsciiDoc source. +- Read the `*.txt` source files in the distribution `./doc` directory + along with the corresponding HTML and DocBook XML files. + + +AsciiDoc Document Types +----------------------- +There are three types of AsciiDoc documents: article, book and +manpage. All document types share the same AsciiDoc format with some +minor variations. If you are familiar with DocBook you will have +noticed that AsciiDoc document types correspond to the same-named +DocBook document types. + +Use the asciidoc(1) `-d` (`--doctype`) option to specify the AsciiDoc +document type -- the default document type is 'article'. + +By convention the `.txt` file extension is used for AsciiDoc document +source files. + +article +~~~~~~~ +Used for short documents, articles and general documentation. See the +AsciiDoc distribution `./doc/article.txt` example. + +AsciiDoc defines standard DocBook article frontmatter and backmatter +<> (appendix, abstract, bibliography, +glossary, index). + +book +~~~~ +Books share the same format as articles, with the following +differences: + +- The part titles in multi-part books are <> + (same level as book title). +- Some sections are book specific e.g. preface and colophon. + +Book documents will normally be used to produce DocBook output since +DocBook processors can automatically generate footnotes, table of +contents, list of tables, list of figures, list of examples and +indexes. + +AsciiDoc defines standard DocBook book frontmatter and backmatter +<> (appendix, dedication, preface, +bibliography, glossary, index, colophon). + +.Example book documents +Book:: + The `./doc/book.txt` file in the AsciiDoc distribution. + +Multi-part book:: + The `./doc/book-multi.txt` file in the AsciiDoc distribution. + +manpage +~~~~~~~ +Used to generate roff format UNIX manual pages. AsciiDoc manpage +documents observe special header title and section naming conventions +-- see the <> section for details. + +AsciiDoc defines the 'synopsis' <> to +generate the DocBook `refsynopsisdiv` section. + +See also the asciidoc(1) man page source (`./doc/asciidoc.1.txt`) from +the AsciiDoc distribution. + + +[[X5]] +AsciiDoc Backends +----------------- +The asciidoc(1) command translates an AsciiDoc formatted file to the +backend format specified by the `-b` (`--backend`) command-line +option. asciidoc(1) itself has little intrinsic knowledge of backend +formats, all translation rules are contained in customizable cascading +configuration files. Backend specific attributes are listed in the +<> section. + +docbook45:: + Outputs DocBook XML 4.5 markup. + +docbook5:: + Outputs DocBook XML 5.0 markup. + +html4:: + This backend generates plain HTML 4.01 Transitional markup. + +xhtml11:: + This backend generates XHTML 1.1 markup styled with CSS2. Output + files have an `.html` extension. + +html5:: + This backend generates HTML 5 markup, apart from the inclusion of + <> it is functionally identical to + the 'xhtml11' backend. + +slidy:: + Use this backend to generate self-contained + https://www.w3.org/Talks/Tools/Slidy2[Slidy] HTML slideshows for + your web browser from AsciiDoc documents. The Slidy backend is + documented in the distribution `doc/slidy.txt` file and + {website}slidy.html[online]. + +wordpress:: + A minor variant of the 'html4' backend to support + https://srackham.wordpress.com/blogpost1/[blogpost]. + +latex:: + Experimental LaTeX backend. + +Backend Aliases +~~~~~~~~~~~~~~~ +Backend aliases are alternative names for AsciiDoc backends. AsciiDoc +comes with two backend aliases: 'html' (aliased to 'xhtml11') and +'docbook' (aliased to 'docbook45'). + +You can assign (or reassign) backend aliases by setting an AsciiDoc +attribute named like `backend-alias-` to an AsciiDoc backend +name. For example, the following backend alias attribute definitions +appear in the `[attributes]` section of the global `asciidoc.conf` +configuration file: + + backend-alias-html=xhtml11 + backend-alias-docbook=docbook45 + +[[X100]] +Backend Plugins +~~~~~~~~~~~~~~~ +The asciidoc(1) `--backend` option is also used to install and manage +backend <>. + +- A backend plugin is used just like the built-in backends. +- Backend plugins <> over built-in backends with + the same name. +- You can use the `{asciidoc-confdir}` <> to + refer to the built-in backend configuration file location from + backend plugin configuration files. +- You can use the `{backend-confdir}` <> to + refer to the backend plugin configuration file location. +- By default backends plugins are installed in + `$HOME/.asciidoc/backends/` where `` is the + backend name. + + +DocBook +------- +AsciiDoc generates 'article', 'book' and 'refentry' +https://docbook.org/[DocBook] documents (corresponding to the +AsciiDoc 'article', 'book' and 'manpage' document types). + +Most Linux distributions come with conversion tools (collectively +called a toolchain) for <> to +presentation formats such as Postscript, HTML, PDF, EPUB, DVI, +PostScript, LaTeX, roff (the native man page format), HTMLHelp, +JavaHelp and text. There are also programs that allow you to view +DocBook files directly, for example +https://wiki.gnome.org/action/show/Apps/Yelp[Yelp] (the GNOME help +viewer). + +[[X12]] +Converting DocBook to other file formats +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +DocBook files are validated, parsed and translated various +presentation file formats using a combination of applications +collectively called a DocBook 'tool chain'. The function of a tool +chain is to read the DocBook markup (produced by AsciiDoc) and +transform it to a presentation format (for example HTML, PDF, HTML +Help, EPUB, DVI, PostScript, LaTeX). + +A wide range of user output format requirements coupled with a choice +of available tools and stylesheets results in many valid tool chain +combinations. + +[[X43]] +a2x Toolchain Wrapper +~~~~~~~~~~~~~~~~~~~~~ +One of the biggest hurdles for new users is installing, configuring +and using a DocBook XML toolchain. `a2x(1)` can help -- it's a +toolchain wrapper command that will generate XHTML (chunked and +unchunked), PDF, EPUB, DVI, PS, LaTeX, man page, HTML Help and text +file outputs from an AsciiDoc text file. `a2x(1)` does all the grunt +work associated with generating and sequencing the toolchain commands +and managing intermediate and output files. `a2x(1)` also optionally +deploys admonition and navigation icons and a CSS stylesheet. See the +`a2x(1)` man page for more details. In addition to `asciidoc(1)` you +also need <>, <> and +optionally: <> or <> (to generate PDF); +`w3m(1)` or `lynx(1)` (to generate text). + +The following examples generate `doc/source-highlight-filter.pdf` from +the AsciiDoc `doc/source-highlight-filter.txt` source file. The first +example uses `dblatex(1)` (the default PDF generator) the second +example forces FOP to be used: + + $ a2x -f pdf doc/source-highlight-filter.txt + $ a2x -f pdf --fop doc/source-highlight-filter.txt + +See the `a2x(1)` man page for details. + +TIP: Use the `--verbose` command-line option to view executed +toolchain commands. + +HTML generation +~~~~~~~~~~~~~~~ +AsciiDoc produces nicely styled HTML directly without requiring a +DocBook toolchain but there are also advantages in going the DocBook +route: + +- HTML from DocBook can optionally include automatically generated + indexes, tables of contents, footnotes, lists of figures and tables. +- DocBook toolchains can also (optionally) generate separate (chunked) + linked HTML pages for each document section. +- Toolchain processing performs link and document validity checks. +- If the DocBook 'lang' attribute is set then things like table of + contents, figure and table captions and admonition captions will be + output in the specified language (setting the AsciiDoc 'lang' + attribute sets the DocBook 'lang' attribute). + +On the other hand, HTML output directly from AsciiDoc is much faster, +is easily customized and can be used in situations where there is no +suitable DocBook toolchain (for example, see the {website}[AsciiDoc +website]). + +PDF generation +~~~~~~~~~~~~~~ +There are two commonly used tools to generate PDFs from DocBook, +<> and <>. + +.dblatex or FOP? +- 'dblatex' is easier to install, there's zero configuration + required and no Java VM to install -- it just works out of the box. +- 'dblatex' source code highlighting and numbering is superb. +- 'dblatex' is easier to use as it converts DocBook directly to PDF + whereas before using 'FOP' you have to convert DocBook to XML-FO + using <>. +- 'FOP' is more feature complete (for example, callouts are processed + inside literal layouts) and arguably produces nicer looking output. + +HTML Help generation +~~~~~~~~~~~~~~~~~~~~ +. Convert DocBook XML documents to HTML Help compiler source files + using <> and <>. +. Convert the HTML Help source (`.hhp` and `.html`) files to HTML Help + (`.chm`) files using the <>. + +Toolchain components summary +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +AsciiDoc:: + Converts AsciiDoc (`.txt`) files to DocBook XML (`.xml`) files. + +[[X13]]https://github.com/docbook/xslt10-stylesheets[DocBook XSLT Stylesheets]:: + These are a set of XSL stylesheets containing rules for converting + DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files. + The stylesheets are used in conjunction with an XML parser such as + <>. + +[[X40]]http://www.xmlsoft.org[xsltproc]:: + An XML parser for applying XSLT stylesheets (in our case the + <>) to XML documents. + +[[X31]]http://dblatex.sourceforge.net/[dblatex]:: + Generates PDF, DVI, PostScript and LaTeX formats directly from + DocBook source via the intermediate LaTeX typesetting language -- + uses <>, <> and + `latex(1)`. + +[[X14]]https://xmlgraphics.apache.org/fop/[FOP]:: + The Apache Formatting Objects Processor converts XSL-FO (`.fo`) + files to PDF files. The XSL-FO files are generated from DocBook + source files using <> and + <>. + +[[X67]]Microsoft Help Compiler:: + The Microsoft HTML Help Compiler (`hhc.exe`) is a command-line tool + that converts HTML Help source files to a single HTML Help (`.chm`) + file. It runs on MS Windows platforms and can be downloaded from + https://www.microsoft.com/. + +AsciiDoc dblatex configuration files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The AsciiDoc distribution `./dblatex` directory contains +`asciidoc-dblatex.xsl` (customized XSL parameter settings) and +`asciidoc-dblatex.sty` (customized LaTeX settings). These are examples +of optional <> output customization and are used by +<>. + +AsciiDoc DocBook XSL Stylesheets drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You will have noticed that the distributed HTML and HTML Help +documentation files (for example `./doc/asciidoc.html`) are not the +plain outputs produced using the default 'DocBook XSL Stylesheets' +configuration. This is because they have been processed using +customized DocBook XSL Stylesheets along with (in the case of HTML +outputs) the custom `./stylesheets/docbook-xsl.css` CSS stylesheet. + +You'll find the customized DocBook XSL drivers along with additional +documentation in the distribution `./docbook-xsl` directory. The +examples that follow are executed from the distribution documentation +(`./doc`) directory. These drivers are also used by <>. + +`common.xsl`:: + Shared driver parameters. This file is not used directly but is + included in all the following drivers. + +`chunked.xsl`:: + Generate chunked XHTML (separate HTML pages for each document + section) in the `./doc/chunked` directory. For example: + + $ python ../asciidoc.py -b docbook asciidoc.txt + $ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml + +`epub.xsl`:: + Used by <> to generate EPUB formatted documents. + +`fo.xsl`:: + Generate XSL Formatting Object (`.fo`) files for subsequent PDF + file generation using FOP. For example: + + $ python ../asciidoc.py -b docbook article.txt + $ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo + $ fop article.fo article.pdf + +`htmlhelp.xsl`:: + Generate Microsoft HTML Help source files for the MS HTML Help + Compiler in the `./doc/htmlhelp` directory. This example is run on + MS Windows from a Cygwin shell prompt: + + $ python ../asciidoc.py -b docbook asciidoc.txt + $ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml + $ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp + +`manpage.xsl`:: + Generate a `roff(1)` format UNIX man page from a DocBook XML + 'refentry' document. This example generates an `asciidoc.1` man + page file: + + $ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt + $ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml + +`xhtml.xsl`:: + Convert a DocBook XML file to a single XHTML file. For example: + + $ python ../asciidoc.py -b docbook asciidoc.txt + $ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html + +If you want to see how the complete documentation set is processed +take a look at the A-A-P script `./doc/main.aap`. + + +Generating Plain Text Files +--------------------------- +AsciiDoc does not have a text backend (for most purposes AsciiDoc +source text is fine), however you can convert AsciiDoc text files to +formatted text using the AsciiDoc <> toolchain wrapper +utility. + + +[[X35]] +HTML5 and XHTML 1.1 +------------------- +The 'xhtml11' and 'html5' backends embed or link CSS and JavaScript +files in their outputs, there is also a <> plugin +framework. + +- If the AsciiDoc 'linkcss' attribute is defined then CSS and + JavaScript files are linked to the output document, otherwise they + are embedded (the default behavior). +- The default locations for CSS and JavaScript files can be changed by + setting the AsciiDoc 'stylesdir' and 'scriptsdir' attributes + respectively. +- The default locations for embedded and linked files differ and are + calculated at different times -- embedded files are loaded when + asciidoc(1) generates the output document, linked files are loaded + by the browser when the user views the output document. +- Embedded files are automatically inserted in the output files but + you need to manually copy linked CSS and Javascript files from + AsciiDoc <> to the correct location + relative to the output document. + +.Stylesheet file locations +[cols="3*",frame="topbot",options="header"] +|==================================================================== +|'stylesdir' attribute +|Linked location ('linkcss' attribute defined) +|Embedded location ('linkcss' attribute undefined) + +|Undefined (default). +|Same directory as the output document. +|`stylesheets` subdirectory in the AsciiDoc configuration directory +(the directory containing the backend conf file). + +|Absolute or relative directory name. +|Absolute or relative to the output document. +|Absolute or relative to the AsciiDoc configuration directory (the +directory containing the backend conf file). + +|==================================================================== + +.JavaScript file locations +[cols="3*",frame="topbot",options="header"] +|==================================================================== +|'scriptsdir' attribute +|Linked location ('linkcss' attribute defined) +|Embedded location ('linkcss' attribute undefined) + +|Undefined (default). +|Same directory as the output document. +|`javascripts` subdirectory in the AsciiDoc configuration directory +(the directory containing the backend conf file). + +|Absolute or relative directory name. +|Absolute or relative to the output document. +|Absolute or relative to the AsciiDoc configuration directory (the +directory containing the backend conf file). + +|==================================================================== + +[[X99]] +Themes +~~~~~~ +The AsciiDoc 'theme' attribute is used to select an alternative CSS +stylesheet and to optionally include additional JavaScript code. + +- Theme files reside in an AsciiDoc <> + named `themes//` (where `` is the the theme name set + by the 'theme' attribute). asciidoc(1) sets the 'themedir' attribute + to the theme directory path name. +- The 'theme' attribute can also be set using the asciidoc(1) + `--theme` option, the `--theme` option can also be used to manage + theme <>. +- AsciiDoc ships with two themes: 'flask' and 'volnitsky'. +- The `.css` file replaces the default `asciidoc.css` CSS file. +- The `.js` file is included in addition to the default + `asciidoc.js` JavaScript file. +- If the <> attribute is defined then icons are loaded + from the theme `icons` sub-directory if it exists (i.e. the + 'iconsdir' attribute is set to theme `icons` sub-directory path). +- Embedded theme files are automatically inserted in the output files + but you need to manually copy linked CSS and Javascript files to the + location of the output documents. +- Linked CSS and JavaScript theme files are linked to the same linked + locations as <>. + +For example, the command-line option `--theme foo` (or `--attribute +theme=foo`) will cause asciidoc(1) to search <> for a sub-directory called `themes/foo` +containing the stylesheet `foo.css` and optionally a JavaScript file +name `foo.js`. + + +Document Structure +------------------ +An AsciiDoc document consists of a series of <> +starting with an optional document Header, followed by an optional +Preamble, followed by zero or more document Sections. + +Almost any combination of zero or more elements constitutes a valid +AsciiDoc document: documents can range from a single sentence to a +multi-part book. + +Block Elements +~~~~~~~~~~~~~~ +Block elements consist of one or more lines of text and may contain +other block elements. + +The AsciiDoc block structure can be informally summarized as follows +footnote:[This is a rough structural guide, not a rigorous syntax +definition]: + + Document ::= (Header?,Preamble?,Section*) + Header ::= (Title,(AuthorInfo,RevisionInfo?)?) + AuthorInfo ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?) + RevisionInfo ::= (RevisionNumber?,RevisionDate,RevisionRemark?) + Preamble ::= (SectionBody) + Section ::= (Title,SectionBody?,(Section)*) + SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+ + Block ::= (Paragraph|DelimitedBlock|List|Table) + List ::= (BulletedList|NumberedList|LabeledList|CalloutList) + BulletedList ::= (ListItem)+ + NumberedList ::= (ListItem)+ + CalloutList ::= (ListItem)+ + LabeledList ::= (ListEntry)+ + ListEntry ::= (ListLabel,ListItem) + ListLabel ::= (ListTerm+) + ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*) + +Where: + +- '?' implies zero or one occurrence, '+' implies one or more + occurrences, '*' implies zero or more occurrences. +- All block elements are separated by line boundaries. +- `BlockId`, `AttributeEntry` and `AttributeList` block elements (not + shown) can occur almost anywhere. +- There are a number of document type and backend specific + restrictions imposed on the block syntax. +- The following elements cannot contain blank lines: Header, Title, + Paragraph, ItemText. +- A ListParagraph is a Paragraph with its 'listelement' option set. +- A ListContinuation is a <>. + +[[X95]] +Header +~~~~~~ +The Header contains document meta-data, typically title plus optional +authorship and revision information: + +- The Header is optional, but if it is used it must start with a + document <>. +- Optional Author and Revision information immediately follows the + header title. +- The document header must be separated from the remainder of the + document by one or more blank lines and cannot contain blank lines. +- The header can include comments. +- The header can include <>, typically + 'doctype', 'lang', 'encoding', 'icons', 'data-uri', 'toc', + 'numbered'. +- Header attributes are overridden by command-line attributes. +- If the header contains non-UTF-8 characters then the 'encoding' must + precede the header (either in the document or on the command-line). + +Here's an example AsciiDoc document header: + + Writing Documentation using AsciiDoc + ==================================== + Joe Bloggs + v2.0, February 2003: + Rewritten for version 2 release. + +The author information line contains the author's name optionally +followed by the author's email address. The author's name is formatted +like: + + firstname[ [middlename ]lastname][ ]] + +i.e. a first name followed by optional middle and last names followed +by an email address in that order. Multi-word first, middle and last +names can be entered using the underscore as a word separator. The +email address comes last and must be enclosed in angle <> brackets. +Here a some examples of author information lines: + + Joe Bloggs + Joe Bloggs + Vincent Willem van_Gogh + +If the author line does not match the above specification then the +entire author line is treated as the first name. + +The optional revision information line follows the author information +line. The revision information can be one of two formats: + +. An optional document revision number followed by an optional + revision date followed by an optional revision remark: ++ +-- + * If the revision number is specified it must be followed by a + comma. + * The revision number must contain at least one numeric character. + * Any non-numeric characters preceding the first numeric character + will be dropped. + * If a revision remark is specified it must be preceded by a colon. + The revision remark extends from the colon up to the next blank + line, attribute entry or comment and is subject to normal text + substitutions. + * If a revision number or remark has been set but the revision date + has not been set then the revision date is set to the value of the + 'docdate' attribute. + +Examples: + + v2.0, February 2003 + February 2003 + v2.0, + v2.0, February 2003: Rewritten for version 2 release. + February 2003: Rewritten for version 2 release. + v2.0,: Rewritten for version 2 release. + :Rewritten for version 2 release. +-- + +. The revision information line can also be an RCS/CVS/SVN $Id$ + marker: ++ +-- + * AsciiDoc extracts the 'revnumber', 'revdate', and 'author' + attributes from the $Id$ revision marker and displays them in the + document header. + * If an $Id$ revision marker is used the header author line can be + omitted. + +Example: + + $Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $ +-- + +You can override or set header parameters by passing 'revnumber', +'revremark', 'revdate', 'email', 'author', 'authorinitials', +'firstname' and 'lastname' attributes using the asciidoc(1) `-a` +(`--attribute`) command-line option. For example: + + $ asciidoc -a revdate=2004/07/27 article.txt + +Attribute entries can also be added to the header for substitution in +the header template with <> elements. + +The 'title' element in HTML outputs is set to the AsciiDoc document +title, you can set it to a different value by including a 'title' +attribute entry in the document header. + +[[X87]] +Additional document header information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +AsciiDoc has two mechanisms for optionally including additional +meta-data in the header of the output document: + +'docinfo' configuration file sections:: +If a <> section named 'docinfo' has been loaded +then it will be included in the document header. Typically the +'docinfo' section name will be prefixed with a '+' character so that it +is appended to (rather than replace) other 'docinfo' sections. + +'docinfo' files:: +Two docinfo files are recognized: one named `docinfo` and a second +named like the AsciiDoc source file with a `-docinfo` suffix. For +example, if the source document is called `mydoc.txt` then the +document information files would be `docinfo.xml` and +`mydoc-docinfo.xml` (for DocBook outputs) and `docinfo.html` and +`mydoc-docinfo.html` (for HTML outputs). The <> attributes control which docinfo files are included in +the output files. + +The contents docinfo templates and files is dependent on the type of +output: + +HTML:: + Valid 'head' child elements. Typically 'style' and 'script' elements + for CSS and JavaScript inclusion. + +DocBook:: + Valid 'articleinfo' or 'bookinfo' child elements. DocBook defines + numerous elements for document meta-data, for example: copyrights, + document history and authorship information. See the DocBook + `./doc/article-docinfo.xml` example that comes with the AsciiDoc + distribution. The rendering of meta-data elements (or not) is + DocBook processor dependent. + + +[[X86]] +Preamble +~~~~~~~~ +The Preamble is an optional untitled section body between the document +Header and the first Section title. + +Sections +~~~~~~~~ +In addition to the document title (level 0), AsciiDoc supports four +section levels: 1 (top) to 4 (bottom). Section levels are delimited +by section <>. Sections are translated using +configuration file <>. AsciiDoc +generates the following <> specifically for +use in section markup templates: + +level:: +The `level` attribute is the section level number, it is normally just +the <> level number (1..4). However, if the `leveloffset` +attribute is defined it will be added to the `level` attribute. The +`leveloffset` attribute is useful for <>. + +sectnum:: +The `-n` (`--section-numbers`) command-line option generates the +`sectnum` (section number) attribute. The `sectnum` attribute is used +for section numbers in HTML outputs (DocBook section numbering are +handled automatically by the DocBook toolchain commands). + +[[X93]] +Section markup templates +^^^^^^^^^^^^^^^^^^^^^^^^ +Section markup templates specify output markup and are defined in +AsciiDoc configuration files. Section markup template names are +derived as follows (in order of precedence): + +1. From the title's first positional attribute or 'template' + attribute. For example, the following three section titles are + functionally equivalent: ++ +..................................................................... +[[terms]] +[glossary] +List of Terms +------------- + +["glossary",id="terms"] +List of Terms +------------- + +[template="glossary",id="terms"] +List of Terms +------------- +..................................................................... + +2. When the title text matches a configuration file + <> entry. +3. If neither of the above the default `sect` template is used + (where `` is a number from 1 to 4). + +In addition to the normal section template names ('sect1', 'sect2', +'sect3', 'sect4') AsciiDoc has the following templates for +frontmatter, backmatter and other special sections: 'abstract', +'preface', 'colophon', 'dedication', 'glossary', 'bibliography', +'synopsis', 'appendix', 'index'. These special section templates +generate the corresponding Docbook elements; for HTML outputs they +default to the 'sect1' section template. + +Section IDs +^^^^^^^^^^^ +If no explicit section ID is specified an ID will be synthesised from +the section title. The primary purpose of this feature is to ensure +persistence of table of contents links (permalinks): the missing +section IDs are generated dynamically by the JavaScript TOC generator +*after* the page is loaded. If you link to a dynamically generated TOC +address the page will load but the browser will ignore the (as yet +ungenerated) section ID. + +The IDs are generated by the following algorithm: + +- Replace all non-alphanumeric title characters with underscores. +- Strip leading or trailing underscores. +- Convert to lowercase. +- Prepend the `idprefix` attribute (so there's no possibility of name + clashes with existing document IDs). Prepend an underscore if the + `idprefix` attribute is not defined. +- A numbered suffix (`_2`, `_3` ...) is added if a same named + auto-generated section ID exists. +- If the `ascii-ids` attribute is defined then non-ASCII characters + are replaced with ASCII equivalents. This attribute should be + *should be avoided* if possible as its sole purpose is to accommodate + deficient downstream applications that cannot process non-ASCII ID + attributes. If available, it will use the + https://pypi.org/project/trans/[trans python module], otherwise it + will fallback to using NFKD algorithm, which cannot handle all + unicode characters. For example, 'Wstęp żółtej łąki' will be + translated to 'Wstep zoltej laki' under trans and 'Wstep zotej aki' + under NFKD. + +Example: the title 'Jim's House' would generate the ID `_jim_s_house`. + +Section ID synthesis can be disabled by undefining the `sectids` +attribute. + +[[X16]] +Special Section Titles +^^^^^^^^^^^^^^^^^^^^^^ +AsciiDoc has a mechanism for mapping predefined section titles +auto-magically to specific markup templates. For example a title +'Appendix A: Code Reference' will automatically use the 'appendix' +<>. The mappings from title to template +name are specified in `[specialsections]` sections in the Asciidoc +language configuration files (`lang-*.conf`). Section entries are +formatted like: + + =<template> + +`<title>` is a Python regular expression and `<template>` is the name +of a configuration file markup template section. If the `<title>` +matches an AsciiDoc document section title then the backend output is +marked up using the `<template>` markup template (instead of the +default `sect<level>` section template). The `{title}` attribute value +is set to the value of the matched regular expression group named +'title', if there is no 'title' group `{title}` defaults to the whole +of the AsciiDoc section title. If `<template>` is blank then any +existing entry with the same `<title>` will be deleted. + +.Special section titles vs. explicit template names +********************************************************************* +AsciiDoc has two mechanisms for specifying non-default section markup +templates: you can specify the template name explicitly (using the +'template' attribute) or indirectly (using 'special section titles'). +Specifying a <<X93,section template>> attribute explicitly is +preferred. Auto-magical 'special section titles' have the following +drawbacks: + +- They are non-obvious, you have to know the exact matching + title for each special section on a language by language basis. +- Section titles are predefined and can only be customised with a + configuration change. +- The implementation is complicated by multiple languages: every + special section title has to be defined for each language (in each + of the `lang-*.conf` files). + +Specifying special section template names explicitly does add more +noise to the source document (the 'template' attribute declaration), +but the intention is obvious and the syntax is consistent with other +AsciiDoc elements c.f. bibliographic, Q&A and glossary lists. + +Special section titles have been deprecated but are retained for +backward compatibility. + +********************************************************************* + +Inline Elements +~~~~~~~~~~~~~~~ +<<X34,Inline document elements>> are used to format text and to +perform various types of text substitution. Inline elements and inline +element syntax is defined in the asciidoc(1) configuration files. + +Here is a list of AsciiDoc inline elements in the (default) order in +which they are processed: + +Special characters:: + These character sequences escape special characters used by + the backend markup (typically `<`, `>`, and `&` characters). + See `[specialcharacters]` configuration file sections. + +Quotes:: + Elements that markup words and phrases; usually for character + formatting. See `[quotes]` configuration file sections. + +Special Words:: + Word or word phrase patterns singled out for markup without + the need for further annotation. See `[specialwords]` + configuration file sections. + +Replacements:: + Each replacement defines a word or word phrase pattern to + search for along with corresponding replacement text. See + `[replacements]` configuration file sections. + +Attribute references:: + Document attribute names enclosed in braces are replaced by + the corresponding attribute value. + +Inline Macros:: + Inline macros are replaced by the contents of parametrized + configuration file sections. + + +Document Processing +------------------- +The AsciiDoc source document is read and processed as follows: + +1. The document 'Header' is parsed, header parameter values are + substituted into the configuration file `[header]` template section + which is then written to the output file. +2. Each document 'Section' is processed and its constituent elements + translated to the output file. +3. The configuration file `[footer]` template section is substituted + and written to the output file. + +When a block element is encountered asciidoc(1) determines the type of +block by checking in the following order (first to last): (section) +Titles, BlockMacros, Lists, DelimitedBlocks, Tables, AttributeEntrys, +AttributeLists, BlockTitles, Paragraphs. + +The default paragraph definition `[paradef-default]` is last element +to be checked. + +Knowing the parsing order will help you devise unambiguous macro, list +and block syntax rules. + +Inline substitutions within block elements are performed in the +following default order: + +1. Special characters +2. Quotes +3. Special words +4. Replacements +5. Attributes +6. Inline Macros +7. Replacements2 + +The substitutions and substitution order performed on +Title, Paragraph and DelimitedBlock elements is determined by +configuration file parameters. + + +Text Formatting +--------------- +[[X51]] +Quoted Text +~~~~~~~~~~~ +Words and phrases can be formatted by enclosing inline text with +quote characters: + +_Emphasized text_:: + Word phrases \'enclosed in single quote characters' (acute + accents) or \_underline characters_ are emphasized. + +*Strong text*:: + Word phrases \*enclosed in asterisk characters* are rendered + in a strong font (usually bold). + +[[X81]]+Monospaced text+:: + Word phrases \+enclosed in plus characters+ are rendered in a + monospaced font. Word phrases \`enclosed in backtick + characters` (grave accents) are also rendered in a monospaced + font but in this case the enclosed text is rendered literally + and is not subject to further expansion (see <<X80,inline + literal passthrough>>). + +`Single quoted text':: + Phrases enclosed with a \`single grave accent to the left and + a single acute accent to the right' are rendered in single + quotation marks. + +``Double quoted text'':: + Phrases enclosed with \\``two grave accents to the left and + two acute accents to the right'' are rendered in quotation + marks. + +#Unquoted text#:: + Placing \#hashes around text# does nothing, it is a mechanism + to allow inline attributes to be applied to otherwise + unformatted text. + +New quote types can be defined by editing asciidoc(1) configuration +files. See the <<X7,Configuration Files>> section for details. + +.Quoted text behavior +- Quoting cannot be overlapped. +- Different quoting types can be nested. +- To suppress quoted text formatting place a backslash character + immediately in front of the leading quote character(s). In the case + of ambiguity between escaped and non-escaped text you will need to + escape both leading and trailing quotes, in the case of + multi-character quotes you may even need to escape individual + characters. + +[[X96]] +Quoted text attributes +^^^^^^^^^^^^^^^^^^^^^^ +Quoted text can be prefixed with an <<X21,attribute list>>. The first +positional attribute ('role' attribute) is translated by AsciiDoc to +an HTML 'span' element 'class' attribute or a DocBook 'phrase' element +'role' attribute. + +DocBook XSL Stylesheets translate DocBook 'phrase' elements with +'role' attributes to corresponding HTML 'span' elements with the same +'class' attributes; CSS can then be used +http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the +generated HTML]. Thus CSS styling can be applied to both DocBook and +AsciiDoc generated HTML outputs. You can also specify multiple class +names separated by spaces. + +CSS rules for text color, text background color, text size and text +decorators are included in the distributed AsciiDoc CSS files and are +used in conjunction with AsciiDoc 'xhtml11', 'html5' and 'docbook' +outputs. The CSS class names are: + +- '<color>' (text foreground color). +- '<color>-background' (text background color). +- 'big' and 'small' (text size). +- 'underline', 'overline' and 'line-through' (strike through) text + decorators. + +Where '<color>' can be any of the +https://en.wikipedia.org/wiki/Web_colors#HTML_color_names[sixteen HTML +color names]. Examples: + + [red]#Obvious# and [big red yellow-background]*very obvious*. + + [underline]#Underline text#, [overline]#overline text# and + [blue line-through]*bold blue and line-through*. + +is rendered as: + +[red]#Obvious# and [big red yellow-background]*very obvious*. + +[underline]#Underline text#, [overline]#overline text# and +[bold blue line-through]*bold blue and line-through*. + +NOTE: Color and text decorator attributes are rendered for XHTML and +HTML 5 outputs using CSS stylesheets. The mechanism to implement +color and text decorator attributes is provided for DocBook toolchains +via the DocBook 'phrase' element 'role' attribute, but the actual +rendering is toolchain specific and is not part of the AsciiDoc +distribution. + +[[X52]] +Constrained and Unconstrained Quotes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +There are actually two types of quotes: + +Constrained quotes +++++++++++++++++++ +Quoted must be bounded by white space or commonly adjoining +punctuation characters. These are the most commonly used type of +quote. + +Unconstrained quotes +++++++++++++++++++++ +Unconstrained quotes have no boundary constraints and can be placed +anywhere within inline text. For consistency and to make them easier +to remember unconstrained quotes are double-ups of the `_`, `*`, `+` +and `#` constrained quotes: + + __unconstrained emphasized text__ + **unconstrained strong text** + ++unconstrained monospaced text++ + ##unconstrained unquoted text## + +The following example emboldens the letter F: + + **F**ile Open... + +Superscripts and Subscripts +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Put \^carets on either^ side of the text to be superscripted, put +\~tildes on either side~ of text to be subscripted. For example, the +following line: + + e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^ + and ~some sub text~ + +Is rendered like: + +e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^ +and ~some sub text~ + +Superscripts and subscripts are implemented as <<X52,unconstrained +quotes>> and they can be escaped with a leading backslash and prefixed +with with an attribute list. + +Line Breaks +~~~~~~~~~~~ +A plus character preceded by at least one space character at the end +of a non-blank line forces a line break. It generates a line break +(`br`) tag for HTML outputs and a custom XML `asciidoc-br` processing +instruction for DocBook outputs. The `asciidoc-br` processing +instruction is handled by <<X43,a2x(1)>>. + +Page Breaks +~~~~~~~~~~~ +A line of three or more less-than (`<<<`) characters will generate a +hard page break in DocBook and printed HTML outputs. It uses the CSS +`page-break-after` property for HTML outputs and a custom XML +`asciidoc-pagebreak` processing instruction for DocBook outputs. The +`asciidoc-pagebreak` processing instruction is handled by +<<X43,a2x(1)>>. Hard page breaks are sometimes handy but as a general +rule you should let your page processor generate page breaks for you. + +Rulers +~~~~~~ +A line of three or more apostrophe characters will generate a ruler +line. It generates a ruler (`hr`) tag for HTML outputs and a custom +XML `asciidoc-hr` processing instruction for DocBook outputs. The +`asciidoc-hr` processing instruction is handled by <<X43,a2x(1)>>. + +Tabs +~~~~ +By default tab characters input files will translated to 8 spaces. Tab +expansion is set with the 'tabsize' entry in the configuration file +`[miscellaneous]` section and can be overridden in included files by +setting a 'tabsize' attribute in the `include` macro's attribute list. +For example: + + include::addendum.txt[tabsize=2] + +The tab size can also be set using the attribute command-line option, +for example `--attribute tabsize=4` + +Replacements +~~~~~~~~~~~~ +The following replacements are defined in the default AsciiDoc +configuration: + + (C) copyright, (TM) trademark, (R) registered trademark, + -- em dash, ... ellipsis, -> right arrow, <- left arrow, => right + double arrow, <= left double arrow. + +Which are rendered as: + +(C) copyright, (TM) trademark, (R) registered trademark, +-- em dash, ... ellipsis, -> right arrow, <- left arrow, => right +double arrow, <= left double arrow. + +You can also include arbitrary entity references in the AsciiDoc +source. Examples: + + ➊ ¶ + +renders: + +➊ ¶ + +To render a replacement literally escape it with a leading back-slash. + +The <<X7,Configuration Files>> section explains how to configure your +own replacements. + +Special Words +~~~~~~~~~~~~~ +Words defined in `[specialwords]` configuration file sections are +automatically marked up without having to be explicitly notated. + +The <<X7,Configuration Files>> section explains how to add and replace +special words. + + +[[X17]] +Titles +------ +Document and section titles can be in either of two formats: + +Two line titles +~~~~~~~~~~~~~~~ +A two line title consists of a title line, starting hard against the +left margin, and an underline. Section underlines consist a repeated +character pairs spanning the width of the preceding title (give or +take up to two characters): + +The default title underlines for each of the document levels are: + + + Level 0 (top level): ====================== + Level 1: ---------------------- + Level 2: ~~~~~~~~~~~~~~~~~~~~~~ + Level 3: ^^^^^^^^^^^^^^^^^^^^^^ + Level 4 (bottom level): ++++++++++++++++++++++ + +Examples: + + Level One Section Title + ----------------------- + + Level 2 Subsection Title + ~~~~~~~~~~~~~~~~~~~~~~~~ + +[[X46]] +One line titles +~~~~~~~~~~~~~~~ +One line titles consist of a single line delimited on either side by +one or more equals characters (the number of equals characters +corresponds to the section level minus one). Here are some examples: + + = Document Title (level 0) = + == Section title (level 1) == + === Section title (level 2) === + ==== Section title (level 3) ==== + ===== Section title (level 4) ===== + +[NOTE] +===================================================================== +- One or more spaces must fall between the title and the delimiters. +- The trailing title delimiter is optional. +- The one-line title syntax can be changed by editing the + configuration file `[titles]` section `sect0`...`sect4` entries. +===================================================================== + +Floating titles +~~~~~~~~~~~~~~~ +Setting the title's first positional attribute or 'style' attribute to +'float' generates a free-floating title. A free-floating title is +rendered just like a normal section title but is not formally +associated with a text body and is not part of the regular section +hierarchy so the normal ordering rules do not apply. Floating titles +can also be used in contexts where section titles are illegal: for +example sidebar and admonition blocks. Example: + + [float] + The second day + ~~~~~~~~~~~~~~ + +Floating titles do not appear in a document's table of contents. + + +[[X42]] +Block Titles +------------ +A 'BlockTitle' element is a single line beginning with a period +followed by the title text. A BlockTitle is applied to the immediately +following Paragraph, DelimitedBlock, List, Table or BlockMacro. For +example: + +........................ +.Notes +- Note 1. +- Note 2. +........................ + +is rendered as: + +.Notes +- Note 1. +- Note 2. + + +[[X41]] +BlockId Element +--------------- +A 'BlockId' is a single line block element containing a unique +identifier enclosed in double square brackets. It is used to assign an +identifier to the ensuing block element. For example: + + [[chapter-titles]] + Chapter titles can be ... + +The preceding example identifies the ensuing paragraph so it can be +referenced from other locations, for example with +`<<chapter-titles,chapter titles>>`. + +'BlockId' elements can be applied to Title, Paragraph, List, +DelimitedBlock, Table and BlockMacro elements. The BlockId element +sets the `{id}` attribute for substitution in the subsequent block's +markup template. If a second positional argument is supplied it sets +the `{reftext}` attribute which is used to set the DocBook `xreflabel` +attribute. + +The 'BlockId' element has the same syntax and serves the same function +to the <<X30,anchor inline macro>>. + +[[X79]] +AttributeList Element +--------------------- +An 'AttributeList' block element is an <<X21,attribute list>> on a +line by itself: + +- 'AttributeList' attributes are only applied to the immediately + following block element -- the attributes are made available to the + block's markup template. +- Multiple contiguous 'AttributeList' elements are additively combined + in the order they appear. +- The first positional attribute in the list is often used to specify + the ensuing element's <<X23,style>>. + +Attribute value substitution +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +By default, only substitutions that take place inside attribute list +values are attribute references, this is because not all attributes +are destined to be marked up and rendered as text (for example the +table 'cols' attribute). To perform normal inline text substitutions +(special characters, quotes, macros, replacements) on an attribute +value you need to enclose it in single quotes. In the following quote +block the second attribute value in the AttributeList is quoted to +ensure the 'http' macro is expanded to a hyperlink. + +--------------------------------------------------------------------- +[quote,'https://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]'] +_____________________________________________________________________ +Sir, a woman's preaching is like a dog's walking on his hind legs. It +is not done well; but you are surprised to find it done at all. +_____________________________________________________________________ +--------------------------------------------------------------------- + +Common attributes +~~~~~~~~~~~~~~~~~ +Most block elements support the following attributes: + +[cols="1e,1,5a",frame="topbot",options="header"] +|==================================================================== +|Name |Backends |Description + +|id |html4, html5, xhtml11, docbook | +Unique identifier typically serve as link targets. +Can also be set by the 'BlockId' element. + +|role |html4, html5, xhtml11, docbook | +Role contains a string used to classify or subclassify an element and +can be applied to AsciiDoc block elements. The AsciiDoc 'role' +attribute is translated to the 'role' attribute in DocBook outputs and +is included in the 'class' attribute in HTML outputs, in this respect +it behaves like the <<X96,quoted text role attribute>>. + +DocBook XSL Stylesheets translate DocBook 'role' attributes to HTML +'class' attributes; CSS can then be used +http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the +generated HTML]. + +|reftext |docbook | +'reftext' is used to set the DocBook 'xreflabel' attribute. +The 'reftext' attribute can an also be set by the 'BlockId' element. + +|floatstyle |docbook | +'floatstyle' is used to specify the floatstyle attribute for the +titled table, example, image and equation blocks. This is useful when +used in conjuction with the dblatex toolchain. A typical example +would be to specify the value as 'floatstyle="[htbp]"'. + +|==================================================================== + + +Paragraphs +---------- +Paragraphs are blocks of text terminated by a blank line, the end of +file, or the start of a delimited block or a list. There are three +paragraph syntaxes: normal, indented (literal) and admonition which +are rendered, by default, with the corresponding paragraph style. + +Each syntax has a default style, but you can explicitly apply any +paragraph style to any paragraph syntax. You can also apply +<<X104,delimited block>> styles to single paragraphs. + +The built-in paragraph styles are: 'normal', 'literal', 'verse', +'quote', 'listing', 'TIP', 'NOTE', 'IMPORTANT', 'WARNING', 'CAUTION', +'abstract', 'partintro', 'comment', 'example', 'sidebar', 'source', +'music', 'latex', 'graphviz'. + +normal paragraph syntax +~~~~~~~~~~~~~~~~~~~~~~~ +Normal paragraph syntax consists of one or more non-blank lines of +text. The first line must start hard against the left margin (no +intervening white space). The default processing expectation is that +of a normal paragraph of text. + +[[X85]] +literal paragraph syntax +~~~~~~~~~~~~~~~~~~~~~~~~ +Literal paragraphs are rendered verbatim in a monospaced font without +any distinguishing background or border. By default there is no text +formatting or substitutions within Literal paragraphs apart from +Special Characters and Callouts. + +The 'literal' style is applied implicitly to indented paragraphs i.e. +where the first line of the paragraph is indented by one or more space +or tab characters. For example: + +--------------------------------------------------------------------- + Consul *necessitatibus* per id, + consetetur, eu pro everti postulant + homero verear ea mea, qui. +--------------------------------------------------------------------- + +Renders: + + Consul *necessitatibus* per id, + consetetur, eu pro everti postulant + homero verear ea mea, qui. + +NOTE: Because <<X64,lists>> can be indented it's possible for your +indented paragraph to be misinterpreted as a list -- in situations +like this apply the 'literal' style to a normal paragraph. + +Instead of using a paragraph indent you could apply the 'literal' +style explicitly, for example: + +--------------------------------------------------------------------- +[literal] +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. +--------------------------------------------------------------------- + +Renders: + +[literal] +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +[[X94]] +quote and verse paragraph styles +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The optional 'attribution' and 'citetitle' attributes (positional +attributes 2 and 3) specify the author and source respectively. + +The 'verse' style retains the line breaks, for example: + +--------------------------------------------------------------------- +[verse, William Blake, from Auguries of Innocence] +To see a world in a grain of sand, +And a heaven in a wild flower, +Hold infinity in the palm of your hand, +And eternity in an hour. +--------------------------------------------------------------------- + +Which is rendered as: + +[verse, William Blake, from Auguries of Innocence] +To see a world in a grain of sand, +And a heaven in a wild flower, +Hold infinity in the palm of your hand, +And eternity in an hour. + +The 'quote' style flows the text at left and right margins, for +example: + +--------------------------------------------------------------------- +[quote, Bertrand Russell, The World of Mathematics (1956)] +A good notation has subtlety and suggestiveness which at times makes +it almost seem like a live teacher. +--------------------------------------------------------------------- + +Which is rendered as: + +[quote, Bertrand Russell, The World of Mathematics (1956)] +A good notation has subtlety and suggestiveness which at times makes +it almost seem like a live teacher. + +[[X28]] +Admonition Paragraphs +~~~~~~~~~~~~~~~~~~~~~ +'TIP', 'NOTE', 'IMPORTANT', 'WARNING' and 'CAUTION' admonishment +paragraph styles are generated by placing `NOTE:`, `TIP:`, +`IMPORTANT:`, `WARNING:` or `CAUTION:` as the first word of the +paragraph. For example: + + NOTE: This is an example note. + +Alternatively, you can specify the paragraph admonition style +explicitly using an <<X79,AttributeList element>>. For example: + + [NOTE] + This is an example note. + +Renders: + +NOTE: This is an example note. + +TIP: If your admonition requires more than a single paragraph use an +<<X22,admonition block>> instead. + +[[X47]] +Admonition Icons and Captions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +NOTE: Admonition customization with `icons`, `iconsdir`, `icon` and +`caption` attributes does not apply when generating DocBook output. If +you are going the DocBook route then the <<X43,a2x(1)>> `--no-icons` +and `--icons-dir` options can be used to set the appropriate XSL +Stylesheets parameters. + +By default the asciidoc(1) HTML backends generate text captions +instead of admonition icon image links. To generate links to icon +images define the <<X45,`icons`>> attribute, for example using the `-a +icons` command-line option. + +The <<X44,`iconsdir`>> attribute sets the location of linked icon +images. + +You can override the default icon image using the `icon` attribute to +specify the path of the linked image. For example: + + [icon="./images/icons/wink.png"] + NOTE: What lovely war. + +Use the `caption` attribute to customize the admonition captions (not +applicable to `docbook` backend). The following example suppresses the +icon image and customizes the caption of a 'NOTE' admonition +(undefining the `icons` attribute with `icons=None` is only necessary +if <<X45,admonition icons>> have been enabled): + + [icons=None, caption="My Special Note"] + NOTE: This is my special note. + +This subsection also applies to <<X22,Admonition Blocks>>. + + +[[X104]] +Delimited Blocks +---------------- +Delimited blocks are blocks of text enveloped by leading and trailing +delimiter lines (normally a series of four or more repeated +characters). The behavior of Delimited Blocks is specified by entries +in configuration file `[blockdef-*]` sections. + +Predefined Delimited Blocks +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +AsciiDoc ships with a number of predefined DelimitedBlocks (see the +`asciidoc.conf` configuration file in the asciidoc(1) program +directory): + +Predefined delimited block underlines: + + CommentBlock: ////////////////////////// + PassthroughBlock: ++++++++++++++++++++++++++ + ListingBlock: -------------------------- + LiteralBlock: .......................... + SidebarBlock: ************************** + QuoteBlock: __________________________ + ExampleBlock: ========================== + OpenBlock: -- + +.Default DelimitedBlock substitutions +[cols="2e,7*^",frame="topbot",options="header,autowidth"] +|===================================================== +| |Attributes |Callouts |Macros | Quotes |Replacements +|Special chars |Special words + +|PassthroughBlock |Yes |No |Yes |No |No |No |No +|ListingBlock |No |Yes |No |No |No |Yes |No +|LiteralBlock |No |Yes |No |No |No |Yes |No +|SidebarBlock |Yes |No |Yes |Yes |Yes |Yes |Yes +|QuoteBlock |Yes |No |Yes |Yes |Yes |Yes |Yes +|ExampleBlock |Yes |No |Yes |Yes |Yes |Yes |Yes +|OpenBlock |Yes |No |Yes |Yes |Yes |Yes |Yes +|===================================================== + +Listing Blocks +~~~~~~~~~~~~~~ +'ListingBlocks' are rendered verbatim in a monospaced font, they +retain line and whitespace formatting and are often distinguished by a +background or border. There is no text formatting or substitutions +within Listing blocks apart from Special Characters and Callouts. +Listing blocks are often used for computer output and file listings. + +Here's an example: + +[listing] +...................................... +-------------------------------------- +#include <stdio.h> + +int main() { + printf("Hello World!\n"); + exit(0); +} +-------------------------------------- +...................................... + +Which will be rendered like: + +-------------------------------------- +#include <stdio.h> + +int main() { + printf("Hello World!\n"); + exit(0); +} +-------------------------------------- + +By convention <<X59,filter blocks>> use the listing block syntax and +are implemented as distinct listing block styles. + +[[X65]] +Literal Blocks +~~~~~~~~~~~~~~ +'LiteralBlocks' are rendered just like <<X85,literal paragraphs>>. +Example: + +--------------------------------------------------------------------- +................................... +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. +................................... +--------------------------------------------------------------------- + +Renders: +................................... +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. +................................... + +If the 'listing' style is applied to a LiteralBlock it will be +rendered as a ListingBlock (this is handy if you have a listing +containing a ListingBlock). + +Sidebar Blocks +~~~~~~~~~~~~~~ +A sidebar is a short piece of text presented outside the narrative +flow of the main text. The sidebar is normally presented inside a +bordered box to set it apart from the main text. + +The sidebar body is treated like a normal section body. + +Here's an example: + +--------------------------------------------------------------------- +.An Example Sidebar +************************************************ +Any AsciiDoc SectionBody element (apart from +SidebarBlocks) can be placed inside a sidebar. +************************************************ +--------------------------------------------------------------------- + +Which will be rendered like: + +.An Example Sidebar +************************************************ +Any AsciiDoc SectionBody element (apart from +SidebarBlocks) can be placed inside a sidebar. +************************************************ + +[[X26]] +Comment Blocks +~~~~~~~~~~~~~~ +The contents of 'CommentBlocks' are not processed; they are useful for +annotations and for excluding new or outdated content that you don't +want displayed. CommentBlocks are never written to output files. +Example: + +--------------------------------------------------------------------- +////////////////////////////////////////// +CommentBlock contents are not processed by +asciidoc(1). +////////////////////////////////////////// +--------------------------------------------------------------------- + +See also <<X25,Comment Lines>>. + +NOTE: System macros are executed inside comment blocks. + +[[X76]] +Passthrough Blocks +~~~~~~~~~~~~~~~~~~ +By default the block contents is subject only to 'attributes' and +'macros' substitutions (use an explicit 'subs' attribute to apply +different substitutions). PassthroughBlock content will often be +backend specific. Here's an example: + +--------------------------------------------------------------------- +[subs="quotes"] +++++++++++++++++++++++++++++++++++++++ +<table border="1"><tr> + <td>*Cell 1*</td> + <td>*Cell 2*</td> +</tr></table> +++++++++++++++++++++++++++++++++++++++ +--------------------------------------------------------------------- + +The following styles can be applied to passthrough blocks: + +pass:: + No substitutions are performed. This is equivalent to `subs="none"`. + +asciimath, latexmath:: + By default no substitutions are performed, the contents are rendered + as <<X78,mathematical formulas>>. + +Quote Blocks +~~~~~~~~~~~~ +'QuoteBlocks' are used for quoted passages of text. There are two +styles: 'quote' and 'verse'. The style behavior is identical to +<<X94,quote and verse paragraphs>> except that blocks can contain +multiple paragraphs and, in the case of the 'quote' style, other +section elements. The first positional attribute sets the style, if +no attributes are specified the 'quote' style is used. The optional +'attribution' and 'citetitle' attributes (positional attributes 2 and +3) specify the quote's author and source. For example: + +--------------------------------------------------------------------- +[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes] +____________________________________________________________________ +As he spoke there was the sharp sound of horses' hoofs and +grating wheels against the curb, followed by a sharp pull at the +bell. Holmes whistled. + +"A pair, by the sound," said he. "Yes," he continued, glancing +out of the window. "A nice little brougham and a pair of +beauties. A hundred and fifty guineas apiece. There's money in +this case, Watson, if there is nothing else." +____________________________________________________________________ +--------------------------------------------------------------------- + +Which is rendered as: + +[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes] +____________________________________________________________________ +As he spoke there was the sharp sound of horses' hoofs and +grating wheels against the curb, followed by a sharp pull at the +bell. Holmes whistled. + +"A pair, by the sound," said he. "Yes," he continued, glancing +out of the window. "A nice little brougham and a pair of +beauties. A hundred and fifty guineas apiece. There's money in +this case, Watson, if there is nothing else." +____________________________________________________________________ + +[[X48]] +Example Blocks +~~~~~~~~~~~~~~ +'ExampleBlocks' encapsulate the DocBook Example element and are used +for, well, examples. Example blocks can be titled by preceding them +with a 'BlockTitle'. DocBook toolchains will normally automatically +number examples and generate a 'List of Examples' backmatter section. + +Example blocks are delimited by lines of equals characters and can +contain any block elements apart from Titles, BlockTitles and +Sidebars) inside an example block. For example: + +--------------------------------------------------------------------- +.An example +===================================================================== +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. +===================================================================== +--------------------------------------------------------------------- + +Renders: + +.An example +===================================================================== +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. +===================================================================== + +A title prefix that can be inserted with the `caption` attribute +(HTML backends). For example: + +--------------------------------------------------------------------- +[caption="Example 1: "] +.An example with a custom caption +===================================================================== +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. +===================================================================== +--------------------------------------------------------------------- + +[[X22]] +Admonition Blocks +~~~~~~~~~~~~~~~~~ +The 'ExampleBlock' definition includes a set of admonition +<<X23,styles>> ('NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION') for +generating admonition blocks (admonitions containing more than a +<<X28,single paragraph>>). Just precede the 'ExampleBlock' with an +attribute list specifying the admonition style name. For example: + +--------------------------------------------------------------------- +[NOTE] +.A NOTE admonition block +===================================================================== +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. + +. Fusce euismod commodo velit. +. Vivamus fringilla mi eu lacus. + .. Fusce euismod commodo velit. + .. Vivamus fringilla mi eu lacus. +. Donec eget arcu bibendum + nunc consequat lobortis. +===================================================================== +--------------------------------------------------------------------- + +Renders: + +[NOTE] +.A NOTE admonition block +===================================================================== +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. + +. Fusce euismod commodo velit. +. Vivamus fringilla mi eu lacus. + .. Fusce euismod commodo velit. + .. Vivamus fringilla mi eu lacus. +. Donec eget arcu bibendum + nunc consequat lobortis. +===================================================================== + +See also <<X47,Admonition Icons and Captions>>. + +[[X29]] +Open Blocks +~~~~~~~~~~~ +Open blocks are special: + +- The open block delimiter is line containing two hyphen characters + (instead of four or more repeated characters). + +- They can be used to group block elements for <<X15,List item + continuation>>. + +- Open blocks can be styled to behave like any other type of delimited + block. The following built-in styles can be applied to open + blocks: 'literal', 'verse', 'quote', 'listing', 'TIP', 'NOTE', + 'IMPORTANT', 'WARNING', 'CAUTION', 'abstract', 'partintro', + 'comment', 'example', 'sidebar', 'source', 'music', 'latex', + 'graphviz'. For example, the following open block and listing block + are functionally identical: + + [listing] + -- + Lorum ipsum ... + -- + + --------------- + Lorum ipsum ... + --------------- + +- An unstyled open block groups section elements but otherwise does + nothing. + +Open blocks are used to generate document abstracts and book part +introductions: + +- Apply the 'abstract' style to generate an abstract, for example: + + [abstract] + -- + In this paper we will ... + -- + +. Apply the 'partintro' style to generate a book part introduction for + a multi-part book, for example: + + [partintro] + .Optional part introduction title + -- + Optional part introduction goes here. + -- + + +[[X64]] +Lists +----- +.List types +- Bulleted lists. Also known as itemized or unordered lists. +- Numbered lists. Also called ordered lists. +- Labeled lists. Sometimes called variable or definition lists. +- Callout lists (a list of callout annotations). + +.List behavior +- List item indentation is optional and does not determine nesting, + indentation does however make the source more readable. +- Another list or a literal paragraph immediately following a list + item will be implicitly included in the list item; use <<X15, list + item continuation>> to explicitly append other block elements to a + list item. +- A comment block or a comment line block macro element will terminate + a list -- use inline comment lines to put comments inside lists. +- The `listindex` <<X60,intrinsic attribute>> is the current list item + index (1..). If this attribute is used outside a list then it's value + is the number of items in the most recently closed list. Useful for + displaying the number of items in a list. + +Bulleted Lists +~~~~~~~~~~~~~~ +Bulleted list items start with a single dash or one to five asterisks +followed by some white space then some text. Bulleted list syntaxes +are: + +................... +- List item. +* List item. +** List item. +*** List item. +**** List item. +***** List item. +................... + +Numbered Lists +~~~~~~~~~~~~~~ +List item numbers are explicit or implicit. + +.Explicit numbering +List items begin with a number followed by some white space then the +item text. The numbers can be decimal (arabic), roman (upper or lower +case) or alpha (upper or lower case). Decimal and alpha numbers are +terminated with a period, roman numbers are terminated with a closing +parenthesis. The different terminators are necessary to ensure 'i', +'v' and 'x' roman numbers are are distinguishable from 'x', 'v' and +'x' alpha numbers. Examples: + +..................................................................... +1. Arabic (decimal) numbered list item. +a. Lower case alpha (letter) numbered list item. +F. Upper case alpha (letter) numbered list item. +iii) Lower case roman numbered list item. +IX) Upper case roman numbered list item. +..................................................................... + +.Implicit numbering +List items begin one to five period characters, followed by some white +space then the item text. Examples: + +..................................................................... +. Arabic (decimal) numbered list item. +.. Lower case alpha (letter) numbered list item. +... Lower case roman numbered list item. +.... Upper case alpha (letter) numbered list item. +..... Upper case roman numbered list item. +..................................................................... + +You can use the 'style' attribute (also the first positional +attribute) to specify an alternative numbering style. The numbered +list style can be one of the following values: 'arabic', 'loweralpha', +'upperalpha', 'lowerroman', 'upperroman'. + +Here are some examples of bulleted and numbered lists: + +--------------------------------------------------------------------- +- Praesent eget purus quis magna eleifend eleifend. + 1. Fusce euismod commodo velit. + a. Fusce euismod commodo velit. + b. Vivamus fringilla mi eu lacus. + c. Donec eget arcu bibendum nunc consequat lobortis. + 2. Vivamus fringilla mi eu lacus. + i) Fusce euismod commodo velit. + ii) Vivamus fringilla mi eu lacus. + 3. Donec eget arcu bibendum nunc consequat lobortis. + 4. Nam fermentum mattis ante. +- Lorem ipsum dolor sit amet, consectetuer adipiscing elit. + * Fusce euismod commodo velit. + ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis + adolescens. Sit munere ponderum dignissim et. Minim luptatum et + vel. + ** Vivamus fringilla mi eu lacus. + * Donec eget arcu bibendum nunc consequat lobortis. +- Nulla porttitor vulputate libero. + . Fusce euismod commodo velit. + . Vivamus fringilla mi eu lacus. +[upperroman] + .. Fusce euismod commodo velit. + .. Vivamus fringilla mi eu lacus. + . Donec eget arcu bibendum nunc consequat lobortis. +--------------------------------------------------------------------- + +Which render as: + +- Praesent eget purus quis magna eleifend eleifend. + 1. Fusce euismod commodo velit. + a. Fusce euismod commodo velit. + b. Vivamus fringilla mi eu lacus. + c. Donec eget arcu bibendum nunc consequat lobortis. + 2. Vivamus fringilla mi eu lacus. + i) Fusce euismod commodo velit. + ii) Vivamus fringilla mi eu lacus. + 3. Donec eget arcu bibendum nunc consequat lobortis. + 4. Nam fermentum mattis ante. +- Lorem ipsum dolor sit amet, consectetuer adipiscing elit. + * Fusce euismod commodo velit. + ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis + adolescens. Sit munere ponderum dignissim et. Minim luptatum et + vel. + ** Vivamus fringilla mi eu lacus. + * Donec eget arcu bibendum nunc consequat lobortis. +- Nulla porttitor vulputate libero. + . Fusce euismod commodo velit. + . Vivamus fringilla mi eu lacus. +[upperroman] + .. Fusce euismod commodo velit. + .. Vivamus fringilla mi eu lacus. + . Donec eget arcu bibendum nunc consequat lobortis. + +A predefined 'compact' option is available to bulleted and numbered +lists -- this translates to the DocBook 'spacing="compact"' lists +attribute which may or may not be processed by the DocBook toolchain. +Example: + + [options="compact"] + - Compact list item. + - Another compact list item. + +TIP: To apply the 'compact' option globally define a document-wide +'compact-option' attribute, e.g. using the `-a compact-option` +command-line option. + +You can set the list start number using the 'start' attribute (works +for HTML outputs and DocBook outputs processed by DocBook XSL +Stylesheets). Example: + + [start=7] + . List item 7. + . List item 8. + +Labeled Lists +~~~~~~~~~~~~~ +Labeled list items consist of one or more text labels followed by the +text of the list item. + +An item label begins a line with an alphanumeric character hard +against the left margin and ends with two, three or four colons or two +semi-colons. A list item can have multiple labels, one per line. + +The list item text consists of one or more lines of text starting +after the last label (either on the same line or a new line) and can +be followed by nested List or ListParagraph elements. Item text can be +optionally indented. + +Here are some examples: + +--------------------------------------------------------------------- +In:: +Lorem:: + Fusce euismod commodo velit. + + Fusce euismod commodo velit. + +Ipsum:: Vivamus fringilla mi eu lacus. + * Vivamus fringilla mi eu lacus. + * Donec eget arcu bibendum nunc consequat lobortis. +Dolor:: + Donec eget arcu bibendum nunc consequat lobortis. + Suspendisse;; + A massa id sem aliquam auctor. + Morbi;; + Pretium nulla vel lorem. + In;; + Dictum mauris in urna. + Vivamus::: Fringilla mi eu lacus. + Donec::: Eget arcu bibendum nunc consequat lobortis. +--------------------------------------------------------------------- + +Which render as: + +In:: +Lorem:: + Fusce euismod commodo velit. + + Fusce euismod commodo velit. + +Ipsum:: Vivamus fringilla mi eu lacus. + * Vivamus fringilla mi eu lacus. + * Donec eget arcu bibendum nunc consequat lobortis. +Dolor:: + Donec eget arcu bibendum nunc consequat lobortis. + Suspendisse;; + A massa id sem aliquam auctor. + Morbi;; + Pretium nulla vel lorem. + In;; + Dictum mauris in urna. + Vivamus::: Fringilla mi eu lacus. + Donec::: Eget arcu bibendum nunc consequat lobortis. + +Horizontal labeled list style +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The 'horizontal' labeled list style (also the first positional +attribute) places the list text side-by-side with the label instead of +under the label. Here is an example: + +--------------------------------------------------------------------- +[horizontal] +*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est +labitur dolorum an. Est ne magna primis adolescens. + + Fusce euismod commodo velit. + +*Ipsum*:: Vivamus fringilla mi eu lacus. +- Vivamus fringilla mi eu lacus. +- Donec eget arcu bibendum nunc consequat lobortis. + +*Dolor*:: + - Vivamus fringilla mi eu lacus. + - Donec eget arcu bibendum nunc consequat lobortis. + +--------------------------------------------------------------------- + +Which render as: + +[horizontal] +*Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est +labitur dolorum an. Est ne magna primis adolescens. + + Fusce euismod commodo velit. + +*Ipsum*:: Vivamus fringilla mi eu lacus. +- Vivamus fringilla mi eu lacus. +- Donec eget arcu bibendum nunc consequat lobortis. + +*Dolor*:: + - Vivamus fringilla mi eu lacus. + - Donec eget arcu bibendum nunc consequat lobortis. + +[NOTE] +===================================================================== +- Current PDF toolchains do not make a good job of determining + the relative column widths for horizontal labeled lists. +- Nested horizontal labeled lists will generate DocBook validation + errors because the 'DocBook XML V4.2' DTD does not permit nested + informal tables (although <<X13,DocBook XSL Stylesheets>> and + <<X31,dblatex>> process them correctly). +- The label width can be set as a percentage of the total width by + setting the 'width' attribute e.g. `width="10%"` +===================================================================== + +Question and Answer Lists +~~~~~~~~~~~~~~~~~~~~~~~~~ +AsciiDoc comes pre-configured with a 'qanda' style labeled list for generating +DocBook question and answer (Q&A) lists. Example: + +--------------------------------------------------------------------- +[qanda] +Question one:: + Answer one. +Question two:: + Answer two. +--------------------------------------------------------------------- + +Renders: + +[qanda] +Question one:: + Answer one. +Question two:: + Answer two. + +Glossary Lists +~~~~~~~~~~~~~~ +AsciiDoc comes pre-configured with a 'glossary' style labeled list for +generating DocBook glossary lists. Example: + +--------------------------------------------------------------------- +[glossary] +A glossary term:: + The corresponding definition. +A second glossary term:: + The corresponding definition. +--------------------------------------------------------------------- + +For working examples see the `article.txt` and `book.txt` documents in +the AsciiDoc `./doc` distribution directory. + +NOTE: To generate valid DocBook output glossary lists must be located +in a section that uses the 'glossary' <<X93,section markup template>>. + +Bibliography Lists +~~~~~~~~~~~~~~~~~~ +AsciiDoc comes with a predefined 'bibliography' bulleted list style +generating DocBook bibliography entries. Example: + +--------------------------------------------------------------------- +[bibliography] +.Optional list title +- [[[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. +--------------------------------------------------------------------- + +The `[[[<reference>]]]` syntax is a bibliography entry anchor, it +generates an anchor named `<reference>` and additionally displays +`[<reference>]` at the anchor position. For example `[[[taoup]]]` +generates an anchor named `taoup` that displays `[taoup]` at the +anchor position. Cite the reference from elsewhere your document using +`<<taoup>>`, this displays a hyperlink (`[taoup]`) to the +corresponding bibliography entry anchor. + +For working examples see the `article.txt` and `book.txt` documents in +the AsciiDoc `./doc` distribution directory. + +NOTE: To generate valid DocBook output bibliography lists must be +located in a <<X93,bibliography section>>. + +[[X15]] +List Item Continuation +~~~~~~~~~~~~~~~~~~~~~~ +Another list or a literal paragraph immediately following a list item +is implicitly appended to the list item; to append other block +elements to a list item you need to explicitly join them to the list +item with a 'list continuation' (a separator line containing a single +plus character). Multiple block elements can be appended to a list +item using list continuations (provided they are legal list item +children in the backend markup). + +Here are some examples of list item continuations: list item one +contains multiple continuations; list item two is continued with an +<<X29,OpenBlock>> containing multiple elements: + +--------------------------------------------------------------------- +1. List item one. ++ +List item one continued with a second paragraph followed by an +Indented block. ++ +................. +$ ls *.sh +$ mv *.sh ~/tmp +................. ++ +List item continued with a third paragraph. + +2. List item two continued with an open block. ++ +-- +This paragraph is part of the preceding list item. + +a. This list is nested and does not require explicit item continuation. ++ +This paragraph is part of the preceding list item. + +b. List item b. + +This paragraph belongs to item two of the outer list. +-- +--------------------------------------------------------------------- + +Renders: + +1. List item one. ++ +List item one continued with a second paragraph followed by an +Indented block. ++ +................. +$ ls *.sh +$ mv *.sh ~/tmp +................. ++ +List item continued with a third paragraph. + +2. List item two continued with an open block. ++ +-- +This paragraph is part of the preceding list item. + +a. This list is nested and does not require explicit item continuation. ++ +This paragraph is part of the preceding list item. + +b. List item b. + +This paragraph belongs to item two of the outer list. +-- + + +[[X92]] +Footnotes +--------- +The shipped AsciiDoc configuration includes three footnote inline +macros: + +`footnote:[<text>]`:: + Generates a footnote with text `<text>`. + +`footnoteref:[<id>,<text>]`:: + Generates a footnote with a reference ID `<id>` and text `<text>`. + +`footnoteref:[<id>]`:: + Generates a reference to the footnote with ID `<id>`. + +The footnote text can span multiple lines. + +The 'xhtml11' and 'html5' backends render footnotes dynamically using +JavaScript; 'html4' outputs do not use JavaScript and leave the +footnotes inline; 'docbook' footnotes are processed by the downstream +DocBook toolchain. + +Example footnotes: + + A footnote footnote:[An example footnote.]; + a second footnote with a reference ID footnoteref:[note2,Second footnote.]; + finally a reference to the second footnote footnoteref:[note2]. + +Renders: + +A footnote footnote:[An example footnote.]; +a second footnote with a reference ID footnoteref:[note2,Second footnote.]; +finally a reference to the second footnote footnoteref:[note2]. + + +Indexes +------- +The shipped AsciiDoc configuration includes the inline macros for +generating DocBook index entries. + +`indexterm:[<primary>,<secondary>,<tertiary>]`:: +`(((<primary>,<secondary>,<tertiary>)))`:: + This inline macro generates an index term (the `<secondary>` and + `<tertiary>` positional attributes are optional). Example: + `indexterm:[Tigers,Big cats]` (or, using the alternative syntax + `(((Tigers,Big cats)))`. Index terms that have secondary and + tertiary entries also generate separate index terms for the + secondary and tertiary entries. The index terms appear in the + index, not the primary text flow. + +`indexterm2:[<primary>]`:: +`((<primary>))`:: + This inline macro generates an index term that appears in both the + index and the primary text flow. The `<primary>` should not be + padded to the left or right with white space characters. + +For working examples see the `article.txt` and `book.txt` documents in +the AsciiDoc `./doc` distribution directory. + +NOTE: Index entries only really make sense if you are generating +DocBook markup -- DocBook conversion programs automatically generate +an index at the point an 'Index' section appears in source document. + + +[[X105]] +Callouts +-------- +Callouts are a mechanism for annotating verbatim text (for example: +source code, computer output and user input). Callout markers are +placed inside the annotated text while the actual annotations are +presented in a callout list after the annotated text. Here's an +example: + +--------------------------------------------------------------------- + .MS-DOS directory listing + ----------------------------------------------------- + 10/17/97 9:04 <DIR> bin + 10/16/97 14:11 <DIR> DOS \<1> + 10/16/97 14:40 <DIR> Program Files + 10/16/97 14:46 <DIR> TEMP + 10/17/97 9:04 <DIR> tmp + 10/16/97 14:37 <DIR> WINNT + 10/16/97 14:25 119 AUTOEXEC.BAT \<2> + 2/13/94 6:21 54,619 COMMAND.COM \<2> + 10/16/97 14:25 115 CONFIG.SYS \<2> + 11/16/97 17:17 61,865,984 pagefile.sys + 2/13/94 6:21 9,349 WINA20.386 \<3> + ----------------------------------------------------- + + \<1> This directory holds MS-DOS. + \<2> System startup code for DOS. + \<3> Some sort of Windows 3.1 hack. +--------------------------------------------------------------------- + +Which renders: + +.MS-DOS directory listing +----------------------------------------------------- +10/17/97 9:04 <DIR> bin +10/16/97 14:11 <DIR> DOS <1> +10/16/97 14:40 <DIR> Program Files +10/16/97 14:46 <DIR> TEMP +10/17/97 9:04 <DIR> tmp +10/16/97 14:37 <DIR> WINNT +10/16/97 14:25 119 AUTOEXEC.BAT <2> + 2/13/94 6:21 54,619 COMMAND.COM <2> +10/16/97 14:25 115 CONFIG.SYS <2> +11/16/97 17:17 61,865,984 pagefile.sys + 2/13/94 6:21 9,349 WINA20.386 <3> +----------------------------------------------------- + +<1> This directory holds MS-DOS. +<2> System startup code for DOS. +<3> Some sort of Windows 3.1 hack. + +.Explanation +- The callout marks are whole numbers enclosed in angle brackets -- + they refer to the correspondingly numbered item in the following + callout list. +- By default callout marks are confined to 'LiteralParagraphs', + 'LiteralBlocks' and 'ListingBlocks' (although this is a + configuration file option and can be changed). +- Callout list item numbering is fairly relaxed -- list items can + start with `<n>`, `n>` or `>` where `n` is the optional list item + number (in the latter case list items starting with a single `>` + character are implicitly numbered starting at one). +- Callout lists should not be nested. +- Callout lists cannot be used within tables. +- Callout lists start list items hard against the left margin. +- If you want to present a number inside angle brackets you'll need to + escape it with a backslash to prevent it being interpreted as a + callout mark. + +NOTE: Define the AsciiDoc 'icons' attribute (for example using the `-a +icons` command-line option) to display callout icons. + +Implementation Notes +~~~~~~~~~~~~~~~~~~~~ +Callout marks are generated by the 'callout' inline macro while +callout lists are generated using the 'callout' list definition. The +'callout' macro and 'callout' list are special in that they work +together. The 'callout' inline macro is not enabled by the normal +'macros' substitutions option, instead it has its own 'callouts' +substitution option. + +The following attributes are available during inline callout macro +substitution: + +`{index}`:: + The callout list item index inside the angle brackets. +`{coid}`:: + An identifier formatted like `CO<listnumber>-<index>` that + uniquely identifies the callout mark. For example `CO2-4` + identifies the fourth callout mark in the second set of callout + marks. + +The `{coids}` attribute can be used during callout list item +substitution -- it is a space delimited list of callout IDs that refer +to the explanatory list item. + +Including callouts in included code +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can annotate working code examples with callouts -- just remember +to put the callouts inside source code comments. This example displays +the `test.py` source file (containing a single callout) using the +'source' (code highlighter) filter: + +.AsciiDoc source +--------------------------------------------------------------------- + [source,python] + ------------------------------------------- + \include::test.py[] + ------------------------------------------- + + \<1> Print statement. +--------------------------------------------------------------------- + +.Included `test.py` source +--------------------------------------------------------------------- +print 'Hello World!' # \<1> +--------------------------------------------------------------------- + + +Macros +------ +Macros are a mechanism for substituting parametrized text into output +documents. + +Macros have a 'name', a single 'target' argument and an 'attribute +list'. The usual syntax is `<name>:<target>[<attrlist>]` (for +inline macros) and `<name>::<target>[<attrlist>]` (for block +macros). Here are some examples: + + https://docbook.org/[DocBook.org] + include::chapt1.txt[tabsize=2] + mailto:srackham@gmail.com[] + +.Macro behavior +- `<name>` is the macro name. It can only contain letters, digits or + dash characters and cannot start with a dash. +- The optional `<target>` cannot contain white space characters. +- `<attrlist>` is a <<X21,list of attributes>> enclosed in square + brackets. +- `]` characters inside attribute lists must be escaped with a + backslash. +- Expansion of macro references can normally be escaped by prefixing a + backslash character (see the AsciiDoc 'FAQ' for examples of + exceptions to this rule). +- Attribute references in block macros are expanded. +- The substitutions performed prior to Inline macro macro expansion + are determined by the inline context. +- Macros are processed in the order they appear in the configuration + file(s). +- Calls to inline macros can be nested inside different inline macros + (an inline macro call cannot contain a nested call to itself). +- In addition to `<name>`, `<target>` and `<attrlist>` the + `<passtext>` and `<subslist>` named groups are available to + <<X77,passthrough macros>>. A macro is a passthrough macro if the + definition includes a `<passtext>` named group. + +Inline Macros +~~~~~~~~~~~~~ +Inline Macros occur in an inline element context. Predefined Inline +macros include 'URLs', 'image' and 'link' macros. + +URLs +^^^^ +'http', 'https', 'ftp', 'file', 'mailto' and 'callto' URLs are +rendered using predefined inline macros. + +- If you don't need a custom link caption you can enter the 'http', + 'https', 'ftp', 'file' URLs and email addresses without any special + macro syntax. +- If the `<attrlist>` is empty the URL is displayed. + +Here are some examples: + + https://docbook.org/[DocBook.org] + https://docbook.org/ + mailto:joe.bloggs@foobar.com[email Joe Bloggs] + joe.bloggs@foobar.com + +Which are rendered: + +https://docbook.org/[DocBook.org] + +https://docbook.org/ + +mailto:joe.bloggs@foobar.com[email Joe Bloggs] + +joe.bloggs@foobar.com + +If the `<target>` necessitates space characters use `%20`, for example +`large%20image.png`. + +Internal Cross References +^^^^^^^^^^^^^^^^^^^^^^^^^ +Two AsciiDoc inline macros are provided for creating hypertext links +within an AsciiDoc document. You can use either the standard macro +syntax or the (preferred) alternative. + +[[X30]] +anchor +++++++ +Used to specify hypertext link targets: + + [[<id>,<xreflabel>]] + anchor:<id>[<xreflabel>] + +The `<id>` is a unique string that conforms to the output markup's +anchor syntax. The optional `<xreflabel>` is the text to be displayed +by captionless 'xref' macros that refer to this anchor. The optional +`<xreflabel>` is only really useful when generating DocBook output. +Example anchor: + + [[X1]] + +You may have noticed that the syntax of this inline element is the +same as that of the <<X41,BlockId block element>>, this is no +coincidence since they are functionally equivalent. + +xref +++++ +Creates a hypertext link to a document anchor. + + <<<id>,<caption>>> + xref:<id>[<caption>] + +The `<id>` refers to an anchor ID. The optional `<caption>` is the +link's displayed text. Example: + + <<X21,attribute lists>> + +If `<caption>` is not specified then the displayed text is +auto-generated: + +- The AsciiDoc 'xhtml11' and 'html5' backends display the `<id>` + enclosed in square brackets. +- If DocBook is produced the DocBook toolchain is responsible for the + displayed text which will normally be the referenced figure, table + or section title number followed by the element's title text. + +Here is an example: + +--------------------------------------------------------------------- +[[tiger_image]] +.Tyger tyger +image::tiger.png[] + +This can be seen in <<tiger_image>>. +--------------------------------------------------------------------- + +Linking to Local Documents +^^^^^^^^^^^^^^^^^^^^^^^^^^ +Hypertext links to files on the local file system are specified using +the 'link' inline macro. + + link:<target>[<caption>] + +The 'link' macro generates relative URLs. The link macro `<target>` is +the target file name (relative to the file system location of the +referring document). The optional `<caption>` is the link's displayed +text. If `<caption>` is not specified then `<target>` is displayed. +Example: + + link:downloads/foo.zip[download foo.zip] + +You can use the `<filename>#<id>` syntax to refer to an anchor within +a target document but this usually only makes sense when targeting +HTML documents. + +[[X9]] +Images +^^^^^^ +Inline images are inserted into the output document using the 'image' +macro. The inline syntax is: + + image:<target>[<attributes>] + +The contents of the image file `<target>` is displayed. To display the +image its file format must be supported by the target backend +application. HTML and DocBook applications normally support PNG or JPG +files. + +`<target>` file name paths are relative to the location of the +referring document. + +[[X55]] +.Image macro attributes +- The optional 'alt' attribute is also the first positional attribute, + it specifies alternative text which is displayed if the output + application is unable to display the image file (see also + https://htmlhelp.com/feature/art3.htm[Use of ALT texts in IMGs]). For + example: + + image:images/logo.png[Company Logo] + +- The optional 'title' attribute provides a title for the image. The + <<X49,block image macro>> renders the title alongside the image. + The inline image macro displays the title as a popup ``tooltip'' in + visual browsers (AsciiDoc HTML outputs only). + +- The optional `width` and `height` attributes scale the image size + and can be used in any combination. The units are pixels. The + following example scales the previous example to a height of 32 + pixels: + + image:images/logo.png["Company Logo",height=32] + +- The optional `link` attribute is used to link the image to an + external document. The following example links a screenshot + thumbnail to a full size version: + + image:screen-thumbnail.png[height=32,link="screen.png"] + +- The optional `scaledwidth` attribute is only used in DocBook block + images (specifically for PDF documents). The following example + scales the images to 75% of the available print width: + + image::images/logo.png[scaledwidth="75%",alt="Company Logo"] + +- The image `scale` attribute sets the DocBook `imagedata` element + `scale` attribute. + +- The optional `align` attribute aligns block macro images + horizontally. Allowed values are `center`, `left` and `right`. For + example: + + image::images/tiger.png["Tiger image",align="left"] + +- The optional `float` attribute floats the image `left` or `right` on + the page (works with HTML outputs only, has no effect on DocBook + outputs). `float` and `align` attributes are mutually exclusive. + Use the `unfloat::[]` block macro to stop floating. + +Comment Lines +^^^^^^^^^^^^^ +See <<X25,comment block macro>>. + +Block Macros +~~~~~~~~~~~~ +A Block macro reference must be contained in a single line separated +either side by a blank line or a block delimiter. + +Block macros behave just like Inline macros, with the following +differences: + +- They occur in a block context. +- The default syntax is `<name>::<target>[<attrlist>]` (two + colons, not one). +- Markup template section names end in `-blockmacro` instead of + `-inlinemacro`. + +Block Identifier +^^^^^^^^^^^^^^^^ +The Block Identifier macro sets the `id` attribute and has the same +syntax as the <<X30,anchor inline macro>> since it performs +essentially the same function -- block templates use the `id` +attribute as a block element ID. For example: + + [[X30]] + +This is equivalent to the `[id="X30"]` <<X79,AttributeList element>>). + +[[X49]] +Images +^^^^^^ +The 'image' block macro is used to display images in a block context. +The syntax is: + + image::<target>[<attributes>] + +The block `image` macro has the same <<X55,macro attributes>> as it's +<<X9,inline image macro>> counterpart. + +WARNING: Unlike the inline `image` macro, the entire block `image` macro +must be on a single line. + +Block images can be titled by preceding the 'image' macro with a +'BlockTitle'. DocBook toolchains normally number titled block images +and optionally list them in an automatically generated 'List of +Figures' backmatter section. + +This example: + + .Main circuit board + image::images/layout.png[J14P main circuit board] + +is equivalent to: + + image::images/layout.png["J14P main circuit board", title="Main circuit board"] + +A title prefix that can be inserted with the `caption` attribute +(HTML backends). For example: + + .Main circuit board + [caption="Figure 2: "] + image::images/layout.png[J14P main circuit board] + +[[X66]] +.Embedding images in XHTML documents +********************************************************************* +If you define the `data-uri` attribute then images will be embedded in +XHTML outputs using the +https://en.wikipedia.org/wiki/Data_URI_scheme[data URI scheme]. You +can use the 'data-uri' attribute with the 'xhtml11' and 'html5' +backends to produce single-file XHTML documents with embedded images +and CSS, for example: + + $ asciidoc -a data-uri mydocument.txt + +[NOTE] +====== +- All current popular browsers support data URIs, although versions + of Internet Explorer prior to version 8 do not. +- Some browsers limit the size of data URIs. +====== +********************************************************************* + +[[X25]] +Comment Lines +^^^^^^^^^^^^^ +Single lines starting with two forward slashes hard up against the +left margin are treated as comments. Comment lines do not appear in +the output unless the 'showcomments' attribute is defined. Comment +lines have been implemented as both block and inline macros so a +comment line can appear as a stand-alone block or within block elements +that support inline macro expansion. Example comment line: + + // This is a comment. + +If the 'showcomments' attribute is defined comment lines are written +to the output: + +- In DocBook the comment lines are enclosed by the 'remark' element + (which may or may not be rendered by your toolchain). +- The 'showcomments' attribute does not expose <<X26,Comment Blocks>>. + Comment Blocks are never passed to the output. + +System Macros +~~~~~~~~~~~~~ +System macros are block macros that perform a predefined task and are +hardwired into the asciidoc(1) program. + +- You can escape system macros with a leading backslash character + (as you can with other macros). +- The syntax and tasks performed by system macros is built into + asciidoc(1) so they don't appear in configuration files. You can + however customize the syntax by adding entries to a configuration + file `[macros]` section. + +[[X63]] +Include Macros +^^^^^^^^^^^^^^ +The `include` and `include1` system macros to include the contents of +a named file into the source document. + +The `include` macro includes a file as if it were part of the parent +document -- tabs are expanded and system macros processed. The +contents of `include1` files are not subject to tab expansion or +system macro processing nor are attribute or lower priority +substitutions performed. The `include1` macro's intended use is to +include verbatim embedded CSS or scripts into configuration file +headers. Example: + +------------------------------------ +\include::chapter1.txt[tabsize=4] +------------------------------------ + +.Include macro behavior +- If the included file name is specified with a relative path then the + path is relative to the location of the referring document. +- Include macros can appear inside configuration files. +- Files included from within 'DelimitedBlocks' are read to completion + to avoid false end-of-block underline termination. +- Attribute references are expanded inside the include 'target'; if an + attribute is undefined then the included file is silently skipped. +- The 'tabsize' macro attribute sets the number of space characters to + be used for tab expansion in the included file (not applicable to + `include1` macro). +- The 'depth' macro attribute sets the maximum permitted number of + subsequent nested includes (not applicable to `include1` macro which + does not process nested includes). Setting 'depth' to '1' disables + nesting inside the included file. By default, nesting is limited to + a depth of ten. +- The `lines` macro attribute can be used to include specific lines of + the file. You can specify a range of pages by using `..` between + the two numbers, for example `1..10` would include the first 10 + lines. You can include multiple ranges or invdividual pages by using + a comma or semi-colon, for example `1..10,45,50..60`. +- If the 'warnings' attribute is set to 'False' (or any other + Python literal that evaluates to boolean false) then no warning + message is printed if the included file does not exist. By default + 'warnings' are enabled. +- 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. To inhibit nested substitution in + included files it is preferable to use the `include` macro and set + the attribute `depth=1`. + +Conditional Inclusion Macros +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Lines of text in the source document can be selectively included or +excluded from processing based on the existence (or not) of a document +attribute. + +Document text between the `ifdef` and `endif` macros is included if a +document attribute is defined: + + ifdef::<attribute>[] + : + endif::<attribute>[] + +Document text between the `ifndef` and `endif` macros is not included +if a document attribute is defined: + + ifndef::<attribute>[] + : + endif::<attribute>[] + +`<attribute>` is an attribute name which is optional in the trailing +`endif` macro. + +If you only want to process a single line of text then the text can be +put inside the square brackets and the `endif` macro omitted, for +example: + + ifdef::revnumber[Version number 42] + +Is equivalent to: + + ifdef::revnumber[] + Version number 42 + endif::revnumber[] + +'ifdef' and 'ifndef' macros also accept multiple attribute names: + +- Multiple ',' separated attribute names evaluate to defined if one + or more of the attributes is defined, otherwise it's value is + undefined. +- Multiple '+' separated attribute names evaluate to defined if all + of the attributes is defined, otherwise it's value is undefined. + +Document text between the `ifeval` and `endif` macros is included if +the Python expression inside the square brackets is true. Example: + + ifeval::[{rs458}==2] + : + endif::[] + +- Document attribute references are expanded before the expression is + evaluated. +- If an attribute reference is undefined then the expression is + considered false. + +Take a look at the `*.conf` configuration files in the AsciiDoc +distribution for examples of conditional inclusion macro usage. + +Executable system macros +^^^^^^^^^^^^^^^^^^^^^^^^ +The 'eval', 'sys' and 'sys2' block macros exhibit the same behavior as +their same named <<X24, system attribute references>>. The difference +is that system macros occur in a block macro context whereas system +attributes are confined to inline contexts where attribute +substitution is enabled. + +The following example displays a long directory listing inside a +literal block: + + ------------------ + sys::[ls -l *.txt] + ------------------ + +NOTE: There are no block macro versions of the 'eval3' and 'sys3' +system attributes. + +Template System Macro +^^^^^^^^^^^^^^^^^^^^^ +The `template` block macro allows the inclusion of one configuration +file template section within another. The following example includes +the `[admonitionblock]` section in the `[admonitionparagraph]` +section: + + [admonitionparagraph] + template::[admonitionblock] + +.Template macro behavior +- The `template::[]` macro is useful for factoring configuration file + markup. +- `template::[]` macros cannot be nested. +- `template::[]` macro expansion is applied after all configuration + files have been read. + + +[[X77]] +Passthrough macros +~~~~~~~~~~~~~~~~~~ +Passthrough macros are analogous to <<X76,passthrough blocks>> and are +used to pass text directly to the output. The substitution performed +on the text is determined by the macro definition but can be overridden +by the `<subslist>`. The usual syntax is +`<name>:<subslist>[<passtext>]` (for inline macros) and +`<name>::<subslist>[<passtext>]` (for block macros). Passthroughs, by +definition, take precedence over all other text substitutions. + +pass:: + Inline and block. Passes text unmodified (apart from explicitly + specified substitutions). Examples: + + pass:[<q>To be or not to be</q>] + pass:attributes,quotes[<u>the '{author}'</u>] + +asciimath, latexmath:: + Inline and block. Passes text unmodified. Used for + <<X78,mathematical formulas>>. + +\+++:: + Inline and block. The triple-plus passthrough is functionally + identical to the 'pass' macro but you don't have to escape `]` + characters and you can prefix with quoted attributes in the inline + version. Example: + + Red [red]+++`sum_(i=1)\^n i=(n(n+1))/2`$+++ AsciiMath formula + +$$:: + Inline and block. The double-dollar passthrough is functionally + identical to the triple-plus passthrough with one exception: special + characters are escaped. Example: + + $$`[[a,b],[c,d]]((n),(k))`$$ + +[[X80]]`:: + Text quoted with single backtick characters constitutes an 'inline + literal' passthrough. The enclosed text is rendered in a monospaced + font and is only subject to special character substitution. This + makes sense since monospace text is usually intended to be rendered + literally and often contains characters that would otherwise have to + be escaped. If you need monospaced text containing inline + substitutions use a <<X81,plus character instead of a backtick>>. + +Macro Definitions +~~~~~~~~~~~~~~~~~ +Each entry in the configuration `[macros]` section is a macro +definition which can take one of the following forms: + +`<pattern>=<name>[<subslist]`:: Inline macro definition. +`<pattern>=#<name>[<subslist]`:: Block macro definition. +`<pattern>=+<name>[<subslist]`:: System macro definition. +`<pattern>`:: Delete the existing macro with this `<pattern>`. + +`<pattern>` is a Python regular expression and `<name>` is the name of +a markup template. If `<name>` is omitted then it is the value of the +regular expression match group named 'name'. The optional +`[<subslist]` is a comma-separated list of substitution names enclosed +in `[]` brackets, it sets the default substitutions for passthrough +text, if omitted then no passthrough substitutions are performed. + +.Pattern named groups +The following named groups can be used in macro `<pattern>` regular +expressions and are available as markup template attributes: + +name:: + The macro name. + +target:: + The macro target. + +attrlist:: + The macro attribute list. + +passtext:: + Contents of this group are passed unmodified to the output subject + only to 'subslist' substitutions. + +subslist:: + Processed as a comma-separated list of substitution names for + 'passtext' substitution, overrides the the macro definition + 'subslist'. + +.Here's what happens during macro substitution +- Each contextually relevant macro 'pattern' from the `[macros]` + section is matched against the input source line. +- If a match is found the text to be substituted is loaded from a + configuration markup template section named like + `<name>-inlinemacro` or `<name>-blockmacro` (depending on the macro + type). +- Global and macro attribute list attributes are substituted in the + macro's markup template. +- The substituted template replaces the macro reference in the output + document. + + +[[X98]] +HTML 5 audio and video block macros +----------------------------------- +The 'html5' backend 'audio' and 'video' block macros generate the HTML +5 'audio' and 'video' elements respectively. They follow the usual +AsciiDoc block macro syntax `<name>::<target>[<attrlist>]` where: + +[horizontal] +`<name>`:: 'audio' or 'video'. +`<target>`:: The URL or file name of the video or audio file. +`<attrlist>`:: A list of named attributes (see below). + +.Audio macro attributes +[options="header",cols="1,5",frame="topbot"] +|==================================================================== +|Name | Value +|options +|A comma separated list of one or more of the following items: +'autoplay', 'loop' which correspond to the same-named HTML 5 'audio' +element boolean attributes. By default the player 'controls' are +enabled, include the 'nocontrols' option value to hide them. +|==================================================================== + +.Video macro attributes +[options="header",cols="1,5",frame="topbot"] +|==================================================================== +|Name | Value +|height | The height of the player in pixels. +|width | The width of the player in pixels. +|poster | The URL or file name of an image representing the video. +|options +|A comma separated list of one or more of the following items: +'autoplay', 'loop' and 'nocontrols'. The 'autoplay' and 'loop' options +correspond to the same-named HTML 5 'video' element boolean +attributes. By default the player 'controls' are enabled, include the +'nocontrols' option value to hide them. +|==================================================================== + +Examples: + +--------------------------------------------------------------------- +audio::images/example.ogg[] + +video::gizmo.ogv[width=200,options="nocontrols,autoplay"] + +.Example video +video::gizmo.ogv[] + +video::http://www.808.dk/pics/video/gizmo.ogv[] +--------------------------------------------------------------------- + +If your needs are more complex put raw HTML 5 in a markup block, for +example (from http://www.808.dk/?code-html-5-video): + +--------------------------------------------------------------------- +++++ +<video poster="pics/video/gizmo.jpg" id="video" style="cursor: pointer;" > + <source src="pics/video/gizmo.mp4" /> + <source src="pics/video/gizmo.webm" type="video/webm" /> + <source src="pics/video/gizmo.ogv" type="video/ogg" /> + Video not playing? <a href="pics/video/gizmo.mp4">Download file</a> instead. +</video> + +<script type="text/javascript"> + var video = document.getElementById('video'); + video.addEventListener('click',function(){ + video.play(); + },false); +</script> +++++ +--------------------------------------------------------------------- + + +Tables +------ +The AsciiDoc table syntax looks and behaves like other delimited block +types and supports standard <<X73,block configuration entries>>. +Formatting is easy to read and, just as importantly, easy to enter. + +- Cells and columns can be formatted using built-in customizable styles. +- Horizontal and vertical cell alignment can be set on columns and + cell. +- Horizontal and vertical cell spanning is supported. + +.Use tables sparingly +********************************************************************* +When technical users first start creating documents, tables (complete +with column spanning and table nesting) are often considered very +important. The reality is that tables are seldom used, even in +technical documentation. + +Try this exercise: thumb through your library of technical books, +you'll be surprised just how seldom tables are actually used, even +less seldom are tables containing block elements (such as paragraphs +or lists) or spanned cells. This is no accident, like figures, tables +are outside the normal document flow -- tables are for consulting not +for reading. + +Tables are designed for, and should normally only be used for, +displaying column oriented tabular data. +********************************************************************* + +Example tables +~~~~~~~~~~~~~~ + +.Simple table +[width="15%"] +|======= +|1 |2 |A +|3 |4 |B +|5 |6 |C +|======= + +.AsciiDoc source +--------------------------------------------------------------------- +[width="15%"] +|======= +|1 |2 |A +|3 |4 |B +|5 |6 |C +|======= +--------------------------------------------------------------------- + +.Columns formatted with strong, monospaced and emphasis styles +[width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"] +|========================== +| 2+|Columns 2 and 3 +|1 |Item 1 |Item 1 +|2 |Item 2 |Item 2 +|3 |Item 3 |Item 3 +|4 |Item 4 |Item 4 +|footer 1|footer 2|footer 3 +|========================== + +.AsciiDoc source +--------------------------------------------------------------------- +.An example table +[width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"] +|========================== +| 2+|Columns 2 and 3 +|1 |Item 1 |Item 1 +|2 |Item 2 |Item 2 +|3 |Item 3 |Item 3 +|4 |Item 4 |Item 4 +|footer 1|footer 2|footer 3 +|========================== +--------------------------------------------------------------------- + +.Horizontal and vertical source data +[width="80%",cols="3,^2,^2,10",options="header"] +|========================================================= +|Date |Duration |Avg HR |Notes + +|22-Aug-08 |10:24 | 157 | +Worked out MSHR (max sustainable heart rate) by going hard +for this interval. + +|22-Aug-08 |23:03 | 152 | +Back-to-back with previous interval. + +|24-Aug-08 |40:00 | 145 | +Moderately hard interspersed with 3x 3min intervals (2min +hard + 1min really hard taking the HR up to 160). + +|========================================================= + +Short cells can be entered horizontally, longer cells vertically. The +default behavior is to strip leading and trailing blank lines within a +cell. These characteristics aid readability and data entry. + +.AsciiDoc source +--------------------------------------------------------------------- +.Windtrainer workouts +[width="80%",cols="3,^2,^2,10",options="header"] +|========================================================= +|Date |Duration |Avg HR |Notes + +|22-Aug-08 |10:24 | 157 | +Worked out MSHR (max sustainable heart rate) by going hard +for this interval. + +|22-Aug-08 |23:03 | 152 | +Back-to-back with previous interval. + +|24-Aug-08 |40:00 | 145 | +Moderately hard interspersed with 3x 3min intervals (2min +hard + 1min really hard taking the HR up to 160). + +|========================================================= +--------------------------------------------------------------------- + +.A table with externally sourced CSV data +[format="csv",cols="^1,4*2",options="header"] +|=================================================== +ID,Customer Name,Contact Name,Customer Address,Phone +include::customers.csv[] +|=================================================== + +.AsciiDoc source +--------------------------------------------------------------------- +[format="csv",cols="^1,4*2",options="header"] +|=================================================== +ID,Customer Name,Contact Name,Customer Address,Phone +\include::customers.csv[] +|=================================================== +--------------------------------------------------------------------- + + +.Cell spans, alignments and styles +[cols="e,m,^,>s",width="25%"] +|============================ +|1 >s|2 |3 |4 +^|5 2.2+^.^|6 .3+<.>m|7 +^|8 +|9 2+>|10 +|============================ + +.AsciiDoc source +--------------------------------------------------------------------- +[cols="e,m,^,>s",width="25%"] +|============================ +|1 >s|2 |3 |4 +^|5 2.2+^.^|6 .3+<.>m|7 +^|8 +|9 2+>|10 +|============================ +--------------------------------------------------------------------- + +[[X68]] +Table input data formats +~~~~~~~~~~~~~~~~~~~~~~~~ +AsciiDoc table data can be 'psv', 'dsv' or 'csv' formatted. The +default table format is 'psv'. + +AsciiDoc 'psv' ('Prefix Separated Values') and 'dsv' ('Delimiter +Separated Values') formats are cell oriented -- the table is treated +as a sequence of cells -- there are no explicit row separators. + +- 'psv' prefixes each cell with a separator whereas 'dsv' delimits + cells with a separator. +- 'psv' and 'dsv' separators are Python regular expressions. +- The default 'psv' separator contains <<X84, cell specifier>> related + named regular expression groups. +- The default 'dsv' separator is `:|\n` (a colon or a new line + character). +- 'psv' and 'dsv' cell separators can be escaped by preceding them + with a backslash character. + +Here are four 'psv' cells (the second item spans two columns; the +last contains an escaped separator): + + |One 2+|Two and three |A \| separator character + +'csv' is the quasi-standard row oriented 'Comma Separated Values +(CSV)' format commonly used to import and export spreadsheet and +database data. + +[[X69]] +Table attributes +~~~~~~~~~~~~~~~~ +Tables can be customized by the following attributes: + +format:: +'psv' (default), 'dsv' or 'csv' (See <<X68, Table Data Formats>>). + +separator:: +The cell separator. A Python regular expression ('psv' and 'dsv' +formats) or a single character ('csv' format). + +frame:: +Defines the table border and can take the following values: 'topbot' +(top and bottom), 'all' (all sides), 'none' and 'sides' (left and +right sides). The default value is 'all'. + +grid:: +Defines which ruler lines are drawn between table rows and columns. +The 'grid' attribute value can be any of the following values: 'none', +'cols', 'rows' and 'all'. The default value is 'all'. + +align:: +Use the 'align' attribute to horizontally align the table on the +page (works with HTML outputs only, has no effect on DocBook outputs). +The following values are valid: 'left', 'right', and 'center'. + +float:: +Use the 'float' attribute to float the table 'left' or 'right' on the +page (works with HTML outputs only, has no effect on DocBook outputs). +Floating only makes sense in conjunction with a table 'width' +attribute value of less than 100% (otherwise the table will take up +all the available space). 'float' and 'align' attributes are mutually +exclusive. Use the `unfloat::[]` block macro to stop floating. + +halign:: +Use the 'halign' attribute to horizontally align all cells in a table. +The following values are valid: 'left', 'right', and 'center' +(defaults to 'left'). Overridden by <<X70,Column specifiers>> and +<<X84,Cell specifiers>>. + +valign:: +Use the 'valign' attribute to vertically align all cells in a table. +The following values are valid: 'top', 'bottom', and 'middle' +(defaults to 'top'). Overridden by <<X70,Column specifiers>> and +<<X84,Cell specifiers>>. + +options:: +The 'options' attribute can contain comma separated values, for +example: 'header', 'footer'. By default header and footer rows are +omitted. See <<X74,attribute options>> for a complete list of +available table options. + +cols:: +The 'cols' attribute is a comma separated list of <<X70,column +specifiers>>. For example `cols="2<p,2*,4p,>"`. + +- If 'cols' is present it must specify all columns. +- If the 'cols' attribute is not specified the number of columns is + calculated as the number of data items in the *first line* of the + table. +- The degenerate form for the 'cols' attribute is an integer + specifying the number of columns e.g. `cols=4`. + +width:: +The 'width' attribute is expressed as a percentage value +('"1%"'...'"99%"'). The width specifies the table width relative to +the available width. HTML backends use this value to set the table +width attribute. It's a bit more complicated with DocBook, see the +<<X89,DocBook table widths>> sidebar. + +filter:: +The 'filter' attribute defines an external shell command that is +invoked for each cell. The built-in 'asciidoc' table style is +implemented using a filter. + +[[X89]] +.DocBook table widths +********************************************************************** +The AsciiDoc docbook backend generates CALS tables. CALS tables do not +support a table width attribute -- table width can only be controlled +by specifying absolute column widths. + +Specifying absolute column widths is not media independent because +different presentation media have different physical dimensions. To +get round this limitation both +http://www.sagehill.net/docbookxsl/Tables.html#TableWidth[DocBook XSL +Stylesheets] and +http://dblatex.sourceforge.net/doc/manual/ch03s05.html#sec-table-width[dblatex] +have implemented table width processing instructions for setting the +table width as a percentage of the available width. AsciiDoc emits +these processing instructions if the 'width' attribute is set along +with proportional column widths (the AsciiDoc docbook backend +'pageunits' attribute defaults to '*'). + +To generate DocBook tables with absolute column widths set the +'pageunits' attribute to a CALS absolute unit such as 'pt' and set the +'pagewidth' attribute to match the width of the presentation media. +********************************************************************** + +[[X70]] +Column Specifiers +~~~~~~~~~~~~~~~~~ +Column specifiers define how columns are rendered and appear in the +table <<X69,cols attribute>>. A column specifier consists of an +optional column multiplier followed by optional alignment, width and +style values and is formatted like: + + [<multiplier>*][<align>][<width>][<style>] + +- All components are optional. The multiplier must be first and the + style last. The order of `<align>` or `<width>` is not important. +- Column `<width>` can be either an integer proportional value (1...) + or a percentage (1%...100%). The default value is 1. To ensure + portability across different backends, there is no provision for + absolute column widths (not to be confused with output column width + <<X72,markup attributes>> which are available in both percentage and + absolute units). +- The '<align>' column alignment specifier is formatted like: + + [<horizontal>][.<vertical>] ++ +Where `<horizontal>` and `<vertical>` are one of the following +characters: `<`, `^` or `>` which represent 'left', 'center' and +'right' horizontal alignment or 'top', 'middle' and 'bottom' vertical +alignment respectively. + +- A `<multiplier>` can be used to specify repeated columns e.g. + `cols="4*<"` specifies four left-justified columns. The default + multiplier value is 1. +- The `<style>` name specifies a <<X71,table style>> to used to markup + column cells (you can use the full style names if you wish but the + first letter is normally sufficient). +- Column specific styles are not applied to header rows. + +[[X84]] +Cell Specifiers +~~~~~~~~~~~~~~~ +Cell specifiers allow individual cells in 'psv' formatted tables to be +spanned, multiplied, aligned and styled. Cell specifiers prefix 'psv' +`|` delimiters and are formatted like: + + [<span>*|+][<align>][<style>] + +- '<span>' specifies horizontal and vertical cell spans ('+' operator) or + the number of times the cell is replicated ('*' operator). '<span>' + is formatted like: + + [<colspan>][.<rowspan>] ++ +Where `<colspan>` and `<rowspan>` are integers specifying the number of +columns and rows to span. + +- `<align>` specifies horizontal and vertical cell alignment an is the + same as in <<X70,column specifiers>>. +- A `<style>` value is the first letter of <<X71,table style>> name. + +For example, the following 'psv' formatted cell will span two columns +and the text will be centered and emphasized: + + `2+^e| Cell text` + +[[X71]] +Table styles +~~~~~~~~~~~~ +Table styles can be applied to the entire table (by setting the +'style' attribute in the table's attribute list) or on a per column +basis (by specifying the style in the table's <<X69,cols attribute>>). +Table data can be formatted using the following predefined styles: + +default:: +The default style: AsciiDoc inline text formatting; blank lines are +treated as paragraph breaks. + +emphasis:: +Like default but all text is emphasised. + +monospaced:: +Like default but all text is in a monospaced font. + +strong:: +Like default but all text is bold. + +header:: +Apply the same style as the table header. Normally used to create a +vertical header in the first column. + +asciidoc:: +With this style table cells can contain any of the AsciiDoc elements +that are allowed inside document sections. This style runs asciidoc(1) +as a filter to process cell contents. See also <<X83,Docbook table +limitations>>. + +literal:: +No text formatting; monospaced font; all line breaks are retained +(the same as the AsciiDoc <<X65,LiteralBlock>> element). + +verse:: +All line breaks are retained (just like the AsciiDoc <<X94,verse +paragraph style>>). + +[[X72]] +Markup attributes +~~~~~~~~~~~~~~~~~ +AsciiDoc makes a number of attributes available to table markup +templates and tags. Column specific attributes are available when +substituting the 'colspec' cell data tags. + +pageunits:: +DocBook backend only. Specifies table column absolute width units. +Defaults to '*'. + +pagewidth:: +DocBook backend only. The nominal output page width in 'pageunit' +units. Used to calculate CALS tables absolute column and table +widths. Defaults to '425'. + +tableabswidth:: +Integer value calculated from 'width' and 'pagewidth' attributes. +In 'pageunit' units. + +tablepcwidth:: +Table width expressed as a percentage of the available width. Integer +value (0..100). + +colabswidth:: +Integer value calculated from 'cols' column width, 'width' and +'pagewidth' attributes. In 'pageunit' units. + +colpcwidth:: +Column width expressed as a percentage of the table width. Integer +value (0..100). + +colcount:: +Total number of table columns. + +rowcount:: +Total number of table rows. + +halign:: +Horizontal cell content alignment: 'left', 'right' or 'center'. + +valign:: +Vertical cell content alignment: 'top', 'bottom' or 'middle'. + +colnumber, colstart:: +The number of the leftmost column occupied by the cell (1...). + +colend:: +The number of the rightmost column occupied by the cell (1...). + +colspan:: +Number of columns the cell should span. + +rowspan:: +Number of rows the cell should span (1...). + +morerows:: +Number of additional rows the cell should span (0...). + +Nested tables +~~~~~~~~~~~~~ +An alternative 'psv' separator character '!' can be used (instead of +'|') in nested tables. This allows a single level of table nesting. +Columns containing nested tables must use the 'asciidoc' style. An +example can be found in `./examples/website/newtables.txt`. + +[[X83]] +DocBook table limitations +~~~~~~~~~~~~~~~~~~~~~~~~~ +Fully implementing tables is not trivial, some DocBook toolchains do +better than others. AsciiDoc HTML table outputs are rendered +correctly in all the popular browsers -- if your DocBook generated +tables don't look right compare them with the output generated by the +AsciiDoc 'xhtml11' backend or try a different DocBook toolchain. Here +is a list of things to be aware of: + +- Although nested tables are not legal in DocBook 4 the FOP and + dblatex toolchains will process them correctly. If you use `a2x(1)` + you will need to include the `--no-xmllint` option to suppress + DocBook validation errors. ++ +NOTE: In theory you can nest DocBook 4 tables one level using the +'entrytbl' element, but not all toolchains process 'entrytbl'. + +- DocBook only allows a subset of block elements inside table cells so + not all AsciiDoc elements produce valid DocBook inside table cells. + If you get validation errors running `a2x(1)` try the `--no-xmllint` + option, toolchains will often process nested block elements such as + sidebar blocks and floating titles correctly even though, strictly + speaking, they are not legal. + +- Text formatting in cells using the 'monospaced' table style will + raise validation errors because the DocBook 'literal' element was + not designed to support formatted text (using the 'literal' element + is a kludge on the part of AsciiDoc as there is no easy way to set + the font style in DocBook. + +- Cell alignments are ignored for 'verse', 'literal' or 'asciidoc' + table styles. + + +[[X1]] +Manpage Documents +----------------- +Sooner or later, if you program in a UNIX environment, you're going +to have to write a man page. + +By observing a couple of additional conventions (detailed below) you +can write AsciiDoc files that will generate HTML and PDF man pages +plus the native manpage roff format. The easiest way to generate roff +manpages from AsciiDoc source is to use the a2x(1) command. The +following example generates a roff formatted manpage file called +`asciidoc.1` (a2x(1) uses asciidoc(1) to convert `asciidoc.1.txt` to +DocBook which it then converts to roff using DocBook XSL Stylesheets): + + a2x --doctype manpage --format manpage asciidoc.1.txt + +.Viewing and printing manpage files +********************************************************************** +Use the `man(1)` command to view the manpage file: + + $ man -l asciidoc.1 + +To print a high quality man page to a postscript printer: + + $ man -l -Tps asciidoc.1 | lpr + +You could also create a PDF version of the man page by converting +PostScript to PDF using `ps2pdf(1)`: + + $ man -l -Tps asciidoc.1 | ps2pdf - asciidoc.1.pdf + +The `ps2pdf(1)` command is included in the Ghostscript distribution. +********************************************************************** + +To find out more about man pages view the `man(7)` manpage +(`man 7 man` and `man man-pages` commands). + + +Document Header +~~~~~~~~~~~~~~~ +A manpage document Header is mandatory. The title line contains the +man page name followed immediately by the manual section number in +brackets, for example 'ASCIIDOC(1)'. The title name should not contain +white space and the manual section number is a single digit optionally +followed by a single character. + +The NAME Section +~~~~~~~~~~~~~~~~ +The first manpage section is mandatory, must be titled 'NAME' and must +contain a single paragraph (usually a single line) consisting of a +list of one or more comma separated command name(s) separated from the +command purpose by a dash character. The dash must have at least one +white space character on either side. For example: + + printf, fprintf, sprintf - print formatted output + +The SYNOPSIS Section +~~~~~~~~~~~~~~~~~~~~ +The second manpage section is mandatory and must be titled 'SYNOPSIS'. + +refmiscinfo attributes +~~~~~~~~~~~~~~~~~~~~~~ +In addition to the automatically created man page <<X60,intrinsic +attributes>> you can assign DocBook +https://tdg.docbook.org/tdg/4.5/refmiscinfo.html[refmiscinfo] +element 'source', 'version' and 'manual' values using AsciiDoc +`{mansource}`, `{manversion}` and `{manmanual}` attributes +respectively. This example is from the AsciiDoc header of a man page +source file: + + :man source: AsciiDoc + :man version: {revnumber} + :man manual: AsciiDoc Manual + + +[[X78]] +Mathematical Formulas +--------------------- +The 'asciimath' and 'latexmath' <<X76,passthrough blocks>> along with +the 'asciimath' and 'latexmath' <<X77,passthrough macros>> provide a +(backend dependent) mechanism for rendering mathematical formulas. You +can use the following math markups: + +LaTeX Math +~~~~~~~~~~ +ftp://ftp.ams.org/pub/tex/doc/amsmath/short-math-guide.pdf[LaTeX +math] can be included in documents that are processed by +<<X31,dblatex(1)>>. Example inline formula: + + latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$] + +For more examples see the {website}[AsciiDoc website] or the +distributed `doc/latexmath.txt` file. + +MathJax +~~~~~~~ +https://www.mathjax.org/[MathJax] allows LaTeX Math style formulas to be included +in XHTML documents generated via the AsciiDoc 'xhtml11' and 'html5' backends. +This route overcomes several restrictions of the MathML-based approaches, +notably, restricted support of MathML by many mainstream browsers. To enable +'MathJax' support you must define the 'mathjax' attribute, for example using the +`-a mathjax` command-line option. Equations are specified as explained above +using the 'latexmath' passthrough blocks. By default, rendering of equations +with 'MathJax' requires a working internet connection and will thus not work if +you are offline (but it can be configured differently). + +LaTeXMathML +~~~~~~~~~~~ +///////////////////////////////////////////////////////////////////// +There is an https://math.etsu.edu/LaTeXMathML/[extended LaTeXMathML +version] by Jeff Knisley, in addition to a JavaScript file it requires +the inclusion of a CSS file. +///////////////////////////////////////////////////////////////////// + +'LaTeXMathML' allows LaTeX Math style formulas to be included in XHTML +documents generated using the AsciiDoc 'xhtml11' and 'html5' backends. +AsciiDoc uses the +https://www.maths.nottingham.ac.uk/plp/pmadw/lm.html[original +LaTeXMathML] by Douglas Woodall. 'LaTeXMathML' is derived from +ASCIIMath and is for users who are more familiar with or prefer +using LaTeX math formulas (it recognizes a subset of LaTeX Math, the +differences are documented on the 'LaTeXMathML' web page). To enable +LaTeXMathML support you must define the 'latexmath' attribute, for +example using the `-a latexmath` command-line option. Example inline +formula: + + latexmath:[$\sum_{n=1}^\infty \frac{1}{2^n}$] + +For more examples see the {website}[AsciiDoc website] or the +distributed `doc/latexmathml.txt` file. + +NOTE: The 'latexmath' macro used to include 'LaTeX Math' in DocBook +outputs is not the same as the 'latexmath' macro used to include +'LaTeX MathML' in XHTML outputs. 'LaTeX Math' applies to DocBook +outputs that are processed by <<X31,dblatex>> and is normally used to +generate PDF files. 'LaTeXMathML' is very much a subset of 'LaTeX +Math' and applies to XHTML documents. This remark does not +apply to 'MathJax' which does not use any of the 'latexmath' macros +(but only requires the 'latexmath' passthrough blocks for identification +of the equations). + +ASCIIMath +~~~~~~~~~~~ +///////////////////////////////////////////////////////////////////// +The older ASCIIMath 1.47 version is used instead of version 2 +because: + +1. Version 2 doesn't work when embedded. +2. Version 2 is much larger. +///////////////////////////////////////////////////////////////////// + +http://asciimath.org/[ASCIIMath] formulas can be included in XHTML +documents generated using the 'xhtml11' and 'html5' backends. To enable +ASCIIMath support you must define the 'asciimath' attribute, for +example using the `-a asciimath` command-line option. Example inline +formula: + + asciimath:[`x/x={(1,if x!=0),(text{undefined},if x=0):}`] + +For more examples see the {website}[AsciiDoc website] or the +distributed `doc/asciimath.txt` file. + +MathML +~~~~~~ +https://www.w3.org/Math/[MathML] is a low level XML markup for +mathematics. AsciiDoc has no macros for MathML but users familiar with +this markup could use passthrough macros and passthrough blocks to +include MathML in output documents. + + +[[X7]] +Configuration Files +------------------- +AsciiDoc source file syntax and output file markup is largely +controlled by a set of cascading, text based, configuration files. At +runtime The AsciiDoc default configuration files are combined with +optional user and document specific configuration files. + +Configuration File Format +~~~~~~~~~~~~~~~~~~~~~~~~~ +Configuration files contain named sections. Each section begins with a +section name in square brackets []. The section body consists of the +lines of text between adjacent section headings. + +- Section names consist of one or more alphanumeric, underscore or + dash characters and cannot begin or end with a dash. +- Lines starting with a '#' character are treated as comments and + ignored. +- If the section name is prefixed with a '+' character then the + section contents is appended to the contents of an already existing + same-named section. +- Otherwise same-named sections and section entries override + previously loaded sections and section entries (this is sometimes + referred to as 'cascading'). Consequently, downstream configuration + files need only contain those sections and section entries that need + to be overridden. + +TIP: When creating custom configuration files you only need to include +the sections and entries that differ from the default configuration. + +TIP: The best way to learn about configuration files is to read the +default configuration files in the AsciiDoc distribution in +conjunction with asciidoc(1) output files. You can view configuration +file load sequence by turning on the asciidoc(1) `-v` (`--verbose`) +command-line option. + +AsciiDoc reserves the following section names for specific purposes: + +miscellaneous:: + Configuration options that don't belong anywhere else. +attributes:: + Attribute name/value entries. +specialcharacters:: + Special characters reserved by the backend markup. +tags:: + Backend markup tags. +quotes:: + Definitions for quoted inline character formatting. +specialwords:: + Lists of words and phrases singled out for special markup. +replacements, replacements2, replacements3:: + Find and replace substitution definitions. +specialsections:: + Used to single out special section names for specific markup. +macros:: + Macro syntax definitions. +titles:: + Heading, section and block title definitions. +paradef-*:: + Paragraph element definitions. +blockdef-*:: + DelimitedBlock element definitions. +listdef-*:: + List element definitions. +listtags-*:: + List element tag definitions. +tabledef-*:: + Table element definitions. +tabletags-*:: + Table element tag definitions. + +Each line of text in these sections is a 'section entry'. Section +entries share the following syntax: + +name=value:: + The entry value is set to value. +name=:: + The entry value is set to a zero length string. +name!:: + The entry is undefined (deleted from the configuration). This + syntax only applies to 'attributes' and 'miscellaneous' + sections. + +.Section entry behavior +- All equals characters inside the `name` must be escaped with a + backslash character. +- `name` and `value` are stripped of leading and trailing white space. +- Attribute names, tag entry names and markup template section names + consist of one or more alphanumeric, underscore or dash characters. + Names should not begin or end with a dash. +- A blank configuration file section (one without any entries) deletes + any preceding section with the same name (applies to non-markup + template sections). + + +Miscellaneous section +~~~~~~~~~~~~~~~~~~~~~ +The optional `[miscellaneous]` section specifies the following +`name=value` options: + +newline:: + Output file line termination characters. Can include any + valid Python string escape sequences. The default value is + `\r\n` (carriage return, line feed). Should not be quoted or + contain explicit spaces (use `\x20` instead). For example: + + $ asciidoc -a 'newline=\n' -b docbook mydoc.txt + +outfilesuffix:: + The default extension for the output file, for example + `outfilesuffix=.html`. Defaults to backend name. +tabsize:: + The number of spaces to expand tab characters, for example + `tabsize=4`. Defaults to 8. A 'tabsize' of zero suppresses tab + expansion (useful when piping included files through block + filters). Included files can override this option using the + 'tabsize' attribute. +pagewidth, pageunits:: + These global table related options are documented in the + <<X4,Table Configuration File Definitions>> sub-section. + +NOTE: `[miscellaneous]` configuration file entries can be set using +the asciidoc(1) `-a` (`--attribute`) command-line option. + +Titles section +~~~~~~~~~~~~~~ +sectiontitle:: + Two line section title pattern. The entry value is a Python + regular expression containing the named group 'title'. + +underlines:: + A comma separated list of document and section title underline + character pairs starting with the section level 0 and ending + with section level 4 underline. The default setting is: + + underlines="==","--","~~","^^","++" + +sect0...sect4:: + One line section title patterns. The entry value is a Python + regular expression containing the named group 'title'. + +blocktitle:: + <<X42,BlockTitle element>> pattern. The entry value is a + Python regular expression containing the named group 'title'. + +subs:: + A comma separated list of substitutions that are performed on + the document header and section titles. Defaults to 'normal' + substitution. + +Tags section +~~~~~~~~~~~~ +The `[tags]` section contains backend tag definitions (one per +line). Tags are used to translate AsciiDoc elements to backend +markup. + +An AsciiDoc tag definition is formatted like +`<tagname>=<starttag>|<endtag>`. For example: + + emphasis=<em>|</em> + +In this example asciidoc(1) replaces the | character with the +emphasized text from the AsciiDoc input file and writes the result to +the output file. + +Use the `{brvbar}` attribute reference if you need to include a | pipe +character inside tag text. + +Attributes section +~~~~~~~~~~~~~~~~~~ +The optional `[attributes]` section contains predefined attributes. + +If the attribute value requires leading or trailing spaces then the +text text should be enclosed in quotation mark (") characters. + +To delete a attribute insert a `name!` entry in a downstream +configuration file or use the asciidoc(1) `--attribute name!` +command-line option (an attribute name suffixed with a `!` character +deletes the attribute) + +Special Characters section +~~~~~~~~~~~~~~~~~~~~~~~~~~ +The `[specialcharacters]` section specifies how to escape characters +reserved by the backend markup. Each translation is specified on a +single line formatted like: + + <special_character>=<translated_characters> + +Special characters are normally confined to those that resolve +markup ambiguity (in the case of HTML and XML markups the ampersand, +less than and greater than characters). The following example causes +all occurrences of the `<` character to be replaced by `<`. + + <=< + +Quoted Text section +~~~~~~~~~~~~~~~~~~~ +Quoting is used primarily for text formatting. The `[quotes]` section +defines AsciiDoc quoting characters and their corresponding backend +markup tags. Each section entry value is the name of a of a `[tags]` +section entry. The entry name is the character (or characters) that +quote the text. The following examples are taken from AsciiDoc +configuration files: + + [quotes] + _=emphasis + + [tags] + emphasis=<em>|</em> + +You can specify the left and right quote strings separately by +separating them with a | character, for example: + + ``|''=quoted + +Omitting the tag will disable quoting, for example, if you don't want +superscripts or subscripts put the following in a custom configuration +file or edit the global `asciidoc.conf` configuration file: + + [quotes] + ^= + ~= + +<<X52,Unconstrained quotes>> are differentiated from constrained +quotes by prefixing the tag name with a hash character, for example: + + __=#emphasis + +.Quoted text behavior +- Quote characters must be non-alphanumeric. +- To minimize quoting ambiguity try not to use the same quote + characters in different quote types. + +Special Words section +~~~~~~~~~~~~~~~~~~~~~ +The `[specialwords]` section is used to single out words and phrases +that you want to consistently format in some way throughout your +document without having to repeatedly specify the markup. The name of +each entry corresponds to a markup template section and the entry +value consists of a list of words and phrases to be marked up. For +example: + + [specialwords] + strongwords=NOTE IMPORTANT + + [strongwords] + <strong>{words}</strong> + +The examples specifies that any occurrence of `NOTE` or `IMPORTANT` +should appear in a bold font. + +Words and word phrases are treated as Python regular expressions: for +example, the word `^NOTE` would only match `NOTE` if appeared at +the start of a line. + +AsciiDoc comes with three built-in Special Word types: +'emphasizedwords', 'monospacedwords' and 'strongwords', each has a +corresponding (backend specific) markup template section. Edit the +configuration files to customize existing Special Words and to add new +ones. + +.Special word behavior +- Word list entries must be separated by space characters. +- Word list entries with embedded spaces should be enclosed in quotation (") + characters. +- A `[specialwords]` section entry of the form + +name=word1{nbsp}[word2...]+ adds words to existing `name` entries. +- A `[specialwords]` section entry of the form `name` undefines + (deletes) all existing `name` words. +- Since word list entries are processed as Python regular expressions + you need to be careful to escape regular expression special + characters. +- By default Special Words are substituted before Inline Macros, this + may lead to undesirable consequences. For example the special word + `foobar` would be expanded inside the macro call + `http://www.foobar.com[]`. A possible solution is to emphasize + whole words only by defining the word using regular expression + characters, for example `\bfoobar\b`. +- If the first matched character of a special word is a backslash then + the remaining characters are output without markup i.e. the + backslash can be used to escape special word markup. For example + the special word `\\?\b[Tt]en\b` will mark up the words `Ten` and + `ten` only if they are not preceded by a backslash. + +[[X10]] +Replacements section +~~~~~~~~~~~~~~~~~~~~ +`[replacements]`, `[replacements2]` and `[replacements3]` +configuration file entries specify find and replace text and are +formatted like: + + <find_pattern>=<replacement_text> + +The find text can be a Python regular expression; the replace text can +contain Python regular expression group references. + +Use Replacement shortcuts for often used macro references, for +example (the second replacement allows us to backslash escape the +macro name): + + NEW!=image:./images/smallnew.png[New!] + \\NEW!=NEW! + +The only difference between the three replacement types is how they +are applied. By default 'replacements' and 'replacements2' are applied +in <<X102,normal>> substitution contexts whereas 'replacements3' needs +to be configured explicitly and should only be used in backend +configuration files. + +.Replacement behavior +- The built-in replacements can be escaped with a backslash. +- If the find or replace text has leading or trailing spaces then the + text should be enclosed in quotation (") characters. +- Since the find text is processed as a regular expression you need to + be careful to escape regular expression special characters. +- Replacements are performed in the same order they appear in the + configuration file replacements section. + +Markup Template Sections +~~~~~~~~~~~~~~~~~~~~~~~~ +Markup template sections supply backend markup for translating +AsciiDoc elements. Since the text is normally backend dependent +you'll find these sections in the backend specific configuration +files. Template sections differ from other sections in that they +contain a single block of text instead of per line 'name=value' +entries. A markup template section body can contain: + +- Attribute references +- System macro calls. +- A document content placeholder + +The document content placeholder is a single | character and is +replaced by text from the source element. Use the `{brvbar}` +attribute reference if you need a literal | character in the template. + +[[X27]] +Configuration file names, precedence and locations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Configuration files have a `.conf` file name extension; they are +loaded from the following locations: + +1. The directory containing the asciidoc executable. +2. If there is no `asciidoc.conf` file in the directory containing the + asciidoc executable then load from the global configuration + directory (normally `/etc/asciidoc` or `/usr/local/etc/asciidoc`) + i.e. the global configuration files directory is skipped if + AsciiDoc configuration files are installed in the same directory as + the asciidoc executable. This allows both a system wide copy and + multiple local copies of AsciiDoc to coexist on the same host PC. +3. The user's `$HOME/.asciidoc` directory (if it exists). +4. The directory containing the AsciiDoc source file. +5. Explicit configuration files specified using: + - The `conf-files` attribute (one or more file names separated by a + `|` character). These files are loaded in the order they are + specified and prior to files specified using the `--conf-file` + command-line option. + - The asciidoc(1) `--conf-file`) command-line option. The + `--conf-file` option can be specified multiple times, in which + case configuration files will be processed in the same order they + appear on the command-line. +6. <<X100,Backend plugin>> configuration files are loaded from + subdirectories named like `backends/<backend>` in locations 1, 2 + and 3. +7. <<X59,Filter>> configuration files are loaded from subdirectories + named like `filters/<filter>` in locations 1, 2 and 3. + +Configuration files from the above locations are loaded in the +following order: + +- The `[attributes]` section only from: + * `asciidoc.conf` in location 3 + * Files from location 5. ++ +This first pass makes locally set attributes available in the global +`asciidoc.conf` file. + +- `asciidoc.conf` from locations 1, 2, 3. +- 'attributes', 'titles' and 'specialcharacters' sections from the + `asciidoc.conf` in location 4. +- The document header is parsed at this point and we can assume the + 'backend' and 'doctype' have now been defined. +- Backend plugin `<backend>.conf` and `<backend>-<doctype>.conf` files + from locations 6. If a backend plugin is not found then try + locations 1, 2 and 3 for `<backend>.conf` and + `<backend>-<doctype>.conf` backend configuration files. +- Filter conf files from locations 7. +- `lang-<lang>.conf` from locations 1, 2, 3. +- `asciidoc.conf` from location 4. +- `<backend>.conf` and `<backend>-<doctype>.conf` from location 4. +- Filter conf files from location 4. +- `<docfile>.conf` and `<docfile>-<backend>.conf` from location 4. +- Configuration files from location 5. + +Where: + +- `<backend>` and `<doctype>` are values specified by the asciidoc(1) + `-b` (`--backend`) and `-d` (`--doctype`) command-line options. +- `<infile>` is the path name of the AsciiDoc input file without the + file name extension. +- `<lang>` is a two letter country code set by the the AsciiDoc 'lang' + attribute. + +[NOTE] +===================================================================== +The backend and language global configuration files are loaded *after* +the header has been parsed. This means that you can set most +attributes in the document header. Here's an example header: + + Life's Mysteries + ================ + :author: Hu Nose + :doctype: book + :toc: + :icons: + :data-uri: + :lang: en + :encoding: iso-8859-1 + +Attributes set in the document header take precedence over +configuration file attributes. + +===================================================================== + +TIP: Use the asciidoc(1) `-v` (`--verbose`) command-line option to see +which configuration files are loaded and the order in which they are +loaded. + + +Document Attributes +------------------- +A document attribute is comprised of a 'name' and a textual 'value' +and is used for textual substitution in AsciiDoc documents and +configuration files. An attribute reference (an attribute name +enclosed in braces) is replaced by the corresponding attribute +value. Attribute names are case insensitive and can only contain +alphanumeric, dash and underscore characters. + +There are four sources of document attributes (from highest to lowest +precedence): + +- Command-line attributes. +- AttributeEntry, AttributeList, Macro and BlockId elements. +- Configuration file `[attributes]` sections. +- Intrinsic attributes. + +Within each of these divisions the last processed entry takes +precedence. + +NOTE: If an attribute is not defined then the line containing the +attribute reference is dropped. This property is used extensively in +AsciiDoc configuration files to facilitate conditional markup +generation. + + +[[X18]] +Attribute Entries +----------------- +The `AttributeEntry` block element allows document attributes to be +assigned within an AsciiDoc document. Attribute entries are added to +the global document attributes dictionary. The attribute name/value +syntax is a single line like: + + :<name>: <value> + +For example: + + :Author Initials: JB + +This will set an attribute reference `{authorinitials}` to the value +'JB' in the current document. + +To delete (undefine) an attribute use the following syntax: + + :<name>!: + +.AttributeEntry behavior +- The attribute entry line begins with colon -- no white space allowed + in left margin. +- AsciiDoc converts the `<name>` to a legal attribute name (lower + case, alphanumeric, dash and underscore characters only -- all other + characters deleted). This allows more human friendly text to be + used. +- Leading and trailing white space is stripped from the `<value>`. +- Lines ending in a space followed by a plus character are continued + to the next line, for example: + + :description: AsciiDoc is a text document format for writing notes, + + documentation, articles, books, slideshows, web pages + + and man pages. + +- If the `<value>` is blank then the corresponding attribute value is + set to an empty string. +- Attribute references contained in the entry `<value>` will be + expanded. +- By default AttributeEntry values are substituted for + `specialcharacters` and `attributes` (see above), if you want to + change or disable AttributeEntry substitution use the <<X77,\pass:[] + inline macro>> syntax. +- Attribute entries in the document Header are available for header + markup template substitution. +- Attribute elements override configuration file and intrinsic + attributes but do not override command-line attributes. + +Here are some more attribute entry examples: + +--------------------------------------------------------------------- +AsciiDoc User Manual +==================== +:author: Stuart Rackham +:email: srackham@gmail.com +:revdate: April 23, 2004 +:revnumber: 5.1.1 +--------------------------------------------------------------------- + +Which creates these attributes: + + {author}, {firstname}, {lastname}, {authorinitials}, {email}, + {revdate}, {revnumber} + +The previous example is equivalent to this <<X95,document header>>: + +--------------------------------------------------------------------- +AsciiDoc User Manual +==================== +Stuart Rackham <srackham@gmail.com> +5.1.1, April 23, 2004 +--------------------------------------------------------------------- + +Setting configuration entries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A variant of the Attribute Entry syntax allows configuration file +section entries and markup template sections to be set from within an +AsciiDoc document: + + :<section_name>.[<entry_name>]: <entry_value> + +Where `<section_name>` is the configuration section name, +`<entry_name>` is the name of the entry and `<entry_value>` is the +optional entry value. This example sets the default labeled list +style to 'horizontal': + + :listdef-labeled.style: horizontal + +It is exactly equivalent to a configuration file containing: + + [listdef-labeled] + style=horizontal + +- If the `<entry_name>` is omitted then the entire section is + substituted with the `<entry_value>`. This feature should only be + used to set markup template sections. The following example sets the + 'xref2' inline macro markup template: + + :xref2-inlinemacro.: <a href="#{1}">{2?{2}}</a> + +- No substitution is performed on configuration file attribute entries + and they cannot be undefined. +- This feature can only be used in attribute entries -- configuration + attributes cannot be set using the asciidoc(1) command `--attribute` + option. + +[[X62]] +.Attribute entries promote clarity and eliminate repetition +********************************************************************* +URLs and file names in AsciiDoc macros are often quite long -- they +break paragraph flow and readability suffers. The problem is +compounded by redundancy if the same name is used repeatedly. +Attribute entries can be used to make your documents easier to read +and write, here are some examples: + + :1: http://freshmeat.sourceforge.net/projects/asciidoc/ + :homepage: https://asciidoc.org[AsciiDoc home page] + :new: image:./images/smallnew.png[] + :footnote1: footnote:[A meaningless latin term] + + Using previously defined attributes: See the {1}[Freshmeat summary] + or the {homepage} for something new {new}. Lorem ispum {footnote1}. + +.Note +- The attribute entry definition must precede it's usage. +- You are not limited to URLs or file names, entire macro calls or + arbitrary lines of text can be abbreviated. +- Shared attributes entries could be grouped into a separate file and + <<X63,included>> in multiple documents. +********************************************************************* + + +[[X21]] +Attribute Lists +--------------- +- An attribute list is a comma separated list of attribute values. +- The entire list is enclosed in square brackets. +- Attribute lists are used to pass parameters to macros, blocks (using + the <<X79,AttributeList element>>) and inline quotes. + +The list consists of zero or more positional attribute values followed +by zero or more named attribute values. Here are three examples: a +single unquoted positional attribute; three unquoted positional +attribute values; one positional attribute followed by two named +attributes; the unquoted attribute value in the final example contains +comma (`,`) and double-quote (`"`) character entities: + + [Hello] + [quote, Bertrand Russell, The World of Mathematics (1956)] + ["22 times", backcolor="#0e0e0e", options="noborders,wide"] + [A footnote, "with an image" image:smallnew.png[]] + +.Attribute list behavior +- If one or more attribute values contains a comma the all string + values must be quoted (enclosed in double quotation mark + characters). +- If the list contains any named or quoted attributes then all string + attribute values must be quoted. +- To include a double quotation mark (") character in a quoted + attribute value the the quotation mark must be escaped with a + backslash. +- List attributes take precedence over existing attributes. +- List attributes can only be referenced in configuration file markup + templates and tags, they are not available elsewhere in the + document. +- Setting a named attribute to `None` undefines the attribute. +- Positional attributes are referred to as `{1}`,`{2}`,`{3}`,... +- Attribute `{0}` refers to the entire list (excluding the enclosing + square brackets). +- Named attribute names cannot contain dash characters. + +[[X75]] +Options attribute +~~~~~~~~~~~~~~~~~ +If the attribute list contains an attribute named `options` it is +processed as a comma separated list of option names: + +- Each name generates an attribute named like `<option>-option` (where + `<option>` is the option name) with an empty string value. For + example `[options="opt1,opt2,opt3"]` is equivalent to setting the + following three attributes + `[opt1-option="",opt2-option="",opt2-option=""]`. +- If you define a an option attribute globally (for example with an + <<X18,attribute entry>>) then it will apply to all elements in the + document. +- AsciiDoc implements a number of predefined options which are listed + in the <<X74,Attribute Options appendix>>. + +Macro Attribute lists +~~~~~~~~~~~~~~~~~~~~~ +Macros calls are suffixed with an attribute list. The list may be +empty but it cannot be omitted. List entries are used to pass +attribute values to macro markup templates. + + +Attribute References +-------------------- +An attribute reference is an attribute name (possibly followed by an +additional parameters) enclosed in curly braces. When an attribute +reference is encountered it is evaluated and replaced by its +corresponding text value. If the attribute is undefined the line +containing the attribute is dropped. + +There are three types of attribute reference: 'Simple', 'Conditional' +and 'System'. + +.Attribute reference evaluation +- You can suppress attribute reference expansion by placing a + backslash character immediately in front of the opening brace + character. +- By default attribute references are not expanded in + 'LiteralParagraphs', 'ListingBlocks' or 'LiteralBlocks'. +- Attribute substitution proceeds line by line in reverse line order. +- Attribute reference evaluation is performed in the following order: + 'Simple' then 'Conditional' and finally 'System'. + +Simple Attributes References +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Simple attribute references take the form `{<name>}`. If the +attribute name is defined its text value is substituted otherwise the +line containing the reference is dropped from the output. + +Conditional Attribute References +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Additional parameters are used in conjunction with attribute names to +calculate a substitution value. Conditional attribute references take +the following forms: + +`{<names>=<value>}`:: + `<value>` is substituted if the attribute `<names>` is + undefined otherwise its value is substituted. `<value>` can + contain simple attribute references. + +`{<names>?<value>}`:: + `<value>` is substituted if the attribute `<names>` is defined + otherwise an empty string is substituted. `<value>` can + contain simple attribute references. + +`{<names>!<value>}`:: + `<value>` is substituted if the attribute `<names>` is + undefined otherwise an empty string is substituted. `<value>` + can contain simple attribute references. + +`{<names>#<value>}`:: + `<value>` is substituted if the attribute `<names>` is defined + otherwise the undefined attribute entry causes the containing + line to be dropped. `<value>` can contain simple attribute + references. + +`{<names>%<value>}`:: + `<value>` is substituted if the attribute `<names>` is not + defined otherwise the containing line is dropped. `<value>` + can contain simple attribute references. + +`{<names>@<regexp>:<value1>[:<value2>]}`:: + `<value1>` is substituted if the value of attribute `<names>` + matches the regular expression `<regexp>` otherwise `<value2>` + is substituted. If attribute `<names>` is not defined the + containing line is dropped. If `<value2>` is omitted an empty + string is assumed. The values and the regular expression can + contain simple attribute references. To embed colons in the + values or the regular expression escape them with backslashes. + +`{<names>$<regexp>:<value1>[:<value2>]}`:: + Same behavior as the previous ternary attribute except for + the following cases: + + `{<names>$<regexp>:<value>}`;; + Substitutes `<value>` if `<names>` matches `<regexp>` + otherwise the result is undefined and the containing + line is dropped. + + `{<names>$<regexp>::<value>}`;; + Substitutes `<value>` if `<names>` does not match + `<regexp>` otherwise the result is undefined and the + containing line is dropped. + +The attribute `<names>` parameter normally consists of a single +attribute name but it can be any one of the following: + +- A single attribute name which evaluates to the attributes value. +- Multiple ',' separated attribute names which evaluates to an empty + string if one or more of the attributes is defined, otherwise it's + value is undefined. +- Multiple '+' separated attribute names which evaluates to an empty + string if all of the attributes are defined, otherwise it's value is + undefined. + +Conditional attributes with single attribute names are evaluated first +so they can be used inside the multi-attribute conditional `<value>`. + +Conditional attribute examples +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Conditional attributes are mainly used in AsciiDoc configuration +files -- see the distribution `.conf` files for examples. + +Attribute equality test:: + If `{backend}` is 'docbook45' or 'xhtml11' the example evaluates to + ``DocBook 4.5 or XHTML 1.1 backend'' otherwise it evaluates to + ``some other backend'': + + {backend@docbook45|xhtml11:DocBook 4.5 or XHTML 1.1 backend:some other backend} + +Attribute value map:: + This example maps the `frame` attribute values [`topbot`, `all`, + `none`, `sides`] to [`hsides`, `border`, `void`, `vsides`]: + + {frame@topbot:hsides}{frame@all:border}{frame@none:void}{frame@sides:vsides} + + +[[X24]] +System Attribute References +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +System attribute references generate the attribute text value by +executing a predefined action that is parametrized by one or more +arguments. The syntax is `{<action>:<arguments>}`. + +`{counter:<attrname>[:<seed>]}`:: + Increments the document attribute (if the attribute is + undefined it is set to `1`). Returns the new attribute value. + + - Counters generate global (document wide) attributes. + - The optional `<seed>` specifies the counter's initial value; + it can be a number or a single letter; defaults to '1'. + - `<seed>` can contain simple and conditional attribute + references. + - The 'counter' system attribute will not be executed if the + containing line is dropped by the prior evaluation of an + undefined attribute. + +`{counter2:<attrname>[:<seed>]}`:: + Same as `counter` except the it always returns a blank string. + +`{eval:<expression>}`:: + Substitutes the result of the Python `<expression>`. + + - If `<expression>` evaluates to `None` or `False` the + reference is deemed undefined and the line containing the + reference is dropped from the output. + - If the expression evaluates to `True` the attribute + evaluates to an empty string. + - `<expression>` can contain simple and conditional attribute + references. + - The 'eval' system attribute can be nested inside other + system attributes. + +`{eval3:<command>}`:: + Passthrough version of `{eval:<expression>}` -- the generated + output is written directly to the output without any further + substitutions. + +`{include:<filename>}`:: + Substitutes contents of the file named `<filename>`. + + - The included file is read at the time of attribute + substitution. + - If the file does not exist a warning is emitted and the line + containing the reference is dropped from the output file. + - Tabs are expanded based on the current 'tabsize' attribute + value. + +`{set:<attrname>[!][:<value>]}`:: + Sets or unsets document attribute. Normally only used in + configuration file markup templates (use + <<X18,AttributeEntries>> in AsciiDoc documents). + + - If the attribute name is followed by an exclamation mark + the attribute becomes undefined. + - If `<value>` is omitted the attribute is set to a blank + string. + - `<value>` can contain simple and conditional attribute + references. + - Returns a blank string unless the attribute is undefined in + which case the return value is undefined and the enclosing + line will be dropped. + +`{set2:<attrname>[!][:<value>]}`:: + Same as `set` except that the attribute scope is local to the + template. + +`{sys:<command>}`:: + Substitutes the stdout generated by the execution of the shell + `<command>`. + +`{sys2:<command>}`:: + Substitutes the stdout and stderr generated by the execution + of the shell `<command>`. + +`{sys3:<command>}`:: + Passthrough version of `{sys:<command>}` -- the generated + output is written directly to the output without any further + substitutions. + +`{template:<template>}`:: + Substitutes the contents of the configuration file section + named `<template>`. Attribute references contained in the + template are substituted. + +.System reference behavior +- System attribute arguments can contain non-system attribute + references. +- Closing brace characters inside system attribute arguments must be + escaped with a backslash. + +[[X60]] +Intrinsic Attributes +-------------------- +Intrinsic attributes are simple attributes that are created +automatically from: AsciiDoc document header parameters; asciidoc(1) +command-line arguments; attributes defined in the default +configuration files; the execution context. Here's the list of +predefined intrinsic attributes: + + {amp} ampersand (&) character entity + {asciidoc-args} used to pass inherited arguments to asciidoc filters + {asciidoc-confdir} the asciidoc(1) global configuration directory + {asciidoc-dir} the asciidoc(1) application directory + {asciidoc-file} the full path name of the asciidoc(1) script + {asciidoc-version} the version of asciidoc(1) + {author} author's full name + {authored} empty string '' if {author} or {email} defined, + {authorinitials} author initials (from document header) + {backend-<backend>} empty string '' + {<backend>-<doctype>} empty string '' + {backend} document backend specified by `-b` option + {backend-confdir} the directory containing the <backend>.conf file + {backslash} backslash character + {basebackend-<base>} empty string '' + {basebackend} html or docbook + {blockname} current block name (note 8). + {brvbar} broken vertical bar (|) character + {docdate} document last modified date (note 9) + {docdir} document input directory name (note 5) + {docfile} document file name (note 5) + {docname} document file name without extension (note 6) + {doctime} document last modified time (note 9) + {doctitle} document title (from document header) + {doctype-<doctype>} empty string '' + {doctype} document type specified by `-d` option + {email} author's email address (from document header) + {empty} empty string '' + {encoding} specifies input and output encoding + {filetype-<fileext>} empty string '' + {filetype} output file name file extension + {firstname} author first name (from document header) + {gt} greater than (>) character entity + {id} running block id generated by BlockId elements + {indir} input file directory name (note 2,5) + {infile} input file name (note 2,5) + {lastname} author last name (from document header) + {ldquo} Left double quote character (note 7) + {level} title level 1..4 (in section titles) + {listindex} the list index (1..) of the most recent list item + {localdate} the current date (note 9) + {localtime} the current time (note 9) + {lsquo} Left single quote character (note 7) + {lt} less than (<) character entity + {manname} manpage name (defined in NAME section) + {manpurpose} manpage (defined in NAME section) + {mantitle} document title minus the manpage volume number + {manvolnum} manpage volume number (1..8) (from document header) + {middlename} author middle name (from document header) + {nbsp} non-breaking space character entity + {notitle} do not display the document title + {outdir} document output directory name (note 2) + {outfile} output file name (note 2) + {plus} plus character + {python} the full path name of the Python interpreter executable + {rdquo} right double quote character (note 7) + {reftext} running block xreflabel generated by BlockId elements + {revdate} document revision date (from document header) + {revnumber} document revision number (from document header) + {rsquo} right single quote character (note 7) + {sectnum} formatted section number (in section titles) + {sp} space character + {showcomments} send comment lines to the output + {title} section title (in titled elements) + {two-colons} two colon characters + {two-semicolons} two semicolon characters + {user-dir} the ~/.asciidoc directory (if it exists) + {verbose} defined as '' if --verbose command option specified + {wj} word-joiner + {zwsp} zero-width space character entity + +[NOTE] +====== +1. Intrinsic attributes are global so avoid defining custom attributes + with the same names. +2. `{outfile}`, `{outdir}`, `{infile}`, `{indir}` attributes are + effectively read-only (you can set them but it won't affect the + input or output file paths). +3. See also the <<X88,Backend Attributes>> section for attributes + that relate to AsciiDoc XHTML file generation. +4. The entries that translate to blank strings are designed to be used + for conditional text inclusion. You can also use the `ifdef`, + `ifndef` and `endif` System macros for conditional inclusion. + footnote:[Conditional inclusion using `ifdef` and `ifndef` macros + differs from attribute conditional inclusion in that the former + occurs when the file is read while the latter occurs when the + contents are written.] +5. `{docfile}` and `{docdir}` refer to root document specified on the + asciidoc(1) command-line; `{infile}` and `{indir}` refer to the + current input file which may be the root document or an included + file. When the input is being read from the standard input + (`stdin`) these attributes are undefined. +6. If the input file is the standard input and the output file is not + the standard output then `{docname}` is the output file name sans + file extension. +7. See + https://en.wikipedia.org/wiki/Quotation_mark#Summary_table[non-English + usage of quotation marks]. +8. The `{blockname}` attribute identifies the style of the current + block. It applies to delimited blocks, lists and tables. Here is a + list of `{blockname}` values (does not include filters or custom + block and style names): + + delimited blocks:: comment, sidebar, open, pass, literal, verse, + listing, quote, example, note, tip, important, caution, warning, + abstract, partintro + + lists:: arabic, loweralpha, upperalpha, lowerroman, upperroman, + labeled, labeled3, labeled4, qanda, horizontal, bibliography, + glossary + + tables:: table +9. 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.) + + +====== + + +[[X73]] +Block Element Definitions +------------------------- +The syntax and behavior of Paragraph, DelimitedBlock, List and Table +block elements is determined by block definitions contained in +<<X7,AsciiDoc configuration file>> sections. + +Each definition consists of a section title followed by one or more +section entries. Each entry defines a block parameter controlling some +aspect of the block's behavior. Here's an example: + +--------------------------------------------------------------------- +[blockdef-listing] +delimiter=^-{4,}$ +template=listingblock +presubs=specialcharacters,callouts +--------------------------------------------------------------------- + +Configuration file block definition sections are processed +incrementally after each configuration file is loaded. Block +definition section entries are merged into the block definition, this +allows block parameters to be overridden and extended by later +<<X27,loading configuration files>>. + +AsciiDoc Paragraph, DelimitedBlock, List and Table block elements +share a common subset of configuration file parameters: + +delimiter:: + A Python regular expression that matches the first line of a block + element -- in the case of DelimitedBlocks and Tables it also matches + the last line. + +template:: + The name of the configuration file markup template section that will + envelope the block contents. The pipe ('|') character is substituted + for the block contents. List elements use a set of (list specific) + tag parameters instead of a single template. The template name can + contain attribute references allowing dynamic template selection a + the time of template substitution. + +options:: + A comma delimited list of element specific option names. In addition + to being used internally, options are available during markup tag + and template substitution as attributes with an empty string value + named like `<option>-option` (where `<option>` is the option name). + See <<X74,attribute options>> for a complete list of available + options. + +subs, presubs, postsubs:: + * 'presubs' and 'postsubs' are lists of comma separated substitutions that are + performed on the block contents. 'presubs' is applied first, + 'postsubs' (if specified) second. + + * 'subs' is an alias for 'presubs'. + + * If a 'filter' is allowed (Paragraphs, DelimitedBlocks and Tables) + and has been specified then 'presubs' and 'postsubs' substitutions + are performed before and after the filter is run respectively. + + * Allowed values: 'specialcharacters', 'quotes', 'specialwords', + 'replacements', 'macros', 'attributes', 'callouts'. + + * [[X102]]The following composite values are also allowed: + + 'none';; + No substitutions. + 'normal';; + The following substitutions in the following order: + 'specialcharacters', 'quotes', 'attributes', 'specialwords', + 'replacements', 'macros', 'replacements2'. + 'verbatim';; + The following substitutions in the following order: + 'specialcharacters' and 'callouts'. + + * 'normal' and 'verbatim' substitutions can be redefined by with + `subsnormal` and `subsverbatim` entries in a configuration file + `[miscellaneous]` section. + + * The substitutions are processed in the order in which they are + listed and can appear more than once. + +filter:: + This optional entry specifies an executable shell command for + processing block content (Paragraphs, DelimitedBlocks and Tables). + The filter command can contain attribute references. + +posattrs:: + Optional comma separated list of positional attribute names. This + list maps positional attributes (in the block's <<X21,attribute + list>>) to named block attributes. The following example, from the + QuoteBlock definition, maps the first and section positional + attributes: + + posattrs=attribution,citetitle + +style:: + This optional parameter specifies the default style name. + + +<stylename>-style:: + Optional style definition (see <<X23,Styles>> below). + +The following block parameters behave like document attributes and can +be set in block attribute lists and style definitions: 'template', +'options', 'subs', 'presubs', 'postsubs', 'filter'. + +[[X23]] +Styles +~~~~~~ +A style is a set of block parameter bundled as a single named +parameter. The following example defines a style named 'verbatim': + + verbatim-style=template="literalblock",subs="verbatim" + +If a block's <<X21,attribute list>> contains a 'style' attribute then +the corresponding style parameters are be merged into the default +block definition parameters. + +- All style parameter names must be suffixed with `-style` and the + style parameter value is in the form of a list of <<X21,named + attributes>>. +- The 'template' style parameter is mandatory, other parameters can be + omitted in which case they inherit their values from the default + block definition parameters. +- Multi-item style parameters ('subs','presubs','postsubs','posattrs') + must be specified using Python tuple syntax (rather than a simple + list of values as they in separate entries) e.g. + `postsubs=("callouts",)` not `postsubs="callouts"`. + +Paragraphs +~~~~~~~~~~ +Paragraph translation is controlled by `[paradef-*]` configuration +file section entries. Users can define new types of paragraphs and +modify the behavior of existing types by editing AsciiDoc +configuration files. + +Here is the shipped Default paragraph definition: + +-------------------------------------------------------------------- +[paradef-default] +delimiter=(?P<text>\S.*) +template=paragraph +-------------------------------------------------------------------- + +The normal paragraph definition has a couple of special properties: + +1. It must exist and be defined in a configuration file section named + `[paradef-default]`. +2. Irrespective of its position in the configuration files default + paragraph document matches are attempted only after trying all + other paragraph types. + +Paragraph specific block parameter notes: + +delimiter:: + This regular expression must contain the named group 'text' which + matches the text on the first line. Paragraphs are terminated by a + blank line, the end of file, or the start of a DelimitedBlock. + +options:: + The 'listelement' option specifies that paragraphs of this type will + automatically be considered part of immediately preceding list + items. The 'skip' option causes the paragraph to be treated as a + comment (see <<X26,CommentBlocks>>). + +.Paragraph processing proceeds as follows: +1. The paragraph text is aligned to the left margin. +2. Optional 'presubs' inline substitutions are performed on the + paragraph text. +3. If a filter command is specified it is executed and the paragraph + text piped to its standard input; the filter output replaces the + paragraph text. +4. Optional 'postsubs' inline substitutions are performed on the + paragraph text. +5. The paragraph text is enveloped by the paragraph's markup template + and written to the output file. + +Delimited Blocks +~~~~~~~~~~~~~~~~ +DelimitedBlock 'options' values are: + +sectionbody:: + The block contents are processed as a SectionBody. + +skip:: + The block is treated as a comment (see <<X26,CommentBlocks>>). + Preceding <<X21,attribute lists>> and <<X42,block titles>> are not + consumed. + +'presubs', 'postsubs' and 'filter' entries are ignored when +'sectionbody' or 'skip' options are set. + +DelimitedBlock processing proceeds as follows: + +1. Optional 'presubs' substitutions are performed on the block + contents. +2. If a filter is specified it is executed and the block's contents + piped to its standard input. The filter output replaces the block + contents. +3. Optional 'postsubs' substitutions are performed on the block + contents. +4. The block contents is enveloped by the block's markup template and + written to the output file. + +TIP: Attribute expansion is performed on the block filter command +before it is executed, this is useful for passing arguments to the +filter. + +Lists +~~~~~ +List behavior and syntax is determined by `[listdef-*]` configuration +file sections. The user can change existing list behavior and add new +list types by editing configuration files. + +List specific block definition notes: + +type:: + This is either 'bulleted','numbered','labeled' or 'callout'. + +delimiter:: + A Python regular expression that matches the first line of a + list element entry. This expression can contain the named groups + 'text' (bulleted groups), 'index' and 'text' (numbered lists), + 'label' and 'text' (labeled lists). + +tags:: + The `<name>` of the `[listtags-<name>]` configuration file section + containing list markup tag definitions. The tag entries ('list', + 'entry', 'label', 'term', 'text') map the AsciiDoc list structure to + backend markup; see the 'listtags' sections in the AsciiDoc + distributed backend `.conf` configuration files for examples. + +Tables +~~~~~~ +Table behavior and syntax is determined by `[tabledef-*]` and +`[tabletags-*]` configuration file sections. The user can change +existing table behavior and add new table types by editing +configuration files. The following `[tabledef-*]` section entries +generate table output markup elements: + +colspec:: + The table 'colspec' tag definition. + +headrow, footrow, bodyrow:: + Table header, footer and body row tag definitions. 'headrow' and + 'footrow' table definition entries default to 'bodyrow' if + they are undefined. + +headdata, footdata, bodydata:: + Table header, footer and body data tag definitions. 'headdata' and + 'footdata' table definition entries default to 'bodydata' if they + are undefined. + +paragraph:: + If the 'paragraph' tag is specified then blank lines in the cell + data are treated as paragraph delimiters and marked up using this + tag. + +[[X4]] +Table behavior is also influenced by the following `[miscellaneous]` +configuration file entries: + +pagewidth:: + This integer value is the printable width of the output media. See + <<X69,table attributes>>. + +pageunits:: + The units of width in output markup width attribute values. + +.Table definition behavior +- The output markup generation is specifically designed to work with + the HTML and CALS (DocBook) table models, but should be adaptable to + most XML table schema. +- Table definitions can be ``mixed in'' from multiple cascading + configuration files. +- New table definitions inherit the default table and table tags + definitions (`[tabledef-default]` and `[tabletags-default]`) so you + only need to override those conf file entries that require + modification. + + +[[X59]] +Filters +------- +AsciiDoc filters allow external commands to process AsciiDoc +'Paragraphs', 'DelimitedBlocks' and 'Table' content. Filters are +primarily an extension mechanism for generating specialized outputs. +Filters are implemented using external commands which are specified in +configuration file definitions. + +There's nothing special about the filters, they're just standard UNIX +filters: they read text from the standard input, process it, and write +to the standard output. + +The asciidoc(1) command `--filter` option can be used to install and +remove filters. The same option is used to unconditionally load a +filter. + +Attribute substitution is performed on the filter command prior to +execution -- attributes can be used to pass parameters from the +AsciiDoc source document to the filter. + +WARNING: Filters sometimes included executable code. Before installing +a filter you should verify that it is from a trusted source. + +Filter Search Paths +~~~~~~~~~~~~~~~~~~~ +If the filter command does not specify a directory path then +asciidoc(1) recursively searches for the executable filter command: + +- First it looks in the user's `$HOME/.asciidoc/filters` directory. +- Next the global filters directory (usually `/etc/asciidoc/filters` + or `/usr/local/etc/asciidoc`) directory is searched. +- Then it looks in the asciidoc(1) `./filters` directory. +- Finally it relies on the executing shell to search the environment + search path (`$PATH`). + +Standard practice is to install each filter in it's own sub-directory +with the same name as the filter's style definition. For example the +music filter's style name is 'music' so it's configuration and filter +files are stored in the `filters/music` directory. + +Filter Configuration Files +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Filters are normally accompanied by a configuration file containing a +Paragraph or DelimitedBlock definition along with corresponding markup +templates. + +While it is possible to create new 'Paragraph' or 'DelimitedBlock' +definitions the preferred way to implement a filter is to add a +<<X23,style>> to the existing Paragraph and ListingBlock definitions +(all filters shipped with AsciiDoc use this technique). The filter is +applied to the paragraph or delimited block by preceding it with an +attribute list: the first positional attribute is the style name, +remaining attributes are normally filter specific parameters. + +asciidoc(1) auto-loads all `.conf` files found in the filter search +paths unless the container directory also contains a file named +`__noautoload__` (see previous section). The `__noautoload__` feature +is used for filters that will be loaded manually using the `--filter` +option. + +[[X56]] +Example Filter +~~~~~~~~~~~~~~ +AsciiDoc comes with a toy filter for highlighting source code keywords +and comments. See also the `./filters/code/code-filter-readme.txt` +file. + +NOTE: The purpose of this toy filter is to demonstrate how to write a +filter -- it's much to simplistic to be passed off as a code syntax +highlighter. If you want a full featured multi-language highlighter +use the {website}source-highlight-filter.html[source code highlighter +filter]. + +Built-in filters +~~~~~~~~~~~~~~~~ +The AsciiDoc distribution includes 'source', 'music', 'latex' and +'graphviz' filters, details are on the +{website}index.html#_filters[AsciiDoc website]. + +[cols="1e,5",frame="topbot",options="header"] +.Built-in filters list +|==================================================================== +|Filter name |Description + +|music +|A {website}music-filter.html[music filter] is included in the +distribution `./filters/` directory. It translates music in +https://lilypond.org/[LilyPond] or https://abcnotation.com/[ABC] +notation to standard classical notation. + +|source +|A {website}source-highlight-filter.html[source code highlight filter] +is included in the distribution `./filters/` directory. + +|latex +|The {website}latex-filter.html[AsciiDoc LaTeX filter] translates +LaTeX source to an image that is automatically inserted into the +AsciiDoc output documents. + +|graphviz +|Gouichi Iisaka has written a https://www.graphviz.org/[Graphviz] +filter for AsciiDoc. Graphviz generates diagrams from a textual +specification. Gouichi Iisaka's Graphviz filter is included in the +AsciiDoc distribution. Here are some +{website}asciidoc-graphviz-sample.html[AsciiDoc Graphviz examples]. + +|==================================================================== + +[[X58]] +Filter plugins +~~~~~~~~~~~~~~ +Filter <<X101,plugins>> are a mechanism for distributing AsciiDoc +filters. A filter plugin is a Zip file containing the files that +constitute a filter. The asciidoc(1) `--filter` option is used to +load and manage filer <<X101,plugins>>. + +- Filter plugins <<X27,take precedence>> over built-in filters with + the same name. +- By default filter plugins are installed in + `$HOME/.asciidoc/filters/<filter>` where `<filter>` is the filter + name. + + +[[X101]] +Plugins +------- +The AsciiDoc plugin architecture is an extension mechanism that allows +additional <<X100,backends>>, <<X58,filters>> and <<X99,themes>> to be +added to AsciiDoc. + +- A plugin is a Zip file containing an AsciiDoc backend, filter or + theme (configuration files, stylesheets, scripts, images). +- The asciidoc(1) `--backend`, `--filter` and `--theme` command-line + options are used to load and manage plugins. Each of these options + responds to the plugin management 'install', 'list', 'remove' and + 'build' commands. +- The plugin management command names are reserved and cannot be used + for filter, backend or theme names. +- The plugin Zip file name always begins with the backend, filter or + theme name. + +Plugin commands and conventions are documented in the asciidoc(1) man +page. You can find lists of plugins on the +{website}plugins.html[AsciiDoc website]. + + +[[X36]] +Help Commands +------------- +The asciidoc(1) command has a `--help` option which prints help topics +to stdout. The default topic summarizes asciidoc(1) usage: + + $ asciidoc --help + +To print a help topic specify the topic name as a command argument. +Help topic names can be shortened so long as they are not ambiguous. +Examples: + + $ asciidoc --help manpage + $ asciidoc -h m # Short version of previous example. + $ asciidoc --help syntax + $ asciidoc -h s # Short version of previous example. + +Customizing Help +~~~~~~~~~~~~~~~~ +To change, delete or add your own help topics edit a help +configuration file. The help file name `help-<lang>.conf` is based on +the setting of the `lang` attribute, it defaults to `help.conf` +(English). The <<X27,help file location>> will depend on whether you +want the topics to apply to all users or just the current user. + +The help topic files have the same named section format as other +<<X7,configuration files>>. The `help.conf` files are stored in the +same locations and loaded in the same order as other configuration +files. + +When the `--help` command-line option is specified AsciiDoc loads the +appropriate help files and then prints the contents of the section +whose name matches the help topic name. If a topic name is not +specified `default` is used. You don't need to specify the whole help +topic name on the command-line, just enough letters to ensure it's not +ambiguous. If a matching help file section is not found a list of +available topics is printed. + + +Tips and Tricks +--------------- + +Know Your Editor +~~~~~~~~~~~~~~~~ +Writing AsciiDoc documents will be a whole lot more pleasant if you +know your favorite text editor. Learn how to indent and reformat text +blocks, paragraphs, lists and sentences. <<X20,Tips for 'vim' users>> +follow. + +[[X20]] +Vim Commands for Formatting AsciiDoc +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Text Wrap Paragraphs +^^^^^^^^^^^^^^^^^^^^ +Use the vim `:gq` command to reformat paragraphs. Setting the +'textwidth' sets the right text wrap margin; for example: + + :set textwidth=70 + +To reformat a paragraph: + +1. Position the cursor at the start of the paragraph. +2. Type `gq}`. + +Execute `:help gq` command to read about the vim gq command. + +[TIP] +===================================================================== +- Assign the `gq}` command to the Q key with the `nnoremap Q gq}` + command or put it in your `~/.vimrc` file to so it's always + available (see the <<X61, Example `~/.vimrc` file>>). +- Put `set` commands in your `~/.vimrc` file so you don't have to + enter them manually. +- The Vim website (https://www.vim.org/) has a wealth of resources, + including scripts for automated spell checking and ASCII Art + drawing. +===================================================================== + +Format Lists +^^^^^^^^^^^^ +The `gq` command can also be used to format bulleted, numbered and +callout lists. First you need to set the `comments`, `formatoptions` +and `formatlistpat` (see the <<X61, Example `~/.vimrc` file>>). + +Now you can format simple lists that use dash, asterisk, period and +plus bullets along with numbered ordered lists: + +1. Position the cursor at the start of the list. +2. Type `gq}`. + +Indent Paragraphs +^^^^^^^^^^^^^^^^^ +Indent whole paragraphs by indenting the fist line with the desired +indent and then executing the `gq}` command. + +[[X61]] +Example `~/.vimrc` File +^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------------------------------------------------- +" Use bold bright fonts. +set background=dark + +" Show tabs and trailing characters. +"set listchars=tab:»·,trail:·,eol:¬ +set listchars=tab:»·,trail:· +set list + +" Reformat paragraphs and list. +nnoremap <Leader>r gq} + +" Delete trailing white space and Dos-returns and to expand tabs to spaces. +nnoremap <Leader>t :set et<CR>:retab!<CR>:%s/[\r \t]\+$//<CR> + +autocmd BufRead,BufNewFile *.txt,*.asciidoc,README,TODO,CHANGELOG,NOTES,ABOUT + \ setlocal autoindent expandtab tabstop=8 softtabstop=2 shiftwidth=2 filetype=asciidoc + \ textwidth=70 wrap formatoptions=tcqn + \ formatlistpat=^\\s*\\d\\+\\.\\s\\+\\\\|^\\s*<\\d\\+>\\s\\+\\\\|^\\s*[a-zA-Z.]\\.\\s\\+\\\\|^\\s*[ivxIVX]\\+\\.\\s\\+ + \ comments=s1:/*,ex:*/,://,b:#,:%,:XCOMM,fb:-,fb:*,fb:+,fb:.,fb:> +--------------------------------------------------------------------- + +Troubleshooting +~~~~~~~~~~~~~~~ +AsciiDoc diagnostic features are detailed in the <<X82,Diagnostics +appendix>>. + +Gotchas +~~~~~~~ +Incorrect character encoding:: + If you get an error message like `'UTF-8' codec can't decode ...` + then you source file contains invalid UTF-8 characters -- set the + AsciiDoc <<X54,encoding attribute>> for the correct character set + (typically ISO-8859-1 (Latin-1) for European languages). + +Invalid output:: + AsciiDoc attempts to validate the input AsciiDoc source but makes + no attempt to validate the output markup, it leaves that to + external tools such as `xmllint(1)` (integrated into `a2x(1)`). + Backend validation cannot be hardcoded into AsciiDoc because + backends are dynamically configured. The following example + generates valid HTML but invalid DocBook (the DocBook `literal` + element cannot contain an `emphasis` element): + + +monospaced text with an _emphasized_ word+ + +Misinterpreted text formatting:: + You can suppress markup expansion by placing a backslash character + immediately in front of the element. The following example + suppresses inline monospaced formatting: + + \+1 for C++. + +Overlapping text formatting:: + Overlapping text formatting will generate illegal overlapping + markup tags which will result in downstream XML parsing errors. + Here's an example: + + Some *strong markup _that overlaps* emphasized markup_. + +Ambiguous underlines:: + A DelimitedBlock can immediately follow a paragraph without an + intervening blank line, but be careful, a single line paragraph + underline may be misinterpreted as a section title underline + resulting in a ``closing block delimiter expected'' error. + +Ambiguous ordered list items:: + Lines beginning with numbers at the end of sentences will be + interpreted as ordered list items. The following example + (incorrectly) begins a new list with item number 1999: + + He was last sighted in + 1999. Since then things have moved on. ++ +The 'list item out of sequence' warning makes it unlikely that this +problem will go unnoticed. + +Special characters in attribute values:: + Special character substitution precedes attribute substitution so + if attribute values contain special characters you may, depending + on the substitution context, need to escape the special characters + yourself. For example: + + $ asciidoc -a 'orgname=Bill & Ben Inc.' mydoc.txt + +Attribute lists:: + If any named attribute entries are present then all string + attribute values must be quoted. For example: + + ["Desktop screenshot",width=32] + +[[X90]] +Combining separate documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You have a number of stand-alone AsciiDoc documents that you want to +process as a single document. Simply processing them with a series of +`include` macros won't work because the documents contain (level 0) +document titles. The solution is to create a top level wrapper +document and use the `leveloffset` attribute to push them all down one +level. For example: + +[listing] +..................................................................... +Combined Document Title +======================= + +// Push titles down one level. +:leveloffset: 1 + +\include::document1.txt[] + +// Return to normal title levels. +:leveloffset: 0 + +A Top Level Section +------------------- +Lorum ipsum. + +// Push titles down one level. +:leveloffset: 1 + +\include::document2.txt[] + +\include::document3.txt[] +..................................................................... + +The document titles in the included documents will now be processed as +level 1 section titles, level 1 sections as level 2 sections and so +on. + +- Put a blank line between the `include` macro lines to ensure the + title of the included document is not seen as part of the last + paragraph of the previous document. +- You won't want non-title document header lines (for example, Author + and Revision lines) in the included files -- conditionally exclude + them if they are necessary for stand-alone processing. + +Processing document sections separately +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You have divided your AsciiDoc document into separate files (one per +top level section) which are combined and processed with the following +top level document: + +--------------------------------------------------------------------- +Combined Document Title +======================= +Joe Bloggs +v1.0, 12-Aug-03 + +\include::section1.txt[] + +\include::section2.txt[] + +\include::section3.txt[] +--------------------------------------------------------------------- + +You also want to process the section files as separate documents. +This is easy because asciidoc(1) will quite happily process +`section1.txt`, `section2.txt` and `section3.txt` separately -- the +resulting output documents contain the section but have no document +title. + +Processing document snippets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Use the `-s` (`--no-header-footer`) command-line option to suppress +header and footer output, this is useful if the processed output is to +be included in another file. For example: + + $ asciidoc -sb docbook section1.txt + +asciidoc(1) can be used as a filter, so you can pipe chunks of text +through it. For example: + + $ echo 'Hello *World!*' | asciidoc -s - + <div class="paragraph"><p>Hello <strong>World!</strong></p></div> + +Badges in HTML page footers +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +See the `[footer]` section in the AsciiDoc distribution `xhtml11.conf` +configuration file. + +Pretty printing AsciiDoc output +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If the indentation and layout of the asciidoc(1) output is not to your +liking you can: + +1. Change the indentation and layout of configuration file markup + template sections. The `{empty}` attribute is useful for outputting + trailing blank lines in markup templates. + +2. Use https://www.html-tidy.org/[HTML Tidy] program to tidy + asciidoc(1) output. Example: + + $ asciidoc -b docbook -o - mydoc.txt | tidy -indent -xml >mydoc.xml + +3. Use the `xmllint(1)` format option. Example: + + $ xmllint --format mydoc.xml + +Supporting minor DocBook DTD variations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The conditional inclusion of DocBook SGML markup at the end of the +distribution `docbook45.conf` file illustrates how to support minor +DTD variations. The included sections override corresponding entries +from preceding sections. + +Creating stand-alone HTML documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If you've ever tried to send someone an HTML document that includes +stylesheets and images you'll know that it's not as straight-forward +as exchanging a single file. AsciiDoc has options to create +stand-alone documents containing embedded images, stylesheets and +scripts. The following AsciiDoc command creates a single file +containing <<X66,embedded images>>, CSS stylesheets, and JavaScript +(for table of contents and footnotes): + + $ asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt + +You can view the HTML file here: {website}article-standalone.html[] + +Shipping stand-alone AsciiDoc source +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Reproducing presentation documents from someone else's source has one +major problem: unless your configuration files are the same as the +creator's you won't get the same output. + +The solution is to create a single backend specific configuration file +using the asciidoc(1) `-c` (`--dump-conf`) command-line option. You +then ship this file along with the AsciiDoc source document plus the +`asciidoc.py` script. The only end user requirement is that they have +Python installed (and that they consider you a trusted source). This +example creates a composite HTML configuration file for `mydoc.txt`: + + $ asciidoc -cb xhtml11 mydoc.txt > mydoc-xhtml11.conf + +Ship `mydoc.txt`, `mydoc-html.conf`, and `asciidoc.py`. With +these three files (and a Python interpreter) the recipient can +regenerate the HMTL output: + + $ ./asciidoc.py -eb xhtml11 mydoc.txt + +The `-e` (`--no-conf`) option excludes the use of implicit +configuration files, ensuring that only entries from the +`mydoc-html.conf` configuration are used. + +Inserting blank space +~~~~~~~~~~~~~~~~~~~~~ +Adjust your style sheets to add the correct separation between block +elements. Inserting blank paragraphs containing a single non-breaking +space character `{nbsp}` works but is an ad hoc solution compared +to using style sheets. + +Closing open sections +~~~~~~~~~~~~~~~~~~~~~ +You can close off section tags up to level `N` by calling the +`eval::[Section.setlevel(N)]` system macro. This is useful if you +want to include a section composed of raw markup. The following +example includes a DocBook glossary division at the top section level +(level 0): + +--------------------------------------------------------------------- +\ifdef::basebackend-docbook[] + +\eval::[Section.setlevel(0)] + ++++++++++++++++++++++++++++++++ +<glossary> + <title>Glossary + + ... + + ++++++++++++++++++++++++++++++++ +\endif::basebackend-docbook[] +--------------------------------------------------------------------- + +Validating output files +~~~~~~~~~~~~~~~~~~~~~~~ +Use `xmllint(1)` to check the AsciiDoc generated markup is both well +formed and valid. Here are some examples: + + $ xmllint --nonet --noout --valid docbook-file.xml + $ xmllint --nonet --noout --valid xhtml11-file.html + $ xmllint --nonet --noout --valid --html html4-file.html + +The `--valid` option checks the file is valid against the document +type's DTD, if the DTD is not installed in your system's catalog then +it will be fetched from its Internet location. If you omit the +`--valid` option the document will only be checked that it is well +formed. + +The online https://validator.w3.org/#validate_by_uri+with_options[W3C +Markup Validation Service] is the defacto standard when it comes to +validating HTML (it validates all HTML standards including HTML5). + + +:numbered!: + +[glossary] +Glossary +-------- +[glossary] +[[X8]] Block element:: + An AsciiDoc block element is a document entity composed of one or + more whole lines of text. + +[[X34]] Inline element:: + AsciiDoc inline elements occur within block element textual + content, they perform formatting and substitution tasks. + +Formal element:: + An AsciiDoc block element that has a BlockTitle. Formal elements + are normally listed in front or back matter, for example lists of + tables, examples and figures. + +Verbatim element:: + The word verbatim indicates that white space and line breaks in + the source document are to be preserved in the output document. + + +[appendix] +Migration Notes +--------------- +[[X53]] +Version 7 to version 8 +~~~~~~~~~~~~~~~~~~~~~~ +- A new set of quotes has been introduced which may match inline text + in existing documents -- if they do you'll need to escape the + matched text with backslashes. +- The index entry inline macro syntax has changed -- if your documents + include indexes you may need to edit them. +- Replaced a2x(1) `--no-icons` and `--no-copy` options with their + negated equivalents: `--icons` and `--copy` respectively. The + default behavior has also changed -- the use of icons and copying of + icon and CSS files must be specified explicitly with the `--icons` + and `--copy` options. + +The rationale for the changes can be found in the AsciiDoc +`CHANGELOG`. + +NOTE: If you want to disable unconstrained quotes, the new alternative +constrained quotes syntax and the new index entry syntax then you can +define the attribute `asciidoc7compatible` (for example by using the +`-a asciidoc7compatible` command-line option). + +[[X38]] +[appendix] +Packager Notes +-------------- +Read the `README` and `INSTALL` files (in the distribution root +directory) for install prerequisites and procedures. The distribution +`Makefile.in` (used by `configure` to generate the `Makefile`) is the +canonical installation procedure. + + +[[X39]] +[appendix] +AsciiDoc Safe Mode +------------------- +AsciiDoc 'safe mode' skips potentially dangerous scripted sections in +AsciiDoc source files by inhibiting the execution of arbitrary code or +the inclusion of arbitrary files. + +The safe mode is disabled by default, it can be enabled with the +asciidoc(1) `--safe` command-line option. + +.Safe mode constraints +- `eval`, `sys` and `sys2` executable attributes and block macros are + not executed. +- `include::[]` and `include1::[]` block macro + files must reside inside the parent file's directory. +- `{include:}` executable attribute files must reside + inside the source document directory. +- Passthrough Blocks are dropped. + +[WARNING] +===================================================================== +The safe mode is not designed to protect against unsafe AsciiDoc +configuration files. Be especially careful when: + +1. Implementing filters. +2. Implementing elements that don't escape special characters. +3. Accepting configuration files from untrusted sources. +===================================================================== + + +[appendix] +Using AsciiDoc with non-English Languages +----------------------------------------- +AsciiDoc can process UTF-8 character sets but there are some things +you need to be aware of: + +- If you are generating output documents using a DocBook toolchain + then you should set the AsciiDoc `lang` attribute to the appropriate + language (it defaults to `en` (English)). This will ensure things + like table of contents, figure and table captions and admonition + captions are output in the specified language. For example: + + $ a2x -a lang=es doc/article.txt + +- If you are outputting HTML directly from asciidoc(1) you'll + need to set the various `*_caption` attributes to match your target + language (see the list of captions and titles in the `[attributes]` + section of the distribution `lang-*.conf` files). The easiest way is + to create a language `.conf` file (see the AsciiDoc's `lang-en.conf` + file). ++ +NOTE: You still use the 'NOTE', 'CAUTION', 'TIP', 'WARNING', +'IMPORTANT' captions in the AsciiDoc source, they get translated in +the HTML output file. + +- asciidoc(1) automatically loads configuration files named like + `lang-.conf` where `` is a two letter language code that + matches the current AsciiDoc `lang` attribute. See also + <>. + + +[appendix] +Vim Syntax Highlighter +---------------------- +Syntax highlighting is incredibly useful, in addition to making +reading AsciiDoc documents much easier syntax highlighting also helps +you catch AsciiDoc syntax errors as you write your documents. + +If you use the Vim editor, it comes with an +https://github.com/vim/vim/blob/master/runtime/syntax/asciidoc.vim[AsciiDoc +syntax highlighter pre-included]. By default, it will activate for +files that use the .asciidoc or .adoc file extensions. + +Alternatively, to enable syntax highlighting for the current document or +other extensions: + +- Put a Vim 'autocmd' in your Vim configuration file (see the + <>). +- or execute the Vim command `:set syntax=asciidoc`. +- or add the following line to the end of you AsciiDoc source files: + + // vim: set syntax=asciidoc: + + +[[X74]] +[appendix] +Attribute Options +----------------- +Here is the list of predefined <>: + + +[cols="2e,2,2,5",frame="topbot",options="header"] +|==================================================================== +|Option|Backends|AsciiDoc Elements|Description + +|autowidth |xhtml11, html5, html4 |table| +The column widths are determined by the browser, not the AsciiDoc +'cols' attribute. If there is no 'width' attribute the table width is +also left up to the browser. + +|unbreakable |xhtml11, html5 |block elements| +'unbreakable' attempts to keep the block element together on a single +printed page c.f. the 'breakable' and 'unbreakable' docbook (XSL/FO) +options below. + +|breakable, unbreakable |docbook (XSL/FO) |table, example, block image| +The 'breakable' options allows block elements to break across page +boundaries; 'unbreakable' attempts to keep the block element together +on a single page. If neither option is specified the default XSL +stylesheet behavior prevails. + +|compact |docbook, xhtml11, html5 |bulleted list, numbered list| +Minimizes vertical space in the list + +|footer |docbook, xhtml11, html5, html4 |table| +The last row of the table is rendered as a footer. + +|header |docbook, xhtml11, html5, html4 |table| +The first row of the table is rendered as a header. + +|pgwide |docbook (XSL/FO) |table, block image, horizontal labeled list| +Specifies that the element should be rendered across the full text +width of the page irrespective of the current indentation. + +|strong |xhtml11, html5, html4 |labeled lists| +Emboldens label text. +|==================================================================== + + +[[X82]] +[appendix] +Diagnostics +----------- +The `asciidoc(1)` `--verbose` command-line option prints additional +information to stderr: files processed, filters processed, warnings, +system attribute evaluation. + +A special attribute named 'trace' enables the output of +element-by-element diagnostic messages detailing output markup +generation to stderr. The 'trace' attribute can be set on the +command-line or from within the document using <> (the latter allows tracing to be confined to specific +portions of the document). + +- Trace messages print the source file name and line number and the + trace name followed by related markup. +- 'trace names' are normally the names of AsciiDoc elements (see the + list below). +- The trace message is only printed if the 'trace' attribute value + matches the start of a 'trace name'. The 'trace' attribute value can + be any Python regular expression. If a trace value is not specified + all trace messages will be printed (this can result in large amounts + of output if applied to the whole document). + +- In the case of inline substitutions: + * The text before and after the substitution is printed; the before + text is preceded by a line containing `<<<` and the after text by + a line containing `>>>`. + * The 'subs' trace value is an alias for all inline substitutions. + +.Trace names +..................................................................... + block close + block open + +dropped line (a line containing an undefined attribute reference). +floating title +footer +header +list close +list entry close +list entry open +list item close +list item open +list label close +list label open +list open +macro block (a block macro) +name (man page NAME section) +paragraph +preamble close +preamble open +push blockname +pop blockname +section close +section open: level +subs (all inline substitutions) +table +..................................................................... + +Where: + +- `` is section level number '0...4'. +- `` is a delimited block name: 'comment', 'sidebar', + 'open', 'pass', 'listing', 'literal', 'quote', 'example'. +- `` is an inline substitution type: + 'specialcharacters','quotes','specialwords', 'replacements', + 'attributes','macros','callouts', 'replacements2', 'replacements3'. + +Command-line examples: + +. Trace the entire document. + + $ asciidoc -a trace mydoc.txt + +. Trace messages whose names start with `quotes` or `macros`: + + $ asciidoc -a 'trace=quotes|macros' mydoc.txt + +. Print the first line of each trace message: + + $ asciidoc -a trace mydoc.txt 2>&1 | grep ^TRACE: + +Attribute Entry examples: + +. Begin printing all trace messages: + + :trace: + +. Print only matched trace messages: + + :trace: quotes|macros + +. Turn trace messages off: + + :trace!: + + +[[X88]] +[appendix] +Backend Attributes +------------------ +This table contains a list of optional attributes that influence the +generated outputs. + +[cols="1e,1,5a",frame="topbot",options="header"] +|==================================================================== +|Name |Backends |Description + +|badges |xhtml11, html5 | +Link badges ('XHTML 1.1' and 'CSS') in document footers. By default +badges are omitted ('badges' is undefined). + +NOTE: The path names of images, icons and scripts are relative path +names to the output document not the source document. + +|data-uri |xhtml11, html5 | +Embed images using the <>. + +|css-signature |html5, xhtml11 | +Set a 'CSS signature' for the document (sets the 'id' attribute of the +HTML 'body' element). CSS signatures provide a mechanism that allows +users to personalize the document appearance. The term 'CSS signature' +was https://juicystudio.com/article/css-selectors.php[coined by +Eric Meyer]. + + +|disable-javascript |xhtml11, html5 | +If the `disable-javascript` attribute is defined the `asciidoc.js` +JavaScript is not embedded or linked to the output document. By +default AsciiDoc automatically embeds or links the `asciidoc.js` +JavaScript to the output document. The script dynamically generates +<> and <>. + +|[[X97]] docinfo, docinfo1, docinfo2 |All backends | +These three attributes control which <> will be included in the the header of the output file: + +docinfo:: Include `-docinfo.` +docinfo1:: Include `docinfo.` +docinfo2:: Include `docinfo.` and `-docinfo.` + +Where `` is the file name (sans extension) of the AsciiDoc +input file and `` is `.html` for HTML outputs or `.xml` for +DocBook outputs. If the input file is the standard input then the +output file name is used. The following example will include the +`mydoc-docinfo.xml` docinfo file in the DocBook `mydoc.xml` output +file: + + $ asciidoc -a docinfo -b docbook mydoc.txt + +This next example will include `docinfo.html` and `mydoc-docinfo.html` +docinfo files in the HTML output file: + + $ asciidoc -a docinfo2 -b html4 mydoc.txt + + +|[[X54]]encoding |html4, html5, xhtml11, docbook | +Set the input and output document character set encoding. For example +the `--attribute encoding=ISO-8859-1` command-line option will set the +character set encoding to `ISO-8859-1`. + +- The default encoding is UTF-8. +- This attribute specifies the character set in the output document. +- The encoding name must correspond to a Python codec name or alias. +- The 'encoding' attribute can be set using an AttributeEntry inside + the document header. For example: + + :encoding: ISO-8859-1 + +|hr |html4 | +Defines the 'html4' inter-section horizontal ruler element. By default +'html4' top level sections are separated by a horizontal ruler +element, undefine this attribute or set it to an empty string if you +do not want them. The default 'html4' backend value for the 'hr' +attribute is `
`. + +|[[X45]]icons |xhtml11, html5 | +Link admonition paragraph and admonition block icon images and badge +images. By default 'icons' is undefined and text is used in place of +icon images. + +|[[X44]]iconsdir |html4, html5, xhtml11, docbook | +The name of the directory containing linked admonition icons, +navigation icons and the `callouts` sub-directory (the `callouts` +sub-directory contains <> number images). 'iconsdir' +defaults to `./images/icons`. If admonition icons are embedded using +the <> scheme then the 'iconsdir' attribute defaults to +the location of the icons installed in the AsciiDoc configuration +directory. + +|imagesdir |html4, html5, xhtml11, docbook | +If this attribute is defined it is prepended to the target image file +name paths in inline and block image macros. + +|keywords, description, title |html4, html5, xhtml11 | +The 'keywords' and 'description' attributes set the correspondingly +named HTML meta tag contents; the 'title' attribute sets the HTML +title tag contents. Their principle use is for SEO (Search Engine +Optimisation). All three are optional, but if they are used they must +appear in the document header (or on the command-line). If 'title' is +not specified the AsciiDoc document title is used. + +|linkcss |html5, xhtml11 | +Link CSS stylesheets and JavaScripts. By default 'linkcss' is +undefined in which case stylesheets and scripts are automatically +embedded in the output document. + +|[[X103]]max-width |html5, xhtml11 | +Set the document maximum display width (sets the 'body' element CSS +'max-width' property). + +|numbered |html4, html5, xhtml11, docbook (XSL Stylesheets) | +Adds section numbers to section titles. The 'docbook' backend ignores +'numbered' attribute entries after the document header. + +|plaintext | All backends | +If this global attribute is defined all inline substitutions are +suppressed and block indents are retained. This option is useful when +dealing with large amounts of imported plain text. + +|quirks |xhtml11 | +Include the `xhtml11-quirks.conf` configuration file and +`xhtml11-quirks.css` <> to work around IE6 browser +incompatibilities. This feature is deprecated and its use is +discouraged -- documents are still viewable in IE6 without it. + +|revremark |docbook | +A short summary of changes in this document revision. Must be defined +prior to the first document section. The document also needs to be +dated to output this attribute. + +|footer-style |html4, html5, xhtml11 | +Changes the "Last updated" field in the footer of the document or removes this +field and the revision number (in the footer only). + +Can take 3 values: + +- none : Don't display the "Last updated" and "Revision number" fields in the + footer of the document +- revdate : The "Last updated" field's date in the footer will be the revision + date specified in the document (`revdate` attribute) +- default (or any other value) : The "Last updated" field's date in the footer + will be the date of the input file modification + +This attribute can be set, for example, using `:footer-style: revdate` in the +header of the file or using the `--attribute footer-style=revdate` command-line +option. + +|scriptsdir |html5, xhtml11 | +The name of the directory containing linked JavaScripts. +See <>. + +|sgml |docbook45 | +The `--backend=docbook45` command-line option produces DocBook 4.5 +XML. You can produce the older DocBook SGML format using the +`--attribute sgml` command-line option. + +|stylesdir |html5, xhtml11 | +The name of the directory containing linked or embedded +<>. +See <>. + +|stylesheet |html5, xhtml11 | +The file name of an optional additional CSS <>. + +|theme |html5, xhtml11 | +Use alternative stylesheet (see <>). + +|[[X91]]toc |html5, xhtml11, docbook (XSL Stylesheets) | +Adds a table of contents to the start of an article or book document. +The `toc` attribute can be specified using the `--attribute toc` +command-line option or a `:toc:` attribute entry in the document +header. The 'toc' attribute is defined by default when the 'docbook' +backend is used. To disable table of contents generation undefine the +'toc' attribute by putting a `:toc!:` attribute entry in the document +header or from the command-line with an `--attribute toc!` option. + +*xhtml11 and html5 backends* + +- JavaScript needs to be enabled in your browser. +- The following example generates a numbered table of contents using a + JavaScript embedded in the `mydoc.html` output document: + + $ asciidoc -a toc -a numbered mydoc.txt + +|toc2 |html5, xhtml11 | +Adds a scrollable table of contents in the left hand margin of an +article or book document. Use the 'max-width' attribute to change the +content width. In all other respects behaves the same as the 'toc' +attribute. + +|toc-placement |html5, xhtml11 | +When set to 'auto' (the default value) asciidoc(1) will place the +table of contents in the document header. When 'toc-placement' is set +to 'manual' the TOC can be positioned anywhere in the document by +placing the `toc::[]` block macro at the point you want the TOC to +appear. + +NOTE: If you use 'toc-placement' then you also have to define the +<> attribute. + +|toc-title |html5, xhtml11 | +Sets the table of contents title (defaults to 'Table of Contents'). + +|toclevels |html5, xhtml11 | +Sets the number of title levels (1..4) reported in the table of +contents (see the 'toc' attribute above). Defaults to 2 and must be +used with the 'toc' attribute. Example usage: + + $ asciidoc -a toc -a toclevels=3 doc/asciidoc.txt + +|==================================================================== + + +[appendix] +License +------- +AsciiDoc is free software; you can redistribute it and/or modify it +under the terms of the 'GNU General Public License version 2' (GPLv2) +as published by the Free Software Foundation. + +AsciiDoc is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License version 2 for more details. + +Copyright (C) 2002-2013 Stuart Rackham. + +Copyright (C) 2013-2020 AsciiDoc Contributors. diff --git a/tests/inputs/asciimath.txt b/tests/inputs/asciimath.txt new file mode 100644 index 0000000..a528ba5 --- /dev/null +++ b/tests/inputs/asciimath.txt @@ -0,0 +1,59 @@ +ASCIIMath Formulae +==================== + +http://asciimath.org/[ASCIIMath] is a clever JavaScript written by +Peter Jipsen that dynamically transforms mathematical formulae +written in a wiki-like plain text markup to +https://www.w3.org/Math/[MathML] markup which is displayed as +standard mathematical notation by the Web Browser. See 'Appendix E' +in the AsciiDoc User Guide for more details. + +The AsciiDoc `xhtml11` backend supports ASCIIMath -- it links the +ASCIIMath script and escapes ASCIIMath delimiters and special +characters to yield valid XHTML. To use ASCIIMath: + +1. Include the `-a asciimath` command-line option when you run + `asciidoc(1)`. +2. Enclose ASCIIMath formulas inside math or double-dollar + passthroughs or in math passthrough blocks. + +Here's the link:asciimath.txt[AsciiDoc source] that generated this +page. + +.NOTE +- When you use the `asciimath:[]` inline macro you need to escape `]` + characters in the formulas with a backslash, escaping is unnecessary + if you use the double-dollar macro (for examples see the second + formula below). +- See the http://asciimath.org[ASCIIMath] website for ASCIIMath + documentation and the latest version. +- If the formulas don't appear to be correct you probably need to + install the correct math fonts (see the + http://asciimath.org[ASCIIMath] website for details). +- See the link:latexmathml.html[LaTeXMathML page] if you prefer to use + LaTeX math formulas. + +A list of example formulas: + +- $$`[[a,b],[c,d]]((n),(k))`$$ +- asciimath:[x/x={(1,if x!=0),(text{undefined},if x=0):}] +- asciimath:[d/dxf(x)=lim_(h->0)(f(x+h)-f(x))/h] +- +++`sum_(i=1)\^n i=(n(n+1))/2`$+++ and *bold + asciimath:[int_0\^(pi/2) sinx\ dx=1]* +- asciimath:[(a,b\]={x in RR : a < x <= b}] +- asciimath:[x^2+y_1+z_12^34] + +********************************************************************* +The first three terms factor to give +asciimath:[(x+b/(2a))^2=(b^2)/(4a^2)-c/a]. + +asciimath:[x+b/(2a)=+-sqrt((b^2)/(4a^2)-c/a)]. + +Now we take square roots on both sides and get +asciimath:[x+b/(2a)=+-sqrt((b^2)/(4a^2)-c/a)]. +Finally we move the asciimath:[b/(2a)] to the right and simplify to +get the two solutions: +*asciimath:[x_(1,2)=(-b+-sqrt(b^2-4ac))/(2a)]*. + +********************************************************************* + diff --git a/tests/inputs/barchart.py b/tests/inputs/barchart.py new file mode 100644 index 0000000..c79a514 --- /dev/null +++ b/tests/inputs/barchart.py @@ -0,0 +1,4 @@ +print( + "No barchart to avoid depending on Pychart for the tests.\n" + "See also: https://asciidoc.org/faq.html#_is_it_possible_to_include_charts_in_asciidoc_documents" # noqa: E501 +) diff --git a/tests/inputs/book-multi.txt b/tests/inputs/book-multi.txt new file mode 100644 index 0000000..7db57ea --- /dev/null +++ b/tests/inputs/book-multi.txt @@ -0,0 +1,181 @@ +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. +//////////////////////////////////////////////////////////////// diff --git a/tests/inputs/book.txt b/tests/inputs/book.txt new file mode 100644 index 0000000..7579851 --- /dev/null +++ b/tests/inputs/book.txt @@ -0,0 +1,156 @@ +Book Title Goes Here +==================== +Author's Name +v1.0, 2003-12 +:doctype: book + + +[dedication] +Example Dedication +------------------ +Optional dedication. + +This document is an AsciiDoc book skeleton containing briefly +annotated example elements plus a couple of example index entries and +footnotes. + +Books are normally used to generate DocBook markup and the titles of +the preface, appendix, bibliography, glossary and index sections are +significant ('specialsections'). + + +[preface] +Example Preface +--------------- +Optional preface. + +Preface Sub-section +~~~~~~~~~~~~~~~~~~~ +Preface sub-section body. + + +The First Chapter +----------------- +Chapters can contain sub-sections nested up to three deep. +footnote:[An example footnote.] +indexterm:[Example index entry] + +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 Third Chapter +----------------- +Book chapters are at level 1 and can contain sub-sections. + + +:numbered!: + +[appendix] +Example Appendix +---------------- +One or more optional appendixes go here at section level 1. + +Appendix Sub-section +~~~~~~~~~~~~~~~~~~~ +Sub-section body. + + +[bibliography] +Example Bibliography +-------------------- +The bibliography list is a style of AsciiDoc bulleted list. + +[bibliography] +.Books +- [[[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. + +[bibliography] +.Articles +- [[[abc2003]]] Gall Anonim. 'An article', Whatever. 2003. + + +[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 being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// diff --git a/tests/inputs/customers.csv b/tests/inputs/customers.csv new file mode 100644 index 0000000..01f862a --- /dev/null +++ b/tests/inputs/customers.csv @@ -0,0 +1,18 @@ +"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" diff --git a/tests/inputs/deprecated-quotes.txt b/tests/inputs/deprecated-quotes.txt new file mode 100644 index 0000000..2f44edf --- /dev/null +++ b/tests/inputs/deprecated-quotes.txt @@ -0,0 +1,12 @@ +// Deprecated quote attributes. +[role="foo"]##fun with text##. +["green","yellow",2,role="foo"]##fun with text##. +[green,yellow,2]##fun with text##. +More [red,black,4]*fun with text*. +Yet more [red,,1.5]**fun with text**. +Yet more [red,,1.5]+fun with text+. +Yet more [red,,1.5]'fun with text'. + +Yet more [red,,1.5]_fun with text_. + +Yet more [orange]'fun with text'. diff --git a/tests/inputs/dummy_file.py b/tests/inputs/dummy_file.py new file mode 100644 index 0000000..aec34aa --- /dev/null +++ b/tests/inputs/dummy_file.py @@ -0,0 +1,470 @@ +#!/usr/bin/env python3 + +__version__ = '0.4.0' + + +import difflib +import io +import os +from pathlib import Path +import re +import shutil +import sys + +sys.path.append(str(Path(__file__).resolve().parent.parent)) +from asciidoc import asciidoc # noqa: E402 + +# Default backends. +BACKENDS = ('html4', 'xhtml11', 'docbook', 'docbook5', 'html5') +BACKEND_EXT = { + 'html4': '.html', + 'xhtml11': '.html', + 'docbook': '.xml', + 'docbook5': '.xml', + 'slidy': '.html', + 'html5': '.html' +} + + +def iif(condition, iftrue, iffalse=None): + """ + Immediate if c.f. ternary ?: operator. + False value defaults to '' if the true value is a string. + False value defaults to 0 if the true value is a number. + """ + if iffalse is None: + if isinstance(iftrue, str): + iffalse = '' + if type(iftrue) in (int, float): + iffalse = 0 + if condition: + return iftrue + else: + return iffalse + + +def message(msg=''): + print(msg, file=sys.stderr) + + +def strip_end(lines): + """ + Strip blank strings from the end of list of strings. + """ + for i in range(len(lines) - 1, -1, -1): + if not lines[i]: + del lines[i] + else: + break + + +def normalize_data(lines): + """ + Strip comments and trailing blank strings from lines. + """ + result = [s for s in lines if not s.startswith('#')] + strip_end(result) + return result + + +class AsciiDocTest(object): + def __init__(self): + self.number = None # Test number (1..). + self.name = '' # Optional test name. + self.title = '' # Optional test name. + self.description = [] # List of lines followoing title. + self.source = None # AsciiDoc test source file name. + self.options = [] + self.attributes = {'asciidoc-version': 'test'} + self.backends = BACKENDS + self.artifacts = [] # list of generated artifacts to delete + self.requires = [] # list of dependencies to check for for the test + self.confdir = None + self.datadir = None # Where output files are stored. + self.disabled = False + self.passed = self.skipped = self.failed = 0 + + def backend_filename(self, backend): + """ + Return the path name of the backend output file that is generated from + the test name and output file type. + """ + return '%s-%s%s' % ( + os.path.normpath(os.path.join(self.datadir, self.name)), + backend, + BACKEND_EXT[backend] + ) + + def parse(self, lines, confdir, datadir): + """ + Parse conf file test section from list of text lines. + """ + self.__init__() + self.confdir = confdir + self.datadir = datadir + lines = Lines(lines) + while not lines.eol(): + text = lines.read_until(r'^%') + if text: + if not text[0].startswith('%'): + if text[0][0] == '!': + self.disabled = True + self.title = text[0][1:] + else: + self.title = text[0] + self.description = text[1:] + continue + reo = re.match(r'^%\s*(?P[\w_-]+)', text[0]) + if not reo: + raise ValueError + directive = reo.groupdict()['directive'] + data = normalize_data(text[1:]) + if directive == 'source': + if data: + self.source = os.path.normpath(os.path.join( + self.confdir, os.path.normpath(data[0]) + )) + elif directive == 'options': + self.options = eval(' '.join(data)) + for i, v in enumerate(self.options): + if isinstance(v, str): + self.options[i] = (v, None) + elif directive == 'attributes': + self.attributes.update(eval(' '.join(data))) + elif directive == 'backends': + self.backends = eval(' '.join(data)) + elif directive == 'name': + self.name = data[0].strip() + elif directive == 'requires': + self.requires = eval(' '.join(data)) + elif directive == 'artifacts': + self.artifacts = eval(' '.join(data)) + else: + raise ValueError + if not self.title: + self.title = self.source + if not self.name: + self.name = os.path.basename(os.path.splitext(self.source)[0]) + + def is_missing(self, backend): + """ + Returns True if there is no output test data file for backend. + """ + return not os.path.isfile(self.backend_filename(backend)) + + def is_missing_or_outdated(self, backend): + """ + Returns True if the output test data file is missing or out of date. + """ + return self.is_missing(backend) or ( + os.path.getmtime(self.source) + > os.path.getmtime(self.backend_filename(backend)) + ) + + def clean_artifacts(self): + for artifact in self.artifacts: + loc = os.path.join(self.confdir, artifact) + if os.path.exists(loc): + os.unlink(loc) + + def get_expected(self, backend): + """ + Return expected test data output for backend. + """ + with open( + self.backend_filename(backend), + encoding='utf-8', + newline='' + ) as open_file: + return open_file.readlines() + + def generate_expected(self, backend): + """ + Generate and return test data output for backend. + """ + asciidoc.reset_asciidoc() + outfile = io.StringIO() + options = self.options[:] + options.append(('--out-file', outfile)) + options.append(('--backend', backend)) + for k, v in self.attributes.items(): + if v == '' or k[-1] in '!@': + s = str(k) + elif v is None: + s = k + '!' + else: + s = '%s=%s' % (k, v) + options.append(('--attribute', s)) + asciidoc.execute('asciidoc', options, [self.source]) + return outfile.getvalue().splitlines(keepends=True) + + def update_expected(self, backend): + """ + Generate and write backend data. + """ + lines = self.generate_expected(backend) + if not os.path.isdir(self.datadir): + print('CREATING: %s' % self.datadir) + os.mkdir(self.datadir) + with open( + self.backend_filename(backend), + 'w+', + encoding='utf-8', + newline='' + ) as open_file: + print('WRITING: %s' % open_file.name) + open_file.writelines(lines) + + def update(self, backend=None, force=False): + """ + Regenerate and update expected test data outputs. + """ + if backend is None: + backends = self.backends + else: + backends = [backend] + + print('SOURCE: asciidoc: %s' % self.source) + for backend in backends: + if force or self.is_missing_or_outdated(backend): + self.update_expected(backend) + print() + + self.clean_artifacts() + + def run(self, backend=None): + """ + Execute test. + Return True if test passes. + """ + if backend is None: + backends = self.backends + else: + backends = [backend] + result = True # Assume success. + self.passed = self.failed = self.skipped = 0 + print('%d: %s' % (self.number, self.title)) + if self.source and os.path.isfile(self.source): + print('SOURCE: asciidoc: %s' % self.source) + for backend in backends: + fromfile = self.backend_filename(backend) + skip = False + for require in self.requires: + if shutil.which(require) is None: + skip = True + break + if not skip and not self.is_missing(backend): + expected = self.get_expected(backend) + strip_end(expected) + got = self.generate_expected(backend) + strip_end(got) + lines = [] + for line in difflib.unified_diff(got, expected, n=0): + lines.append(line) + if lines: + result = False + self.failed += 1 + lines = lines[3:] + print('FAILED: %s: %s' % (backend, fromfile)) + message('+++ %s' % fromfile) + message('--- got') + for line in lines: + message(line) + message() + else: + self.passed += 1 + print('PASSED: %s: %s' % (backend, fromfile)) + else: + self.skipped += 1 + print('SKIPPED: %s: %s' % (backend, fromfile)) + self.clean_artifacts() + else: + self.skipped += len(backends) + if self.source: + msg = 'MISSING: %s' % self.source + else: + msg = 'NO ASCIIDOC SOURCE FILE SPECIFIED' + print(msg) + print('') + return result + + +class AsciiDocTests(object): + def __init__(self, conffile): + """ + Parse configuration file + :param conffile: + """ + self.conffile = conffile + self.passed = self.failed = self.skipped = 0 + # All file names are relative to configuration file directory. + self.confdir = os.path.dirname(self.conffile) + self.datadir = self.confdir # Default expected files directory. + self.tests = [] # List of parsed AsciiDocTest objects. + self.globals = {} + with open(self.conffile, encoding='utf-8') as open_file: + lines = Lines(open_file.readlines()) + first = True + while not lines.eol(): + s = lines.read_until(r'^%+$') + s = [line for line in s if len(line) > 0] # Drop blank lines. + # Must be at least one non-blank line in addition to delimiter. + if len(s) > 1: + # Optional globals precede all tests. + if first and re.match(r'^%\s*globals$', s[0]): + self.globals = eval(' '.join(normalize_data(s[1:]))) + if 'datadir' in self.globals: + self.datadir = os.path.join( + self.confdir, + os.path.normpath(self.globals['datadir']) + ) + else: + test = AsciiDocTest() + test.parse(s[1:], self.confdir, self.datadir) + self.tests.append(test) + test.number = len(self.tests) + first = False + + def run(self, number=None, backend=None): + """ + Run all tests. + If number is specified run test number (1..). + """ + self.passed = self.failed = self.skipped = 0 + for test in self.tests: + if ( + (not test.disabled or number) + and (not number or number == test.number) + and (not backend or backend in test.backends) + ): + test.run(backend) + self.passed += test.passed + self.failed += test.failed + self.skipped += test.skipped + if self.passed > 0: + print('TOTAL PASSED: %s' % self.passed) + if self.failed > 0: + print('TOTAL FAILED: %s' % self.failed) + if self.skipped > 0: + print('TOTAL SKIPPED: %s' % self.skipped) + + def update(self, number=None, backend=None, force=False): + """ + Regenerate expected test data and update configuratio file. + """ + for test in self.tests: + if (not test.disabled or number) and (not number or number == test.number): + test.update(backend, force=force) + + def list(self): + """ + Lists tests to stdout. + """ + for test in self.tests: + print('%d: %s%s' % (test.number, iif(test.disabled, '!'), test.title)) + + +class Lines(list): + """ + A list of strings. + Adds eol() and read_until() to list type. + """ + + def __init__(self, lines): + super(Lines, self).__init__() + self.extend([s.rstrip() for s in lines]) + self.pos = 0 + + def eol(self): + return self.pos >= len(self) + + def read_until(self, regexp): + """ + Return a list of lines from current position up until the next line + matching regexp. + Advance position to matching line. + """ + result = [] + if not self.eol(): + result.append(self[self.pos]) + self.pos += 1 + while not self.eol(): + if re.match(regexp, self[self.pos]): + break + result.append(self[self.pos]) + self.pos += 1 + return result + + +if __name__ == '__main__': + # guarantee a stable timestamp matching the test fixtures + os.environ['SOURCE_DATE_EPOCH'] = '1038184662' + # Process command line options. + from argparse import ArgumentParser + parser = ArgumentParser( + description='Run AsciiDoc conformance tests specified in configuration' + 'FILE.' + ) + msg = 'Use configuration file CONF_FILE (default configuration file is '\ + 'testasciidoc.conf in testasciidoc.py directory)' + parser.add_argument( + '-v', + '--version', + action='version', + version='%(prog)s {}'.format(__version__) + ) + parser.add_argument('-f', '--conf-file', help=msg) + + subparsers = parser.add_subparsers(metavar='command', dest='command') + subparsers.required = True + + subparsers.add_parser('list', help='List tests') + + options = ArgumentParser(add_help=False) + options.add_argument('-n', '--number', type=int, help='Test number to run') + options.add_argument('-b', '--backend', type=str, help='Backend to run') + + subparsers.add_parser('run', help='Execute tests', parents=[options]) + + subparser = subparsers.add_parser( + 'update', + help='Regenerate and update test data', + parents=[options] + ) + subparser.add_argument( + '--force', + action='store_true', + help='Update all test data overwriting existing data' + ) + + args = parser.parse_args() + + conffile = os.path.join(os.path.dirname(sys.argv[0]), 'testasciidoc.conf') + force = 'force' in args and args.force is True + if args.conf_file is not None: + conffile = args.conf_file + if not os.path.isfile(conffile): + message('missing CONF_FILE: %s' % conffile) + sys.exit(1) + tests = AsciiDocTests(conffile) + cmd = args.command + number = None + backend = None + if 'number' in args: + number = args.number + if 'backend' in args: + backend = args.backend + if backend and backend not in BACKENDS: + message('illegal BACKEND: {:s}'.format(backend)) + sys.exit(1) + if number is not None and (number < 1 or number > len(tests.tests)): + message('illegal test NUMBER: {:d}'.format(number)) + sys.exit(1) + if cmd == 'run': + tests.run(number, backend) + if tests.failed: + sys.exit(1) + elif cmd == 'update': + tests.update(number, backend, force=force) + elif cmd == 'list': + tests.list() diff --git a/tests/inputs/filters-test.txt b/tests/inputs/filters-test.txt new file mode 100644 index 0000000..a8b051e --- /dev/null +++ b/tests/inputs/filters-test.txt @@ -0,0 +1,90 @@ +Filter Tests +============ + + +== Toy filter example from User Guide + +[code,python] +---------------------------------------------- +''' A multi-line + comment.''' +def sub_word(mo): + ''' Single line comment.''' + word = mo.group('word') # Inline comment + if word in keywords[language]: + return quote + word + quote + else: + return word +---------------------------------------------- + + +== Pychart Chart generations from FAQ + +// Generate chart image file. +sys2::[python "{indir}/barchart.py" --format=png --output="{outdir={indir}}/{imagesdir=}{imagesdir?/}barchart.png" --scale=2] + +// Display chart image file. +image::barchart.png[] + + +== Graphviz Graphs + +.Simple graph +["graphviz", "graphviz1.png", alt="Graphviz->AsciiDoc->HTML"] +--------------------------------------------------------------------- +digraph G { rankdir=LR; Graphviz->AsciiDoc->HTML} +--------------------------------------------------------------------- + +.Not so simple graph +["graphviz", "graphviz2.png"] +--------------------------------------------------------------------- +digraph automata_0 { + size ="8.5, 11"; + node [shape = circle]; + 0 [ style = filled, color=lightgrey ]; + 2 [ shape = doublecircle ]; + 0 -> 2 [ label = "a " ]; + 0 -> 1 [ label = "other " ]; + 1 -> 2 [ label = "a " ]; + 1 -> 1 [ label = "other " ]; + 2 -> 2 [ label = "a " ]; + 2 -> 1 [ label = "other " ]; + "Machine: a" [ shape = plaintext ]; +} +--------------------------------------------------------------------- + + +== Music filter + +.A tune generated from ABC notation +[music,music1.png] +--------------------------------------------------------------------- +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. +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):| +--------------------------------------------------------------------- + +<>. + +[[X1]] +.A fragment generated from LilyPond source +["music", "music2.png", "ly", link="music2.ly"] +--------------------------------------------------------------------- +\version "2.10.0" +\paper { + ragged-right = ##t +} +{ + \time 3/4 + \clef bass + c2 e4 g2. f4 e d c2 r4 +} +--------------------------------------------------------------------- diff --git a/tests/inputs/include-lines-test.txt b/tests/inputs/include-lines-test.txt new file mode 100644 index 0000000..6f0fd2c --- /dev/null +++ b/tests/inputs/include-lines-test.txt @@ -0,0 +1,23 @@ +include line test +================= + +The imports: + +[source,python] +---- +include::./dummy_file.py[lines="6..15"] +---- + +Some random ranges: + +[source,python] +---- +include::./dummy_file.py[lines="29..44,61..68,70,398..-1"] +---- + +Using ; as separator: + +[source,python] +---- +include::./dummy_file.py[lines="29..44;61..68"] +---- diff --git a/tests/inputs/lang-cs-man-test.txt b/tests/inputs/lang-cs-man-test.txt new file mode 100644 index 0000000..9c3726a --- /dev/null +++ b/tests/inputs/lang-cs-man-test.txt @@ -0,0 +1,21 @@ +// Test for lang-it.conf language file. +:lang: cs + +ASCIIDOC(1) +=========== +:doctype: manpage + +NAME +---- +asciidoc - converts an AsciiDoc text file to HTML or DocBook + +SINOSSI +------- +*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. + +... diff --git a/tests/inputs/lang-cs-test.txt b/tests/inputs/lang-cs-test.txt new file mode 100644 index 0000000..f960fb7 --- /dev/null +++ b/tests/inputs/lang-cs-test.txt @@ -0,0 +1,106 @@ +// Test for lang-cs.conf language file. +:lang: cs + +Languages Test +============== +:revnumber: v1.0 +:revdate: 2003-12-21 + +ifdef::doctype-article[] +Abstract +-------- +Abstract special section. + +endif::doctype-article[] + + +ifdef::doctype-book[] +Dedica +------ +Dedication special section. + + +Prefazione +---------- +Preface special section. + + +Colofone +-------- +Colophon special section. + +endif::doctype-book[] + + +The First Section +----------------- +Admonishments +~~~~~~~~~~~~~ +Do not translate in the source file -- they are translated to the +output file + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[Tiger image] + +Followed by an example table: + +.Table +[width="60%",options="header"] +|============================================== +| Option | Description +| -a 'USER GROUP' | Add 'USER' to 'GROUP'. +| -R 'GROUP' | Disables access to 'GROUP'. +|============================================== + +And now for something completely different: ((monkeys)), lions and +tigers. + + +Appendice A: Example Appendix +----------------------------- +Appendix special section. + + +Bibliografia +------------ +Bibliography special section. + +[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. + + +Glossario +--------- +Glossary special section. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + + +ifdef::basebackend-docbook[] +Index +----- +//////////////////////////////////////////////////////////////// +Index special section. +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/lang-de-man-test.txt b/tests/inputs/lang-de-man-test.txt new file mode 100644 index 0000000..f1806d4 --- /dev/null +++ b/tests/inputs/lang-de-man-test.txt @@ -0,0 +1,21 @@ +// Test for lang-de.conf language file. +:lang: de + +ASCIIDOC(1) +=========== +:doctype: manpage + +NAME +---- +asciidoc - converts an AsciiDoc text file to HTML or DocBook + +ÜBERSICHT +--------- +*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. + +... diff --git a/tests/inputs/lang-de-test.txt b/tests/inputs/lang-de-test.txt new file mode 100644 index 0000000..ebddb62 --- /dev/null +++ b/tests/inputs/lang-de-test.txt @@ -0,0 +1,106 @@ +// Test for lang-de.conf language file. +:lang: de + +Languages Test +============== +:revnumber: v1.0 +:revdate: 2003-12-21 + +ifdef::doctype-article[] +Zusammenfassung +--------------- +Abstract special section. + +endif::doctype-article[] + + +ifdef::doctype-book[] +Widmung +------- +Dedication special section. + + +Vorwort +------- +Preface special section. + + +Kolophon +-------- +Colophon special section. + +endif::doctype-book[] + + +The First Section +----------------- +Admonishments +~~~~~~~~~~~~~ +Do not translate in the source file -- they are translated to the +output file + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[Tiger image] + +Followed by an example table: + +.Table +[width="60%",options="header"] +|============================================== +| Option | Description +| -a 'USER GROUP' | Add 'USER' to 'GROUP'. +| -R 'GROUP' | Disables access to 'GROUP'. +|============================================== + +And now for something completely different: ((monkeys)), lions and +tigers. + + +Anhang A: Example Appendix +-------------------------- +Appendix special section. + + +Literaturverzeichnis +-------------------- +Bibliography special section. + +[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. + + +Glossar +------- +Glossary special section. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + + +ifdef::basebackend-docbook[] +Stichwortverzeichnis +-------------------- +//////////////////////////////////////////////////////////////// +Index special section. +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/lang-en-man-test.txt b/tests/inputs/lang-en-man-test.txt new file mode 100644 index 0000000..0dec04a --- /dev/null +++ b/tests/inputs/lang-en-man-test.txt @@ -0,0 +1,21 @@ +// Test for lang-en.conf language file. +:lang: en + +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. + +... diff --git a/tests/inputs/lang-en-test.txt b/tests/inputs/lang-en-test.txt new file mode 100644 index 0000000..a312458 --- /dev/null +++ b/tests/inputs/lang-en-test.txt @@ -0,0 +1,114 @@ +// Test for lang-en.conf language file. +:lang: en + +Languages Test +============== +:revnumber: v1.0 +:revdate: 2003-12-21 + +ifdef::doctype-article[] +// Translate title. +Abstract +-------- +Abstract special section. + +endif::doctype-article[] + + +ifdef::doctype-book[] +// Translate title. +Dedication +---------- +Dedication special section. + + +// Translate title. +Preface +------- +Preface special section. + + +// Translate title. +Colophon +-------- +Colophon special section. + +endif::doctype-book[] + + +The First Section +----------------- +Admonishments +~~~~~~~~~~~~~ +Do not translate in the source file -- they are translated to the +output file + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[Tiger image] + +Followed by an example table: + +.Table +[width="60%",options="header"] +|============================================== +| Option | Description +| -a 'USER GROUP' | Add 'USER' to 'GROUP'. +| -R 'GROUP' | Disables access to 'GROUP'. +|============================================== + +And now for something completely different: ((monkeys)), lions and +tigers. + + +// Translate title. +Appendix A: Example Appendix +---------------------------- +Appendix special section. + + +// Translate title. +Bibliography +------------ +Bibliography special section. + +[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. + + +// Translate title. +Glossary +-------- +Glossary special section. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + + +ifdef::basebackend-docbook[] +// Translate title. +Index +----- +//////////////////////////////////////////////////////////////// +Index special section. +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/lang-es-man-test.txt b/tests/inputs/lang-es-man-test.txt new file mode 100644 index 0000000..cb95b70 --- /dev/null +++ b/tests/inputs/lang-es-man-test.txt @@ -0,0 +1,21 @@ +// Test for lang-es.conf language file. +:lang: es + +ASCIIDOC(1) +=========== +:doctype: manpage + +NAME +---- +asciidoc - converts an AsciiDoc text file to HTML or DocBook + +SINOPSIS +-------- +*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. + +... diff --git a/tests/inputs/lang-es-test.txt b/tests/inputs/lang-es-test.txt new file mode 100644 index 0000000..97eca94 --- /dev/null +++ b/tests/inputs/lang-es-test.txt @@ -0,0 +1,106 @@ +// Test for lang-es.conf language file. +:lang: es + +Languages Test +============== +:revnumber: v1.0 +:revdate: 2003-12-21 + +ifdef::doctype-article[] +Resumen +------- +Abstract special section. + +endif::doctype-article[] + + +ifdef::doctype-book[] +Dedicación +---------- +Dedication special section. + + +Prefacio +-------- +Preface special section. + + +Colofón +------- +Colophon special section. + +endif::doctype-book[] + + +The First Section +----------------- +Admonishments +~~~~~~~~~~~~~ +Do not translate in the source file -- they are translated to the +output file + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[Tiger image] + +Followed by an example table: + +.Table +[width="60%",options="header"] +|============================================== +| Option | Description +| -a 'USER GROUP' | Add 'USER' to 'GROUP'. +| -R 'GROUP' | Disables access to 'GROUP'. +|============================================== + +And now for something completely different: ((monkeys)), lions and +tigers. + + +Apéndice A: Example Appendix +---------------------------- +Appendix special section. + + +Bibliografía +------------ +Bibliography special section. + +[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. + + +Glosario +-------- +Glossary special section. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + + +ifdef::basebackend-docbook[] +Índice +------ +//////////////////////////////////////////////////////////////// +Index special section. +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/lang-fr-man-test.txt b/tests/inputs/lang-fr-man-test.txt new file mode 100644 index 0000000..edb681f --- /dev/null +++ b/tests/inputs/lang-fr-man-test.txt @@ -0,0 +1,21 @@ +// Test for lang-fr.conf language file. +:lang: fr + +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. + +... diff --git a/tests/inputs/lang-fr-test.txt b/tests/inputs/lang-fr-test.txt new file mode 100644 index 0000000..84c25fa --- /dev/null +++ b/tests/inputs/lang-fr-test.txt @@ -0,0 +1,106 @@ +// Test for lang-fr.conf language file. +:lang: fr + +Languages Test +============== +:revnumber: v1.0 +:revdate: 2003-12-21 + +ifdef::doctype-article[] +Résumé +------ +Abstract special section. + +endif::doctype-article[] + + +ifdef::doctype-book[] +Dédicace +-------- +Dedication special section. + + +Préface +------- +Preface special section. + + +Colophon +-------- +Colophon special section. + +endif::doctype-book[] + + +The First Section +----------------- +Admonishments +~~~~~~~~~~~~~ +Do not translate in the source file -- they are translated to the +output file + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[Tiger image] + +Followed by an example table: + +.Table +[width="60%",options="header"] +|============================================== +| Option | Description +| -a 'USER GROUP' | Add 'USER' to 'GROUP'. +| -R 'GROUP' | Disables access to 'GROUP'. +|============================================== + +And now for something completely different: ((monkeys)), lions and +tigers. + + +Appendice A: Example Appendix +----------------------------- +Appendix special section. + + +Bibliographie +------------- +Bibliography special section. + +[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. + + +Glossaire +--------- +Glossary special section. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + + +ifdef::basebackend-docbook[] +Index +----- +//////////////////////////////////////////////////////////////// +Index special section. +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/lang-hu-man-test.txt b/tests/inputs/lang-hu-man-test.txt new file mode 100644 index 0000000..7caf1ad --- /dev/null +++ b/tests/inputs/lang-hu-man-test.txt @@ -0,0 +1,21 @@ +// Test for lang-hu.conf language file. +:lang: hu + +ASCIIDOC(1) +=========== +:doctype: manpage + +NAME +---- +asciidoc - converts an AsciiDoc text file to HTML or DocBook + +ÁTTEKINTÉS +---------- +*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. + +... diff --git a/tests/inputs/lang-hu-test.txt b/tests/inputs/lang-hu-test.txt new file mode 100644 index 0000000..cf873c2 --- /dev/null +++ b/tests/inputs/lang-hu-test.txt @@ -0,0 +1,106 @@ +// Test for lang-hu.conf language file. +:lang: hu + +Languages Test +============== +:revnumber: v1.0 +:revdate: 2003-12-21 + +ifdef::doctype-article[] +Kivonat +------- +Abstract special section. + +endif::doctype-article[] + + +ifdef::doctype-book[] +Ajánlás +-------- +Dedication special section. + + +Előszó +------ +Preface special section. + + +Utószó +------ +Colophon special section. + +endif::doctype-book[] + + +The First Section +----------------- +Admonishments +~~~~~~~~~~~~~ +Do not translate in the source file -- they are translated to the +output file + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[Tiger image] + +Followed by an example table: + +.Table +[width="60%",options="header"] +|============================================== +| Option | Description +| -a 'USER GROUP' | Add 'USER' to 'GROUP'. +| -R 'GROUP' | Disables access to 'GROUP'. +|============================================== + +And now for something completely different: ((monkeys)), lions and +tigers. + + +A függelék: Example Appendix +---------------------------- +Appendix special section. + + +Bibliográfia +------------ +Bibliography special section. + +[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. + + +Szójegyzék +---------- +Glossary special section. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + + +ifdef::basebackend-docbook[] +Index +----- +//////////////////////////////////////////////////////////////// +Index special section. +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/lang-it-man-test.txt b/tests/inputs/lang-it-man-test.txt new file mode 100644 index 0000000..7309a0c --- /dev/null +++ b/tests/inputs/lang-it-man-test.txt @@ -0,0 +1,21 @@ +// Test for lang-it.conf language file. +:lang: it + +ASCIIDOC(1) +=========== +:doctype: manpage + +NAME +---- +asciidoc - converts an AsciiDoc text file to HTML or DocBook + +SINOSSI +------- +*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. + +... diff --git a/tests/inputs/lang-it-test.txt b/tests/inputs/lang-it-test.txt new file mode 100644 index 0000000..790a57e --- /dev/null +++ b/tests/inputs/lang-it-test.txt @@ -0,0 +1,106 @@ +// Test for lang-it.conf language file. +:lang: it + +Languages Test +============== +:revnumber: v1.0 +:revdate: 2003-12-21 + +ifdef::doctype-article[] +Abstract +-------- +Abstract special section. + +endif::doctype-article[] + + +ifdef::doctype-book[] +Dedica +------ +Dedication special section. + + +Prefazione +---------- +Preface special section. + + +Colofone +-------- +Colophon special section. + +endif::doctype-book[] + + +The First Section +----------------- +Admonishments +~~~~~~~~~~~~~ +Do not translate in the source file -- they are translated to the +output file + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[Tiger image] + +Followed by an example table: + +.Table +[width="60%",options="header"] +|============================================== +| Option | Description +| -a 'USER GROUP' | Add 'USER' to 'GROUP'. +| -R 'GROUP' | Disables access to 'GROUP'. +|============================================== + +And now for something completely different: ((monkeys)), lions and +tigers. + + +Appendice A: Example Appendix +----------------------------- +Appendix special section. + + +Bibliografia +------------ +Bibliography special section. + +[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. + + +Glossario +--------- +Glossary special section. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + + +ifdef::basebackend-docbook[] +Index +----- +//////////////////////////////////////////////////////////////// +Index special section. +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/lang-ja-man-test.txt b/tests/inputs/lang-ja-man-test.txt new file mode 100644 index 0000000..2ecaa14 --- /dev/null +++ b/tests/inputs/lang-ja-man-test.txt @@ -0,0 +1,18 @@ +// Test for lang-ja.conf language file. +:lang: ja + +ASCIIDOC(1) +=========== +:doctype: manpage + +== 名前 +asciidoc - AsciiDoc テキストファイルを HTML や DocBook に変換する + +== 書式 +*asciidoc* ['OPTIONS'] 'FILE' + +== 説明 +asciidoc(1) コマンドは AsciiDoc テキストファイル 'FILE' を DocBook +や HTML に変換する。 'FILE' が '-' ならば標準入力を使用する。 + +... diff --git a/tests/inputs/lang-ja-test.txt b/tests/inputs/lang-ja-test.txt new file mode 100644 index 0000000..13bec4c --- /dev/null +++ b/tests/inputs/lang-ja-test.txt @@ -0,0 +1,94 @@ +// Test for lang-ja.conf language file. +:lang: ja + +Languages Test +============== +:revnumber: v1.0 +:revdate: 2003-12-21 + +ifdef::doctype-article[] +== 概要 +概要セクション + +endif::doctype-article[] + + +ifdef::doctype-book[] +== 献辞 +献辞セクション + + +== 前書 +前書セクション + + +== 奥付 +奥付セクション + +endif::doctype-book[] + + +== 第一セクション +=== 警告 +以下は処理系が翻訳するのでこのソースでは翻訳しない。 + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[虎の絵] + +続いて表の例。 + +.Table +[width="60%",options="header"] +|================================================= +| オプション | 説明 +| -a 'USER GROUP' | 'USER' を 'GROUP' に追加する +| -R 'GROUP' | 'GROUP' へのアクセスを禁止する +|================================================= + +そしてまったく異なるものの例: ((猿))、ライオン、虎。 + + +== 付録 A: 付録の例 +付録セクション + + +== 参考文献 +参考文献セクション + +[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] +用語:: + （インデントされた）用語の定義 + +別の用語:: + （インデントされた）用語の定義 + + +ifdef::basebackend-docbook[] +== 索引 +//////////////////////////////////////////////////////////////// +索引セクション。 +内容は DocBook ツールチェーンが自動生成するので、 +通常このセクションは空である。 +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/lang-nl-man-test.txt b/tests/inputs/lang-nl-man-test.txt new file mode 100644 index 0000000..4844c17 --- /dev/null +++ b/tests/inputs/lang-nl-man-test.txt @@ -0,0 +1,21 @@ +// Test for lang-nl.conf language file. +:lang: nl + +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. + +... diff --git a/tests/inputs/lang-nl-test.txt b/tests/inputs/lang-nl-test.txt new file mode 100644 index 0000000..7e6e823 --- /dev/null +++ b/tests/inputs/lang-nl-test.txt @@ -0,0 +1,94 @@ +// Test for lang-nl.conf language file. +:lang: nl + += Languages Test +:revnumber: v1.0 +:revdate: 2003-12-21 + +ifdef::doctype-article[] +== Samenvatting +Bijzonder 'abstract' sectie. + +endif::doctype-article[] + + +ifdef::doctype-book[] +== Opdracht +Bijzonder 'dedication' sectie. + + +== Voorwoord +Bijzonder 'preface' sectie. + + +== Colofon +Bijzonder 'colophon' sectie. + +endif::doctype-book[] + + +== Het Eerste Hoofdstuk +=== Vermaningen +Vertaal ze niet in the broncode -- ze worden vanzelf vertaald in het +output bestand + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[Tiger image] + +Gevolgd door een voorbeeld tabel: + +.Table +[width="60%",options="header"] +|============================================== +| Optie | Beschrijving +| -a 'USER GROUP' | Voeg 'USER' toe aan 'GROUP'. +| -R 'GROUP' | Schakel toegang uit tot 'GROUP'. +|============================================== + +En nu iets totaal anders: ((apen)), leeuwen en tijgers. + + +== Bijlage A: Voorbeeld Bijlage +Bijzonder 'appendix' sectie. + + +== Literatuurlijst +Bijzonder 'bibliography' sectie. + +[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. + + +== Woordenlijst +Bijzonder 'glossary' sectie. + +[glossary] +Een woordenlijst term:: + De bijhorende (ingesprongen) definitie. + +Een tweede term:: + De bijhorende (ingesprongen) definitie. + + +ifdef::basebackend-docbook[] +== Register +//////////////////////////////////////////////////////////////// +Bijzonder 'index' sectie. +Het register wordt normaal leeg gehouden, de inhoud wordt +automatisch gegenereerd door de DocBook hulpmiddelen. +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/lang-pt-BR-man-test.txt b/tests/inputs/lang-pt-BR-man-test.txt new file mode 100644 index 0000000..0363ea6 --- /dev/null +++ b/tests/inputs/lang-pt-BR-man-test.txt @@ -0,0 +1,21 @@ +// Test for lang-pt-BR.conf language file. +:lang: pt-BR + +ASCIIDOC(1) +=========== +:doctype: manpage + +NAME +---- +asciidoc - converts an AsciiDoc text file to HTML or DocBook + +SINOPSE +------- +*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. + +... diff --git a/tests/inputs/lang-pt-BR-test.txt b/tests/inputs/lang-pt-BR-test.txt new file mode 100644 index 0000000..daaff18 --- /dev/null +++ b/tests/inputs/lang-pt-BR-test.txt @@ -0,0 +1,106 @@ +// Test for lang-pt-BR.conf language file. +:lang: pt-BR + +Languages Test +============== +:revnumber: v1.0 +:revdate: 2003-12-21 + +ifdef::doctype-article[] +Resumo +------ +Abstract special section. + +endif::doctype-article[] + + +ifdef::doctype-book[] +Dedicação +--------- +Dedication special section. + + +Prefácio +-------- +Preface special section. + + +Cólofon +------- +Colophon special section. + +endif::doctype-book[] + + +The First Section +----------------- +Admonishments +~~~~~~~~~~~~~ +Do not translate in the source file -- they are translated to the +output file + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[Tiger image] + +Followed by an example table: + +.Table +[width="60%",options="header"] +|============================================== +| Option | Description +| -a 'USER GROUP' | Add 'USER' to 'GROUP'. +| -R 'GROUP' | Disables access to 'GROUP'. +|============================================== + +And now for something completely different: ((monkeys)), lions and +tigers. + + +Appêndice A: Example Appendix +----------------------------- +Appendix special section. + + +Bibliografia +------------ +Bibliography special section. + +[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. + + +Glossário +--------- +Glossary special section. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + + +ifdef::basebackend-docbook[] +Índice +------ +//////////////////////////////////////////////////////////////// +Index special section. +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/lang-ro-man-test.txt b/tests/inputs/lang-ro-man-test.txt new file mode 100644 index 0000000..7309a0c --- /dev/null +++ b/tests/inputs/lang-ro-man-test.txt @@ -0,0 +1,21 @@ +// Test for lang-it.conf language file. +:lang: it + +ASCIIDOC(1) +=========== +:doctype: manpage + +NAME +---- +asciidoc - converts an AsciiDoc text file to HTML or DocBook + +SINOSSI +------- +*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. + +... diff --git a/tests/inputs/lang-ro-test.txt b/tests/inputs/lang-ro-test.txt new file mode 100644 index 0000000..790a57e --- /dev/null +++ b/tests/inputs/lang-ro-test.txt @@ -0,0 +1,106 @@ +// Test for lang-it.conf language file. +:lang: it + +Languages Test +============== +:revnumber: v1.0 +:revdate: 2003-12-21 + +ifdef::doctype-article[] +Abstract +-------- +Abstract special section. + +endif::doctype-article[] + + +ifdef::doctype-book[] +Dedica +------ +Dedication special section. + + +Prefazione +---------- +Preface special section. + + +Colofone +-------- +Colophon special section. + +endif::doctype-book[] + + +The First Section +----------------- +Admonishments +~~~~~~~~~~~~~ +Do not translate in the source file -- they are translated to the +output file + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[Tiger image] + +Followed by an example table: + +.Table +[width="60%",options="header"] +|============================================== +| Option | Description +| -a 'USER GROUP' | Add 'USER' to 'GROUP'. +| -R 'GROUP' | Disables access to 'GROUP'. +|============================================== + +And now for something completely different: ((monkeys)), lions and +tigers. + + +Appendice A: Example Appendix +----------------------------- +Appendix special section. + + +Bibliografia +------------ +Bibliography special section. + +[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. + + +Glossario +--------- +Glossary special section. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + + +ifdef::basebackend-docbook[] +Index +----- +//////////////////////////////////////////////////////////////// +Index special section. +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/lang-ru-man-test.txt b/tests/inputs/lang-ru-man-test.txt new file mode 100644 index 0000000..3e50548 --- /dev/null +++ b/tests/inputs/lang-ru-man-test.txt @@ -0,0 +1,21 @@ +// Test for lang-ru.conf language file. +:lang: ru + +ASCIIDOC(1) +=========== +:doctype: manpage + +NAME +---- +asciidoc - converts an AsciiDoc text file to HTML or DocBook + +ОБЗОР +----- +*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. + +... diff --git a/tests/inputs/lang-ru-test.txt b/tests/inputs/lang-ru-test.txt new file mode 100644 index 0000000..51d9b60 --- /dev/null +++ b/tests/inputs/lang-ru-test.txt @@ -0,0 +1,106 @@ +// Test for lang-ru.conf language file. +:lang: ru + +Languages Test +============== +:revnumber: v1.0 +:revdate: 2003-12-21 + +ifdef::doctype-article[] +Аннотация +--------- +Abstract special section. + +endif::doctype-article[] + + +ifdef::doctype-book[] +Посвящение +---------- +Dedication special section. + + +Введение +-------- +Preface special section. + + +Колофон +------- +Colophon special section. + +endif::doctype-book[] + + +The First Section +----------------- +Admonishments +~~~~~~~~~~~~~ +Do not translate in the source file -- they are translated to the +output file + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[Tiger image] + +Followed by an example table: + +.Table +[width="60%",options="header"] +|============================================== +| Option | Description +| -a 'USER GROUP' | Add 'USER' to 'GROUP'. +| -R 'GROUP' | Disables access to 'GROUP'. +|============================================== + +And now for something completely different: ((monkeys)), lions and +tigers. + + +Приложение A: Example Appendix +------------------------------ +Appendix special section. + + +Библиография +------------ +Bibliography special section. + +[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 special section. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + + +ifdef::basebackend-docbook[] +Предметный указатель +-------------------- +//////////////////////////////////////////////////////////////// +Index special section. +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/lang-sv-man-test.txt b/tests/inputs/lang-sv-man-test.txt new file mode 100644 index 0000000..af82d8a --- /dev/null +++ b/tests/inputs/lang-sv-man-test.txt @@ -0,0 +1,21 @@ +// Test for lang-sv.conf language file. +:lang: sv + +ASCIIDOC(1) +=========== +:doctype: manpage + +NAMN +---- +asciidoc - converts an AsciiDoc text file to HTML or DocBook + +ÖVERSIKT +-------- +*asciidoc* ['OPTIONS'] 'FILE' + +BESKRIVNING +----------- +The asciidoc(1) command translates the AsciiDoc text file 'FILE' to +DocBook or HTML. If 'FILE' is '-' then the standard input is used. + +... diff --git a/tests/inputs/lang-sv-test.txt b/tests/inputs/lang-sv-test.txt new file mode 100644 index 0000000..1e64e3c --- /dev/null +++ b/tests/inputs/lang-sv-test.txt @@ -0,0 +1,114 @@ +// Test for lang-sv.conf language file. +:lang: sv + +Languages Test +============== +:revnumber: v1.0 +:revdate: 2003-12-21 + +ifdef::doctype-article[] +// Translate title. +Sammanfattning +-------------- +Abstract special section. + +endif::doctype-article[] + + +ifdef::doctype-book[] +// Translate title. +Dedikation +---------- +Dedication special section. + + +// Translate title. +Förord +------ +Preface special section. + + +// Translate title. +Kolofon +------- +Colophon special section. + +endif::doctype-book[] + + +The First Section +----------------- +Admonishments +~~~~~~~~~~~~~ +Do not translate in the source file -- they are translated to the +output file + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[Tiger image] + +Followed by an example table: + +.Table +[width="60%",options="header"] +|============================================== +| Option | Description +| -a 'USER GROUP' | Add 'USER' to 'GROUP'. +| -R 'GROUP' | Disables access to 'GROUP'. +|============================================== + +And now for something completely different: ((monkeys)), lions and +tigers. + + +// Translate title. +Appendix A: Exempel-appendix +---------------------------- +Appendix special section. + + +// Translate title. +Referenser +---------- +Bibliography special section. + +[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. + + +// Translate title. +Ordlista +-------- +Glossary special section. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + + +ifdef::basebackend-docbook[] +// Translate title. +Sakregister +----------- +//////////////////////////////////////////////////////////////// +Index special section. +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/lang-uk-man-test.txt b/tests/inputs/lang-uk-man-test.txt new file mode 100644 index 0000000..8212e4c --- /dev/null +++ b/tests/inputs/lang-uk-man-test.txt @@ -0,0 +1,21 @@ +// Test for lang-uk.conf language file. +:lang: uk + +ASCIIDOC(1) +=========== +:doctype: manpage + +NAME +---- +asciidoc - converts an AsciiDoc text file to HTML or DocBook + +ОГЛЯД +----- +*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. + +... diff --git a/tests/inputs/lang-uk-test.txt b/tests/inputs/lang-uk-test.txt new file mode 100644 index 0000000..76c58eb --- /dev/null +++ b/tests/inputs/lang-uk-test.txt @@ -0,0 +1,106 @@ +// Test for lang-uk.conf language file. +:lang: uk + +Languages Test +============== +:revnumber: v1.0 +:revdate: 2011-01-30 + +ifdef::doctype-article[] +Анотація +-------- +Abstract special section. + +endif::doctype-article[] + + +ifdef::doctype-book[] +Присвячення +----------- +Dedication special section. + + +Вступ +----- +Preface special section. + + +Колофон +------- +Colophon special section. + +endif::doctype-book[] + + +The First Section +----------------- +Admonishments +~~~~~~~~~~~~~ +Do not translate in the source file -- they are translated to the +output file + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +.Tiger +image::../../images/tiger.png[Tiger image] + +Followed by an example table: + +.Table +[width="60%",options="header"] +|============================================== +| Option | Description +| -a 'USER GROUP' | Add 'USER' to 'GROUP'. +| -R 'GROUP' | Disables access to 'GROUP'. +|============================================== + +And now for something completely different: ((monkeys)), lions and +tigers. + + +Додаток A: Example Appendix +--------------------------- +Appendix special section. + + +Бібліографія +------------ +Bibliography special section. + +[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 special section. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + + +ifdef::basebackend-docbook[] +Предметний покажчик +------------------- +//////////////////////////////////////////////////////////////// +Index special section. +The index is normally left completely empty, it's contents being +generated automatically by the DocBook toolchain. +//////////////////////////////////////////////////////////////// +endif::basebackend-docbook[] diff --git a/tests/inputs/latex-filter.txt b/tests/inputs/latex-filter.txt new file mode 100644 index 0000000..9d1a4f4 --- /dev/null +++ b/tests/inputs/latex-filter.txt @@ -0,0 +1,246 @@ +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. diff --git a/tests/inputs/latexmath.txt b/tests/inputs/latexmath.txt new file mode 100644 index 0000000..6f04321 --- /dev/null +++ b/tests/inputs/latexmath.txt @@ -0,0 +1,121 @@ +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] \] +++++++++++++++++++++++++++++++++++++++++++++ + + diff --git a/tests/inputs/latexmathml.txt b/tests/inputs/latexmathml.txt new file mode 100644 index 0000000..a1df891 --- /dev/null +++ b/tests/inputs/latexmathml.txt @@ -0,0 +1,41 @@ +LaTeXMathML Formulae +==================== + +https://www.maths.nottingham.ac.uk/plp/pmadw/lm.html[LaTeXMathML] +capability has been added to AsciiDoc for users who are more familar +with or prefer LaTeX math formulas to the +https://asciidoc.org/asciimath.html[ASCIIMath] +notation. + +'LaTeXMathML' is a derivative of +https://asciidoc.org/asciimath.html[ASCIIMath] -- in +terms of usage the only difference it that you use the `latexmath` +attribute instead of the `asciimath` attribute. + +'LaTeXMathML' processes LaTeX math formulas not arbitrary LaTeX (as +`dblatex(1)` does). See the +https://www.maths.nottingham.ac.uk/plp/pmadw/lm.html[LaTeXMathML] +website for details. + +Here's the link:latexmathml.txt[AsciiDoc source] that generated this +page. + +Some example 'LaTeXMathML' formulas: + +- latexmath:[$R_x = 10.0 \times \sin(R_\phi)$] + +- latexmath:[$\sum_{n=1}^\infty \frac{1}{2^n}$] + +- latexmath:[$\lim_{x\to\infty} f(x) = k \choose r + \frac ab + \sum_{n=1}^\infty a_n + \displaystyle{ \left\{ \frac{1}{13} + \sum_{n=1}^\infty b_n \right\} }$] + +- latexmath:[$\$\alpha + \$\beta = \$(\alpha + \beta)$] + +- latexmath:[$\begin{eqnarray} x & = & \frac{-7 \pm + \sqrt{49 - 24}}{6} \\ & = & -2 \textrm{ or } -\frac13. + \end{eqnarray}$] + +- latexmath:[$\displaystyle{ V_i = C_0 - C_3 + \frac{C_1\cos(\theta_i+C_3)}{C_4+C_1\cos(\theta_i+C_2)} }$] + diff --git a/tests/inputs/newline.txt b/tests/inputs/newline.txt new file mode 100644 index 0000000..ceead4a --- /dev/null +++ b/tests/inputs/newline.txt @@ -0,0 +1,17 @@ += Newline Tests + +These are tests about newlines. +See https://en.wikipedia.org/wiki/Newline[details] on the history. + +NOTE: Each section in the source file has the newline style from the + description. + +== UNIX Newlines + +Uses \n. + +== DOS Newlines + +Uses \r\n. + +== MAC Newlines Uses \r. Only used prior to Mac OS X. \ No newline at end of file diff --git a/tests/inputs/newtables.txt b/tests/inputs/newtables.txt new file mode 100644 index 0000000..839d347 --- /dev/null +++ b/tests/inputs/newtables.txt @@ -0,0 +1,743 @@ +AsciiDoc New tables +=================== + +*New in version 8.3.0* + +I've finally come up with a 'new tables' syntax that I'm happy with +and can at last remove this footnote from the 'User Guide': ``The +current table syntax is overly complicated and unwieldy to edit, +hopefully a more usable syntax will appear in future versions of +AsciiDoc.'' + +.Update +********************************************************************* +The following additions were made at AsciiDoc 8.4.4: + +- Cell column and row spanning. +- Styles can be applied per cell. +- Vertical cell alignment can be applied to columns and cells. + +See the examples at the end of this document. +********************************************************************* + +At first glance it doesn't look much different to the old syntax but +it's a lot more flexible, easier to enter and supports a lot of column +styles (for example the 'asciidoc' style supports AsciiDoc block and +inline elements). The old tables syntax has been deprecated but is +currently still processed. Here are some examples of AsciiDoc 'new +tables': + +.Simple table +[width="15%"] +|======= +|1 |2 |A +|3 |4 |B +|5 |6 |C +|======= + +.AsciiDoc source +--------------------------------------------------------------------- +[width="15%"] +|======= +|1 |2 |A +|3 |4 |B +|5 |6 |C +|======= +--------------------------------------------------------------------- + + +.Table with title, header and footer +[width="40%",frame="topbot",options="header,footer"] +|====================== +|Column 1 |Column 2 +|1 |Item 1 +|2 |Item 2 +|3 |Item 3 +|6 |Three items +|====================== + +.AsciiDoc source +--------------------------------------------------------------------- +.An example table +[width="40%",frame="topbot",options="header,footer"] +|====================== +|Column 1 |Column 2 +|1 |Item 1 +|2 |Item 2 +|3 |Item 3 +|6 |Three items +|====================== +--------------------------------------------------------------------- + + +.Columns formatted with strong, monospaced and emphasis styles +[width="50%",cols=">s,^2m,^2e",frame="topbot",options="header,footer"] +|========================== +| 2+|Columns 2 and 3 +|1 |Item 1 |Item 1 +|2 |Item 2 |Item 2 +|3 |Item 3 |Item 3 +|4 |Item 4 |Item 4 +|footer 1|footer 2|footer 3 +|========================== + +.AsciiDoc source +--------------------------------------------------------------------- +.An example table +[width="50%",cols=">s,^2m,^2e",frame="topbot",options="header,footer"] +|========================== +| 2+|Columns 2 and 3 +|1 |Item 1 |Item 1 +|2 |Item 2 |Item 2 +|3 |Item 3 |Item 3 +|4 |Item 4 |Item 4 +|footer 1|footer 2|footer 3 +|========================== +--------------------------------------------------------------------- + +.A table with externally sourced CSV data +[format="csv",cols="^1,4*2",options="header"] +|=================================================== +ID,Customer Name,Contact Name,Customer Address,Phone +include::customers.csv[] +|=================================================== + +.AsciiDoc source +--------------------------------------------------------------------- + [format="csv",cols="^1,4*2",options="header"] + |=================================================== + ID,Customer Name,Contact Name,Customer Address,Phone + include::customers.csv[] + |=================================================== +--------------------------------------------------------------------- + + +.DVS formatted table +[width="70%",format="dsv"] +|==================================== +root:x:0:0:root:/root:/bin/bash +daemon:x:1:1:daemon:/usr/sbin:/bin/sh +bin:x:2:2:bin:/bin:/bin/sh +sys:x:3:3:sys:/dev:/bin/sh +sync:x:4:65534:sync:/bin:/bin/sync +games:x:5:60:games:/usr/games:/bin/sh +|==================================== + +.AsciiDoc source +--------------------------------------------------------------------- +[width="70%",format="dsv"] +|==================================== +root:x:0:0:root:/root:/bin/bash +daemon:x:1:1:daemon:/usr/sbin:/bin/sh +bin:x:2:2:bin:/bin:/bin/sh +sys:x:3:3:sys:/dev:/bin/sh +sync:x:4:65534:sync:/bin:/bin/sync +games:x:5:60:games:/usr/games:/bin/sh +|==================================== +--------------------------------------------------------------------- + + +.Horizontal and vertical source data +[width="80%",cols="3,^2,^2,10",options="header"] +|========================================================= +|Date |Duration |Avg HR |Notes + +|22-Aug-08 |10:24 | 157 | +Worked out MSHR (max sustainable heart rate) by going hard +for this interval. + +|22-Aug-08 |23:03 | 152 | +Back-to-back with previous interval. + +|24-Aug-08 |40:00 | 145 | +Moderately hard interspersed with 3x 3min intervals (2min +hard + 1min really hard taking the HR up to 160). + +|========================================================= + +Short cells can be entered horizontally, longer cells vertically. The +default behavior is to strip leading and trailing blank lines within a +cell. These characteristics aid readability and data entry. + +.AsciiDoc source +--------------------------------------------------------------------- +.Windtrainer workouts +[width="80%",cols="3,^2,^2,10",options="header"] +|========================================================= +|Date |Duration |Avg HR |Notes + +|22-Aug-08 |10:24 | 157 | +Worked out MSHR (max sustainable heart rate) by going hard +for this interval. + +|22-Aug-08 |23:03 | 152 | +Back-to-back with previous interval. + +|24-Aug-08 |40:00 | 145 | +Moderately hard interspersed with 3x 3min intervals (2min +hard + 1min really hard taking the HR up to 160). + +|========================================================= +--------------------------------------------------------------------- + + +.Default and verse styles +[cols=",^v",options="header"] +|=================================== +|Default paragraphs |Centered verses +2*|Per id. + +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. +|=================================== + +.AsciiDoc source +--------------------------------------------------------------------- +[cols=",^v",options="header"] +|=================================== +|Default paragraphs |Centered verses +2*|Per id. + +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. +|=================================== +--------------------------------------------------------------------- + + +.Horizontal and vertial headings +[cols="h,4*",options="header",width="50%"] +|================================== +| |West |Central |East | Total +|Q1 |270 |292 |342 | 904 +|Q2 |322 |276 |383 | 981 +|Q3 |298 |252 |274 | 824 +|Q4 |344 |247 |402 | 993 +|================================== + +.AsciiDoc source +--------------------------------------------------------------------- +.Horizontal and vertial headings +[cols="h,4*",options="header",width="50%"] +|================================== +| |West |Central |East | Total +|Q1 |270 |292 |342 | 904 +|Q2 |322 |276 |383 | 981 +|Q3 |298 |252 |274 | 824 +|Q4 |344 |247 |402 | 993 +|================================== +--------------------------------------------------------------------- + + +.AsciiDoc style in first column, Literal in second +[cols="asciidoc,literal",options="header",grid="cols"] +|================================== +|Output markup |AsciiDoc source +2*| +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +----------------------------------- +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. +----------------------------------- + +.Code filter example +[source,python] +----------------------------------- +''' A multi-line + comment.''' +def sub_word(mo): + ''' Single line comment.''' + word = mo.group('word') + if word in keywords[language]: + return quote + word + quote + else: + return word +----------------------------------- + +- Lorem ipsum dolor sit amet, + consectetuer adipiscing elit. + * Fusce euismod commodo velit. + * Qui in magna commodo, est labitur + dolorum an. Est ne magna primis + adolescens. Sit munere ponderum + dignissim et. Minim luptatum et vel. + * Vivamus fringilla mi eu lacus. + * Donec eget arcu bibendum nunc + consequat lobortis. +- Nulla porttitor vulputate libero. + . Fusce euismod commodo velit. + . Vivamus fringilla mi eu lacus. + +|================================== + +.AsciiDoc source +[listing] +..................................................................... +[cols="asciidoc,literal",options="header",grid="cols"] +|================================== +|Output markup |AsciiDoc source +2*| +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +----------------------------------- +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. +----------------------------------- + +.Code filter example +[source,python] +----------------------------------- +''' A multi-line + comment.''' +def sub_word(mo): + ''' Single line comment.''' + word = mo.group('word') + if word in keywords[language]: + return quote + word + quote + else: + return word +----------------------------------- + +- Lorem ipsum dolor sit amet, + consectetuer adipiscing elit. + * Fusce euismod commodo velit. + * Qui in magna commodo, est labitur + dolorum an. Est ne magna primis + adolescens. Sit munere ponderum + dignissim et. Minim luptatum et vel. + * Vivamus fringilla mi eu lacus. + * Donec eget arcu bibendum nunc + consequat lobortis. +- Nulla porttitor vulputate libero. + . Fusce euismod commodo velit. + . Vivamus fringilla mi eu lacus. + +|================================== +..................................................................... + + +.Cell containing lots of example markup elements +|==================================================================== +|'URLs': +https://asciidoc.org/[The AsciiDoc home page], +https://asciidoc.org/, +mailto:joe.bloggs@example.com[email Joe Bloggs], +joe.bloggs@example.com, +callto:joe.bloggs[]. + +'Link': See <>. + +'Emphasized text', *Strong text*, +Monospaced text+, ``Quoted text''. + +'Subscripts and superscripts': e^{amp}#960;i^+1 = 0. H~2~O and x^10^. +Some ^super text^ and ~some sub text~ + +'Replacements': (C) copyright, (TM) trademark, (R) registered trademark, +-- em dash, ... ellipsis, -> right arrow, <- left arrow, => right +double arrow, <= left double arrow. +|==================================================================== + +[[X1]] +.AsciiDoc source +--------------------------------------------------------------------- +|==================================================================== +|'URLs': +https://asciidoc.org/[The AsciiDoc home page], +https://asciidoc.org/, +mailto:joe.bloggs@example.com[email Joe Bloggs], +joe.bloggs@example.com, +callto:joe.bloggs[]. + +'Link': See <>. + +'Emphasized text', *Strong text*, +Monospaced text+, ``Quoted text''. + +'Subscripts and superscripts': e^{amp}#960;i^+1 = 0. H~2~O and x^10^. +Some ^super text^ and ~some sub text~ + +'Replacements': (C) copyright, (TM) trademark, (R) registered trademark, +-- em dash, ... ellipsis, -> right arrow, <- left arrow, => right +double arrow, <= left double arrow. +|==================================================================== +--------------------------------------------------------------------- + + +.Nested table +[width="75%",cols="1,2a"] +|============================================== +|Normal cell + +|Cell with nested table + +[cols="2,1"] +!============================================== +!Nested table cell 1 !Nested table cell 2 +!============================================== + +|============================================== + +.AsciiDoc source +--------------------------------------------------------------------- +[width="75%",cols="1,2a"] +|============================================== +|Normal cell + +|Cell with nested table + +[cols="2,1"] +!============================================== +!Nested table cell 1 !Nested table cell 2 +!============================================== + +|============================================== +--------------------------------------------------------------------- + + +.Spans, alignments and styles +[cols="e,m,^,>s",width="25%"] +|================ +|1 >s|2 |3 |4 +^|5 2.2+^.^|6 .3+<.>m|7 +^|8 +|9 2+>|10 +|================ + +.AsciiDoc source +--------------------------------------------------------------------- +.Spans, alignments and styles +[cols="e,m,^,>s",width="25%"] +|================ +|1 >s|2 |3 |4 +^|5 2.2+^.^|6 .3+<.>m|7 +^|8 +|9 2+>|10 +|================ +--------------------------------------------------------------------- + +.Three panes +[cols="a,2a"] +|================================== +| +[float] +Top Left Pane +~~~~~~~~~~~~~ +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +.2+| +[float] +Right Pane +~~~~~~~~~~ +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +----------------------------------- +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. +----------------------------------- + +.Code filter example +[source,python] +----------------------------------- +''' A multi-line + comment.''' +def sub_word(mo): + ''' Single line comment.''' + word = mo.group('word') + if word in keywords[language]: + return quote + word + quote + else: + return word +----------------------------------- + +- Lorem ipsum dolor sit amet, + consectetuer adipiscing elit. + * Fusce euismod commodo velit. + * Qui in magna commodo, est labitur + dolorum an. Est ne magna primis + adolescens. Sit munere ponderum + dignissim et. Minim luptatum et vel. + * Vivamus fringilla mi eu lacus. + * Donec eget arcu bibendum nunc + consequat lobortis. +- Nulla porttitor vulputate libero. + . Fusce euismod commodo velit. + . Vivamus fringilla mi eu lacus. + +| +[float] +Bottom Left Pane +~~~~~~~~~~~~~~~~ +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +- Lorem ipsum dolor sit amet, + consectetuer adipiscing elit. + * Fusce euismod commodo velit. + * Qui in magna commodo, est labitur + dolorum an. Est ne magna primis + adolescens. Sit munere ponderum + dignissim et. Minim luptatum et vel. + * Vivamus fringilla mi eu lacus. + * Donec eget arcu bibendum nunc + consequat lobortis. +- Nulla porttitor vulputate libero. + . Fusce euismod commodo velit. + . Vivamus fringilla mi eu lacus. + +|================================== + +.AsciiDoc source +[listing] +..................................................................... +.Three panes +[cols="a,2a"] +|================================== +| +[float] +Top Left Pane +~~~~~~~~~~~~~ +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +.2+| +[float] +Right Pane +~~~~~~~~~~ +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +----------------------------------- +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. +----------------------------------- + +.Code filter example +[source,python] +----------------------------------- +''' A multi-line + comment.''' +def sub_word(mo): + ''' Single line comment.''' + word = mo.group('word') + if word in keywords[language]: + return quote + word + quote + else: + return word +----------------------------------- + +- Lorem ipsum dolor sit amet, + consectetuer adipiscing elit. + * Fusce euismod commodo velit. + * Qui in magna commodo, est labitur + dolorum an. Est ne magna primis + adolescens. Sit munere ponderum + dignissim et. Minim luptatum et vel. + * Vivamus fringilla mi eu lacus. + * Donec eget arcu bibendum nunc + consequat lobortis. +- Nulla porttitor vulputate libero. + . Fusce euismod commodo velit. + . Vivamus fringilla mi eu lacus. + +| +[float] +Bottom Left Pane +~~~~~~~~~~~~~~~~ +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +Consul *necessitatibus* per id, +consetetur, eu pro everti postulant +homero verear ea mea, qui. + +- Lorem ipsum dolor sit amet, + consectetuer adipiscing elit. + * Fusce euismod commodo velit. + * Qui in magna commodo, est labitur + dolorum an. Est ne magna primis + adolescens. Sit munere ponderum + dignissim et. Minim luptatum et vel. + * Vivamus fringilla mi eu lacus. + * Donec eget arcu bibendum nunc + consequat lobortis. +- Nulla porttitor vulputate libero. + . Fusce euismod commodo velit. + . Vivamus fringilla mi eu lacus. + +|================================== +..................................................................... + + +== Combinations of 'align', 'frame', 'grid', 'valign' and 'halign' attributes + +:frame: all +:grid: all +:halign: left +:valign: top + +[options="header"] +|==== +||frame | grid |valign |halign +v|  +  +  +|{frame} | {grid} |{valign} |{halign} +|==== + +.AsciiDoc source +--------------------------------------------------------------------- +:frame: all +:grid: all +:halign: left +:valign: top + +[options="header"] +|==== +||frame | grid |valign |halign +v|  +  +  +|{frame} | {grid} |{valign} |{halign} +|==== +--------------------------------------------------------------------- + + +:frame: sides +:grid: rows +:halign: center +:valign: middle + +.Table test +[width="50%",options="header"] +|==== +||frame | grid |valign |halign +v|  +  +  +|{frame} | {grid} |{valign} |{halign} +|==== + +.AsciiDoc source +--------------------------------------------------------------------- +:frame: sides +:grid: rows +:halign: center +:valign: middle + +.Table test +[width="50%",options="header"] +|==== +||frame | grid |valign |halign +v|  +  +  +|{frame} | {grid} |{valign} |{halign} +|==== +--------------------------------------------------------------------- + + +:frame: topbot +:grid: cols +:halign: right +:valign: bottom + +[align="right",width="50%",options="header"] +|==== +||frame | grid |valign |halign +v|  +  +  +|{frame} | {grid} |{valign} |{halign} +|==== + +.AsciiDoc source +--------------------------------------------------------------------- +:frame: topbot +:grid: cols +:halign: right +:valign: bottom + +[align="right",width="50%",options="header"] +|==== +||frame | grid |valign |halign +v|  +  +  +|{frame} | {grid} |{valign} |{halign} +|==== +--------------------------------------------------------------------- + + +:frame: none +:grid: none +:halign: left +:valign: top + +[align="center",width="50%",options="header"] +|==== +||frame | grid |valign |halign +v|  +  +  +|{frame} | {grid} |{valign} |{halign} +|==== + +.AsciiDoc source +--------------------------------------------------------------------- +:frame: none +:grid: none +:halign: left +:valign: top + +[align="center",width="50%",options="header"] +|==== +||frame | grid |valign |halign +v|  +  +  +|{frame} | {grid} |{valign} |{halign} +|==== +--------------------------------------------------------------------- + +:frame!: +:grid!: +:halign!: +:valign!: + diff --git a/tests/inputs/oldtables.txt b/tests/inputs/oldtables.txt new file mode 100644 index 0000000..f6e0706 --- /dev/null +++ b/tests/inputs/oldtables.txt @@ -0,0 +1,64 @@ +AsciiDoc Old Tables +=================== + +Examples of the AsciiDoc 'old tables' syntax. This syntax was used in +AsciiDoc versions up to 8.2.7 and has since been deprecated in favor +of the 'new tables' syntax. + +Simple table: + +`---`--- +1 2 +3 4 +5 6 +-------- + +Table with title, header and footer: + +.An example table +[grid="all"] +`-----------.-------------- +Column 1 Column 2 +--------------------------- +1 Item 1 +2 Item 2 +3 Item 3 +--------------------------- +6 Three items +--------------------------- + +Four columns totaling 15% of the 'pagewidth', CSV data: + +[frame="all"] +````~15 +1,2,3,4 +a,b,c,d +A,B,C,D +~~~~~~~~ + +A table with a numeric ruler and externally sourced CSV data: + +[frame="all", grid="all"] +`15`20`25`20`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +ID,Customer Name,Contact Name,Customer Address,Phone +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +"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" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + diff --git a/tests/inputs/open-block-test.txt b/tests/inputs/open-block-test.txt new file mode 100644 index 0000000..4826c3a --- /dev/null +++ b/tests/inputs/open-block-test.txt @@ -0,0 +1,117 @@ += Additional Open Block and Paragraph styles + + +[comment] +Lorum ipsum... + +[comment] +-- +Lorum ipsum... +-- + +[example] +Lorum ipsum... + +[example] +-- +Lorum ipsum... + +Lorum ipsum... +-- + +[sidebar] +Lorum ipsum... + +[sidebar] +.A title +-- +Lorum ipsum... + +Lorum ipsum... +-- + +[NOTE] +-- +Lorum ipsum... + +Lorum ipsum... +-- + +[CAUTION] +-- +Lorum ipsum... + +Lorum ipsum... +-- + +[IMPORTANT] +-- +Lorum ipsum... + +Lorum ipsum... +-- + +[WARNING] +-- +Lorum ipsum... + +Lorum ipsum... +-- + +[TIP] +-- +Lorum ipsum... + +Lorum ipsum... +-- + +[quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes] +-- +As he spoke there was the sharp sound of horses' hoofs and +grating wheels against the curb, followed by a sharp pull at the +bell. Holmes whistled. + +"A pair, by the sound," said he. "Yes," he continued, glancing +out of the window. "A nice little brougham and a pair of +beauties. A hundred and fifty guineas apiece. There's money in +this case, Watson, if there is nothing else." +-- + +[verse, William Blake, from Auguries of Innocence] +-- +To see a world in a grain of sand, +And a heaven in a wild flower, +Hold infinity in the palm of your hand, +And eternity in an hour. +-- + +[source,python] +-- +y = 15 + +if y == 24: + x = 42 +-- + +[latex] +-- +$y = \int_0^\infty \gamma^2 \cos(x) dx$ +-- + +[graphviz] +-- +digraph G { rankdir=LR; Graphviz->AsciiDoc->HTML} +-- + +[music] +-- +\version "2.10.0" +\paper { + ragged-right = ##t +} +{ + \time 3/4 + \clef bass + c2 e4 g2. f4 e d c2 r4 +} +-- diff --git a/tests/inputs/rcs-id-marker-test.txt b/tests/inputs/rcs-id-marker-test.txt new file mode 100644 index 0000000..55b0892 --- /dev/null +++ b/tests/inputs/rcs-id-marker-test.txt @@ -0,0 +1,6 @@ +RCS $Id$ Marker Test +==================== +$Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $ + + +Lorum ipsum... diff --git a/tests/inputs/slidy-example.txt b/tests/inputs/slidy-example.txt new file mode 100644 index 0000000..f5d0363 --- /dev/null +++ b/tests/inputs/slidy-example.txt @@ -0,0 +1,174 @@ +Slidy Example Slideshow +======================= +:author: Joe Bloggs +:copyright: Foobar Inc. +:backend: slidy +:max-width: 45em +:data-uri: +:icons: + + +This preamble will appear on a separate slide. + + +AsciiDoc Elements +----------------- +Sagittis in vestibulum. Habitasse ante nulla enim bibendum nulla. Odio +sed pede litora. + +[float] +=== Titles inside delimited blocks must be floated +Porta nisl metus. Justo porttitor vel. Cras consequat tincidunt id sed +conubia. Feugiat felis justo. Nunc amet nulla. Eu ac orci mollis. + +.Tiger +image::images/tiger.png[] + + +Incremental Elements +-------------------- +The remaining elements on this page are incremental, press the space +bar to reveal them. + +[role="incremental"] +- Rhoncus pede justo. +- Velit pede dolor. +- Iaculis commodo et. +- Volutpat tristique nec. + +[role="incremental"] +-- +Sagittis in vestibulum. Habitasse ante nulla enim bibendum nulla. Odio +sed pede litora. +-- + +[role="incremental"] +. Rhoncus pede justo. +. Velit pede dolor. +. Iaculis commodo et. +. Volutpat tristique nec. + + +Outline Elements +---------------- +The following list is a Slidy 'outline' list -- nested bulleted or +numbered lists are expanded when the enclosing list item (the ones +with blue bullet points or numbers) are clicked. + +[role="outline"] +- Rhoncus pede justo. + * Rhoncus pede justo. + * Velit pede dolor. + +- Velit pede dolor. + * Iaculis commodo et. ++ +NOTE: 'Note' admonition paragraph. + + * Volutpat tristique nec. ++ +image::images/tiger.png[] + * Iaculis commodo et. + * Volutpat tristique nec. + +- Iaculis commodo et. +[role="outline"] + . Rhoncus pede justo. + ** Velit pede dolor. + ** Iaculis commodo et. + . Volutpat tristique nec. + +- Volutpat tristique nec. + + +AsciiDoc Elements +----------------- +NOTE: 'Note' admonition paragraph. + +IMPORTANT: 'Important' admonition paragraph. + +.Sidebar +********************************************************************* +Faucibus sagittis commodo sed et eu. Quam nullam ornare. Sed vel est. +Mauris urna lobortis interdum placerat per id magnis enim. +********************************************************************* + + +AsciiDoc Elements +----------------- +A quote block: + +[quote, Bertrand Russell, The World of Mathematics (1956)] +____________________________________________________________________ +A good notation has subtlety and suggestiveness which at times makes +it almost seem like a live teacher. +____________________________________________________________________ + +A verse block: + +[verse, William Blake, from Auguries of Innocence] +__________________________________________________ +To see a world in a grain of sand, +And a heaven in a wild flower, +Hold infinity in the palm of your hand, +And eternity in an hour. +__________________________________________________ + + +AsciiDoc Elements +----------------- +.Horizontal and vertical source data +[width="80%",cols="3,^2,^2,10",options="header"] +|========================================================= +|Date |Duration |Avg HR |Notes + +|22-Aug-08 |10:24 | 157 | +Worked out MSHR (max sustainable heart rate) by going hard +for this interval. + +|22-Aug-08 |23:03 | 152 | +Back-to-back with previous interval. + +|24-Aug-08 |40:00 | 145 | +Moderately hard interspersed with 3x 3min intervals (2min +hard + 1min really hard taking the HR up to 160). + +|========================================================= + + +Filters +------- +[source,python] +.Python source +--------------------------------------------------------------------- +''' A multi-line + comment.''' +def sub_word(mo): + ''' Single line comment.''' + word = mo.group('word') # Inline comment + if word in keywords[language]: + return quote + word + quote + else: + return word +--------------------------------------------------------------------- + +//// +The music generation block is ignored for testing as it generates a PNG +that is unique to the combination of lilypond and libpng used, which is +easily different from environment to environment + +[music] +.Music +--------------------------------------------------------------------- +\version "2.10.0" +\paper { + ragged-right = ##t +} +{ + \time 3/4 + \clef bass + c2 e4 g2. f4 e d c2 r4 +} +--------------------------------------------------------------------- + +//// diff --git a/tests/inputs/source-highlight-filter.txt b/tests/inputs/source-highlight-filter.txt new file mode 100644 index 0000000..41af974 --- /dev/null +++ b/tests/inputs/source-highlight-filter.txt @@ -0,0 +1,275 @@ +Source Code Highlight Filter +============================ + +The AsciiDoc distribution includes a 'source' filter for highlighting +code syntax. + + +DocBook Outputs +--------------- +AsciiDoc encloses the source code in a DocBook 'programlisting' +element and leaves source code highlighting to the DocBook toolchain +(dblatex has a particularly nice programlisting highlighter). The +DocBook programlisting element is assigned two attributes: + +. The 'language' attribute is set to the AsciiDoc 'language' + attribute. +. The 'linenumbering' attribute is set to the AsciiDoc 'src_numbered' + attribute ('numbered' or 'unnumbered'). + + +HTML Outputs +------------ +You have the choice of three HTML source code highlighters, your +selection is determined by the 'source-highlighter' attribute (defaults +to 'source-highlight'): + +NOTE: Set the 'source-highlighter' attribute from the asciidoc(1) +command-line or in the document header (not in the document body, +because the configuration file conditional macros are processed at +load time). + +=== GNU Source Highlight +The default highlighter is the +https://www.gnu.org/software/src-highlite/[GNU source-highlight] which +can highlight 'html4', 'html5' and 'xhtml11' outputs. The GNU +source-highlight must be installed and the 'source-highlight' command +must reside in the shell search 'PATH'. + +=== Highlight +You can use +http://www.andre-simon.de/doku/highlight/en/highlight.html[Highlight] +syntax highlighter for 'xhtml11', 'html5' and 'html4' outputs (set the +'source-highlighter' attribute to 'highlighter'). + +- The 'highlight' command must reside in the shell search 'PATH'. +- To make Highlighter your default highlighter put the following line + your `~/.asciidoc/asciidoc.conf` file: + + source-highlighter=highlight + +- The AsciiDoc 'encoding' attribute is passed to Highlighter using the + `--encoding` command-line option. + +=== Pygments +The https://pygments.org/[Pygments] syntax highlighter can be used for +'xhtml11' and 'html5' outputs (set the 'source-highlighter' attribute +to 'pygments'). + +- The 'pygmentize' command must reside in the shell search 'PATH'. +- You can customize Pygments CSS styles by editing + `./stylesheets/pygments.css`. The `pygments.css` CSS file was + generated with: + + from pygments.formatters import HtmlFormatter + print HtmlFormatter().get_style_defs('.highlight') + +- To make Pygments your default highlighter put the following line + your `~/.asciidoc/asciidoc.conf` file: + + source-highlighter=pygments + +- The AsciiDoc 'encoding' attribute is passed to Pygments using the + `-O` command-line option. + + +Block attributes +---------------- +The following attributes can be included in source code block +attribute lists. + +- 'style' and 'language' are mandatory. +- 'style', 'language' and 'src_numbered' are the first three + positional attributes in that order. +- The 'args' attribute allows the inclusion of arbitrary (highlighter + dependent) command options. + +// + +style:: + Set to 'source'. +language:: + The source code language name. ++ +NOTE: The language names vary between highlighters -- consult the +selected highlighter manual. + +src_numbered:: + Set to 'numbered' to include line numbers. +src_tab:: + Set tab size (GNU source-highlight only). +args:: + Include this attribute value in the highlighter command-line (HTML + outputs) or in the `programlisting` element (DocBook). + + +Testing +------- +Test the filter by converting the test file to HTML with AsciiDoc: + + $ asciidoc -v ./filters/source/source-highlight-filter-test.txt + $ firefox ./filters/source/source-highlight-filter-test.html & + + +Examples +-------- + +Source code paragraphs +~~~~~~~~~~~~~~~~~~~~~~ +The `source` paragraph style will highlight a paragraph of source +code. These three code paragraphs: + +--------------------------------------------------------------------- +[source,python] +if n < 0: print 'Hello World!' + +:language: python + +[source] +if n < 0: print 'Hello World!' + +[source,ruby,numbered] +[true, false].cycle([0, 1, 2, 3, 4]) do |a, b| + puts "#{a.inspect} => #{b.inspect}" +--------------------------------------------------------------------- + +Render this highlighted source code: + +[source,python] +if n < 0: print 'Hello World!' + +:language: python + +[source] +if n < 0: print 'Hello World!' + +[source,ruby,numbered] +[true, false].cycle([0, 1, 2, 3, 4]) do |a, b| + puts "#{a.inspect} => #{b.inspect}" + + +Unnumbered source code listing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This source-highlight filtered block: + +--------------------------------------------------------------------- + [source,python] + --------------------------------------------------------------------- + ''' A multi-line + comment.''' + def sub_word(mo): + ''' Single line comment.''' + word = mo.group('word') # Inline comment + if word in keywords[language]: + return quote + word + quote + else: + return word + --------------------------------------------------------------------- +--------------------------------------------------------------------- + +Renders this highlighted source code: + +[source,python] +--------------------------------------------------------------------- +''' A multi-line + comment.''' +def sub_word(mo): + ''' Single line comment.''' + word = mo.group('word') # Inline comment + if word in keywords[language]: + return quote + word + quote + else: + return word +--------------------------------------------------------------------- + +Numbered source code listing with callouts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This source-highlight filtered block: + +--------------------------------------------------------------------- + [source,ruby,numbered] + --------------------------------------------------------------------- + # + # Useful Ruby base class extensions. + # + + class Array + + # Execute a block passing it corresponding items in + # +self+ and +other_array+. + # If self has less items than other_array it is repeated. + + def cycle(other_array) # :yields: item, other_item + other_array.each_with_index do |item, index| + yield(self[index % self.length], item) + end + end + + end + + if $0 == __FILE__ # \<1> + # Array#cycle test + # true => 0 + # false => 1 + # true => 2 + # false => 3 + # true => 4 + puts 'Array#cycle test' # \<2> + [true, false].cycle([0, 1, 2, 3, 4]) do |a, b| + puts "#{a.inspect} => #{b.inspect}" + end + end + --------------------------------------------------------------------- + + \<1> First callout. + \<2> Second callout. + +--------------------------------------------------------------------- + +Renders this highlighted source code: + +[source,ruby,numbered] +--------------------------------------------------------------------- +# +# Useful Ruby base class extensions. +# + +class Array + + # Execute a block passing it corresponding items in + # +self+ and +other_array+. + # If self has less items than other_array it is repeated. + + def cycle(other_array) # :yields: item, other_item + other_array.each_with_index do |item, index| + yield(self[index % self.length], item) + end + end + +end + +if $0 == __FILE__ # <1> + # Array#cycle test + # true => 0 + # false => 1 + # true => 2 + # false => 3 + # true => 4 + puts 'Array#cycle test' # <2> + [true, false].cycle([0, 1, 2, 3, 4]) do |a, b| + puts "#{a.inspect} => #{b.inspect}" + end +end +--------------------------------------------------------------------- + +<1> First callout. +<2> Second callout. + +[TIP] +===== +- If the source 'language' attribute has been set (using an + 'AttributeEntry' or from the command-line) you don't have to specify + it in each source code block. +- You should place callout markers inside source code comments to + ensure they are not misinterpreted and mangled by the highlighter. +===== diff --git a/tests/inputs/testcases.conf b/tests/inputs/testcases.conf new file mode 100644 index 0000000..78517c8 --- /dev/null +++ b/tests/inputs/testcases.conf @@ -0,0 +1,12 @@ +[replacements] +test-replacement=TEST_REPLACEMENT + +[test-template] +This template is overridden and should not be displayed. + +[test-template] +Template line 1. + +[+test-template] +Template line 2. + diff --git a/tests/inputs/testcases.txt b/tests/inputs/testcases.txt new file mode 100644 index 0000000..d7dda45 --- /dev/null +++ b/tests/inputs/testcases.txt @@ -0,0 +1,817 @@ +// +// A collection of AsciiDoc test cases. +// + +Test 'Cases' +============ +:author: Joe Bloggs +// Web page meta data. +:title: Test Cases +:keywords: AsciiDoc, DocBook, EPUB, slideshow +:description: AsciiDoc is a text document format for writing short documents, + + articles, books, slideshows and UNIX man pages. +:replacements.(\w)'(\w): \1’\2 +:test-attribute: TEST_ATTRIBUTE + + +== Passthrough attributes == +ifdef::basebackend-docbook[] +:passtest: pass:[*lorum ipsum*] +endif::basebackend-docbook[] +ifdef::basebackend-html[] +:passtest: pass:[*lorum ipsum*] +endif::basebackend-html[] +{passtest} + +ifdef::basebackend-docbook[] +:passtest: pass:specialcharacters,quotes[*lorum ipsum*] +endif::basebackend-docbook[] +ifdef::basebackend-html[] +:passtest: pass:specialcharacters,quotes[*lorum ipsum*] +endif::basebackend-html[] +{passtest} + + +== Author attributes == +\{eval:expression}, \{sys:command} and \{sys2:command}, \{counter:c1} + +Hello *{author}* ({firstname} {lastname}, {authorinitials}). + +{firstname,lastname,surname#}first name or last name or surname. + +{firstname+lastname+surname#}first name and last name and surname. + +{firstname+lastname#}first name and last name. + + +== System attributes == +{counter:c1} {counter:c2:99} {counter:c3:A} + +{c1} = 1, {c2} = 99, {c3} = A + +{counter:c1} {counter:c2:99} {counter:c3:A} +{c1} {c2} {c3} + +{c1} = 2, {c2} = 100, {c3} = B + +{set:y:Foobar} +y: {y} + +{set:y!} + +y: {y} + +:x: 3 +:y: {eval:{x}+4} + +{x}, {y} + +{set:y:{x}} + +{x}, {y} + + +== Quoted text attributes == + +A=_X_, (_X_), _X_, [_X_] _X_ + +A=*_X_*, (`_X_`), _`X`_, [*_X_*] +_X_+ _X_ + +// These two illustrate that nesting doesn't always work. +[_*X*_] _+X+_ + +[[_intro]] +<<_intro>> <<_intro,intro>> xref:_intro[] _intro_ + +// Quote attributes. +[foo]#fun with text#. +[foo bar]*fun with text*. +[foo]+fun with text+. +[foo]_fun with text_. +[foo]'fun with text'. +[foo]``fun with text''. +[foo]`fun with text'. + +[foo]$$fun with text$$. + +[foo]+++fun with text+++. + +[red]#Obvious# and [big red yellow-background]*very obvious*. + +[underline]#Underline text#, [overline]#overline text# +and [line-through]#line-through text#. + +[firstletter]##T##esting 123 ... + +(``+1\n+'') if (usually ``+-1\n+'') + +(``++1\n++'') if (usually ``++-1\n++'') + +(`{author}') and `{author}' + + +== Configuration attribute entries == + +:listdef-labeled.style: horizontal +term:: definition + +:listdef-labeled.style: vertical +term:: definition + +ifdef::backend-xhtml11[] +<> + +:xref2-inlinemacro.: {2?{2}} + +<> + +:xref2-inlinemacro.: {2=[{1}]} +endif::[] + + +== role attribute == + +[role="test"] +Paragraph with a role attribute. + +[role="test"] +- first +- second +- third + + +== Break list nesting == +1. List 1. +2. List 1. + +// New list. +a. List 2. +b. List 2. + + +== Listing Blocks == +[subs="quotes"] +------------------------------------------ +$ ls *-al* +------------------------------------------ + +[listing] +.......................................... +[subs="quotes"] +------------------------------------------ +$ ls *-al* +------------------------------------------ +.......................................... + +.Listing +------------------------------------------ +$ ls -al +------------------------------------------ + +.Listing example +========================================== +------------------------------------------ +$ ls -al +------------------------------------------ +========================================== + +.Python paragraph +[source,python] +if n < 0: print 'Hello World!' + +.Titled Python listing +[source,python] +------------------------------------------ +if n < 0: print 'Hello World!' +------------------------------------------ + +.Python listing example +========================================== +[source,python] +------------------------------------------ +if n < 0: print 'Hello World!' +------------------------------------------ +========================================== + + +[[X1,anchor reftext]] +== Links == +An [[X2]] inline anchor. +An [[X3, anchor reftext]] inline anchor with reftext. + +<>; captioned link to <>. + +<> link to inline anchor; captioned link to <>. + +Link to <> anchor. + +An example link to a bibliography entry <>. + +[horizontal] +[[[Test::Unit]]]:: http://ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit.html + + +== Titles == + +[float] +===== Level 4 ===== +[float] +==== Level 3 ==== +[float] +=== Level 2 === +[float] +== Level 1 == +[float] +Level 4 ++++++++ +[float] +Level 3 +^^^^^^^ +[float] +Level 2 +~~~~~~~ +[float] +Level 1 +------- + +.Block title +Lorum ipsum. + + +== Lists == + +Bulleted: + +- item text +* item text +** item text +*** item text +**** item text +***** item text + +Numbered: + +1. arabic (decimal) numbering +a. loweralpha numbering +A. upperalpha numbering +i) lowerroman numbering +I) upperroman numbering +. arabic (decimal) numbering +.. loweralpha numbering +... lowerroman numbering +.... upperalpha numbering +..... upperroman numbering + +Labeled: + +label:: item text +label;; item text +label::: item text +label:::: item text + +With item anchor: + +one:: Item one. +[[item_two]]two:: Item two. +three:: Item three. + + +== Inline passthroughs == + +- Test pass:[`ABC`]. +- Test `pass:[ABC]`. +- The `++i` and `++j` auto-increments. +- Paths `~/.vim` and `~/docs`. +- The `__init__` method. +- The `{id}` attribute. + +List start number test: + +// The ol start attribute is not valid XHTML 1.1 (but it works in all +// browsers). +ifndef::backend-xhtml11[] +[start=7] +. List item 7. +. List item 8. +endif::backend-xhtml11[] + +== Images + +=== Block images + +[[tiger_image]] +.Tyger tyger +image::../../images/tiger.png[Tyger tyger] + +:height: 250 +:width: 350 +.Tyger tyger two +image::../../images/tiger.png[caption="Figure 2: ", alt="Tiger", align="center"] +:height!: +:width!: + +// Images and icons directories. +:imagesdir: ../../doc +image::music2.png[] + +:icons: +:iconsdir: ../../images/icons +NOTE: Lorum ipsum. + +:icons!: + +ifdef::backend-xhtml11[] +:imagesdir: ../../images +:data-uri: +image:smallnew.png[NEW] 'testing' `123`. + +endif::[] + +:data-uri!: + +=== Inline images + +:imagesdir: ../../images + +Inline image image:smallnew.png[] + +Inline image image:smallnew.png[NEW!] + +Inline image image:smallnew.png["NEW!",title="Small new"] + + +== Admonishments + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +// With icon images. +:icons: +:iconsdir: ../../images/icons + +NOTE: Lorum ipsum. + +TIP: Lorum ipsum. + +WARNING: Lorum ipsum. + +CAUTION: Lorum ipsum. + +IMPORTANT: Lorum ipsum. + +:icons!: + +== Backslash escapes + +.Apostrophe +Don't vs don\'t. + +.Exceptions +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%",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\... +|======================================== + + +== Paragraphs + +.Normal paragraph +This is a *bold* a line +This is a 'strong' line +This is another _strong_ line + +.Literal paragraph +[literal] +This is a *bold* a line +This is a 'strong' line +This is another _strong_ line + +.Verse paragraph +[verse] +This is a *bold* a line +This is a 'strong' line +This is another _strong_ line + +.Indented (literal) paragraph + This is a *bold* a line + This is a 'strong' line + This is another _strong_ line + +.Indented with quotes substitution +[subs="quotes"] + This is a *bold* a line + This is a 'strong' line + This is another _strong_ line + +.Literal paragraph with quotes substitution +["literal",subs="quotes"] +This is a *bold* a line +This is a 'strong' line +This is another _strong_ line + +ifndef::basebackend-docbook[] +.Monospaced paragraph with line breaks ++This is a *bold* line+ + ++This is a 'strong' line+ + ++This is another _strong_ line+ + + +.Another monospaced paragraph with line breaks ++This is a *bold* a line + +This is a 'strong' line + +This is another _strong_ line+ + +endif::basebackend-docbook[] + +.Literal block with quotes substitution +[subs="quotes"] +............................. +This is a *bold* a line +This is a 'strong' line +This is another _strong_ line +............................. + +[verse, William Blake, from Auguries of Innocence] +To see a world in a grain of sand, +And a heaven in a wild flower, +Hold infinity in the palm of your hand, +And eternity in an hour. + +[quote, Bertrand Russell, The World of Mathematics (1956)] +A good notation has subtlety and suggestiveness which at times makes +it almost seem like a live teacher. + + +URLs +---- +Mail Addresses +~~~~~~~~~~~~~~ +joe_bloggs@mail_server.com_ + +joe-bloggs@mail-server.com. + +joe-bloggs@mail-server.com,joe-bloggs@mail-server.com, + +mailto:joe-bloggs@mail-server.com[Mail] + +mailto:joe_bloggs@mail_server.com[Mail] + +mailto:joe.bloggs@mail.server.com[Mail] + +joe.bloggs@mail.server.com + +lorum ipsum. + + +Comments +-------- +///////////////////////////////////////////////////////////////////// +A comment +block. +///////////////////////////////////////////////////////////////////// + +// This is a comment line. + +Qui in magna commodo, est labitur dolorum an. Est ne magna primis. +// Inline comment line. +adolescens. Sit munere ponderum dignissim et. Minim luptatum et. + +:showcomments: +// This comment line will be displayed in the output. + +Qui in magna commodo, est labitur dolorum an. Est ne magna primis. +// Visible inline comment line. +adolescens. Sit munere ponderum dignissim et. Minim luptatum et. + +///////////////////////////////////////////////////////////////////// +Comment blocks are never displayed in the output. +///////////////////////////////////////////////////////////////////// + +:showcomments!: + +[[comment_macro]] +.Block title +// Block macro comment does not consume titles or attributes. +Lorum ipsum. + +[[comment_block]] +.Block title +///////////////////////////////////////////////////////////////////// +Delimited comment block does not consume titles or attributes. +///////////////////////////////////////////////////////////////////// +Lorum ipsum. + + +ifdef::basebackend-docbook[] +[glossary] +List of terms +------------- +Using positional attribute to specify section template. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + +[template="glossary"] +List of terms +------------- +Using named 'template' attribute to specify section template. + +[glossary] +A glossary term:: + The corresponding (indented) definition. + +A second glossary term:: + The corresponding (indented) definition. + +endif::basebackend-docbook[] + +Index Terms +----------- +Test 1 ((test1)). + +Test 2 (((test2))). + +Test 3 (((test3,secondary))). + +Test 4 (((test4,secondary,tertiary))). + +Test 5 indexterm2:[test5]. + +Test 6 indexterm:[test6]. + +Test 7 indexterm:[test7,secondary]. + +Test 8 indexterm:[test8,secondary,tertiary]. + +Multi-passthough substitution (see +http://groups.google.com/group/asciidoc/browse_frm/thread/1269dc2feb1a482c) +((`foo`)) +(((foo,`bar`))) +(((foo,`bar`,`two`))) + +Table with fractional column width units +---------------------------------------- +NOTE: 'pagewidth' and 'pageunits' only apply to DocBook outputs. + +:miscellaneous.pagewidth: 17.5 +:miscellaneous.pageunits: cm + +.Horizontal and vertical source data +[width="50%",cols="3,^2,^2,10",options="header"] +|========================================================= +|Date |Duration |Avg HR |Notes + +|22-Aug-08 |10:24 | 157 | +Worked out MSHR (max sustainable heart rate) by going hard +for this interval. + +|22-Aug-08 |23:03 | 152 | +Back-to-back with previous interval. + +|24-Aug-08 |40:00 | 145 | +Moderately hard interspersed with 3x 3min intervals (2min +hard + 1min really hard taking the HR up to 160). + +|========================================================= + +== Table with parent configuration file and header attribute entry + +[cols="asciidoc"] +|==== +| +- Attribute entry from header: {test-attribute} +- Replacement from `testcases.conf` configuration file: test-replacement +|==== + +== Table column specifiers with merged cells +See +http://groups.google.com/group/asciidoc/browse_thread/thread/c9238380a1f2507a + +[cols="<1m,>1,^1s, ^1e"] +|============================================ + .2+| .2+|1- A 2+|2- B + |i- a |ii- b + |Values 1 |v1 |v2 |v3 + |Values 2 |v4 |v5 |v6 +|============================================ + +Floating tables and images +-------------------------- +.Simple table +[float="left",width="15%",floatstyle="[htbp]"] +|======= +|1 |2 |A +|3 |4 |B +|5 |6 |C +|======= + +.Tiger +[float="right",floatstyle="[htbp]"] +image::images/tiger.png["Tiger image"] + +unfloat::[] + +Section level offsets +--------------------- +At level 1 + +:leveloffset: -1 +Section title +^^^^^^^^^^^^^ +At level 2 + +:leveloffset: 0 +Section title +~~~~~~~~~~~~~ +At level 2 + +:leveloffset: 2 +Section title +------------- +At level 3 + +:leveloffset!: +:numbered!: + +Section level offsets +--------------------- +At level 1 + +Single-quoted attributes +------------------------ +[quote,'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]'] +_____________________________________________________________________ +Sir, a woman's preaching is like a dog's walking on his hind legs. It +is not done well; but you are surprised to find it done at all. +_____________________________________________________________________ + +["quote","'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]'"] +_____________________________________________________________________ +Sir, a woman's preaching is like a dog's walking on his hind legs. It +is not done well; but you are surprised to find it done at all. +_____________________________________________________________________ + +Footnotes +--------- +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. +footnote:[footnote one. +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel.] +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. +footnoteref:["F2","footnote two. +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel."] +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel +footnoteref:[F2]. +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. +footnote:[https://asciidoc.org/ Qui in magna commodo, +est labitur dolorum an. Est ne magna primis adolescens. Sit munere +ponderum dignissim et. Minim luptatum et vel +image:images/smallnew.png[]] +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. Sit munere ponderum dignissim et. Minim luptatum et vel. +footnote:[https://asciidoc.org/] +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. Sit munere ponderum dignissim et. Minim luptatum et +vel footnote:[https://asciidoc.org/[AsciiDoc website].]. +Qui in magna commodo, est labitur dolorum an. Est ne magna primis +adolescens. Sit munere ponderum dignissim et. Minim luptatum et +footnoteref:[F3,A footnote, "with an image" +image:images/smallnew.png[]]. +footnote:[With [square brackets\]] Qui in magna commodo, est labitur +dolorum an. Est ne magna primis. + + +Rulers and page breaks +---------------------- + +Lorum ipsum... + +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Lorum ipsum... + +<<< + +Lorum ipsum... + + +这是一个测试 +------------ +Double-with character titles. +<<_这是一个测试,link to auto-generated section ID>>. + + +ifdef::backend-html5[] +HTML 5 audio and video block macros +----------------------------------- +audio::images/example.ogg[] + +.Audio tag test +audio::images/example.ogg[] + +video::images/gizmo.ogv[width=200,options="nocontrols,autoplay"] + +.Example video +video::images/gizmo.ogv[] + +video::http://www.808.dk/pics/video/gizmo.ogv[] + +++++ + + + +++++ + +endif::backend-html5[] + + +== Block macros + +:rs458: 2 + +ifeval::[{rs458}==2] +RS458 is 2. +endif::[] +ifeval::[not ({rs458}==2)] +This will not be processed. +endif::[] + +// Test eval block macro. +eval::[Section.setlevel(1)] + +// Test template concatenation. +{template:test-template} + +// Test ascii-ids attribute. +:ascii-ids: +== àn îd without accénts +Lorum ipsum... + +:ascii-ids!: +== àn îd with accénts +Lorum ipsum... + + +== Inline macros +http://groups.google.com/group/asciidoc/[A URL with [square +brackets\]]. + +== Equation +.Equation +[latexmath] +[floatstyle="[htbp]"] +++++++++++++++++++++++++++++++++++++++++++++ +\[C = \alpha + \beta Y^{\gamma} + \epsilon\] +++++++++++++++++++++++++++++++++++++++++++++ + +== Example +.Example +[floatstyle="[htbp]"] +++++++++++++++++++++++++++++++++++++++++++++ +Formal figures, tables, equations and examples can float in docbook backend +++++++++++++++++++++++++++++++++++++++++++++ diff --git a/tests/inputs/utf8-bom-test.txt b/tests/inputs/utf8-bom-test.txt new file mode 100644 index 0000000..09da3a2 --- /dev/null +++ b/tests/inputs/utf8-bom-test.txt @@ -0,0 +1,9 @@ +UTF-8 BOM Test +============== + +Include file with UTF-8 BOM: + +:leveloffset: 1 +include::{docname}.txt[depth=1] + +Lorum ipsum... diff --git a/tests/inputs/utf8-examples.txt b/tests/inputs/utf8-examples.txt new file mode 100644 index 0000000..0358f24 --- /dev/null +++ b/tests/inputs/utf8-examples.txt @@ -0,0 +1,217 @@ +UTF-8 encoded sample plain-text file +==================================== + +Markus Kuhn [ˈmaʳkʊs kuːn] — 2002-07-25 + + +The ASCII compatible UTF-8 encoding used in this plain-text file +is defined in Unicode, ISO 10646-1, and RFC 2279. + + +Using Unicode/UTF-8, you can write in emails and source code things such as + +== Mathematics and sciences + + ∮ E⋅da = Q, n → ∞, ∑ f(i) = ∏ g(i), ⎧⎡⎛┌─────┐⎞⎤⎫ + ⎪⎢⎜│a²+b³ ⎟⎥⎪ + ∀x∈ℝ: ⌈x⌉ = −⌊−x⌋, α ∧ ¬β = ¬(¬α ∨ β), ⎪⎢⎜│───── ⎟⎥⎪ + ⎪⎢⎜⎷ c₈ ⎟⎥⎪ + ℕ ⊆ ℕ₀ ⊂ ℤ ⊂ ℚ ⊂ ℝ ⊂ ℂ, ⎨⎢⎜ ⎟⎥⎬ + ⎪⎢⎜ ∞ ⎟⎥⎪ + ⊥ < a ≠ b ≡ c ≤ d ≪ ⊤ ⇒ (⟦A⟧ ⇔ ⟪B⟫), ⎪⎢⎜ ⎲ ⎟⎥⎪ + ⎪⎢⎜ ⎳aⁱ-bⁱ⎟⎥⎪ + 2H₂ + O₂ ⇌ 2H₂O, R = 4.7 kΩ, ⌀ 200 mm ⎩⎣⎝i=1 ⎠⎦⎭ + + +== Linguistics and dictionaries + +ði ıntəˈnæʃənəl fəˈnɛtık əsoʊsiˈeıʃn + +Y [ˈʏpsilɔn], Yen [jɛn], Yoga [ˈjoːgɑ] + + +== APL + + ((V⍳V)=⍳⍴V)/V←,V ⌷←⍳→⍴∆∇⊃‾⍎⍕⌈ + + +== Nicer typography in plain text files + +- ‘single’ and “double” quotes +- Curly apostrophes: “We’ve been here” +- ‚deutsche‘ „Anführungszeichen“ +- †, ‡, ‰, •, 3–4, —, −5/+5, ™, … +- ASCII safety test: 1lI|, 0OD, 8B +- the euro symbol: 14.95 € + + +== Combining characters + +STARGΛ̊TE SG-1, a = v̇ = r̈, a⃑ ⊥ b⃑ + +== Greek (in Polytonic) + +[verse, The Greek anthem] +________________________________ +Σὲ γνωρίζω ἀπὸ τὴν κόψη +τοῦ σπαθιοῦ τὴν τρομερή, +σὲ γνωρίζω ἀπὸ τὴν ὄψη +ποὺ μὲ βία μετράει τὴ γῆ. + +᾿Απ᾿ τὰ κόκκαλα βγαλμένη +τῶν ῾Ελλήνων τὰ ἱερά +καὶ σὰν πρῶτα ἀνδρειωμένη +χαῖρε, ὦ χαῖρε, ᾿Ελευθεριά! +________________________________ + +[verse,From a speech of Demosthenes in the 4th century BC] +______________________________________________________________ +Οὐχὶ ταὐτὰ παρίσταταί μοι γιγνώσκειν, ὦ ἄνδρες ᾿Αθηναῖοι, +ὅταν τ᾿ εἰς τὰ πράγματα ἀποβλέψω καὶ ὅταν πρὸς τοὺς +λόγους οὓς ἀκούω· τοὺς μὲν γὰρ λόγους περὶ τοῦ +τιμωρήσασθαι Φίλιππον ὁρῶ γιγνομένους, τὰ δὲ πράγματ᾿ +εἰς τοῦτο προήκοντα, ὥσθ᾿ ὅπως μὴ πεισόμεθ᾿ αὐτοὶ +πρότερον κακῶς σκέψασθαι δέον. οὐδέν οὖν ἄλλο μοι δοκοῦσιν +οἱ τὰ τοιαῦτα λέγοντες ἢ τὴν ὑπόθεσιν, περὶ ἧς βουλεύεσθαι, +οὐχὶ τὴν οὖσαν παριστάντες ὑμῖν ἁμαρτάνειν. ἐγὼ δέ, ὅτι μέν +ποτ᾿ ἐξῆν τῇ πόλει καὶ τὰ αὑτῆς ἔχειν ἀσφαλῶς καὶ Φίλιππον +τιμωρήσασθαι, καὶ μάλ᾿ ἀκριβῶς οἶδα· ἐπ᾿ ἐμοῦ γάρ, οὐ πάλαι +γέγονεν ταῦτ᾿ ἀμφότερα· νῦν μέντοι πέπεισμαι τοῦθ᾿ ἱκανὸν +προλαβεῖν ἡμῖν εἶναι τὴν πρώτην, ὅπως τοὺς συμμάχους +σώσομεν. ἐὰν γὰρ τοῦτο βεβαίως ὑπάρξῃ, τότε καὶ περὶ τοῦ +τίνα τιμωρήσεταί τις καὶ ὃν τρόπον ἐξέσται σκοπεῖν· πρὶν δὲ +τὴν ἀρχὴν ὀρθῶς ὑποθέσθαι, μάταιον ἡγοῦμαι περὶ τῆς +τελευτῆς ὁντινοῦν ποιεῖσθαι λόγον. + +Δημοσθένους, Γ´ ᾿Ολυνθιακὸς +______________________________________________________________ + + +== Georgian: + +.From a Unicode conference invitation +გთხოვთ ახლავე გაიაროთ რეგისტრაცია Unicode-ის მეათე საერთაშორისო +კონფერენციაზე დასასწრებად, რომელიც გაიმართება 10-12 მარტს, +ქ. მაინცში, გერმანიაში. კონფერენცია შეჰკრებს ერთად მსოფლიოს +ექსპერტებს ისეთ დარგებში როგორიცაა ინტერნეტი და Unicode-ი, +ინტერნაციონალიზაცია და ლოკალიზაცია, Unicode-ის გამოყენება +ოპერაციულ სისტემებსა, და გამოყენებით პროგრამებში, შრიფტებში, +ტექსტების დამუშავებასა და მრავალენოვან კომპიუტერულ სისტემებში. + + +== Russian + +.From a Unicode conference invitation +Зарегистрируйтесь сейчас на Десятую Международную Конференцию по +Unicode, которая состоится 10-12 марта 1997 года в Майнце в Германии. +Конференция соберет широкий круг экспертов по вопросам глобального +Интернета и Unicode, локализации и интернационализации, воплощению и +применению Unicode в различных операционных системах и программных +приложениях, шрифтах, верстке и многоязычных компьютерных системах. + + +== Thai (UCS Level 2) + +Excerpt from a poetry on The Romance of The Three Kingdoms (a Chinese +classic 'San Gua'): + + [----------------------------|------------------------] + ๏ แผ่นดินฮั่นเสื่อมโทรมแสนสังเวช พระปกเกศกองบู๊กู้ขึ้นใหม่ + สิบสองกษัตริย์ก่อนหน้าแลถัดไป สององค์ไซร้โง่เขลาเบาปัญญา + ทรงนับถือขันทีเป็นที่พึ่ง บ้านเมืองจึงวิปริตเป็นนักหนา + โฮจิ๋นเรียกทัพทั่วหัวเมืองมา หมายจะฆ่ามดชั่วตัวสำคัญ + เหมือนขับไสไล่เสือจากเคหา รับหมาป่าเข้ามาเลยอาสัญ + ฝ่ายอ้องอุ้นยุแยกให้แตกกัน ใช้สาวนั้นเป็นชนวนชื่นชวนใจ + พลันลิฉุยกุยกีกลับก่อเหตุ ช่างอาเพศจริงหนาฟ้าร้องไห้ + ต้องรบราฆ่าฟันจนบรรลัย ฤๅหาใครค้ำชูกู้บรรลังก์ ฯ + +(The above is a two-column text. If combining characters are handled +correctly, the lines of the second column should be aligned with the +| character above.) + + +== Ethiopian + +.Proverbs in the Amharic language +[verse] +ሰማይ አይታረስ ንጉሥ አይከሰስ። +ብላ ካለኝ እንደአባቴ በቆመጠኝ። +ጌጥ ያለቤቱ ቁምጥና ነው። +ደሀ በሕልሙ ቅቤ ባይጠጣ ንጣት በገደለው። +የአፍ ወለምታ በቅቤ አይታሽም። +አይጥ በበላ ዳዋ ተመታ። +ሲተረጉሙ ይደረግሙ። +ቀስ በቀስ፥ ዕንቁላል በእግሩ ይሄዳል። +ድር ቢያብር አንበሳ ያስር። +ሰው እንደቤቱ እንጅ እንደ ጉረቤቱ አይተዳደርም። +እግዜር የከፈተውን ጉሮሮ ሳይዘጋው አይድርም። +የጎረቤት ሌባ፥ ቢያዩት ይስቅ ባያዩት ያጠልቅ። +ሥራ ከመፍታት ልጄን ላፋታት። +ዓባይ ማደሪያ የለው፥ ግንድ ይዞ ይዞራል። +የእስላም አገሩ መካ የአሞራ አገሩ ዋርካ። +ተንጋሎ ቢተፉ ተመልሶ ባፉ። +ወዳጅህ ማር ቢሆን ጨርስህ አትላሰው። +እግርህን በፍራሽህ ልክ ዘርጋ። + + +== Runes + +ᚻᛖ ᚳᚹᚫᚦ ᚦᚫᛏ ᚻᛖ ᛒᚢᛞᛖ ᚩᚾ ᚦᚫᛗ ᛚᚪᚾᛞᛖ ᚾᚩᚱᚦᚹᛖᚪᚱᛞᚢᛗ ᚹᛁᚦ ᚦᚪ ᚹᛖᛥᚫ + +(Old English, which transcribed into Latin reads ``He cwaeth that he +bude thaem lande northweardum with tha Westsae.'' and means ``He said +that he lived in the northern land near the Western Sea.'') + + +== Braille + + ⡌⠁⠧⠑ ⠼⠁⠒ ⡍⠜⠇⠑⠹⠰⠎ ⡣⠕⠌ + + ⡍⠜⠇⠑⠹ ⠺⠁⠎ ⠙⠑⠁⠙⠒ ⠞⠕ ⠃⠑⠛⠔ ⠺⠊⠹⠲ ⡹⠻⠑ ⠊⠎ ⠝⠕ ⠙⠳⠃⠞ + ⠱⠁⠞⠑⠧⠻ ⠁⠃⠳⠞ ⠹⠁⠞⠲ ⡹⠑ ⠗⠑⠛⠊⠌⠻ ⠕⠋ ⠙⠊⠎ ⠃⠥⠗⠊⠁⠇ ⠺⠁⠎ + ⠎⠊⠛⠝⠫ ⠃⠹ ⠹⠑ ⠊⠇⠻⠛⠹⠍⠁⠝⠂ ⠹⠑ ⠊⠇⠻⠅⠂ ⠹⠑ ⠥⠝⠙⠻⠞⠁⠅⠻⠂ + ⠁⠝⠙ ⠹⠑ ⠡⠊⠑⠋ ⠍⠳⠗⠝⠻⠲ ⡎⠊⠗⠕⠕⠛⠑ ⠎⠊⠛⠝⠫ ⠊⠞⠲ ⡁⠝⠙ + ⡎⠊⠗⠕⠕⠛⠑⠰⠎ ⠝⠁⠍⠑ ⠺⠁⠎ ⠛⠕⠕⠙ ⠥⠏⠕⠝ ⠰⡡⠁⠝⠛⠑⠂ ⠋⠕⠗ ⠁⠝⠹⠹⠔⠛ ⠙⠑ + ⠡⠕⠎⠑ ⠞⠕ ⠏⠥⠞ ⠙⠊⠎ ⠙⠁⠝⠙ ⠞⠕⠲ + + ⡕⠇⠙ ⡍⠜⠇⠑⠹ ⠺⠁⠎ ⠁⠎ ⠙⠑⠁⠙ ⠁⠎ ⠁ ⠙⠕⠕⠗⠤⠝⠁⠊⠇⠲ + + ⡍⠔⠙⠖ ⡊ ⠙⠕⠝⠰⠞ ⠍⠑⠁⠝ ⠞⠕ ⠎⠁⠹ ⠹⠁⠞ ⡊ ⠅⠝⠪⠂ ⠕⠋ ⠍⠹ + ⠪⠝ ⠅⠝⠪⠇⠫⠛⠑⠂ ⠱⠁⠞ ⠹⠻⠑ ⠊⠎ ⠏⠜⠞⠊⠊⠥⠇⠜⠇⠹ ⠙⠑⠁⠙ ⠁⠃⠳⠞ + ⠁ ⠙⠕⠕⠗⠤⠝⠁⠊⠇⠲ ⡊ ⠍⠊⠣⠞ ⠙⠁⠧⠑ ⠃⠑⠲ ⠔⠊⠇⠔⠫⠂ ⠍⠹⠎⠑⠇⠋⠂ ⠞⠕ + ⠗⠑⠛⠜⠙ ⠁ ⠊⠕⠋⠋⠔⠤⠝⠁⠊⠇ ⠁⠎ ⠹⠑ ⠙⠑⠁⠙⠑⠌ ⠏⠊⠑⠊⠑ ⠕⠋ ⠊⠗⠕⠝⠍⠕⠝⠛⠻⠹ + ⠔ ⠹⠑ ⠞⠗⠁⠙⠑⠲ ⡃⠥⠞ ⠹⠑ ⠺⠊⠎⠙⠕⠍ ⠕⠋ ⠳⠗ ⠁⠝⠊⠑⠌⠕⠗⠎ + ⠊⠎ ⠔ ⠹⠑ ⠎⠊⠍⠊⠇⠑⠆ ⠁⠝⠙ ⠍⠹ ⠥⠝⠙⠁⠇⠇⠪⠫ ⠙⠁⠝⠙⠎ + ⠩⠁⠇⠇ ⠝⠕⠞ ⠙⠊⠌⠥⠗⠃ ⠊⠞⠂ ⠕⠗ ⠹⠑ ⡊⠳⠝⠞⠗⠹⠰⠎ ⠙⠕⠝⠑ ⠋⠕⠗⠲ ⡹⠳ + ⠺⠊⠇⠇ ⠹⠻⠑⠋⠕⠗⠑ ⠏⠻⠍⠊⠞ ⠍⠑ ⠞⠕ ⠗⠑⠏⠑⠁⠞⠂ ⠑⠍⠏⠙⠁⠞⠊⠊⠁⠇⠇⠹⠂ ⠹⠁⠞ + ⡍⠜⠇⠑⠹ ⠺⠁⠎ ⠁⠎ ⠙⠑⠁⠙ ⠁⠎ ⠁ ⠙⠕⠕⠗⠤⠝⠁⠊⠇⠲ + +(The first couple of paragraphs of "A Christmas Carol" by Dickens) + + +== Compact font selection example text + + ABCDEFGHIJKLMNOPQRSTUVWXYZ /0123456789 + abcdefghijklmnopqrstuvwxyz £©µÀÆÖÞßéöÿ + –—‘“”„†•…‰™œŠŸž€ ΑΒΓΔΩαβγδω АБВГДабвгд + ∀∂∈ℝ∧∪≡∞ ↑↗↨↻⇣ ┐┼╔╘░►☺♀ fi�⑀₂ἠḂӥẄɐː⍎אԱა + + +== Greetings in various languages + +Hello world, Καλημέρα κόσμε, コンニチハ + + +== Box drawing alignment tests + +--------------------------------------------------------------------- + █ + ▉ + ╔══╦══╗ ┌──┬──┐ ╭──┬──╮ ╭──┬──╮ ┏━━┳━━┓ ┎┒┏┑ ╷ ╻ ┏┯┓ ┌┰┐ ▊ ╱╲╱╲╳╳╳ + ║┌─╨─┐║ │╔═╧═╗│ │╒═╪═╕│ │╓─╁─╖│ ┃┌─╂─┐┃ ┗╃╄┙ ╶┼╴╺╋╸┠┼┨ ┝╋┥ ▋ ╲╱╲╱╳╳╳ + ║│╲ ╱│║ │║ ║│ ││ │ ││ │║ ┃ ║│ ┃│ ╿ │┃ ┍╅╆┓ ╵ ╹ ┗┷┛ └┸┘ ▌ ╱╲╱╲╳╳╳ + ╠╡ ╳ ╞╣ ├╢ ╟┤ ├┼─┼─┼┤ ├╫─╂─╫┤ ┣┿╾┼╼┿┫ ┕┛┖┚ ┌┄┄┐ ╎ ┏┅┅┓ ┋ ▍ ╲╱╲╱╳╳╳ + ║│╱ ╲│║ │║ ║│ ││ │ ││ │║ ┃ ║│ ┃│ ╽ │┃ ░░▒▒▓▓██ ┊ ┆ ╎ ╏ ┇ ┋ ▎ + ║└─╥─┘║ │╚═╤═╝│ │╘═╪═╛│ │╙─╀─╜│ ┃└─╂─┘┃ ░░▒▒▓▓██ ┊ ┆ ╎ ╏ ┇ ┋ ▏ + ╚══╩══╝ └──┴──┘ ╰──┴──╯ ╰──┴──╯ ┗━━┻━━┛ ▗▄▖▛▀▜ └╌╌┘ ╎ ┗╍╍┛ ┋ ▁▂▃▄▅▆▇█ + ▝▀▘▙▄▟ +--------------------------------------------------------------------- diff --git a/tests/testasciidoc.conf b/tests/testasciidoc.conf index b07f04e..a2635d8 100644 --- a/tests/testasciidoc.conf +++ b/tests/testasciidoc.conf @@ -10,7 +10,7 @@ Test cases ['source-highlight'] % source -data/testcases.txt +inputs/testcases.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Filters @@ -19,10 +19,10 @@ Filters ['dot', 'lilypond'] % source -data/filters-test.txt +inputs/filters-test.txt % artifacts -['data/graphviz1.png', 'data/graphviz2.png', 'data/music1.md5', 'data/music1.png', 'data/music2.md5', 'data/music2.png'] +['inputs/graphviz1.png', 'inputs/graphviz2.png', 'inputs/music1.md5', 'inputs/music1.png', 'inputs/music2.md5', 'inputs/music2.png'] %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Tables @@ -31,13 +31,13 @@ Tables ['source-highlight'] % source -../website/newtables.txt +inputs/newtables.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Old tables % source -data/oldtables.txt +inputs/oldtables.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Source highlighter @@ -46,7 +46,7 @@ Source highlighter ['source-highlight'] % source -../doc/source-highlight-filter.txt +inputs/source-highlight-filter.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Example article @@ -59,13 +59,13 @@ Example article {'docdate':None} % source -../doc/article.txt +inputs/article.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Example article with embedded images (data URIs) % source -../doc/article.txt +inputs/article.txt % name article-data-uri @@ -77,13 +77,13 @@ article-data-uri ['--section-numbers'] % attributes -{'docdate':None, 'data-uri':True, 'icons':True, 'imagesdir': '../'} +{'docdate':None, 'data-uri':True, 'icons':True, 'imagesdir': '../../'} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Example article with included docinfo file. % source -../doc/article.txt +inputs/article.txt % name article-docinfo @@ -104,7 +104,7 @@ Example book ['--section-numbers'] % source -../doc/book.txt +inputs/book.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Example multi-part book @@ -113,7 +113,7 @@ Example multi-part book ['--section-numbers'] % source -../doc/book-multi.txt +inputs/book-multi.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Man page @@ -123,7 +123,7 @@ Man page {'docdate':None} % source -../doc/asciidoc.1.txt +inputs/asciidoc.1.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Example slideshow @@ -138,7 +138,7 @@ Example slideshow {'imagesdir': '../../', 'iconsdir': '../../images/icons'} % source -data/slidy-example.txt +inputs/slidy-example.txt % artifacts ['../slidy-example__1.md5','../slidy-example__1.png'] @@ -153,7 +153,7 @@ ASCIIMathML ['xhtml11','html5'] % source -../doc/asciimath.txt +inputs/asciimath.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LaTeXMathML @@ -165,7 +165,7 @@ LaTeXMathML ['xhtml11','html5'] % source -../doc/latexmathml.txt +inputs/latexmathml.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LaTeX Math @@ -174,7 +174,7 @@ LaTeX Math ['docbook','docbook5'] % source -../doc/latexmath.txt +inputs/latexmath.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LaTeX Filter @@ -183,10 +183,10 @@ LaTeX Filter ['latex', 'dvipng'] % source -../doc/latex-filter.txt +inputs/latex-filter.txt % artifacts -['../doc/latex-filter__1.md5','../doc/latex-filter__1.svg','../doc/latex-filter__2.md5','../doc/latex-filter__2.svg','../doc/latex1.md5','../doc/latex1.svg','../doc/latex2.md5','../doc/latex2.png','../doc/latex3.md5','../doc/latex3.svg'] +['inputs/latex-filter__1.md5','inputs/latex-filter__1.svg','inputs/latex-filter__2.md5','inputs/latex-filter__2.svg','inputs/latex1.md5','inputs/latex1.svg','inputs/latex2.md5','inputs/latex2.png','inputs/latex3.md5','inputs/latex3.svg'] %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% !User Guide @@ -195,13 +195,13 @@ LaTeX Filter ['--section-numbers'] % source -../doc/asciidoc.txt +inputs/asciidoc.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% UTF-8 Examples % source -data/utf8-examples.txt +inputs/utf8-examples.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Additional Open Block and Paragraph styles @@ -210,10 +210,10 @@ Additional Open Block and Paragraph styles ['source-highlight', 'dot'] % source -data/open-block-test.txt +inputs/open-block-test.txt % artifacts -['data/open-block-test__1.md5','data/open-block-test__1.png','data/open-block-test__2.png','data/open-block-test__3.md5','data/open-block-test__3.png'] +['inputs/open-block-test__1.md5','inputs/open-block-test__1.png','inputs/open-block-test__2.png','inputs/open-block-test__3.md5','inputs/open-block-test__3.png'] %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% English language file (article) @@ -225,7 +225,7 @@ English language file (article) lang-en-article-test % source -data/lang-en-test.txt +inputs/lang-en-test.txt % options [('--doctype','article')] @@ -243,7 +243,7 @@ English language file (book) lang-en-book-test % source -data/lang-en-test.txt +inputs/lang-en-test.txt % options [('--doctype','book')] @@ -258,7 +258,7 @@ English language file (manpage) ['docbook','docbook5'] % source -data/lang-en-man-test.txt +inputs/lang-en-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Russian language file (article) @@ -270,7 +270,7 @@ Russian language file (article) lang-ru-article-test % source -data/lang-ru-test.txt +inputs/lang-ru-test.txt % options [('--doctype','article')] @@ -288,7 +288,7 @@ Russian language file (book) lang-ru-book-test % source -data/lang-ru-test.txt +inputs/lang-ru-test.txt % options [('--doctype','book')] @@ -303,7 +303,7 @@ Russian language file (manpage) ['docbook','docbook5'] % source -data/lang-ru-man-test.txt +inputs/lang-ru-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% French language file (article) @@ -315,7 +315,7 @@ French language file (article) lang-fr-article-test % source -data/lang-fr-test.txt +inputs/lang-fr-test.txt % options [('--doctype','article')] @@ -333,7 +333,7 @@ French language file (book) lang-fr-book-test % source -data/lang-fr-test.txt +inputs/lang-fr-test.txt % options [('--doctype','book')] @@ -348,7 +348,7 @@ French language file (manpage) ['docbook','docbook5'] % source -data/lang-fr-man-test.txt +inputs/lang-fr-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% German language file (article) @@ -360,7 +360,7 @@ German language file (article) lang-de-article-test % source -data/lang-de-test.txt +inputs/lang-de-test.txt % options [('--doctype','article')] @@ -378,7 +378,7 @@ German language file (book) lang-de-book-test % source -data/lang-de-test.txt +inputs/lang-de-test.txt % options [('--doctype','book')] @@ -393,7 +393,7 @@ German language file (manpage) ['docbook','docbook5'] % source -data/lang-de-man-test.txt +inputs/lang-de-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Hungarian language file (article) @@ -405,7 +405,7 @@ Hungarian language file (article) lang-hu-article-test % source -data/lang-hu-test.txt +inputs/lang-hu-test.txt % options [('--doctype','article')] @@ -423,7 +423,7 @@ Hungarian language file (book) lang-hu-book-test % source -data/lang-hu-test.txt +inputs/lang-hu-test.txt % options [('--doctype','book')] @@ -438,7 +438,7 @@ Hungarian language file (manpage) ['docbook','docbook5'] % source -data/lang-hu-man-test.txt +inputs/lang-hu-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Spanish language file (article) @@ -450,7 +450,7 @@ Spanish language file (article) lang-es-article-test % source -data/lang-es-test.txt +inputs/lang-es-test.txt % options [('--doctype','article')] @@ -468,7 +468,7 @@ Spanish language file (book) lang-es-book-test % source -data/lang-es-test.txt +inputs/lang-es-test.txt % options [('--doctype','book')] @@ -483,7 +483,7 @@ Spanish language file (manpage) ['docbook','docbook5'] % source -data/lang-es-man-test.txt +inputs/lang-es-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Brazilian Portuguese language file (article) @@ -495,7 +495,7 @@ Brazilian Portuguese language file (article) lang-pt-BR-article-test % source -data/lang-pt-BR-test.txt +inputs/lang-pt-BR-test.txt % options [('--doctype','article')] @@ -513,7 +513,7 @@ Brazilian Portuguese language file (book) lang-pt-BR-book-test % source -data/lang-pt-BR-test.txt +inputs/lang-pt-BR-test.txt % options [('--doctype','book')] @@ -528,7 +528,7 @@ Brazilian Portuguese language file (manpage) ['docbook','docbook5'] % source -data/lang-pt-BR-man-test.txt +inputs/lang-pt-BR-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Ukrainian language file (article) @@ -540,7 +540,7 @@ Ukrainian language file (article) lang-uk-article-test % source -data/lang-uk-test.txt +inputs/lang-uk-test.txt % options [('--doctype','article')] @@ -558,7 +558,7 @@ Ukrainian language file (book) lang-uk-book-test % source -data/lang-uk-test.txt +inputs/lang-uk-test.txt % options [('--doctype','book')] @@ -573,7 +573,7 @@ Ukrainian language file (manpage) ['docbook','docbook5'] % source -data/lang-uk-man-test.txt +inputs/lang-uk-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Dutch language file (article) @@ -585,7 +585,7 @@ Dutch language file (article) lang-nl-article-test % source -data/lang-nl-test.txt +inputs/lang-nl-test.txt % options [('--doctype','article')] @@ -603,7 +603,7 @@ Dutch language file (book) lang-nl-book-test % source -data/lang-nl-test.txt +inputs/lang-nl-test.txt % options [('--doctype','book')] @@ -618,7 +618,7 @@ Dutch language file (manpage) ['docbook','docbook5'] % source -data/lang-nl-man-test.txt +inputs/lang-nl-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Italian language file (article) @@ -630,7 +630,7 @@ Italian language file (article) lang-it-article-test % source -data/lang-it-test.txt +inputs/lang-it-test.txt % options [('--doctype','article')] @@ -648,7 +648,7 @@ Italian language file (book) lang-it-book-test % source -data/lang-it-test.txt +inputs/lang-it-test.txt % options [('--doctype','book')] @@ -663,7 +663,7 @@ Italian language file (manpage) ['docbook','docbook5'] % source -data/lang-it-man-test.txt +inputs/lang-it-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Czech language file (article) @@ -675,7 +675,7 @@ Czech language file (article) lang-cs-article-test % source -data/lang-cs-test.txt +inputs/lang-cs-test.txt % options [('--doctype','article')] @@ -693,7 +693,7 @@ Czech language file (book) lang-cs-book-test % source -data/lang-cs-test.txt +inputs/lang-cs-test.txt % options [('--doctype','book')] @@ -708,7 +708,7 @@ Czech language file (manpage) ['docbook','docbook5'] % source -data/lang-cs-man-test.txt +inputs/lang-cs-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Romanian language file (article) @@ -720,7 +720,7 @@ Romanian language file (article) lang-ro-article-test % source -data/lang-ro-test.txt +inputs/lang-ro-test.txt % options [('--doctype','article')] @@ -738,7 +738,7 @@ Romanian language file (book) lang-ro-book-test % source -data/lang-ro-test.txt +inputs/lang-ro-test.txt % options [('--doctype','book')] @@ -753,7 +753,7 @@ Romanian language file (manpage) ['docbook','docbook5'] % source -data/lang-ro-man-test.txt +inputs/lang-ro-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Japanese language file (article) @@ -765,7 +765,7 @@ Japanese language file (article) lang-ja-article-test % source -data/lang-ja-test.txt +inputs/lang-ja-test.txt % options [('--doctype','article')] @@ -783,7 +783,7 @@ Japanese language file (book) lang-ja-book-test % source -data/lang-ja-test.txt +inputs/lang-ja-test.txt % options [('--doctype','book')] @@ -798,19 +798,19 @@ Japanese language file (manpage) ['docbook','docbook5'] % source -data/lang-ja-man-test.txt +inputs/lang-ja-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% RCS $Id$ marker test % source -data/rcs-id-marker-test.txt +inputs/rcs-id-marker-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% UTF-8 BOM test % source -data/utf8-bom-test.txt +inputs/utf8-bom-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Deprecated quote attributes @@ -819,7 +819,7 @@ Deprecated quote attributes {'deprecated-quotes':''} % source -data/deprecated-quotes.txt +inputs/deprecated-quotes.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Swedish language file (article) @@ -831,7 +831,7 @@ Swedish language file (article) lang-sv-article-test % source -data/lang-sv-test.txt +inputs/lang-sv-test.txt % options [('--doctype','article')] @@ -849,7 +849,7 @@ Swedish language file (book) lang-sv-book-test % source -data/lang-sv-test.txt +inputs/lang-sv-test.txt % options [('--doctype','book')] @@ -864,7 +864,7 @@ Swedish language file (manpage) ['docbook','docbook5'] % source -data/lang-sv-man-test.txt +inputs/lang-sv-man-test.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Last Updated field not displayed in HTML backends @@ -876,7 +876,7 @@ Last Updated field not displayed in HTML backends lang-en-no-last-updated-test % source -data/lang-en-test.txt +inputs/lang-en-test.txt % attributes {'footer-style':'none'} @@ -891,7 +891,7 @@ Last Updated field displays revision date lang-en-last-updated-is-revdate-test % source -data/lang-en-test.txt +inputs/lang-en-test.txt % attributes {'footer-style':'revdate'} @@ -900,7 +900,7 @@ data/lang-en-test.txt !Generated chapter IDs normalized to ASCII test % source -data/ascii-ids1.txt +inputs/ascii-ids1.txt %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Newline Tests (Default With DOS) @@ -912,7 +912,7 @@ Newline Tests (Default With DOS) newline-dos % source -data/newline.txt +inputs/newline.txt % attributes {'toc':True} @@ -927,7 +927,7 @@ Newline Tests (Override To UNIX) newline-unix % source -data/newline.txt +inputs/newline.txt % options [('--attribute','newline=\\n')] @@ -945,7 +945,7 @@ Newline Tests (Override To MAC) newline-mac % source -data/newline.txt +inputs/newline.txt % options [('--attribute','newline=\\r')] @@ -966,4 +966,4 @@ Include Line Ranges include-lines % source -data/include-lines-test.txt +inputs/include-lines-test.txt -- cgit v1.2.1