mizuho 0.9.6 → 0.9.8

data/asciidoc/doc/asciidocapi.txt

@@ -0,0 +1,189 @@
+AsciiDoc API
+============
+
+'asciidocapi' -- a Python API module for 'AsciiDoc'.
+
+
+Introduction
+------------
+The 'asciidocapi' module implements a Python API for AsciiDoc. It
+allows you to set `asciidoc(1)` program options, compile an AsciiDoc
+source file and then interrogate the results.  The `asciidocapi.py`
+module file contains the `AsciiDocAPI` wrapper class for
+`asciidoc.py`.
+
+.Benefits
+- Stable API Shields the user from the undocumented and possibly
+  volatile `asciidoc.py` internals.
+- Easier to use and more flexible than the alternative of running
+  `asciidoc(1)` as a separate process.
+- Executes inside your application (better performance than running
+  separate `asciidoc(1)` command processes).
+
+
+Using asciidocapi
+-----------------
+To use the API just drop the `asciidocapi.py` file into your
+application directory, import it and use the `AsciiDocAPI` class.  The
+only requirement is that a compatible version of 'AsciiDoc' is already
+installed -- simple, no setuptools to run, no Eggs to install, no
+non-standard library dependencies.
+
+You can find `asciidocapi.py` in the AsciiDoc
+http://www.methods.co.nz/asciidoc/INSTALL.html#X1[distribution
+archives] (version 8.4.1 or better).
+
+Once you have `asciidocapi.py` Verify everything is working by running
+the module doctests:
+
+  python asciidocapi.py
+
+If there are no messages then all is well.
+
+The following minimal example compiles `mydoc.txt` to `mydoc.html`:
+
+[source,python]
+-------------------------------------------------------------------------------
+from asciidocapi import AsciiDocAPI
+asciidoc = AsciiDocAPI()
+asciidoc.execute('mydoc.txt')
+-------------------------------------------------------------------------------
+
+The next interactive example uses file-like objects for input and output:
+
+-------------------------------------------------------------------------------
+$ python
+Python 2.5.2 (r252:60911, Jul 31 2008, 17:28:52)
+[GCC 4.2.3 (Ubuntu 4.2.3-2ubuntu7)] on linux2
+Type "help", "copyright", "credits" or "license" for more information.
+>>> from asciidocapi import AsciiDocAPI
+>>> import StringIO
+>>> infile = StringIO.StringIO('Hello *{author}*')
+>>> outfile = StringIO.StringIO()
+>>> asciidoc = AsciiDocAPI()
+>>> asciidoc.options('--no-header-footer')
+>>> asciidoc.attributes['author'] = 'Joe Bloggs'
+>>> asciidoc.execute(infile, outfile, backend='html4')
+>>> print outfile.getvalue()
+<p>Hello <strong>Joe Bloggs</strong></p>
+
+>>>
+-------------------------------------------------------------------------------
+
+
+Implementation Rationale
+------------------------
+.Leverage existing knowledge
+The API maps directly onto the `asciidoc(1)` command -- this is
+deliberate -- if you know the `asciidoc(1)` command learning the API
+will be trivial. A nice side effect of this goal is that API and
+command-line modes share the same code -- virtually no `asciidoc(1)`
+code is specific to API usage.
+
+.Simplicity
+Implemented with a single Python module file (`asciidocapi.py`)
+containing the 'AsciiDocAPI' API class. 'AsciiDocAPI'  contains just
+one method plus a few attributes for processing options and result
+messages.  No external setup tools and no non-standard library
+dependencies are used or required.
+
+.Loose coupling
+The dependency between `asciidocapi.py` and `asciidoc.py` is minimal
+-- the current `asciidocapi.py` module uses only two attributes and
+one function from the `asciidoc.py` module.
+
+.Why isn't the API baked right into the asciidoc.py command script?
+1. You can't just drop `asciidoc.py` into your application because it
+   requires all the related config files and filters -- complex and
+   unnecessary since all this was already done when you installed
+   AsciiDoc.
+2. This scheme separates the API from the AsciiDoc application -- the
+   API implementation can be extended or replaced independently of
+   AsciiDoc.
+
+
+API reference
+-------------
+
+[[X2]]
+Class `AsciiDocAPI(object)`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This is the 'AsciiDoc' API class.
+
+Instance attributes
+^^^^^^^^^^^^^^^^^^^
+`asciidoc`::
+The imported `asciidoc.py` module.
+
+`attributes`::
+A dictionary of AsciiDoc attribute values passed to AsciiDoc.
+
+- Setting an attribute value to `None` (`name: None`) will undefine
+  (delete) the attribute (this in addition to the `name!` attribute
+  name format that the `asciidoc(1)` command uses).
+- To simply define an attribute set the attribute value to a blank
+  string (`name: ''`) 
+
+`cmd`::
+The file path of the `asciidoc.py` script. Set by the `__init__`
+method.
+
+`messages`::
+A chronologically ordered list of message strings generated during
+AsciiDoc execution (last message at the end of the list).
+
+`options`::
+An instance of the <<X1,Options class>>. Contains a list of command
+options passed to AsciiDoc.
+
+Instance methods
+^^^^^^^^^^^^^^^^
+`__init__(self, asciidoc_py=None)`::
+Locate and import `asciidoc.py` module and verify API compatibility.
+Initialize instance attributes. A search for the `asciidoc` module is
+made in the following order:
+
+. Use the `ASCIIDOC_PY` environment variable if it is set.
+. Use the `asciidoc_py` argument if it is set.
+. Search the environment 'PATH' for `asciidoc.py`, `asciidoc.pyc` and
+  `asciidoc` (in that order).
+. Finally repeat the previous search in the current working directory.
+
+`execute(self, infile, outfile=None, backend=None)`::
+Compile `infile` to `outfile` using `backend` format.  `infile` and
+`outfile` can be file path strings or file-like objects. `backend` is
+name of 'AsciiDoc' backend (takes same values as `asciidoc(1)` command
+`--backend` option). If `outfile` or `backend` are `None` then their
+respective `asciidoc(1)` defaults are used.
+
+
+[[X1]]
+Class `Options(object)`
+~~~~~~~~~~~~~~~~~~~~~~~
+Stores `asciidoc(1)` command options. You can use any `asciidoc(1)`
+options with the exception of the `--doctest` and `--filter` options.
+
+Instance attributes
+^^^^^^^^^^^^^^^^^^^
+`values`::
+The list of `(name,value)` command option tuples.
+
+Instance methods
+^^^^^^^^^^^^^^^^
+`__call__(self, name, value=None)`::
+A shortcut for the `append` method. Example:
+
+  opts = Options()
+  opts('--verbose')
+
+`append(self, name, value=None)`::
+Append `(name,value)` to the options list. Example:
+
+  opts = Options()
+  opts.append('--conf-file', 'blog.conf')
+
+
+Class `AsciiDocError(Exception)`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Thrown by the <<X2,AsciiDocAPI class>> when an 'AsciiDoc' execution
+error occurs.

data/asciidoc/doc/asciimathml.txt

@@ -17,14 +17,14 @@ characters to yield valid XHTML. To use ASCIIMathML:
 2. Enclose ASCIIMathML formulas inside math or double-dollar
    passthroughs or in math passthrough blocks.
 
-Here's the link:asciimath.txt[AsciiDoc source] that generated this
+Here's the link:asciimathml.txt[AsciiDoc source] that generated this
 page.
 
 .NOTE
-- When you use the `\asciimath:[]` inline macro you need to escape `]`
+- 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 first two
-  formulas below).
+  if you use the double-dollar macro (for examples see the second
+  formula below).
 - See the
   http://www1.chapman.edu/~jipsen/mathml/asciimath.html[ASCIIMathML]
   website for ASCIIMathML documentation and the latest version.
@@ -35,30 +35,27 @@ page.
 - See the link:latexmathml.html[LaTeXMathML page] if you prefer to use
   LaTeX math formulas.
 
-A list of formulas with a mixture of formatting:
+A list of example formulas:
 
-- asciimath:[[[a,b\],[c,d\]\]((n),(k))]
 - $$`[[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]
-- Red [red]+++`sum_(i=1)\^n i=(n(n+1))/2`$+++ and [blue]*bold
+- +++`sum_(i=1)\^n i=(n(n+1))/2`$+++ and *bold
   asciimath:[int_0\^(pi/2) sinx\ dx=1]*
-- [,,1.5]## 1.5 times normal size asciimath:[(a,b\]={x in RR : a < x <= b}]##
-- A [,,2]##big## [blue]##blue## formula
-  [blue,,2]##asciimath:[x^2+y_1+z_12^34]##.
-- [green,yellow,4]##asciimath:[x^2+y_1+z_12^34]##
+- asciimath:[(a,b\]={x in RR : a < x <= b}]
+- asciimath:[x^2+y_1+z_12^34]
 
 *********************************************************************
 The first three terms factor to give
-[red]##asciimath:[(x+b/(2a))^2=(b^2)/(4a^2)-c/a]##.
+asciimath:[(x+b/(2a))^2=(b^2)/(4a^2)-c/a].
 
-[red]##asciimath:[x+b/(2a)=+-sqrt((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
-[red]##asciimath:[x+b/(2a)=+-sqrt((b^2)/(4a^2)-c/a)]##.  Finally we
-move the [red]##asciimath:[b/(2a)]## to the right and simplify to get
-the two solutions:
-[red]*asciimath:[x_(1,2)=(-b+-sqrt(b^2-4ac))/(2a)]*.
+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)]*.
 
 *********************************************************************
 

data/asciidoc/doc/book-multi.txt

@@ -1,155 +1,181 @@
-Multi-Part Book Title Goes Here
-===============================
-Author's Name
-v1.0, Dec 2003
-
-
-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
-=======
-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
-==========================
-
-The First Chapter
------------------
-Chapters can be grouped by preceeding 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'.
-|==============================================
-
-[[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 <<X1,first sub-section>>.
-indexterm:[Second example index entry]
-
-An example link to a bibliography entry <<taoup>>.
-
-
-
-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.
-
-
-
-Appendix A: 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
-============
-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
-========
-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.
-
-
-Index
-=====
-////////////////////////////////////////////////////////////////
-The index is normally left completely empty, it's contents are
-generated automatically by the DocBook toolchain.
-////////////////////////////////////////////////////////////////
+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 preceeding 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 <<X1,first sub-section>>.
+indexterm:[Second example index entry]
+
+An example link to a bibliography entry <<taoup>>.
+
+
+
+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.
+////////////////////////////////////////////////////////////////