mizuho 0.9.6 → 0.9.8

data/asciidoc/doc/slidy-example.txt

@@ -0,0 +1,167 @@
+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
+---------------------------------------------------------------------
+
+[music]
+.Music
+---------------------------------------------------------------------
+\version "2.10.0"
+\paper {
+  ragged-right = ##t
+}
+{
+  \time 3/4
+  \clef bass
+  c2 e4 g2. f4 e d c2 r4
+}
+---------------------------------------------------------------------

data/asciidoc/doc/slidy.txt

@@ -0,0 +1,113 @@
+Slidy backend for AsciiDoc
+==========================
+:author:    Stuart Rackham
+:backend:   slidy
+:max-width: 45em
+:data-uri:
+:icons:
+
+
+Use the following command to create this document (`slidy.html`):
+
+  asciidoc slidy.txt
+
+Press the 'Space' key or the 'Left Arrow' key to continue the
+slideshow.
+
+
+Overview
+--------
+AsciiDoc has a 'slidy' backend for generating self contained 'Slidy'
+HTML slideshows.
+
+- An overview of 'Slidy' can be found here:
+  http://www.w3.org/Talks/Tools/Slidy2/
+- AsciiDoc ships with the Slidy JavaScript a customised Slidy CSS
+  file.
+- Use the 'asciidoc' `--backend slidy` command-line option to generate
+  browser viewable HTML slideshow. Example:
+
+  asciidoc --backend slidy slidy-example.txt
+
+- By default, 'asciidoc' creates a self contained distributable HTML
+  document which includes all necessary CSS and JavaScripts.  Use the
+  'asciidoc' `--attribute linkcss` command-line option if you prefer
+  to link (rather than embed) external CSS and JavaScript files.
+
+
+How Slidy uses AsciiDoc markup
+------------------------------
+- The document header is displayed as the first page of the slideshow.
+- If the document has a 'preamble' (the content between the header and
+  the first section) it will be displayed on the second page.
+- Each top level section is displayed as a separate slide.
+- If the AsciiDoc 'incremental' attribute is defined then all lists
+  and OpenBlock elements are treated as 'incremental' i.e. Slidy
+  exposes their child elements one at a time as you progress through
+  the slideshow.
+- You can explicitly set an element as incremental by setting its
+  'role' attribute to 'incremental'. Example:
+
+  [role="incremental"]
+  Sagittis in vestibulum. Habitasse ante nulla enim bibendum nulla.
+  Odio sed pede litora.
+
+
+Slidy Specific Attributes
+-------------------------
+incremental::
+If this attribute is defined then all lists and OpenBlock elements are
+classed as incremental i.e. Slidy will expose them one at a time as
+you progress through the slideshow.  The default behavior is for the
+show to progress a full slide at at time.  Elements that have been
+explicitly classed as 'incremental' with the 'role' attribute are
+always displayed incrementally.
+
+duration::
+Set this to the estimated number of minutes that your presentation
+will take and Slidy will display a countdown timer at the bottom right
+of the slideshow. For example, this 'asciidoc' command-line option
+`--attribute duration=5` sets the duration to five minutes.
+
+copyright::
+If you set the 'copyright' attribute it will be displayed in the Slidy
+menu bar at the bottom of the slide. If the 'copyright' attribute is
+not define then the author name, if it is defined, will be displayed.
+
+outline::
+Setting the 'role' attribute to 'outline' in a bulleted or numbered
+list allows nested lists to be expanded and collapsed using the mouse.
+Nested lists are expanded when an enclosing list item (the ones with
+blue bullet points or numbers) is clicked.
+
+
+Stylesheets
+-----------
+- 'slidy' loads the 'asciidoc.css' stylesheet followed by 'slidy.css':
+  * `asciidoc.css` contains content presentational styles.
+  * The customized `slidy.css` stylesheet contains Slidy specific
+    styles (table of contents, menu and transition related).
+- You can use AsciiDoc CSS themes. For example, the 'asciidoc'
+  `--attribute theme=volnitsky` command-line option will substitute
+  the `asciidoc.css` stylesheet for the distributed Volnitsky
+  `volnitsky.css` stylesheet.
+- An additional stylesheet can be specified by setting the
+  'stylesheet' attribute. For example, the `--attribute
+  stylesheet=myslidy.css` will load `myslidy.css` after the standard
+  CSS files.
+
+
+Tips
+----
+- The Slidy 'help?' and 'contents?' links at the bottom left are your
+  friends.
+- Use the AsciiDoc 'data-uri' attribute to embed images in your
+  slideshow -- add this attribute entry to your document's header:
+
+  :data-uri:
+
+- Use the AsciiDoc 'max-width' attribute to set the document display
+  width. For example, add this attribute entry to your document's
+  header:
+
+  :max-width: 45em

data/asciidoc/doc/source-highlight-filter.txt

@@ -2,19 +2,41 @@ Source Code Highlight Filter
 ============================
 
 The AsciiDoc distribution includes a source code syntax highlight
-filter (`source-highlight-filter.conf`). It uses
-http://www.gnu.org/software/src-highlite/[GNU source-highlight] to
-highlight HTML outputs; DocBook outputs are highlighted by toolchains
-that have `programlisting` element highlight support, for example
-'dblatex'.
+filter (`source-highlight-filter.conf`).
 
-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.
+
+HTML Outputs
+------------
+The highlighter uses http://www.gnu.org/software/src-highlite/[GNU
+source-highlight] to highlight 'html4' and 'xhtml11' outputs. You also
+have the option of using the http://pygments.org/[Pygments] syntax
+highlighter for 'xhtml11' outputs.
+
+To use Pygments you need to define an AsciiDoc attribute named
+'pygments' (either from the command-line or in the global
+`asciidoc.conf` configuration file) and you will also need to have
+Pygments installed and the 'pygmentize' command in your PATH.
+
+- You can customize Pygments CSS styles by editing
+  `./stylesheets/pygments.css`.
+- To make Pygments your default highlighter put the following line
+  your `~/.asciidoc/asciidoc.conf` file:
+
+  pygments=
+
+- The AsciiDoc 'encoding' attribute is passed to Pygments as a `-O`
+  command-line option.
+
+
+DocBook Outputs
+---------------
+DocBook outputs are highlighted by toolchains that have
+`programlisting` element highlight support, for example 'dblatex'.
 
 
 Examples
 --------
+
 Source code paragraphs
 ~~~~~~~~~~~~~~~~~~~~~~
 The `source` paragraph style will highlight a paragraph of source
@@ -166,15 +188,25 @@ 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 may need to place callout markers inside source code comments to
+  ensure they are not misinterpreted and mangled by the highlighter.
+=====
+
 
 Installation
 ------------
 HTML
 ~~~~
 If you want to syntax highlight AsciiDoc HTML outputs (`html4` and
-`xhtml11` backends) you need to
-install http://www.gnu.org/software/src-highlite/[GNU
-source-highlight] (most distributions have this package).
+`xhtml11` backends) you need to install
+http://www.gnu.org/software/src-highlite/[GNU source-highlight] or
+http://pygments.org/[Pygments] (most distributions have these
+packages).
 
 DocBook
 ~~~~~~~
@@ -188,16 +220,9 @@ DocBook programlisting element is assigned two attributes:
 . The 'linenumbering' attribute is set to the AsciiDoc 'src_numbered'
   attribute ('numbered' or 'unnumbered').
 
-If you use `a2x(1)` to generate PDF you need to include the
-`--no-xmllint` option to suppress `xmllint(1)` checking -- the
-programlisting 'language' attribute (required by the dblatex source
-highlighter) is not part of the DocBook 4 specification (but it is in
-the newer DocBook 5 specification).
-
-
 Testing
 ~~~~~~~
 Test the filter by converting the test file to HTML with AsciiDoc:
 
-   $ asciidoc -v ./filters/source-highlight-filter-test.txt
-   $ firefox ./filters/source-highlight-filter-test.html &
+  $ asciidoc -v ./filters/source/source-highlight-filter-test.txt
+  $ firefox ./filters/source/source-highlight-filter-test.html &

data/asciidoc/doc/testasciidoc.txt

@@ -0,0 +1,231 @@
+AsciiDoc Tests
+==============
+
+AsciiDoc includes 'testasciidoc', a Python script runs a set of
+AsciiDoc conformance tests. 'testasciidoc' runs through a list of
+AsciiDoc source files, generates backend outputs and then compares
+them to expected result files. The whole process is driven by a
+configuration file containing a list of user configurable test
+specifications.
+
+
+Rationale
+---------
+When modifying AsciiDoc configuration files or source code it's very
+easy to introduce regression errors. 'testasciidoc' is a tool for
+writing many and varied test cases that can be run after changes have
+been made in order to verify that existing behavior has not been
+broken.
+
+The 'testasciidoc' 'update' command automates the (re)generation of
+expected test result data.  Result data regeneration has to be
+performed after changes to test case source files or after legitimate
+changes to the AsciiDoc output formats -- doing this manually is
+prohibitively tedious.
+
+
+Running testasciidoc
+--------------------
+The `testasciidoc.py` script and the default `testasciidoc.conf`
+configuration file are located in the AsciiDoc distribution `tests`
+directory.
+
+To view the command usage run:
+
+---------------------------------------------------------------------
+$ python tests/testasciidoc.py
+Usage: testasciidoc.py [OPTIONS] COMMAND
+
+Run AsciiDoc conformance tests specified in configuration FILE.
+
+Commands:
+  list                          List tests
+  run [NUMBER] [BACKEND]        Execute tests
+  update [NUMBER] [BACKEND]     Regenerate and update test data
+
+Options:
+  -f, --conf-file=CONF_FILE
+        Use configuration file CONF_FILE (default configuration file is
+        testasciidoc.conf in testasciidoc.py directory)
+  --force
+        Update all test data overwriting existing data
+---------------------------------------------------------------------
+
+To view the list of tests in the default `testasciidoc.conf`
+configuration file run the 'list' command:
+
+---------------------------------------------------------------------
+$ python tests/testasciidoc.py list
+1: Test cases
+2: Tables
+3: Source highlighter
+4: Example article
+5: Example book
+6: Example multi-part book
+7: !User Guide
+---------------------------------------------------------------------
+
+The '!' prefix signals that a test is currently disabled.
+
+Before running the tests you will need to regenerate the expected
+outputs by running the 'update' command:
+
+---------------------------------------------------------------------
+$ python tests/testasciidoc.py update
+WRITING: tests/data/testcases-html4.html
+WRITING: tests/data/testcases-xhtml11.html
+WRITING: tests/data/testcases-docbook.xml
+ :
+WRITING: tests/data/book-multi-docbook.xml
+---------------------------------------------------------------------
+
+Now you can run the tests:
+
+---------------------------------------------------------------------
+$ python tests/testasciidoc.py run
+1: Test cases
+SOURCE: asciidoc: tests/data/testcases.txt
+PASSED: html4: tests/data/testcases-html4.html
+PASSED: xhtml11: tests/data/testcases-xhtml11.html
+PASSED: docbook: tests/data/testcases-docbook.xml
+ :
+6: Example multi-part book
+SOURCE: asciidoc: doc/book-multi.txt
+PASSED: html4: tests/data/book-multi-html4.html
+PASSED: xhtml11: tests/data/book-multi-xhtml11.html
+PASSED: docbook: tests/data/book-multi-docbook.xml
+
+TOTAL PASSED:  18
+---------------------------------------------------------------------
+
+[NOTE]
+=====================================================================
+- 'testasciidoc' requires AsciiDoc is located in your environment
+  search path, if not you'll need to set the `ASCIIDOC_PY` environment
+  variable to point to `asciidoc.py`.
+- If you don't have GNU source-highlight installed you should disable
+  the 'Tables' and 'Source highlighter' tests in the
+  `tests/testasciidoc.conf` configuration file.
+=====================================================================
+
+
+testasciidoc commands
+---------------------
+'list'::
+  List test numbers and titles.  A '!' title prefix signals that a
+  test is currently disabled.
+
+'run'::
+  Read and execute tests from the test configuration file. A test
+  specifies AsciiDoc test case source file and command options.  The
+  test compares generated outputs to expected outputs and any
+  differences displayed as a diff.  You can run selected tests by
+  specifying the test number and/or backend after the `run` command.
+  Examples:
+
+  python tests/testasciidoc.py run
+  python tests/testasciidoc.py run 3
+  python tests/testasciidoc.py run html4
+  python tests/testasciidoc.py run 3 html4
+
+'update'::
+  Generates and updates missing and out of date test output data
+  files, this eliminates one of the most time consuming aspect of test
+  management.  Use the `--force` option to force updates.
+  Examples:
+
+  python tests/testasciidoc.py update
+  python tests/testasciidoc.py --force update 4
+
+NOTE: You can run or update disabled tests by explicitly specifying
+the test number.
+
+
+Test configuration file
+-----------------------
+The tests configuration file format consists of one or more test specs
+separated by a line of one or more percent characters. Each test spec
+consists of an optional test title and description followed by one or
+more optional directives (a directive starts with a percent
+character).  A 'directive' consists begins with a line containing a '%'
+character followed by a directive name followed by zero or more lines
+of directive data.
+
+Test spec format
+~~~~~~~~~~~~~~~~
+---------------------------------------------------------------------
+Optional test title
+Optional test description...
+
+% name
+Optional base output file name. Defaults to base source file name.
+
+% source
+AsciiDoc source file name.
+
+% backends
+Optional list of backends to be tested(default is all backends).
+% options
+Optional list of command-line option tuples.
+
+% attributes
+Optional dictionary of attribute values.
+
+---------------------------------------------------------------------
+
+Example test spec:
+
+---------------------------------------------------------------------
+Example book
+
+% options
+['--section-numbers',('--doctype','book')]
+
+% attributes
+# Exclude date from document footer.
+{'docdate':None}
+
+% source
+../doc/book.txt
+---------------------------------------------------------------------
+
+TIP: Take a look at the default `tests/testasciidoc.conf`
+configuration file that comes with AsciiDoc.
+
+- Tests can be disabled by prefixing the test title with an
+  exclamation '!' character.
+- All relative file names are relative to the configuration file
+  directory.
+- Multiple tests must by separated by a `%` separator line (one or
+  more percent characters).
+- Lines starting with a percent character specify a test 'directive'
+  and may be followed by zero or more lines of directive data.
+- Directive data lines cannot start with a percent character.
+- Lines starting with a `#` hash character are ignored.
+- The 'source' directive data is a single line containing the
+  AsciiDoc source file name.
+- The 'options' directive data is a Python list of `(name,value)`
+  tuples specifying AsciiDoc command-line options. A string item is
+  equivalent to a `(name,None)` tuple.
+- The 'attributes' directive data specifies a Python dictionary
+  containing AsciiDoc attributes to be passed to AsciiDoc.
+
+globals directive
+~~~~~~~~~~~~~~~~~
+An optional 'globals' directive can precede all test specs, the
+globals directive data is a Python dictionary containing global
+values.  Currently the only global is 'datadir', the directory
+containing expected output files (defaults to configuration file
+directory). For example:
+
+---------------------------------------------------------------------
+% globals
+{'datadir': 'data'}
+---------------------------------------------------------------------
+
+Expected output test data files are stored in the 'datadir' and are
+named after the corresponding AsciiDoc input source file.  For example
+if the AsciiDoc file name is `article.txt` then the corresponding
+backend output files will be `article-html4.html`,
+`article-xhtml11.html`, `article-docbook.xml` (stored in the 'datadir'
+directory).