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.
Files changed (158) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.adoc +162 -17
  3. data/LICENSE +1 -1
  4. data/README-de.adoc +12 -13
  5. data/README-fr.adoc +11 -12
  6. data/README-jp.adoc +11 -12
  7. data/README-zh_CN.adoc +12 -13
  8. data/README.adoc +6 -7
  9. data/asciidoctor.gemspec +19 -24
  10. data/bin/asciidoctor +5 -4
  11. data/data/reference/syntax.adoc +283 -0
  12. data/data/stylesheets/asciidoctor-default.css +56 -52
  13. data/data/stylesheets/coderay-asciidoctor.css +7 -9
  14. data/lib/asciidoctor.rb +171 -232
  15. data/lib/asciidoctor/abstract_block.rb +96 -105
  16. data/lib/asciidoctor/abstract_node.rb +118 -139
  17. data/lib/asciidoctor/attribute_list.rb +10 -14
  18. data/lib/asciidoctor/block.rb +20 -19
  19. data/lib/asciidoctor/callouts.rb +4 -2
  20. data/lib/asciidoctor/cli.rb +3 -2
  21. data/lib/asciidoctor/cli/invoker.rb +14 -21
  22. data/lib/asciidoctor/cli/options.rb +64 -54
  23. data/lib/asciidoctor/converter.rb +357 -185
  24. data/lib/asciidoctor/converter/composite.rb +40 -48
  25. data/lib/asciidoctor/converter/docbook5.rb +604 -640
  26. data/lib/asciidoctor/converter/html5.rb +949 -963
  27. data/lib/asciidoctor/converter/manpage.rb +569 -548
  28. data/lib/asciidoctor/converter/template.rb +231 -272
  29. data/lib/asciidoctor/core_ext.rb +5 -18
  30. data/lib/asciidoctor/core_ext/float/truncate.rb +19 -0
  31. data/lib/asciidoctor/core_ext/match_data/names.rb +7 -0
  32. data/lib/asciidoctor/core_ext/nil_or_empty.rb +1 -0
  33. data/lib/asciidoctor/core_ext/regexp/is_match.rb +4 -2
  34. data/lib/asciidoctor/document.rb +399 -377
  35. data/lib/asciidoctor/extensions.rb +72 -140
  36. data/lib/asciidoctor/helpers.rb +122 -83
  37. data/lib/asciidoctor/inline.rb +5 -1
  38. data/lib/asciidoctor/list.rb +13 -11
  39. data/lib/asciidoctor/logging.rb +17 -16
  40. data/lib/asciidoctor/parser.rb +390 -423
  41. data/lib/asciidoctor/path_resolver.rb +10 -5
  42. data/lib/asciidoctor/reader.rb +286 -263
  43. data/lib/asciidoctor/rouge_ext.rb +39 -0
  44. data/lib/asciidoctor/section.rb +9 -8
  45. data/lib/asciidoctor/stylesheets.rb +19 -37
  46. data/lib/asciidoctor/substitutors.rb +364 -509
  47. data/lib/asciidoctor/syntax_highlighter.rb +238 -0
  48. data/lib/asciidoctor/syntax_highlighter/coderay.rb +87 -0
  49. data/lib/asciidoctor/syntax_highlighter/highlightjs.rb +26 -0
  50. data/lib/asciidoctor/syntax_highlighter/html_pipeline.rb +10 -0
  51. data/lib/asciidoctor/syntax_highlighter/prettify.rb +27 -0
  52. data/lib/asciidoctor/syntax_highlighter/pygments.rb +149 -0
  53. data/lib/asciidoctor/syntax_highlighter/rouge.rb +129 -0
  54. data/lib/asciidoctor/table.rb +73 -66
  55. data/lib/asciidoctor/timings.rb +4 -2
  56. data/lib/asciidoctor/version.rb +2 -1
  57. data/lib/asciidoctor/writer.rb +30 -0
  58. data/man/asciidoctor.1 +19 -15
  59. data/man/asciidoctor.adoc +14 -12
  60. metadata +69 -216
  61. data/CONTRIBUTING.adoc +0 -185
  62. data/Gemfile +0 -60
  63. data/Rakefile +0 -129
  64. data/bin/asciidoctor-safe +0 -15
  65. data/features/open_block.feature +0 -92
  66. data/features/pass_block.feature +0 -66
  67. data/features/step_definitions.rb +0 -49
  68. data/features/text_formatting.feature +0 -57
  69. data/features/xref.feature +0 -1039
  70. data/lib/asciidoctor/converter/base.rb +0 -59
  71. data/lib/asciidoctor/converter/docbook45.rb +0 -93
  72. data/lib/asciidoctor/converter/factory.rb +0 -226
  73. data/lib/asciidoctor/core_ext/1.8.7/base64/strict_encode64.rb +0 -6
  74. data/lib/asciidoctor/core_ext/1.8.7/concurrent/hash.rb +0 -5
  75. data/lib/asciidoctor/core_ext/1.8.7/hash/key.rb +0 -4
  76. data/lib/asciidoctor/core_ext/1.8.7/io/binread.rb +0 -6
  77. data/lib/asciidoctor/core_ext/1.8.7/io/write.rb +0 -5
  78. data/lib/asciidoctor/core_ext/1.8.7/string/chr.rb +0 -6
  79. data/lib/asciidoctor/core_ext/1.8.7/string/limit_bytesize.rb +0 -29
  80. data/lib/asciidoctor/core_ext/1.8.7/symbol/empty.rb +0 -6
  81. data/lib/asciidoctor/core_ext/1.8.7/symbol/length.rb +0 -6
  82. data/lib/asciidoctor/core_ext/string/limit_bytesize.rb +0 -10
  83. data/test/api_test.rb +0 -1240
  84. data/test/attribute_list_test.rb +0 -242
  85. data/test/attributes_test.rb +0 -1623
  86. data/test/blocks_test.rb +0 -3870
  87. data/test/converter_test.rb +0 -470
  88. data/test/document_test.rb +0 -1853
  89. data/test/extensions_test.rb +0 -1560
  90. data/test/fixtures/asciidoc_index.txt +0 -521
  91. data/test/fixtures/basic-docinfo-footer.html +0 -6
  92. data/test/fixtures/basic-docinfo-footer.xml +0 -8
  93. data/test/fixtures/basic-docinfo.html +0 -1
  94. data/test/fixtures/basic-docinfo.xml +0 -4
  95. data/test/fixtures/basic.asciidoc +0 -5
  96. data/test/fixtures/chapter-a.adoc +0 -3
  97. data/test/fixtures/child-include.adoc +0 -5
  98. data/test/fixtures/circle.svg +0 -9
  99. data/test/fixtures/custom-backends/erb/html5/block_paragraph.html.erb +0 -6
  100. data/test/fixtures/custom-backends/haml/docbook45/block_paragraph.xml.haml +0 -6
  101. data/test/fixtures/custom-backends/haml/html5-tweaks/block_paragraph.html.haml +0 -1
  102. data/test/fixtures/custom-backends/haml/html5/block_paragraph.html.haml +0 -3
  103. data/test/fixtures/custom-backends/haml/html5/block_sidebar.html.haml +0 -5
  104. data/test/fixtures/custom-backends/slim/docbook45/block_paragraph.xml.slim +0 -6
  105. data/test/fixtures/custom-backends/slim/html5/block_paragraph.html.slim +0 -3
  106. data/test/fixtures/custom-backends/slim/html5/block_sidebar.html.slim +0 -5
  107. data/test/fixtures/custom-docinfodir/basic-docinfo.html +0 -1
  108. data/test/fixtures/custom-docinfodir/docinfo.html +0 -1
  109. data/test/fixtures/docinfo-footer.html +0 -1
  110. data/test/fixtures/docinfo-footer.xml +0 -9
  111. data/test/fixtures/docinfo.html +0 -1
  112. data/test/fixtures/docinfo.xml +0 -3
  113. data/test/fixtures/doctime-localtime.adoc +0 -2
  114. data/test/fixtures/dot.gif +0 -0
  115. data/test/fixtures/encoding.asciidoc +0 -13
  116. data/test/fixtures/file-with-missing-include.adoc +0 -1
  117. data/test/fixtures/grandchild-include.adoc +0 -3
  118. data/test/fixtures/hello-asciidoctor.pdf +0 -69
  119. data/test/fixtures/include-file.asciidoc +0 -24
  120. data/test/fixtures/include-file.jsx +0 -8
  121. data/test/fixtures/include-file.ml +0 -3
  122. data/test/fixtures/include-file.xml +0 -5
  123. data/test/fixtures/lists.adoc +0 -96
  124. data/test/fixtures/master.adoc +0 -5
  125. data/test/fixtures/mismatched-end-tag.adoc +0 -7
  126. data/test/fixtures/other-chapters.adoc +0 -11
  127. data/test/fixtures/outer-include.adoc +0 -5
  128. data/test/fixtures/parent-include-restricted.adoc +0 -5
  129. data/test/fixtures/parent-include.adoc +0 -5
  130. data/test/fixtures/sample.asciidoc +0 -30
  131. data/test/fixtures/section-a.adoc +0 -4
  132. data/test/fixtures/stylesheets/custom.css +0 -3
  133. data/test/fixtures/subdir/index.adoc +0 -3
  134. data/test/fixtures/subdir/inner-include.adoc +0 -3
  135. data/test/fixtures/subdir/middle-include.adoc +0 -5
  136. data/test/fixtures/subs-docinfo.html +0 -2
  137. data/test/fixtures/subs.adoc +0 -6
  138. data/test/fixtures/tagged-class-enclosed.rb +0 -25
  139. data/test/fixtures/tagged-class.rb +0 -23
  140. data/test/fixtures/tip.gif +0 -0
  141. data/test/fixtures/unclosed-tag.adoc +0 -3
  142. data/test/fixtures/unexpected-end-tag.adoc +0 -4
  143. data/test/invoker_test.rb +0 -745
  144. data/test/links_test.rb +0 -855
  145. data/test/lists_test.rb +0 -5151
  146. data/test/logger_test.rb +0 -211
  147. data/test/manpage_test.rb +0 -660
  148. data/test/options_test.rb +0 -262
  149. data/test/paragraphs_test.rb +0 -562
  150. data/test/parser_test.rb +0 -742
  151. data/test/paths_test.rb +0 -395
  152. data/test/preamble_test.rb +0 -173
  153. data/test/reader_test.rb +0 -2161
  154. data/test/sections_test.rb +0 -3575
  155. data/test/substitutions_test.rb +0 -2066
  156. data/test/tables_test.rb +0 -2036
  157. data/test/test_helper.rb +0 -447
  158. 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
-