mizuho 0.9.6

data/asciidoc/doc/faq.txt

@@ -0,0 +1,547 @@
+AsciiDoc Frequently Asked Questions
+===================================
+
+An embryonic AsciiDoc FAQ.
+
+
+== Is it possible to include charts in AsciiDoc documents?
+
+There are a number of programs available that generate presentation
+charts from textual specification, for example
+http://home.gna.org/pychart/[Pychart] is a library for writing chart
+scripts in Python. Here's an example from the 'Pychart' documentation:
+
+.barchart.py
+---------------------------------------------------------------------
+#
+# Example bar chart (from Pychart documentation http://home.gna.org/pychart/).
+#
+from pychart import *
+theme.get_options()
+
+data = [(10, 20, 30, 5), (20, 65, 33, 5), (30, 55, 30, 5), (40, 45, 51, 7),
+        (50, 25, 27, 3), (60, 75, 30, 5), (70, 80, 42, 5), (80, 62, 32, 5),
+        (90, 42, 39, 5), (100, 32, 39, 4)]
+
+# The attribute y_coord=... tells that the Y axis values
+# should be taken from samples.
+# In this example, Y values will be [40,50,60,70,80].
+ar = area.T(y_coord = category_coord.T(data[3:8], 0),
+            x_grid_style=line_style.gray50_dash1,
+            x_grid_interval=20, x_range = (0,100),
+            x_axis=axis.X(label="X label"),
+            y_axis=axis.Y(label="Y label"),
+            bg_style = fill_style.gray90,
+            border_line_style = line_style.default,
+            legend = legend.T(loc=(80,10)))
+
+# Below call sets the default attributes for all bar plots.
+chart_object.set_defaults(bar_plot.T, direction="horizontal", data=data)
+
+# Attribute cluster=(0,3) tells that you are going to draw three bar
+# plots side by side.  The plot labeled "foo" will the leftmost (i.e.,
+# 0th out of 3).  Attribute hcol tells the column from which to
+# retrive sample values from.  It defaults to one.
+ar.add_plot(bar_plot.T(label="foo", cluster=(0,3)))
+ar.add_plot(bar_plot.T(label="bar", hcol=2, cluster=(1,3)))
+ar.add_plot(bar_plot.T(label="baz", hcol=3, cluster=(2,3)))
+ar.draw()
+---------------------------------------------------------------------
+
+To execute the script and include the generated chart image in your
+document add the following lines to the AsciiDoc source:
+
+---------------------------------------------------------------------
+// Generate chart image file.
+\sys2::[python barchart.py --format=png --output=barchart.png --scale=2]
+
+// Display chart image file.
+image::barchart.png[]
+---------------------------------------------------------------------
+
+NOTE: You need to run asciidoc(1) with the `--unsafe` command-line
+option to execute the `sys2` system macro.
+
+
+== How can I render indented paragraphs?
+
+To unconditionally indent all paragraphs add the following line to the
+`xhtml11.css` stylesheet (or a custom stylesheet).
+
+---------------------------------------------------------------------
+div.paragraph p {text-indent: 3em;}
+---------------------------------------------------------------------
+
+This will restyle the entire document by indenting all paragraphs
+which is normally what you want to do (mixed paragraph styles produce
+ugly documents).
+
+To selectively indent paragraphs with the 'indented' style add the
+following line to the `xhtml11.css` stylesheet (or a custom
+stylesheet).
+
+---------------------------------------------------------------------
+div.paragraph.indented p {text-indent: 3em;}
+---------------------------------------------------------------------
+
+Then apply the 'indented' style to normal paragraphs, for example:
+
+---------------------------------------------------------------------
+[indented]
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Maecenas
+ultrices justo porttitor augue. Vestibulum pretium. Donec porta
+vestibulum mi. Aliquam pede. Aenean lobortis lorem et lacus. Sed
+lacinia. Vivamus at lectus.
+---------------------------------------------------------------------
+
+NOTE: This FAQ applies to XHTML output not DocBook. To achieve the
+same results with DocBook you would need to customize the DocBook XSL
+stylesheets to indent paragraphs with the `simpara` element
+`role="indented"` attribute.
+
+
+== Is there a way to set default image height and width attributes?
+
+You can set the 'height' and 'width' attributes globally in your
+document with Attribute Entries or from the command-line using the
+`--attribute` option. In the following example images that don't
+explicitly set the 'height' and 'width' values will be 350 by 250
+pixels.
+
+---------------------------------------------------------------------
+:height: 250
+:width: 350
+
+image:images/tiger.png[]
+---------------------------------------------------------------------
+
+
+== How can I place a backslash character in front of an attribute reference without escaping the reference?
+
+Use the predefined `\{backslash}` attribute reference instead of an
+actual backslash, for example if the `\{projectname}` attribute has
+the value `foobar` then:
+
+  d:\data{backslash}{projectname}
+
+would be rendered as:
+
+  d:\data\foobar
+
+== How can I escape AsciiDoc markup?
+
+Most AsciiDoc inline elements can be suppressed by preceding them with
+a backslash character. These elements include:
+
+- Attribute references.
+- Text formatting.
+- Quoting,
+- Macros.
+- Replacements.
+- Special words.
+- Table cell separators.
+
+But there are exceptions -- see the next question.
+
+
+== Some elements can't be escaped with a single backslash
+
+There are a number of  exceptions to the usual single backslash rule
+-- mostly relating to URL macros that  have two syntaxes or quoting
+ambiguity.  Here are some non-standard escape examples:
+
+[cols="1default,4literal",width="70%",grid="none",frame="none"]
+|====================================================================
+|Mailto URLs |
+\srackham@methods.co.nz
+<\srackham@methods.co.nz>
+\mailto:[\srackham@methods.co.nz]
+
+|Web URLs |
+\http://www.foo1.co.nz
+\\http://www.foobar.com[]
+\\http://www.foobar.com[Foobar Limited]
+
+|Other |
+A C+\+ Library for C++
+A C+\+ Library for C+\+ \+++
+\\``double-quotes''
+\*\*F**ile Open...
+|====================================================================
+
+The source of this problem is ambiguity across substitution types --
+the first match unescapes allowing the second to substitute. A
+work-around for difficult cases is to side-step the problem using the
+`\pass:[]` passthrough inline macro.
+
+
+== How can I set default list and tables styles?
+
+You can set the element's 'style' entry in a global or custom
+configuration file.
+
+This example this will horizontally style all labeled lists that don't
+have an explicit style attribute:
+
+----------------------------------
+[listdef-labeled]
+style=horizontal
+
+[listdef-labeled2]
+style=horizontal
+----------------------------------
+
+This example will put a top and bottom border on all tables that don't
+already have an explicit style attribute:
+
+----------------------------------
+[tabledef-default]
+style=topbot
+topbot-style=frame="topbot"
+----------------------------------
+
+Alternatively you can set the configuration entries from inside your
+document, the above examples are equivalent to:
+
+----------------------------------
+:listdef-labeled.style: horizontal
+:listdef-labeled2.style: horizontal
+
+:tabledef-default.topbot-style: frame="topbot"
+:tabledef-default.style: topbot
+----------------------------------
+
+
+== Why do I get a filter non-zero exit code error?
+
+An error was returned when AsciiDoc tried to execute an external
+filter command. The most common reason for this is that the filter
+command could not be found by the command shell. To figure out what
+the problem is run AsciiDoc with the `--verbose` option to determine
+the command that is failing and then try to run the command manually
+from the command-line.
+
+
+== Are there any DocBook viewers?
+
+http://live.gnome.org/Yelp[Yelp], the GNOME help viewer, does a
+creditable job of displaying DocBook files XML files directly. Just
+run it from the command-line, for example:
+
+  $ yelp file://home/srackham/tmp/book.xml
+
+Note that you have to supply the full path name in URI format, this
+shell script makes interactive use easier:
+
+-------------------------------
+#!/bin/sh
+if [ -z "$1" ]; then
+    echo "usage: dbkview FILE"
+    exit 1
+fi
+yelp "file://$(pwd)/$1"
+-------------------------------
+
+This tip was submitted by Lionel Orry.
+
+
+== Can you create ODF documents using AsciiDoc?
+
+The easiest and highest fidelity methods I've seen is to generate
+HTML from AsciiDoc then paste it from your browser (we use Firefox)
+into OpenOffice Writer.
+
+- I found that that there is better fidelity pasting HTML generated by
+  the 'html4' backend instead of the default 'xhtml11' backend.
+- Don't paste AsciiDoc tables of contents, OpenOffice Writer (I was
+  using version 2.3) hangs when saving. This may be something to do
+  with the embedded JavaScript but I haven't looked closely at it, I
+  may even be wrong about this.
+
+This tip was contributed by Bernard Amade.
+
+
+== How can I supress cell separators in included table data files?
+
+Use the `\{include:}` system attribute instead of the `\include::[]`
+macro (the former is not expanded until after the table data has been
+parsed into cells, whereas the latter is included before the table is
+processed.
+
+
+== How can I preserve paragraph line boundaries?
+
+Apply the The 'verse' paragraph style, the rendered text preserves
+line boundaries and is useful for lyrics and poems.  For example:
+
+---------------------------------------------------------------------
+[verse]
+Consul *necessitatibus* per id,
+consetetur, eu pro everti postulant
+homero verear ea mea, qui.
+---------------------------------------------------------------------
+
+If you are generating PDF files (using FOP) or HTML files then you can
+use line breaks. For example:
+
+---------------------------------------------------------------------
+Consul *necessitatibus* per id, +
+consetetur, eu pro everti postulant +
+homero verear ea mea, qui.
+---------------------------------------------------------------------
+
+
+== How can I include non-breaking space characters?
+
+The predefined `\{nbsp}` attribute reference will be replaced by a
+non-breaking space character. You could also use the non-breaking
+space character entity reference `\&#160;` (see the next question).
+
+
+== Can I include HTML and XML character entity references in my document?
+
+Yes, just enter the reference in your document. For example `\&#946;`
+will print a Greek small beta character &#946;
+
+
+[[X1]]
+== How do I include spaces in URLs?
+
+URL inline macro targets (addresses) cannot contain white space
+characters. If you need spaces encode them as `%20`. For example:
+
+  image:large%20image.png[]
+  http://www.foo.bar.com/an%20example%20document.html
+
+
+== How can I get AsciiDoc to assign the correct DocBook language attribute?
+
+Set the AsciiDoc 'lang' attribute to the appropriate language code.
+For example:
+
+  $ a2x -a lang=es doc/article.txt
+
+This will ensure that downstream DocBook processing will generate the
+correct language specific document headings (things like table of
+contents, revision history, figure and table captions, admonition
+captions).
+
+
+== Why does AsciiDoc give me a ``malformed author'' error?
+
+This is normally because there are more than three names (up to three
+are expected: first name, middle name and last name). For example,
+this author line would result in an error:
+
+  Vincent Willem van Gogh
+
+You can enter multi-word first, middle and last names in the author
+line using the underscore as a word separator. For example:
+
+  Vincent Willem van_Gogh
+
+You could also resolve the problem by replacing the author line with
+explicit attribute entries:
+
+  :First name:  Vincent
+  :Middle name: Willem
+  :Last name:   Van Gogh
+
+
+== How can I assign multiple author names?
+
+A quick way to do this is put both authors in a single first name, for 
+example:
+
+  My Document
+  ===========
+  :Author: Bill_and_Ben_the_Flowerpot_Men
+  :Author Initials: BB & BC
+
+asciidoc(1) replaces the underscores with spaces.
+
+The longer, semantically correct, way is to override the
+`[header]` configuration file section in a document specific `.conf`
+file. For example if your document is `mydoc.txt` then a file called
+`mydoc.conf` in the document directory would be picked up
+automatically by asciidoc(1).  Copy and paste the default
+`docbook.conf` file `[header]` to `mydoc.conf` and modify the author
+related markup:
+
+  [header]
+    :
+  <authorgroup>...
+    :
+
+
+== How can I escape a labeled list entry?
+
+Two colons or semicolons in a paragraph may be confused with a labeled
+list entry. Use the predefined `\{two_colons}` and `\{two_semicolons}`
+to suppress this behavior, for example:
+
+  Qui in magna commodo{two_colons} est labitur dolorum an. Est ne
+  magna primis adolescens.
+
+Will be rendered as:
+
+Qui in magna commodo{two_colons} est labitur dolorum an. Est ne
+magna primis adolescens.
+
+
+== How can I selectively disable a quoted text substitution?
+
+Omitting the tag name will disable quoting. For example, if you don't
+want superscripts or subscripts then put the following in a custom
+configuration file or edit the global `asciidoc.conf` configuration
+file:
+
+-------------------
+[quotes]
+^=
+~=
+-------------------
+
+Alternatively you can set the configuration entries from within your
+document, the above examples are equivalent to:
+
+-------------------
+:quotes.^:
+:quotes.~:
+-------------------
+
+
+== How can I customize the \{localdate} format?
+
+The default format for the `\{localdate}` attribute is the ISO 8601
+`yyyy-mm-dd` format. You can change this format by explicitly setting
+the `\{localdate}` attribute. For example by setting it using the
+asciidoc(1) `-a` command-line option:
+
+  $ asciidoc -a localdate=`date +%d-%d-%Y` mydoc.txt
+
+You could also set it by adding an Attribute Entry to your souce
+document, for example:
+
+  :localdate: {sys: date +%Y-%m-%d}
+
+Since it's set using an executable attribute you'll also need to
+include the `--unsafe` option when you run asciidoc).
+
+
+== Why doesn't AsciiDoc support strike through text?
+
+The reason it's not in the distribution is that DocBook does not have
+provision for strike through text and one of the AsciiDoc design goals
+is that AsciiDoc markup should be applicable to all output formats.
+
+Strike through is normally used to mark deleted text -- a more
+comprehensive way to manage document revisions is to use a version
+control system such as Subversion. You can also use the AsciiDoc
+'CommentLines' and 'CommentBlocks' to retain revised text in the
+source document.
+
+If you really need strike through text for (X)HTML outputs then adding
+the following to a configuration file will allow you to quote strike
+through text with hyphen characters:
+
+---------------------------------------------------------------------
+ ifdef::basebackend-html[]
+
+ [quotes]
+ -=strikethrough
+
+ [tags]
+ strikethrough=<span style="text-decoration: line-through;">|</span>
+
+ endif::basebackend-html[]
+---------------------------------------------------------------------
+
+
+== Where can I find examples of commands used to build output documents?
+
+The User Guide has some. You could also look at `./doc/main.aap` in
+the AsciiDoc distribution, it has all the commands used to build the
+AsciiDoc documentation (even if you don't use A-A-P you'll still find
+it useful).
+
+
+== Why have you used the DocBook <simpara> element instead of <para>?
+
+`<simpara>` is really the same as `<para>` except it can't contain
+block elements -- this matched, more closely, the AsciiDoc paragraph
+semantics.
+
+
+== How can I format text inside a listing block?
+
+By default only 'specialcharacters' and 'callouts' are substituted in
+listing blocks; you can add quotes substitutions by explicitly setting
+the block 'subs' attribute, for example:
+
+  [subs="quotes"]
+  ------------------------------------------
+  $ ls *-al*
+  ------------------------------------------
+
+The `-al` will rendered bold. Note that:
+
+- You would need to explicitly escape text you didn't want quoted.
+- Don't do this in source code listing blocks because it modifies the
+  source code which confuses the syntax highlighter.
+- This only works if your DocBook processor recognizes DocBook
+  `<emphasis>` elements inside `<screen>` elements.
+
+
+== Why doesn't the include1::[] macro work?
+
+Internally the `include1` macro is translated to the `include1` system
+attribute which means it must be evaluated in a region where attribute
+substitution is enabled. `include1` won't work, for example, in a
+ListingBlock (unless attribute substitution is enabled).  `include1`
+is intended for use in configuration files, use the `include` macro
+and set the attribute `depth=1` instead, for example:
+
+  -----------------------------------------------
+  include::blogpost_media_processing.txt[depth=1]
+  -----------------------------------------------
+
+== How can I customize PDF files generated by dblatex?
+
+There are a number of dblatex XSL parameters that can be used to
+customize PDF output. You can set them globally in the AsciiDoc
+`./dblatex/asciidoc-dblatex.xsl` configuration file or you can also
+pass them on the a2x(1) command-line, for example:
+
+  a2x -f pdf --dblatex-opts "-P latex.output.revhistory=0" doc/article.txt
+
+See also the http://dblatex.sourceforge.net/[dblatex] documentation.
+
+
+== How can I make the mailto macro work with multiple email addresses?
+
+For the AsciiDoc 'mailto' macro to work with multiple email addresses
+(as per RFC2368) you need to URL encode the '@' characters (replace
+them with '%40'), if you don't the individual addresses will be
+rendered as separate links. You also need to <<X1,replace spaces with
+'%20'>>.
+
+For example, the following call won't work:
+
+  mailto:jb@foobar.com,jd@acme.co.nz?subject=New foofoo release[New foofoo release]
+
+Use this instead:
+
+  mailto:jb%40foobar.com,jd%40acme.co.nz?subject=New%20foofoo%20release[New foofoo release]
+
+
+== How can a replacement have a trailing backslash?
+Quote the entry name -- this nonsensical example replaces `x\` with
+`y`:
+
+  "x\\"=y
+
+If quoting were omitted the equals character (separating the
+entry name `x` from the value `y`) would be escaped.
+
+