asciidoctor 1.5.8 → 2.0.0.rc.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.adoc +162 -17
- data/LICENSE +1 -1
- data/README-de.adoc +12 -13
- data/README-fr.adoc +11 -12
- data/README-jp.adoc +11 -12
- data/README-zh_CN.adoc +12 -13
- data/README.adoc +6 -7
- data/asciidoctor.gemspec +19 -24
- data/bin/asciidoctor +5 -4
- data/data/reference/syntax.adoc +283 -0
- data/data/stylesheets/asciidoctor-default.css +56 -52
- data/data/stylesheets/coderay-asciidoctor.css +7 -9
- data/lib/asciidoctor.rb +171 -232
- data/lib/asciidoctor/abstract_block.rb +96 -105
- data/lib/asciidoctor/abstract_node.rb +118 -139
- data/lib/asciidoctor/attribute_list.rb +10 -14
- data/lib/asciidoctor/block.rb +20 -19
- data/lib/asciidoctor/callouts.rb +4 -2
- data/lib/asciidoctor/cli.rb +3 -2
- data/lib/asciidoctor/cli/invoker.rb +14 -21
- data/lib/asciidoctor/cli/options.rb +64 -54
- data/lib/asciidoctor/converter.rb +357 -185
- data/lib/asciidoctor/converter/composite.rb +40 -48
- data/lib/asciidoctor/converter/docbook5.rb +604 -640
- data/lib/asciidoctor/converter/html5.rb +949 -963
- data/lib/asciidoctor/converter/manpage.rb +569 -548
- data/lib/asciidoctor/converter/template.rb +231 -272
- data/lib/asciidoctor/core_ext.rb +5 -18
- data/lib/asciidoctor/core_ext/float/truncate.rb +19 -0
- data/lib/asciidoctor/core_ext/match_data/names.rb +7 -0
- data/lib/asciidoctor/core_ext/nil_or_empty.rb +1 -0
- data/lib/asciidoctor/core_ext/regexp/is_match.rb +4 -2
- data/lib/asciidoctor/document.rb +399 -377
- data/lib/asciidoctor/extensions.rb +72 -140
- data/lib/asciidoctor/helpers.rb +122 -83
- data/lib/asciidoctor/inline.rb +5 -1
- data/lib/asciidoctor/list.rb +13 -11
- data/lib/asciidoctor/logging.rb +17 -16
- data/lib/asciidoctor/parser.rb +390 -423
- data/lib/asciidoctor/path_resolver.rb +10 -5
- data/lib/asciidoctor/reader.rb +286 -263
- data/lib/asciidoctor/rouge_ext.rb +39 -0
- data/lib/asciidoctor/section.rb +9 -8
- data/lib/asciidoctor/stylesheets.rb +19 -37
- data/lib/asciidoctor/substitutors.rb +364 -509
- data/lib/asciidoctor/syntax_highlighter.rb +238 -0
- data/lib/asciidoctor/syntax_highlighter/coderay.rb +87 -0
- data/lib/asciidoctor/syntax_highlighter/highlightjs.rb +26 -0
- data/lib/asciidoctor/syntax_highlighter/html_pipeline.rb +10 -0
- data/lib/asciidoctor/syntax_highlighter/prettify.rb +27 -0
- data/lib/asciidoctor/syntax_highlighter/pygments.rb +149 -0
- data/lib/asciidoctor/syntax_highlighter/rouge.rb +129 -0
- data/lib/asciidoctor/table.rb +73 -66
- data/lib/asciidoctor/timings.rb +4 -2
- data/lib/asciidoctor/version.rb +2 -1
- data/lib/asciidoctor/writer.rb +30 -0
- data/man/asciidoctor.1 +19 -15
- data/man/asciidoctor.adoc +14 -12
- metadata +69 -216
- data/CONTRIBUTING.adoc +0 -185
- data/Gemfile +0 -60
- data/Rakefile +0 -129
- data/bin/asciidoctor-safe +0 -15
- data/features/open_block.feature +0 -92
- data/features/pass_block.feature +0 -66
- data/features/step_definitions.rb +0 -49
- data/features/text_formatting.feature +0 -57
- data/features/xref.feature +0 -1039
- data/lib/asciidoctor/converter/base.rb +0 -59
- data/lib/asciidoctor/converter/docbook45.rb +0 -93
- data/lib/asciidoctor/converter/factory.rb +0 -226
- data/lib/asciidoctor/core_ext/1.8.7/base64/strict_encode64.rb +0 -6
- data/lib/asciidoctor/core_ext/1.8.7/concurrent/hash.rb +0 -5
- data/lib/asciidoctor/core_ext/1.8.7/hash/key.rb +0 -4
- data/lib/asciidoctor/core_ext/1.8.7/io/binread.rb +0 -6
- data/lib/asciidoctor/core_ext/1.8.7/io/write.rb +0 -5
- data/lib/asciidoctor/core_ext/1.8.7/string/chr.rb +0 -6
- data/lib/asciidoctor/core_ext/1.8.7/string/limit_bytesize.rb +0 -29
- data/lib/asciidoctor/core_ext/1.8.7/symbol/empty.rb +0 -6
- data/lib/asciidoctor/core_ext/1.8.7/symbol/length.rb +0 -6
- data/lib/asciidoctor/core_ext/string/limit_bytesize.rb +0 -10
- data/test/api_test.rb +0 -1240
- data/test/attribute_list_test.rb +0 -242
- data/test/attributes_test.rb +0 -1623
- data/test/blocks_test.rb +0 -3870
- data/test/converter_test.rb +0 -470
- data/test/document_test.rb +0 -1853
- data/test/extensions_test.rb +0 -1560
- data/test/fixtures/asciidoc_index.txt +0 -521
- data/test/fixtures/basic-docinfo-footer.html +0 -6
- data/test/fixtures/basic-docinfo-footer.xml +0 -8
- data/test/fixtures/basic-docinfo.html +0 -1
- data/test/fixtures/basic-docinfo.xml +0 -4
- data/test/fixtures/basic.asciidoc +0 -5
- data/test/fixtures/chapter-a.adoc +0 -3
- data/test/fixtures/child-include.adoc +0 -5
- data/test/fixtures/circle.svg +0 -9
- data/test/fixtures/custom-backends/erb/html5/block_paragraph.html.erb +0 -6
- data/test/fixtures/custom-backends/haml/docbook45/block_paragraph.xml.haml +0 -6
- data/test/fixtures/custom-backends/haml/html5-tweaks/block_paragraph.html.haml +0 -1
- data/test/fixtures/custom-backends/haml/html5/block_paragraph.html.haml +0 -3
- data/test/fixtures/custom-backends/haml/html5/block_sidebar.html.haml +0 -5
- data/test/fixtures/custom-backends/slim/docbook45/block_paragraph.xml.slim +0 -6
- data/test/fixtures/custom-backends/slim/html5/block_paragraph.html.slim +0 -3
- data/test/fixtures/custom-backends/slim/html5/block_sidebar.html.slim +0 -5
- data/test/fixtures/custom-docinfodir/basic-docinfo.html +0 -1
- data/test/fixtures/custom-docinfodir/docinfo.html +0 -1
- data/test/fixtures/docinfo-footer.html +0 -1
- data/test/fixtures/docinfo-footer.xml +0 -9
- data/test/fixtures/docinfo.html +0 -1
- data/test/fixtures/docinfo.xml +0 -3
- data/test/fixtures/doctime-localtime.adoc +0 -2
- data/test/fixtures/dot.gif +0 -0
- data/test/fixtures/encoding.asciidoc +0 -13
- data/test/fixtures/file-with-missing-include.adoc +0 -1
- data/test/fixtures/grandchild-include.adoc +0 -3
- data/test/fixtures/hello-asciidoctor.pdf +0 -69
- data/test/fixtures/include-file.asciidoc +0 -24
- data/test/fixtures/include-file.jsx +0 -8
- data/test/fixtures/include-file.ml +0 -3
- data/test/fixtures/include-file.xml +0 -5
- data/test/fixtures/lists.adoc +0 -96
- data/test/fixtures/master.adoc +0 -5
- data/test/fixtures/mismatched-end-tag.adoc +0 -7
- data/test/fixtures/other-chapters.adoc +0 -11
- data/test/fixtures/outer-include.adoc +0 -5
- data/test/fixtures/parent-include-restricted.adoc +0 -5
- data/test/fixtures/parent-include.adoc +0 -5
- data/test/fixtures/sample.asciidoc +0 -30
- data/test/fixtures/section-a.adoc +0 -4
- data/test/fixtures/stylesheets/custom.css +0 -3
- data/test/fixtures/subdir/index.adoc +0 -3
- data/test/fixtures/subdir/inner-include.adoc +0 -3
- data/test/fixtures/subdir/middle-include.adoc +0 -5
- data/test/fixtures/subs-docinfo.html +0 -2
- data/test/fixtures/subs.adoc +0 -6
- data/test/fixtures/tagged-class-enclosed.rb +0 -25
- data/test/fixtures/tagged-class.rb +0 -23
- data/test/fixtures/tip.gif +0 -0
- data/test/fixtures/unclosed-tag.adoc +0 -3
- data/test/fixtures/unexpected-end-tag.adoc +0 -4
- data/test/invoker_test.rb +0 -745
- data/test/links_test.rb +0 -855
- data/test/lists_test.rb +0 -5151
- data/test/logger_test.rb +0 -211
- data/test/manpage_test.rb +0 -660
- data/test/options_test.rb +0 -262
- data/test/paragraphs_test.rb +0 -562
- data/test/parser_test.rb +0 -742
- data/test/paths_test.rb +0 -395
- data/test/preamble_test.rb +0 -173
- data/test/reader_test.rb +0 -2161
- data/test/sections_test.rb +0 -3575
- data/test/substitutions_test.rb +0 -2066
- data/test/tables_test.rb +0 -2036
- data/test/test_helper.rb +0 -447
- data/test/text_test.rb +0 -309
@@ -1,521 +0,0 @@
|
|
1
|
-
AsciiDoc Home Page
|
2
|
-
==================
|
3
|
-
// Web page meta data.
|
4
|
-
:keywords: AsciiDoc, DocBook, EPUB, PDF, ebooks, slideshow, slidy, man page
|
5
|
-
:description: AsciiDoc is a text document format for writing notes, +
|
6
|
-
documentation, articles, books, ebooks, slideshows, +
|
7
|
-
web pages, man pages and blogs. AsciiDoc files can be +
|
8
|
-
translated to many formats including HTML, PDF, EPUB, +
|
9
|
-
man page.
|
10
|
-
|
11
|
-
|
12
|
-
.{revdate}: AsciiDoc {revnumber} Released
|
13
|
-
************************************************************************
|
14
|
-
Read the link:CHANGELOG.html[CHANGELOG] for release highlights and a
|
15
|
-
full list of all additions, changes and bug fixes. Changes are
|
16
|
-
documented in the updated link:userguide.html[User Guide]. See the
|
17
|
-
link:INSTALL.html[Installation page] for downloads and and
|
18
|
-
installation instructions.
|
19
|
-
|
20
|
-
'Stuart Rackham'
|
21
|
-
************************************************************************
|
22
|
-
|
23
|
-
Introduction
|
24
|
-
------------
|
25
|
-
{description}
|
26
|
-
|
27
|
-
AsciiDoc is highly configurable: both the AsciiDoc source file syntax
|
28
|
-
and the backend output markups (which can be almost any type of
|
29
|
-
SGML/XML markup) can be customized and extended by the user.
|
30
|
-
|
31
|
-
AsciiDoc is free software and is licenced under the terms of the 'GNU
|
32
|
-
General Public License version 2' (GPLv2).
|
33
|
-
|
34
|
-
TIP: The pages you are reading were written using AsciiDoc, to view
|
35
|
-
the corresponding AsciiDoc source click on the *Page Source* menu item
|
36
|
-
in the left hand margin.
|
37
|
-
|
38
|
-
|
39
|
-
Overview and Examples
|
40
|
-
---------------------
|
41
|
-
You write an AsciiDoc document the same way you would write a
|
42
|
-
normal text document, there are no markup tags or weird format
|
43
|
-
notations. AsciiDoc files are designed to be viewed, edited and
|
44
|
-
printed directly or translated to other presentation formats using
|
45
|
-
the asciidoc(1) command.
|
46
|
-
|
47
|
-
The asciidoc(1) command translates AsciiDoc files to HTML, XHTML and
|
48
|
-
DocBook markups. DocBook can be post-processed to presentation
|
49
|
-
formats such as HTML, PDF, EPUB, DVI, LaTeX, roff, and Postscript
|
50
|
-
using readily available Open Source tools.
|
51
|
-
|
52
|
-
Example Articles
|
53
|
-
~~~~~~~~~~~~~~~~
|
54
|
-
- This XHTML version of the
|
55
|
-
link:asciidoc.css-embedded.html[AsciiDoc User Guide]
|
56
|
-
was generated by AsciiDoc from
|
57
|
-
link:asciidoc.txt[this AsciiDoc file].
|
58
|
-
|
59
|
-
- Here's the link:asciidoc.html[same document] created by first
|
60
|
-
generating DocBook markup using AsciiDoc and then converting the
|
61
|
-
DocBook markup to HTML using 'DocBook XSL Stylesheets'.
|
62
|
-
|
63
|
-
- The User Guide again, this time a
|
64
|
-
link:chunked/index.html[chunked version].
|
65
|
-
|
66
|
-
- AsciiDoc generated this link:article-standalone.html[stand-alone
|
67
|
-
HTML file] containing embedded CSS, JavaScript and images from this
|
68
|
-
link:article.txt[AsciiDoc article template] with this command:
|
69
|
-
|
70
|
-
asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt
|
71
|
-
|
72
|
-
- The same link:article.txt[AsciiDoc article template] generated
|
73
|
-
link:article-html5-toc2.html[this HTML 5] (the 'toc2' attribute puts
|
74
|
-
a table of contents in the left margin) from this command:
|
75
|
-
|
76
|
-
asciidoc -b html5 -a icons -a toc2 -a theme=flask article.txt
|
77
|
-
|
78
|
-
- The same link:article.txt[AsciiDoc article template] produced
|
79
|
-
this link:article.html[HTML file] and this
|
80
|
-
link:article.pdf[PDF file] via DocBook markup generated by AsciiDoc.
|
81
|
-
|
82
|
-
[[X7]]
|
83
|
-
Example Books
|
84
|
-
~~~~~~~~~~~~~
|
85
|
-
AsciiDoc markup supports all the standard DocBook frontmatter and
|
86
|
-
backmatter sections (dedication, preface, bibliography, glossary,
|
87
|
-
index, colophon) plus footnotes and index entries.
|
88
|
-
|
89
|
-
- This link:book.txt[AsciiDoc book] produced link:book.html[this HTML
|
90
|
-
file] using the 'DocBook XSL Stylesheets'.
|
91
|
-
- The link:asciidoc.pdf[PDF formatted AsciiDoc User Guide] was
|
92
|
-
generated from asciidoc(1) DocBook output.
|
93
|
-
- The link:asciidoc.epub[EPUB formatted AsciiDoc User Guide] was
|
94
|
-
generated using link:a2x.1.html[a2x].
|
95
|
-
- This link:book.epub[EPUB formatted book skeleton] was generated
|
96
|
-
using link:a2x.1.html[a2x].
|
97
|
-
- This link:book-multi.txt[multi-part AsciiDoc book] produced
|
98
|
-
link:book-multi.html[this HTML file] using the 'DocBook XSL
|
99
|
-
Stylesheets'.
|
100
|
-
|
101
|
-
Example UNIX Man Pages
|
102
|
-
~~~~~~~~~~~~~~~~~~~~~~
|
103
|
-
HTML formatted AsciiDoc man pages
|
104
|
-
link:asciidoc.1.css-embedded.html[with stylesheets] and
|
105
|
-
link:asciidoc.1.html[without stylesheets] were generated by AsciiDoc
|
106
|
-
from link:asciidoc.1.txt[this file].
|
107
|
-
|
108
|
-
This link:asciidoc.1[roff formatted man page] was generated from
|
109
|
-
asciidoc(1) DocBook output using `xsltproc(1)` and DocBook XSL
|
110
|
-
Stylesheets.
|
111
|
-
|
112
|
-
[[X8]]
|
113
|
-
Example Slideshows
|
114
|
-
~~~~~~~~~~~~~~~~~~
|
115
|
-
The http://www.w3.org/Talks/Tools/Slidy2/[Slidy] backend generates
|
116
|
-
HTML slideshows that can be viewed in any web browser. What's nice is
|
117
|
-
that you can create completely self contained slideshows including
|
118
|
-
embedded images.
|
119
|
-
|
120
|
-
- Here is the link:slidy.html[slidy backend documentation] slideshow
|
121
|
-
and here is it's link:slidy.txt[AsciiDoc source].
|
122
|
-
- An link:slidy-example.html[example slidy slideshow] and the
|
123
|
-
link:slidy-example.txt[AsciiDoc source].
|
124
|
-
|
125
|
-
Example Web Site
|
126
|
-
~~~~~~~~~~~~~~~~
|
127
|
-
The link:README-website.html[AsciiDoc website] is included in the
|
128
|
-
AsciiDoc distribution (in `./examples/website/`) as an example website
|
129
|
-
built using AsciiDoc. See `./examples/website/README-website.txt`.
|
130
|
-
|
131
|
-
More examples
|
132
|
-
~~~~~~~~~~~~~
|
133
|
-
- See below: <<X6,'Documents written using AsciiDoc'>>.
|
134
|
-
- Example link:newtables.html[Tables].
|
135
|
-
|
136
|
-
|
137
|
-
eBook Publication
|
138
|
-
-----------------
|
139
|
-
The two most popular open eBook formats are
|
140
|
-
http://en.wikipedia.org/wiki/EPUB[EPUB] and PDF.
|
141
|
-
The AsciiDoc link:a2x.1.html[a2x] toolchain wrapper makes it easy to
|
142
|
-
link:publishing-ebooks-with-asciidoc.html[publish EPUB and PDF eBooks
|
143
|
-
with AsciiDoc]. See also <<X7,example books>> and
|
144
|
-
link:epub-notes.html[AsciiDoc EPUB Notes]).
|
145
|
-
|
146
|
-
|
147
|
-
Blogpost weblog client
|
148
|
-
----------------------
|
149
|
-
http://srackham.wordpress.com/blogpost-readme/[blogpost] is a
|
150
|
-
command-line weblog client for publishing AsciiDoc documents to
|
151
|
-
http://wordpress.org/[WordPress] blog hosts. It creates and updates
|
152
|
-
weblog posts and pages directly from AsciiDoc source documents.
|
153
|
-
|
154
|
-
|
155
|
-
Source code highlighter
|
156
|
-
-----------------------
|
157
|
-
AsciiDoc includes a link:source-highlight-filter.html[source code
|
158
|
-
highlighter filter] that uses
|
159
|
-
http://www.gnu.org/software/src-highlite/[GNU source-highlight] to
|
160
|
-
highlight HTML outputs. You also have the option of using the
|
161
|
-
http://pygments.org/[Pygments] highlighter.
|
162
|
-
|
163
|
-
|
164
|
-
[[X3]]
|
165
|
-
Mathematical Formulae
|
166
|
-
---------------------
|
167
|
-
You can include mathematical formulae in AsciiDoc XHTML documents using
|
168
|
-
link:asciimathml.html[ASCIIMathML] or link:latexmathml.html[LaTeXMathML]
|
169
|
-
notation.
|
170
|
-
|
171
|
-
The link:latex-filter.html[AsciiDoc LaTeX filter] translates LaTeX
|
172
|
-
source to an image that is automatically inserted into the AsciiDoc
|
173
|
-
output documents.
|
174
|
-
|
175
|
-
AsciiDoc also has 'latexmath' macros for DocBook outputs -- they are
|
176
|
-
documented in link:latexmath.pdf[this PDF file] and can be used in
|
177
|
-
AsciiDoc documents processed by `dblatex(1)`.
|
178
|
-
|
179
|
-
|
180
|
-
Editor Support
|
181
|
-
--------------
|
182
|
-
- An AsciiDoc syntax highlighter for the Vim text editor is included in the
|
183
|
-
AsciiDoc distribution (see the 'Vim Syntax Highlighter' appendix in
|
184
|
-
the 'AsciiDoc User Guide' for details).
|
185
|
-
+
|
186
|
-
.Syntax highlighter screenshot
|
187
|
-
image::images/highlighter.png[height=400,caption="",link="images/highlighter.png"]
|
188
|
-
|
189
|
-
- Dag Wieers has implemented an alternative Vim syntax file for
|
190
|
-
AsciiDoc which can be found here
|
191
|
-
http://svn.rpmforge.net/svn/trunk/tools/asciidoc-vim/.
|
192
|
-
- David Avsajanishvili has written a source highlighter for AsciiDoc
|
193
|
-
files for http://projects.gnome.org/gtksourceview/[GtkSourceView]
|
194
|
-
(used by http://projects.gnome.org/gedit/[gedit] and a number of
|
195
|
-
other applications). The project is hosted here:
|
196
|
-
https://launchpad.net/asciidoc-gtk-highlight
|
197
|
-
- AsciiDoc resources for the Emacs editor can be found on the
|
198
|
-
http://www.emacswiki.org/emacs/AsciiDoc[AsciiDoc page] at the
|
199
|
-
http://www.emacswiki.org/emacs/EmacsWiki[Emacs Wiki].
|
200
|
-
- Christian Zuckschwerdt has written a
|
201
|
-
https://github.com/zuckschwerdt/asciidoc.tmbundle[TextMate bundle]
|
202
|
-
for AsciiDoc.
|
203
|
-
|
204
|
-
|
205
|
-
Try AsciiDoc on the Web
|
206
|
-
-----------------------
|
207
|
-
Andrew Koster has written a Web based application to interactively
|
208
|
-
convert and display AsciiDoc source:
|
209
|
-
http://andrewk.webfactional.com/asciidoc.php
|
210
|
-
|
211
|
-
|
212
|
-
[[X2]]
|
213
|
-
External Resources and Applications
|
214
|
-
-----------------------------------
|
215
|
-
Here are resources that I know of, if you know of more drop me a line
|
216
|
-
and I'll add them to the list.
|
217
|
-
|
218
|
-
- Check the link:INSTALL.html#X2[installation page] for packaged versions
|
219
|
-
of AsciiDoc.
|
220
|
-
- Alex Efros has written an HTML formatted
|
221
|
-
http://powerman.name/doc/asciidoc[AsciiDoc Cheatsheet] using
|
222
|
-
Asciidoc.
|
223
|
-
- Thomas Berker has written an
|
224
|
-
http://liksom.info/blog/?q=node/114[AsciiDoc Cheatsheet] in Open
|
225
|
-
Document and PDF formats.
|
226
|
-
- The http://www.wikimatrix.org/[WikiMatrix] website has an excellent
|
227
|
-
http://www.wikimatrix.org/syntax.php[web page] that compares the
|
228
|
-
various Wiki markup syntaxes. An interesting attempt at Wiki markup
|
229
|
-
standardization is http://www.wikicreole.org/[CREOLE].
|
230
|
-
- Franck Pommereau has written
|
231
|
-
http://www.univ-paris12.fr/lacl/pommereau/soft/asciidoctest.html[Asciidoctest],
|
232
|
-
a program that doctests snippets of Python code within your Asciidoc
|
233
|
-
documents.
|
234
|
-
- The http://remips.sourceforge.net/[ReMIPS] project website has been
|
235
|
-
built using AsciiDoc.
|
236
|
-
- Here are some link:asciidoc-docbook-xsl.html[DocBook XSL Stylesheets
|
237
|
-
Notes].
|
238
|
-
- Karl Mowatt-Wilson has developed an http://ikiwiki.info/[ikiwiki]
|
239
|
-
plugin for AsciiDoc which he uses to render
|
240
|
-
http://mowson.org/karl[his website]. The plugin is available
|
241
|
-
http://www.mowson.org/karl/colophon/[here] and there is some
|
242
|
-
discussion of the ikiwiki integration
|
243
|
-
http://ikiwiki.info/users/KarlMW/discussion/[here].
|
244
|
-
- Glenn Eychaner has
|
245
|
-
http://groups.google.com/group/asciidoc/browse_thread/thread/bf04b55628efe214[reworked
|
246
|
-
the Asciidoc plugin for ikiwiki] that was created by Karl Mowson,
|
247
|
-
the source can be downloaded from
|
248
|
-
http://dl.dropbox.com/u/11256359/asciidoc.pm
|
249
|
-
- David Hajage has written an AsciiDoc package for the
|
250
|
-
http://www.r-project.org/[R Project] (R is a free software
|
251
|
-
environment for statistical computing). 'ascii' is available on
|
252
|
-
'CRAN' (just run `install.packages("ascii")` from R). Briefly,
|
253
|
-
'ascii' replaces R results in AsciiDoc document with AsciiDoc
|
254
|
-
markup. More information and examples here:
|
255
|
-
http://eusebe.github.com/ascii/.
|
256
|
-
- Pascal Rapaz has written a Python script to automate AsciiDoc
|
257
|
-
website generation. You can find it at
|
258
|
-
http://www.rapazp.ch/opensource/tools/asciidoc.html.
|
259
|
-
- Jared Henley has written
|
260
|
-
http://jared.henley.id.au/software/awb/documentation.html[AsciiDoc
|
261
|
-
Website Builder]. 'AsciiDoc Website Builder' (awb) is a python
|
262
|
-
program that automates the building of of a website written in
|
263
|
-
AsciiDoc. All you need to write is the AsciiDoc source plus a few
|
264
|
-
simple configuration files.
|
265
|
-
- Brad Adkins has written
|
266
|
-
http://dbixjcl.org/jcl/asciidocgen/asciidocgen.html[AsciiDocGen], a
|
267
|
-
web site generation and deployment tool that allows you write your
|
268
|
-
web site content in AsciiDoc. The
|
269
|
-
http://dbixjcl.org/jcl/asciidocgen/asciidocgen.html[AsciiDocGen web
|
270
|
-
site] is managed using 'AsciiDocGen'.
|
271
|
-
- Filippo Negroni has developed a set of tools to facilitate 'literate
|
272
|
-
programming' using AsciiDoc. The set of tools is called
|
273
|
-
http://eweb.sourceforge.net/[eWEB].
|
274
|
-
- http://vanderwijk.info/2009/4/23/full-text-based-document-generation-using-asciidoc-and-ditaa[Ivo's
|
275
|
-
blog] describes a http://ditaa.sourceforge.net/[ditaa] filter for
|
276
|
-
AsciiDoc which converts http://en.wikipedia.org/wiki/ASCII_art[ASCII
|
277
|
-
art] into graphics.
|
278
|
-
- http://github.com/github/gollum[Gollum] is a git-powered wiki, it
|
279
|
-
supports various formats, including AsciiDoc.
|
280
|
-
- Gregory Romé has written an
|
281
|
-
http://github.com/gpr/redmine_asciidoc_formatter[AsciiDoc plugin]
|
282
|
-
for the http://www.redmine.org/[Redmine] project management
|
283
|
-
application.
|
284
|
-
- Paul Hsu has started a
|
285
|
-
http://github.com/paulhsu/AsciiDoc.CHT.userguide[Chinese translation
|
286
|
-
of the AsciiDoc User Guide].
|
287
|
-
- Dag Wieers has written
|
288
|
-
http://dag.wieers.com/home-made/unoconv/[UNOCONV]. 'UNOCONV' can
|
289
|
-
export AsciiDoc outputs to OpenOffice export formats.
|
290
|
-
- Ed Keith has written http://codeextactor.berlios.de/[Code
|
291
|
-
Extractor], it extracts code snippets from source code files and
|
292
|
-
inserts them into AsciiDoc documents.
|
293
|
-
- The http://csrp.iut-blagnac.fr/jmiwebsite/home/[JMI website] hosts
|
294
|
-
a number of extras for AsciiDoc and Slidy written by Jean-Michel
|
295
|
-
Inglebert.
|
296
|
-
- Ryan Tomayko has written an number of
|
297
|
-
http://tomayko.com/src/adoc-themes/[themes for AsciiDoc] along with
|
298
|
-
a http://tomayko.com/src/adoc-themes/hacking.html[script for
|
299
|
-
combining the CSS files] into single CSS theme files for AsciiDoc
|
300
|
-
embedded CSS documents.
|
301
|
-
- Ilya Portnov has written a
|
302
|
-
https://gitorious.org/doc-building-system[document building system
|
303
|
-
for AsciiDoc], here is
|
304
|
-
http://iportnov.blogspot.com/2011/03/asciidoc-beamer.html[short
|
305
|
-
article in Russian] describing it.
|
306
|
-
- Lex Trotman has written
|
307
|
-
https://github.com/elextr/codiicsa[codiicsa], a program that
|
308
|
-
converts DocBook to AsciiDoc.
|
309
|
-
- Qingping Hou has written http://houqp.github.com/asciidoc-deckjs/[an
|
310
|
-
AsciiDoc backend for deck.js].
|
311
|
-
http://imakewebthings.github.com/deck.js/[deck.js] is a JavaScript
|
312
|
-
library for building modern HTML presentations (slideshows).
|
313
|
-
- The guys from O'Reilly Media have posted an
|
314
|
-
https://github.com/oreillymedia/docbook2asciidoc[XSL Stylesheet to
|
315
|
-
github] that converts DocBook to AsciiDoc.
|
316
|
-
- Lex Trotman has written
|
317
|
-
https://github.com/elextr/flexndex[flexndex], an index generator
|
318
|
-
tool that be used with AsciiDoc.
|
319
|
-
- Michael Haberler has created a
|
320
|
-
https://code.google.com/p/asciidoc-diag-filter/[blockdiag filter for
|
321
|
-
Asciidoc] which embeds http://blockdiag.com/[blockdiag] images in
|
322
|
-
AsciiDoc documents.
|
323
|
-
- Dan Allen has written a
|
324
|
-
https://github.com/mojavelinux/asciidoc-bootstrap-docs-backend[Bootstrap
|
325
|
-
backend] for AsciiDoc.
|
326
|
-
- Steven Boscarine has written
|
327
|
-
https://github.com/StevenBoscarine/JavaAsciidocWrapper[Maven wrapper for AsciiDoc].
|
328
|
-
- Christian Goltz has written
|
329
|
-
https://github.com/christiangoltz/shaape[Shaape], an Ascii art to
|
330
|
-
image converter for AsciiDoc.
|
331
|
-
- Eduardo Santana has written an
|
332
|
-
https://github.com/edusantana/asciidoc-highlight[Asciidoc Highlight
|
333
|
-
for Notepad++].
|
334
|
-
- http://www.geany.org/[Geany] 1.23 adds document structure support
|
335
|
-
for AsciiDoc.
|
336
|
-
|
337
|
-
Please let me know if any of these links need updating.
|
338
|
-
|
339
|
-
|
340
|
-
[[X6]]
|
341
|
-
Documents written using AsciiDoc
|
342
|
-
--------------------------------
|
343
|
-
Here are some documents I know of, if you know of more drop me a line
|
344
|
-
and I'll add them to the list.
|
345
|
-
|
346
|
-
- The book http://practicalunittesting.com/[Practical Unit Testing] by
|
347
|
-
Tomek Kaczanowski was
|
348
|
-
https://groups.google.com/group/asciidoc/browse_frm/thread/4ba13926262efa23[written
|
349
|
-
using Asciidoc].
|
350
|
-
|
351
|
-
- The book http://oreilly.com/catalog/9781449397296[Programming iOS 4]
|
352
|
-
by Matt Neuburg was written using AsciiDoc. Matt has
|
353
|
-
http://www.apeth.net/matt/iosbooktoolchain.html[written an article]
|
354
|
-
describing how he used AsciiDoc and other tools to write the book.
|
355
|
-
|
356
|
-
- The book
|
357
|
-
http://oreilly.com/catalog/9780596155957/index.html[Programming
|
358
|
-
Scala] by Dean Wampler and Alex Payne (O'Reilly) was
|
359
|
-
http://groups.google.com/group/asciidoc/browse_frm/thread/449f1199343f0e27[written
|
360
|
-
using Asciidoc].
|
361
|
-
|
362
|
-
- The http://www.ncfaculty.net/dogle/fishR/index.html[fishR] website
|
363
|
-
has a number of
|
364
|
-
http://www.ncfaculty.net/dogle/fishR/bookex/AIFFD/AIFFD.html[book
|
365
|
-
examples] written using AsciiDoc.
|
366
|
-
|
367
|
-
- The Neo4j graph database project uses Asciidoc, and the output is
|
368
|
-
published here: http://docs.neo4j.org/. The build process includes
|
369
|
-
live tested source code snippets and is described
|
370
|
-
http://groups.google.com/group/asciidoc/browse_thread/thread/49d570062fd3ff52[here].
|
371
|
-
|
372
|
-
- http://frugalware.org/[Frugalware Linux] uses AsciiDoc for
|
373
|
-
http://frugalware.org/docs[documentation].
|
374
|
-
- http://www.cherokee-project.com/doc/[Cherokee documentation].
|
375
|
-
|
376
|
-
- Henrik Maier produced this professional User manual using AsciiDoc:
|
377
|
-
http://www.proconx.com/assets/files/products/modg100/UMMBRG300-1101.pdf
|
378
|
-
|
379
|
-
- Henrik also produced this folded single page brochure format
|
380
|
-
example:
|
381
|
-
http://www.proconx.com/assets/files/products/modg100/IGMBRG300-1101-up.pdf
|
382
|
-
+
|
383
|
-
See this
|
384
|
-
http://groups.google.com/group/asciidoc/browse_thread/thread/16ab5a06864b934f[AsciiDoc
|
385
|
-
discussion group thread] for details.
|
386
|
-
|
387
|
-
- The
|
388
|
-
http://www.kernel.org/pub/software/scm/git/docs/user-manual.html[Git
|
389
|
-
User's Manual].
|
390
|
-
- 'Git Magic' +
|
391
|
-
http://www-cs-students.stanford.edu/~blynn/gitmagic/ +
|
392
|
-
http://github.com/blynn/gitmagic/tree/1e5780f658962f8f9b01638059b27275cfda095c
|
393
|
-
- 'CouchDB: The Definitive Guide' +
|
394
|
-
http://books.couchdb.org/relax/ +
|
395
|
-
http://groups.google.com/group/asciidoc/browse_thread/thread/a60f67cbbaf862aa/d214bf7fa2d538c4?lnk=gst&q=book#d214bf7fa2d538c4
|
396
|
-
- 'Ramaze Manual' +
|
397
|
-
http://book.ramaze.net/ +
|
398
|
-
http://github.com/manveru/ramaze-book/tree/master
|
399
|
-
- Some documentation about git by Nico Schottelius (in German)
|
400
|
-
http://nico.schotteli.us/papers/linux/git-firmen/.
|
401
|
-
- The http://www.netpromi.com/kirbybase_ruby.html[KirbyBase for Ruby]
|
402
|
-
database management system manual.
|
403
|
-
- The http://xpt.sourceforge.net/[*Nix Power Tools project] uses
|
404
|
-
AsciiDoc for documentation.
|
405
|
-
- The http://www.wesnoth.org/[Battle for Wesnoth] project uses
|
406
|
-
AsciiDoc for its http://www.wesnoth.org/wiki/WesnothManual[Manual]
|
407
|
-
in a number of different languages.
|
408
|
-
- Troy Hanson uses AsciiDoc to generate user guides for the
|
409
|
-
http://tpl.sourceforge.net/[tpl] and
|
410
|
-
http://uthash.sourceforge.net/[uthash] projects (the HTML versions
|
411
|
-
have a customised contents sidebar).
|
412
|
-
- http://volnitsky.com/[Leonid Volnitsky's site] is generated using
|
413
|
-
AsciiDoc and includes Leonid's matplotlib filter.
|
414
|
-
- http://www.weechat.org/[WeeChat] uses AsciiDoc for
|
415
|
-
http://www.weechat.org/doc[project documentation].
|
416
|
-
- http://www.clansuite.com/[Clansuite] uses AsciiDoc for
|
417
|
-
http://www.clansuite.com/documentation/[project documentation].
|
418
|
-
- The http://fc-solve.berlios.de/[Freecell Solver program] uses
|
419
|
-
AsciiDoc for its
|
420
|
-
http://fc-solve.berlios.de/docs/#distributed-docs[distributed
|
421
|
-
documentation].
|
422
|
-
- Eric Raymond's http://gpsd.berlios.de/AIVDM.html[AIVDM/AIVDO
|
423
|
-
protocol decoding] documentation is written using AsciiDoc.
|
424
|
-
- Dwight Schauer has written an http://lxc.teegra.net/[LXC HOWTO] in
|
425
|
-
AsciiDoc.
|
426
|
-
- The http://www.rowetel.com/ucasterisk/[Free Telephony Project]
|
427
|
-
website is generated using AsciiDoc.
|
428
|
-
- Warren Block has http://www.wonkity.com/~wblock/docs/[posted a
|
429
|
-
number of articles written using AsciiDoc].
|
430
|
-
- The http://code.google.com/p/waf/[Waf project's] 'Waf Book' is
|
431
|
-
written using AsciiDoc, there is an
|
432
|
-
http://waf.googlecode.com/svn/docs/wafbook/single.html[HTML] and a
|
433
|
-
http://waf.googlecode.com/svn/docs/wafbook/waf.pdf[PDF] version.
|
434
|
-
- The http://www.diffkit.org/[DiffKit] project's documentation and
|
435
|
-
website have been written using Asciidoc.
|
436
|
-
- The http://www.networkupstools.org[Network UPS Tools] project
|
437
|
-
http://www.networkupstools.org/documentation.html[documentation] is
|
438
|
-
an example of a large documentation project written using AsciiDoc.
|
439
|
-
- http://www.archlinux.org/pacman/[Pacman], the
|
440
|
-
http://www.archlinux.org/[Arch Linux] package manager, has been
|
441
|
-
documented using AsciiDoc.
|
442
|
-
- Suraj Kurapati has written a number of customized manuals for his
|
443
|
-
Open Source projects using AsciiDoc:
|
444
|
-
|
445
|
-
* http://snk.tuxfamily.org/lib/detest/
|
446
|
-
* http://snk.tuxfamily.org/lib/ember/
|
447
|
-
* http://snk.tuxfamily.org/lib/inochi/
|
448
|
-
* http://snk.tuxfamily.org/lib/rumai/
|
449
|
-
|
450
|
-
- The http://cxxtest.com/[CxxTest] project (unit testing for C++
|
451
|
-
language) has written its User Guide using AsciiDoc.
|
452
|
-
|
453
|
-
Please let me know if any of these links need updating.
|
454
|
-
|
455
|
-
|
456
|
-
DocBook 5.0 Backend
|
457
|
-
-------------------
|
458
|
-
Shlomi Fish has begun work on a DocBook 5.0 `docbook50.conf` backend
|
459
|
-
configuration file, you can find it
|
460
|
-
http://bitbucket.org/shlomif/asciidoc[here]. See also:
|
461
|
-
http://groups.google.com/group/asciidoc/browse_thread/thread/4386c7cc053d51a9
|
462
|
-
|
463
|
-
|
464
|
-
[[X1]]
|
465
|
-
LaTeX Backend
|
466
|
-
-------------
|
467
|
-
An experimental LaTeX backend was written for AsciiDoc in 2006 by
|
468
|
-
Benjamin Klum. Benjamin did a superhuman job (I admit it, I didn't
|
469
|
-
think this was doable due to AsciiDoc's SGML/XML bias). Owning to to
|
470
|
-
other commitments, Benjamin was unable to maintain this backend.
|
471
|
-
Here's link:latex-backend.html[Benjamin's original documentation].
|
472
|
-
Incompatibilities introduced after AsciiDoc 8.2.7 broke the LaTeX
|
473
|
-
backend.
|
474
|
-
|
475
|
-
In 2009 Geoff Eddy stepped up and updated the LaTeX backend, thanks to
|
476
|
-
Geoff's efforts it now works with AsciiDoc 8.4.3. Geoff's updated
|
477
|
-
`latex.conf` file shipped with AsciiDoc version 8.4.4. The backend
|
478
|
-
still has limitations and remains experimental (see
|
479
|
-
link:latex-bugs.html[Geoff's notes]).
|
480
|
-
|
481
|
-
It's probably also worth pointing out that LaTeX output can be
|
482
|
-
generated by passing AsciiDoc generated DocBook through `dblatex(1)`.
|
483
|
-
|
484
|
-
|
485
|
-
Patches and bug reports
|
486
|
-
-----------------------
|
487
|
-
Patches and bug reports are are encouraged, but please try to follow
|
488
|
-
these guidelines:
|
489
|
-
|
490
|
-
- Post bug reports and patches to the
|
491
|
-
http://groups.google.com/group/asciidoc[asciidoc discussion list],
|
492
|
-
this keeps things transparent and gives everyone a chance to
|
493
|
-
comment.
|
494
|
-
- The email subject line should be a specific and concise topic
|
495
|
-
summary. Commonly accepted subject line prefixes such as '[ANN]',
|
496
|
-
'[PATCH]' and '[SOLVED]' are good.
|
497
|
-
|
498
|
-
=== Bug reports
|
499
|
-
- When reporting problems please illustrate the problem with the
|
500
|
-
smallest possible example that replicates the issue (and please test
|
501
|
-
your example before posting). This technique will also help to
|
502
|
-
eliminate red herrings prior to posting.
|
503
|
-
- Paste the commands that you executed along with any relevant
|
504
|
-
outputs.
|
505
|
-
- Include the version of AsciiDoc and the platform you're running it
|
506
|
-
on.
|
507
|
-
- If you can program please consider writing a patch to fix the
|
508
|
-
problem.
|
509
|
-
|
510
|
-
=== Patches
|
511
|
-
- Keep patches small and atomic (one issue per patch) -- no patch
|
512
|
-
bombs.
|
513
|
-
- If possible test your patch against the current trunk.
|
514
|
-
- If your patch adds or modifies functionality include a short example
|
515
|
-
that illustrates the changes.
|
516
|
-
- Send patches in `diff -u` format, inline inside the mail message is
|
517
|
-
usually best; if it is a very long patch then send it as an
|
518
|
-
attachment.
|
519
|
-
- Include documentation updates if you're up to it; otherwise insert
|
520
|
-
'TODO' comments at relevant places in the documentation.
|
521
|
-
|