asciidoctor 1.5.5 → 1.5.6

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of asciidoctor might be problematic. Click here for more details.

Files changed (119) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.adoc +216 -1
  3. data/CONTRIBUTING.adoc +2 -2
  4. data/Gemfile +20 -1
  5. data/LICENSE.adoc +1 -1
  6. data/README-fr.adoc +4 -3
  7. data/README-jp.adoc +11 -10
  8. data/README-zh_CN.adoc +4 -3
  9. data/README.adoc +17 -202
  10. data/Rakefile +41 -25
  11. data/asciidoctor.gemspec +9 -10
  12. data/data/locale/attributes.adoc +216 -34
  13. data/data/stylesheets/asciidoctor-default.css +23 -16
  14. data/features/step_definitions.rb +15 -19
  15. data/features/xref.feature +584 -20
  16. data/lib/asciidoctor.rb +292 -278
  17. data/lib/asciidoctor/abstract_block.rb +155 -94
  18. data/lib/asciidoctor/abstract_node.rb +108 -94
  19. data/lib/asciidoctor/attribute_list.rb +30 -22
  20. data/lib/asciidoctor/block.rb +7 -7
  21. data/lib/asciidoctor/cli/invoker.rb +47 -34
  22. data/lib/asciidoctor/cli/options.rb +22 -11
  23. data/lib/asciidoctor/converter.rb +3 -3
  24. data/lib/asciidoctor/converter/base.rb +2 -2
  25. data/lib/asciidoctor/converter/composite.rb +1 -1
  26. data/lib/asciidoctor/converter/docbook45.rb +2 -2
  27. data/lib/asciidoctor/converter/docbook5.rb +132 -87
  28. data/lib/asciidoctor/converter/factory.rb +0 -1
  29. data/lib/asciidoctor/converter/html5.rb +116 -98
  30. data/lib/asciidoctor/converter/manpage.rb +51 -52
  31. data/lib/asciidoctor/converter/template.rb +47 -36
  32. data/lib/asciidoctor/core_ext.rb +8 -2
  33. data/lib/asciidoctor/core_ext/1.8.7/hash/key.rb +4 -0
  34. data/lib/asciidoctor/core_ext/1.8.7/io/binread.rb +6 -0
  35. data/lib/asciidoctor/core_ext/1.8.7/io/write.rb +5 -0
  36. data/lib/asciidoctor/core_ext/1.8.7/string/chr.rb +1 -1
  37. data/lib/asciidoctor/core_ext/1.8.7/string/{limit.rb → limit_bytesize.rb} +7 -6
  38. data/lib/asciidoctor/core_ext/1.8.7/symbol/empty.rb +6 -0
  39. data/lib/asciidoctor/core_ext/1.8.7/symbol/length.rb +1 -1
  40. data/lib/asciidoctor/core_ext/nil_or_empty.rb +5 -5
  41. data/lib/asciidoctor/core_ext/regexp/is_match.rb +3 -0
  42. data/lib/asciidoctor/core_ext/string/{limit.rb → limit_bytesize.rb} +2 -2
  43. data/lib/asciidoctor/document.rb +216 -213
  44. data/lib/asciidoctor/extensions.rb +318 -185
  45. data/lib/asciidoctor/helpers.rb +35 -35
  46. data/lib/asciidoctor/inline.rb +32 -1
  47. data/lib/asciidoctor/list.rb +22 -6
  48. data/lib/asciidoctor/parser.rb +1008 -1038
  49. data/lib/asciidoctor/path_resolver.rb +46 -50
  50. data/lib/asciidoctor/reader.rb +275 -251
  51. data/lib/asciidoctor/section.rb +86 -58
  52. data/lib/asciidoctor/stylesheets.rb +6 -6
  53. data/lib/asciidoctor/substitutors.rb +567 -649
  54. data/lib/asciidoctor/table.rb +163 -108
  55. data/lib/asciidoctor/version.rb +1 -1
  56. data/man/asciidoctor.1 +18 -16
  57. data/man/asciidoctor.adoc +15 -13
  58. data/test/attributes_test.rb +138 -22
  59. data/test/blocks_test.rb +377 -97
  60. data/test/converter_test.rb +13 -0
  61. data/test/document_test.rb +244 -34
  62. data/test/extensions_test.rb +409 -42
  63. data/test/fixtures/asciidoc_index.txt +521 -0
  64. data/test/fixtures/basic-docinfo-footer.html +6 -0
  65. data/test/fixtures/basic-docinfo-footer.xml +8 -0
  66. data/test/fixtures/basic-docinfo.html +1 -0
  67. data/test/fixtures/basic-docinfo.xml +4 -0
  68. data/test/fixtures/basic.asciidoc +5 -0
  69. data/test/fixtures/chapter-a.adoc +3 -0
  70. data/test/fixtures/child-include.adoc +5 -0
  71. data/test/fixtures/circle.svg +9 -0
  72. data/test/fixtures/custom-backends/erb/html5/block_paragraph.html.erb +6 -0
  73. data/test/fixtures/custom-backends/haml/docbook45/block_paragraph.xml.haml +6 -0
  74. data/test/fixtures/custom-backends/haml/html5-tweaks/block_paragraph.html.haml +1 -0
  75. data/test/fixtures/custom-backends/haml/html5/block_paragraph.html.haml +3 -0
  76. data/test/fixtures/custom-backends/haml/html5/block_sidebar.html.haml +5 -0
  77. data/test/fixtures/custom-backends/slim/docbook45/block_paragraph.xml.slim +6 -0
  78. data/test/fixtures/custom-backends/slim/html5/block_paragraph.html.slim +3 -0
  79. data/test/fixtures/custom-backends/slim/html5/block_sidebar.html.slim +5 -0
  80. data/test/fixtures/custom-docinfodir/basic-docinfo.html +1 -0
  81. data/test/fixtures/custom-docinfodir/docinfo.html +1 -0
  82. data/test/fixtures/docinfo-footer.html +1 -0
  83. data/test/fixtures/docinfo-footer.xml +9 -0
  84. data/test/fixtures/docinfo.html +1 -0
  85. data/test/fixtures/docinfo.xml +3 -0
  86. data/test/fixtures/dot.gif +0 -0
  87. data/test/fixtures/encoding.asciidoc +13 -0
  88. data/test/fixtures/grandchild-include.adoc +3 -0
  89. data/test/fixtures/hello-asciidoctor.pdf +69 -0
  90. data/test/fixtures/include-file.asciidoc +24 -0
  91. data/test/fixtures/include-file.ml +3 -0
  92. data/test/fixtures/include-file.xml +5 -0
  93. data/test/fixtures/master.adoc +5 -0
  94. data/test/fixtures/mismatched-end-tag.adoc +7 -0
  95. data/test/fixtures/parent-include-restricted.adoc +5 -0
  96. data/test/fixtures/parent-include.adoc +5 -0
  97. data/test/fixtures/sample.asciidoc +26 -0
  98. data/test/fixtures/stylesheets/custom.css +3 -0
  99. data/test/fixtures/subs-docinfo.html +2 -0
  100. data/test/fixtures/subs.adoc +7 -0
  101. data/test/fixtures/tagged-class-enclosed.rb +26 -0
  102. data/test/fixtures/tagged-class.rb +23 -0
  103. data/test/fixtures/tip.gif +0 -0
  104. data/test/invoker_test.rb +82 -4
  105. data/test/links_test.rb +312 -37
  106. data/test/lists_test.rb +204 -25
  107. data/test/manpage_test.rb +191 -4
  108. data/test/options_test.rb +18 -1
  109. data/test/paragraphs_test.rb +32 -7
  110. data/test/parser_test.rb +150 -30
  111. data/test/paths_test.rb +47 -13
  112. data/test/preamble_test.rb +1 -1
  113. data/test/reader_test.rb +366 -126
  114. data/test/sections_test.rb +203 -56
  115. data/test/substitutions_test.rb +339 -131
  116. data/test/tables_test.rb +315 -15
  117. data/test/test_helper.rb +400 -0
  118. data/test/text_test.rb +5 -5
  119. metadata +110 -22
@@ -0,0 +1,521 @@
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
+