mizuho 0.9.10 → 0.9.11

data/asciidoc/examples/website/latex-backend.txt

@@ -0,0 +1,192 @@
+LaTeX backend for Asciidoc
+==========================
+Benjamin Klum <benjamin.klum@gmail.com>
+v1.0, June 2006
+
+== Introduction
+
+
+LaTeX backend is a configuration file for Stuart Rackham's http://www.methods.co.nz/asciidoc/[Asciidoc]. It generates high-level LaTeX markup from Asciidoc documents. LaTeX is a document preparation system for TeX which in turn is a popular typesetting system. It is well known for producing excellently typesetted high quality printouts, especially suited for scientific text.
+
+== Tutorial
+Getting a ready-to-print document from an Asciidoc document using the LaTeX backend involves at least two steps:
+
+1. Conversion of the Asciidoc document into a LaTeX document (this is done by Asciidoc using the LaTeX backend)
+2. Conversion of the LaTeX document into a PDF document (this is done by the TeX system)
+
+Try to create a PDF document from the Asciidoc document `article.txt` which resides in the `doc` directory of Asciidoc:
+
+.. Make a copy of `article.txt` in a directory of your choice, let's call it `latex-test`.
+.. Make sure that all images referenced in `article.txt` exist in `latex-test`. Brute force approach: Copy the whole `images` directory from Asciidoc directory into `latex-test`.
+.. Change directory to `latex-test` and type following commands:
++
+  asciidoc --unsafe --backend=latex article.txt
+  pdflatex article.tex
++
+.. Now there should be a file `article.pdf` in the `latex-test` directory.
+
+[IMPORTANT]
+==============================
+- Asciidoc has to be started in 'unsafe mode' when using LaTeX backend.
+- Note that some special LaTeX packages are necessary, see <<packageRequirements,here>>.
+==============================
+
+== General notes
+
+=== Quality of LaTeX output
+High-level LaTeX is not very straightforward to generate. Therefore there's no guarantee that the generated output is valid and compiles successfully. At all, this backend should be considered as rather experimental.  You should have been already in touch with LaTeX in order to use the backend effectively because LaTeX compilation errors can be really nasty.
+
+Nevertheless good results can be achieved by using LaTeX backend. Try for example to compile Stuart Rackham's Asciidoc documentation, a rather large document. It should compile without problems. However, the code filter might have to be reconfigured for the code filter example to work.
+
+=== Configuration file customization
+Like every other Asciidoc backend the LaTeX backend can be customized easily to fit the user's needs. Actually it is very important to have this option since LaTeX doesn't have a companion language like CSS which allows to put styling information in a separate file. Read more about the LaTeX backend configuration file <<configurationFile,here>>.
+
+=== Output optimization
+The LaTeX output is optimized for creating PDF documents using 'pdflatex'.
+
+[[unicodeSupport]]
+=== Unicode support
+Unfortunately TeX/LaTeX does not have native unicode support. The package 'ucs' adds elementary unicode support by introducing UTF-8 input encoding recognition and by defining lookup tables which contain the corresponding LaTeX commands for unicode characters. But these lookup tables are far from being complete. When a unicode character is found which is not defined in the lookup tables an error is raised by the TeX/LaTeX compiler. Note that TeX/LaTeX compilation errors caused by missing unicode character definitions are not fatal, that means the result is probably readable but undefined unicode characters are replaced with `[U+...]`. You may (de)activate the recognition of escaped unicode characters. See the <<latex-recognize-escaped-unicode>> backend option.
+
+== Backend specific features
+
+=== Special sections
+
+LaTeX backend supports the following special sections and replaces them with corresponding LaTeX commands or environments:
+
+- Abstract (only for document type 'article')
+- Dedication (only for document type 'book')
+- Index
+- Bibliography (only when the attribute 'latex-use-bibliography-environment' is set)
+- Appendix
+- Contents
+
+[[internalCrossReferences]]
+=== Internal cross references
+
+Macros for internal cross references have been extended by the attribute 'style'.
+
+  xref:<id>[<caption>, style=<style>]
+
+or
+
+  <<<id>,<caption>,<style>>>
+
+  
+The additional attribute 'style' can have following values:
+
+page::
+Let's LaTeX print the page number of the referenced anchor.
+
+ref::
+Let's LaTeX print the number of the section, subsection, figure, table or theorem the referenced anchor resides.
+
+autoref::
+Let's LaTeX print the number of the section, subsection, figure, table or theorem the referenced anchor resides preceded with a contextual label.
+
+cite::
+Let's LaTeX interprete this reference as a reference to a bibliography entry. If the attribute 'latex-use-bibliography-environment' is set, references with 'cite' style as well as their corresponding bibliography anchors are presented as automatically generated numbers.
+
+If the 'style' attribute is not set the reference is printed the common way.
+
+
+=== Options
+LaTeX document generation is influenced by the following attributes:
+
+latex-table-rowlimit::
+The maximum number of rows for typesetting tables using the 'tabular' environment. If a table has more rows than 'latex-table-rowlimit', 'longtable' environment is used instead of 'tabular' environment. 'longtable' environment supports tables spanning over several pages.
+
+latex-use-bibliography-environment::
+If 'latex-use-bibliography-environment' is defined, 'thebibliography' environment is used for the bibliography section. As a result bibliography entries are automatically numbered. Note that this works only if the bibliography section contains exclusively bibliography list items which start with a bibliography entry ([[[...]]]). Otherwise a TeX/LaTeX compilation error will occur. In order to display bibliography references correctly their 'style' attribute must be set to 'cite'. For more information see <<internalCrossReferences,Internal cross references>>.
+
+latex-indent-paragraphs::
+If 'latex-indent-paragraphs' is defined, the first line of paragraphs will be indented. By default LaTeX backend prevents paragraph indentation and prints paragraphs with preceding vertical space.
+
+[[latex-recognize-escaped-unicode]] latex-recognize-escaped-unicode::
+If 'latex-recognize-escaped-unicode' is defined, escaped unicode
+characters (e.g. `\$${amp}#960;$$` or `\$${amp}#x3C0;$$`) will be recognized. This can lead to LaTeX compilation errors since LaTeX unicode support is only rudimentary. For more information see <<unicodeSupport, Unicode support>>.
+
+latex-use-custom-list-items::
+If 'latex-use-custom-list-items' is defined, lists will be bulleted or enumerated the way you have typed them in the original Asciidoc document. That means, `*` turns into a circle bullet, `-` turns into a dash, `.` turns into a number and `..` turns into a letter. Otherwise LaTeX will use different bullets and enumeration characters depending on the level of nesting.
+
+latex-use-colored-tables::
+If 'latex-use-colored-tables' is defined, tables will be printed colored.
+
+latex-use-running-title-headings::
+If 'latex-use-running-title-headings' is defined, 'pagestyle' will be set to 'headings' which results in running titles in the head.
+
+latex-use-colored-sidebar-blocks::
+If 'latex-use-colored-sidebar-blocks' is defined, sidebar block content will be put in a color box instead of being indented by a vertical bar.
+
+icons::
+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.
+
+encoding::
+Set the input and output document character set encoding. Currently `ISO-8859-1` and `UTF-8` are supported.
+
+== Requirements
+
+=== General
+
+The following software is necessary for using the LaTeX backend:
+
+- An up-to-date version of http://www.methods.co.nz/asciidoc/[Asciidoc]
+- An up-to-date TeX distribution, e.g.:
+  * http://www.miktex.org/[MiKTeX] for Windows
+  * http://www.tug.org/tetex/[teTeX] for Linux
+
+[[packageRequirements]]
+=== TeX/LaTeX Package requirements
+
+LaTeX backend makes use of some LaTeX specialities which don't belong to a minimal TeX/LaTeX distribution. However, I took special care not to employ exotic packages. Hence the following packages should be available in most package repositories. The table is not complete yet because I don't know the package names for all TeX distributions.
+
+[cols="4*,4",options="header"]
+|====================================================================
+|Speciality | MiKTeX package name | teTeX package name | TeX Live package name | Description
+|KOMA-Script | koma-script | | | LaTeX backend uses the document classes 'scrartcl' and 'scrbook' as well as some other specialities defined in the 'KOMA-Script' package, e.g. the commands `\addmargin{}` and `\minisec{}`.
+|xcolor.sty | xcolor | | | Used to produce colored boxes and tables.
+|colortbl.sty | colortbl | | | Used to produce colored tables.
+|type1ec.sty | cm-super | | | Enables high quality fonts for PDF output.
+|hyperref.sty | hyperref | | | Extensive support for hypertext in PDF documents.
+|enumerate.sty | tools | | | When 'latex-use-custom-list-items' is defined this package is used for determining the enumeration character.
+|graphicx.sty | graphics | | | Used for including images.
+|longtable.sty | tools | | | Enables page spanning tables.
+|ucs.sty | unicode | | | Enables support for unicode characters.
+|textcomp | ltxbase | | | Used for printing various symbols like arrows. Should be already installed.
+|alltt | ltxbase | | | Used in literal-like blocks for retaining line and whitespace formatting. Should be already installed.
+|listings.sty | listings | | | Used for listing blocks.
+|====================================================================
+
+[[configurationFile]]
+== About the LaTeX backend configuration file
+An important note for people who want to adapt the LaTeX backend configuration file to their own needs:
+
+LaTeX markup has a lot of special characters, most importantly ``, `{`, `}`. In order to make things less complicated, I changed the default substitution order (see entry 'subsnormal' in the `[miscellaneous]` section). In contrast to the backends 'docbook' and 'xhtml11', the 'specialcharacters' substitution is applied very late. As a result all special characters produced by 'quotes', 'specialwords', 'replacements', 'attributes' and 'macros' become escaped at the end. If you don't want special characters in the corresponding sections to get escaped, you've to use following symbols instead of the special characters.
+
+- `\$$!..backslash..!$$` instead of ``
+- `\$$!..braceleft..!$$` instead of `{`
+- `\$$!..braceright..!$$` instead of `}`
+
+ 
+For more special characters take a look in the `[replacements2]` sections. `[replacements2]` section is responsible for replacing the symbols with their corresponding special characters.
+
+
+== Ideas
+
+=== Code listing block
+
+For creating highlighted code listings I suggest the use of http://www.andre-simon.de/[Highlight] or http://www.gnu.org/software/src-highlite/[GNU Source Highlight]. Both are suited for use as Asciidoc filters.
+
+== Known Bugs
+
+- Sometimes LaTeX backend handles things differently from the default backends
+- A lot of little bugs
+
+== Todo List
+
+- Remove bugs
+- Support for 'grid' attribute in tables
+- Better looking tables
+- Option for squeezing output (smaller lists)
+- Support for different languages (That would be a nice feature for Asciidoc in general)
+- Option for switching titlepage on and off

data/asciidoc/examples/website/latex-bugs.txt

@@ -0,0 +1,134 @@
+Bugs in asciidoc latex backend
+==============================
+Geoff Eddy
+
+Benjamin Klum was unable to maintain the LaTeX backend beyond version
+8.2.7, and as a consequence the `latex.conf` file ceased to work with
+`asciidoc` sometime after this. For version 8.4.3 I made some changes
+to the file to get it working again. This document summarises the
+remaining issues which I have found with generating LaTeX and thence
+PDF output with `asciidoc`, which is done as follows:
+
+- `asciidoc --backend=latex --unsafe FILE.txt`
+- `latex FILE.tex`
+- `kpdf FILE.pdf`
+
+Many of these were found by processing the `asciidoc.txt` file and
+comparing the HTML output with the PDF.
+
+== Footnotes
+
+Priority:: Low.
+
+Problem:: References to footnotes, and a sensible value for the
+`[footnoteref-inlinemacro]` section, don't seem to be possible.
+
+Cause:: LaTeX doesn't support footnoting much beyond creating a
+footnote at a certain point in text and displaying the footnote
+itself.
+
+Solution:: Unclear. How important or necessary is this, anyway?
+
+== Spurious text at starts of paragraphs
+
+Priority:: Medium
+
+Problem:: It is necessary to insert spurious text in paragraphs.
+
+Cause:: This `asciidoc` input:
++
+  -------------------------------------------------------------------
+  Text
+  -------------------------------------------------------------------
++
+generates this LaTeX code:
++
+  \begin{lstlisting}
+  SPURIOUS TEXTText\end{lstlisting}
++
+which should be:
++
+  \begin{lstlisting}[]
+  Text\end{lstlisting}
+
+Solution:: Find out a way to generate the correct LaTeX output as
+above. The obvious solution, as explained in `latet.conf`, doesn't
+work.
+
+== Tables
+
+Priority:: Rather high.
+
+Problem:: Not all of the table configuration options can be passed
+through to the LaTeX backend. In particular, I've had to assume that
+all tables will be fifteen or fewer left-justified columns wide.
+
+Cause:: The table models in LaTeX and HTML are too dissimilar for one
+`asciidoc` specification to generate valid output in both formats by
+simple regexp replacement. Related to this is the unfortunate fact
+that `<COLGROUP>` and related tags aren't a required part of HTML4,
+and some broswers (at least Firefox and Konqueror) don't implement
+them.
+
+Solution:: Perhaps table processing could be handled by a Python
+plugin, which would read in a table spec and generate the appropriate
+text?
+
+== Unicode escaping
+
+Priority:: Rather high, to me at least.
+
+Problem:: The commented-out section in `latex.conf`, if uncommented,
+converts `&#960;` to `\unichar{960}`, which then causes LaTeX to
+complain that the resulting command is unavailable in encoding T1. The
+more common non-ASCII characters, such as those in `félicité` and
+`świeca`, are handled properly, but some - such as the IPA characters
+in the `tipa` package - are not.
+
+Cause:: The encodings in the LaTeX output are wrong.
+
+Solution:: Correct the encodings.
+
+== Text colours
+
+Priority:: Probably low
+
+Problem:: The text colour options are not processed by LaTeX; for
+example `[#ff0000]#Red text#` is not rendered in red.
+
+Cause:: LaTeX and HTML represent RGB triads differently: HTML is happy
+with `#ff8000`, but LaTeX needs `[rgb]{1,0.5,0}`.
+
+Solution:: Provide some sort of internal RGB conversion mechanism
+which can convert RGB triads to different representations.
+
+== Text sizes
+
+Priority:: Probably low
+
+Problem:: The text size options are not processed by LaTeX:
+`[,,1]#text#` is rendered in the same size as normal text.
+
+Cause:: HTML size tags - `h1` through `h7` - are directly derivable
+from the size number, whereas LaTeX has a series of descriptive words
+(`HUGE` through `normalsize` to `scriptsize`).
+
+Solution:: Provide a way to treat the number as an index into an
+array.
+
+== Background colour in paragraphs
+
+Priority:: Medium
+
+Problem:: If the `backgroundcolor` attribute is specified in the
+`lstset` command, all paragraphs are displayed as black rectangles by
+`kpdf`, `xpdf`, and `evince`, although `kdvi` has no problems. I've
+had to remove the attribute, and so paragraphs all appear on white
+backgrounds. The PDF viewers also complain:
+
+  Error (NNNN): Unknown operator 'rgb'
+
+Cause:: Apparently a known bug in the output of `pdflatex`. Not a bug
+in `asciidoc`.
+
+Solution:: Wait until this bug is fixed?

data/asciidoc/examples/website/latex-filter.txt

@@ -0,0 +1,196 @@
+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 PNG 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.
+
+This LaTeX paragraph:
+
+[listing]
+.....................................................................
+[latex]
+$y = \int_0^\infty \gamma^2 \cos(x) dx$
+.....................................................................
+
+Renders:
+
+[latex]
+$y = \int_0^\infty \gamma^2 \cos(x) dx$
+
+This LaTeX block:
+
+[listing]
+.....................................................................
+["latex","latex1.png",align="center"]
+---------------------------------------------------------------------
+$\displaystyle{ V_i = C_0 - C_3
+\frac{C_1\cos(\theta_i+C_3)}{C_4+C_1\cos(\theta_i+C_2)} }$
+---------------------------------------------------------------------
+.....................................................................
+
+Renders:
+
+["latex","latex1.png",align="center"]
+---------------------------------------------------------------------
+$\displaystyle{ V_i = C_0 - C_3
+\frac{C_1\cos(\theta_i+C_3)}{C_4+C_1\cos(\theta_i+C_2)} }$
+---------------------------------------------------------------------
+
+This LaTeX block:
+
+[listing]
+.....................................................................
+.LaTeX filter example
+[latex]
+["latex","latex3.png"]
+---------------------------------------------------------------------
+\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]
+---------------------------------------------------------------------
+\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]
+\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]
+\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 PNG image file. If this is not supplied a
+  file name like `{docname}__{target-number}.png` is synthesised
+  (where `{docname}` is the document file name and `{target-number}`
+  is an integer number.
+- The third positional attribute, named 'dpi', is also optional; it is
+  an integer number that sets the output resolution in dots per inch.
+
+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/latex2png.py`) can be used outside
+AsciiDoc to convert LaTeX source to PNG images.
+
+Execute the following command to see how to use it:
+
+  $ ./filters/latex/latex2png.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)` and
+`dvipng(1)` installed.