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 a PNG 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 'Appendix F' of the 'AsciiDoc User Guide' for |
---|
184 | 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 | - Florian Kaufman has written 'adoc-mode.el' -- a major-mode for |
---|
198 | editing AsciiDoc files in Emacs, you can find it |
---|
199 | http://code.google.com/p/sensorflo-emacs/[here]. |
---|
200 | - The http://xpt.sourceforge.net/[*Nix Power Tools project] has |
---|
201 | released an http://xpt.sourceforge.net/tools/doc-mode/[AsciiDoc |
---|
202 | syntax highlighter for Emacs]. |
---|
203 | - Terrence Brannon has written |
---|
204 | http://github.com/metaperl/asciidoc-el[AsciiDoc functions for |
---|
205 | Emacs]. |
---|
206 | - Christian Zuckschwerdt has written a |
---|
207 | https://github.com/zuckschwerdt/asciidoc.tmbundle[TextMate bundle] |
---|
208 | for AsciiDoc. |
---|
209 | |
---|
210 | |
---|
211 | Try AsciiDoc on the Web |
---|
212 | ----------------------- |
---|
213 | Andrew Koster has written a Web based application to interactively |
---|
214 | convert and display AsciiDoc source: |
---|
215 | http://andrewk.webfactional.com/asciidoc.php |
---|
216 | |
---|
217 | |
---|
218 | [[X2]] |
---|
219 | External Resources and Applications |
---|
220 | ----------------------------------- |
---|
221 | Here are resources that I know of, if you know of more drop me a line |
---|
222 | and I'll add them to the list. |
---|
223 | |
---|
224 | - Check the link:INSTALL.html#X2[installation page] for packaged versions |
---|
225 | of AsciiDoc. |
---|
226 | - Alex Efros has written an HTML formatted |
---|
227 | http://powerman.name/doc/asciidoc[AsciiDoc Cheatsheet] using |
---|
228 | Asciidoc. |
---|
229 | - Thomas Berker has written an |
---|
230 | http://liksom.info/blog/?q=node/114[AsciiDoc Cheatsheet] in Open |
---|
231 | Document and PDF formats. |
---|
232 | - The http://www.wikimatrix.org/[WikiMatrix] website has an excellent |
---|
233 | http://www.wikimatrix.org/syntax.php[web page] that compares the |
---|
234 | various Wiki markup syntaxes. An interesting attempt at Wiki markup |
---|
235 | standardization is http://www.wikicreole.org/[CREOLE]. |
---|
236 | - Franck Pommereau has written |
---|
237 | http://www.univ-paris12.fr/lacl/pommereau/soft/asciidoctest.html[Asciidoctest], |
---|
238 | a program that doctests snippets of Python code within your Asciidoc |
---|
239 | documents. |
---|
240 | - The http://remips.sourceforge.net/[ReMIPS] project website has been |
---|
241 | built using AsciiDoc. |
---|
242 | - Here are some link:asciidoc-docbook-xsl.html[DocBook XSL Stylesheets |
---|
243 | Notes]. |
---|
244 | - Karl Mowatt-Wilson has developed an http://ikiwiki.info/[ikiwiki] |
---|
245 | plugin for AsciiDoc which he uses to render |
---|
246 | http://mowson.org/karl[his website]. The plugin is available |
---|
247 | http://www.mowson.org/karl/colophon/[here] and there is some |
---|
248 | discussion of the ikiwiki integration |
---|
249 | http://ikiwiki.info/users/KarlMW/discussion/[here]. |
---|
250 | - Glenn Eychaner has |
---|
251 | http://groups.google.com/group/asciidoc/browse_thread/thread/bf04b55628efe214[reworked |
---|
252 | the Asciidoc plugin for ikiwiki] that was created by Karl Mowson, |
---|
253 | the source can be downloaded from |
---|
254 | http://dl.dropbox.com/u/11256359/asciidoc.pm |
---|
255 | - David Hajage has written an AsciiDoc package for the |
---|
256 | http://www.r-project.org/[R Project] (R is a free software |
---|
257 | environment for statistical computing). 'ascii' is available on |
---|
258 | 'CRAN' (just run `install.package("ascii")` from R). Briefly, |
---|
259 | 'ascii' replaces R results in AsciiDoc document with AsciiDoc |
---|
260 | markup. More information and examples here: |
---|
261 | http://eusebe.github.com/ascii/. |
---|
262 | - Pascal Rapaz has written a Python script to automate AsciiDoc |
---|
263 | website generation. You can find it at |
---|
264 | http://www.rapazp.ch/opensource/tools/asciidoc.html. |
---|
265 | - Jared Henley has written |
---|
266 | http://jared.henley.id.au/software/awb/documentation.html[AsciiDoc |
---|
267 | Website Builder]. 'AsciiDoc Website Builder' (awb) is a python |
---|
268 | program that automates the building of of a website written in |
---|
269 | AsciiDoc. All you need to write is the AsciiDoc source plus a few |
---|
270 | simple configuration files. |
---|
271 | - Brad Adkins has written |
---|
272 | http://dbixjcl.org/jcl/asciidocgen/asciidocgen.html[AsciiDocGen], a |
---|
273 | web site generation and deployment tool that allows you write your |
---|
274 | web site content in AsciiDoc. The |
---|
275 | http://dbixjcl.org/jcl/asciidocgen/asciidocgen.html[AsciiDocGen web |
---|
276 | site] is managed using 'AsciiDocGen'. |
---|
277 | - Filippo Negroni has developed a set of tools to facilitate 'literate |
---|
278 | programming' using AsciiDoc. The set of tools is called |
---|
279 | http://eweb.sourceforge.net/[eWEB]. |
---|
280 | - http://vanderwijk.info/2009/4/23/full-text-based-document-generation-using-asciidoc-and-ditaa[Ivo's |
---|
281 | blog] describes a http://ditaa.sourceforge.net/[ditaa] filter for |
---|
282 | AsciiDoc which converts http://en.wikipedia.org/wiki/ASCII_art[ASCII |
---|
283 | art] into graphics. |
---|
284 | - http://github.com/github/gollum[Gollum] is a git-powered wiki, it |
---|
285 | supports various formats, including AsciiDoc. |
---|
286 | - Gregory Romé has written an |
---|
287 | http://github.com/gpr/redmine_asciidoc_formatter[AsciiDoc plugin] |
---|
288 | for the http://www.redmine.org/[Redmine] project management |
---|
289 | application. |
---|
290 | - Paul Hsu has started a |
---|
291 | http://github.com/paulhsu/AsciiDoc.CHT.userguide[Chinese translation |
---|
292 | of the AsciiDoc User Guide]. |
---|
293 | - Dag Wieers has written |
---|
294 | http://dag.wieers.com/home-made/unoconv/[UNOCONV]. 'UNOCONV' can |
---|
295 | export AsciiDoc outputs to OpenOffice export formats. |
---|
296 | - Ed Keith has written http://codeextactor.berlios.de/[Code |
---|
297 | Extractor], it extracts code snippets from source code files and |
---|
298 | inserts them into AsciiDoc documents. |
---|
299 | - The http://csrp.iut-blagnac.fr/jmiwebsite/home/[JMI website] hosts |
---|
300 | a number of extras for AsciiDoc and Slidy written by Jean-Michel |
---|
301 | Inglebert. |
---|
302 | - Ryan Tomayko has written an number of |
---|
303 | http://tomayko.com/src/adoc-themes/[themes for AsciiDoc] along with |
---|
304 | a http://tomayko.com/src/adoc-themes/hacking.html[script for |
---|
305 | combining the CSS files] into single CSS theme files for AsciiDoc |
---|
306 | embedded CSS documents. |
---|
307 | - Ilya Portnov has written a |
---|
308 | https://gitorious.org/doc-building-system[document building system |
---|
309 | for AsciiDoc], here is |
---|
310 | http://iportnov.blogspot.com/2011/03/asciidoc-beamer.html[short |
---|
311 | article in Russian] describing it. |
---|
312 | - Lex Trotman has written |
---|
313 | https://github.com/elextr/codiicsa[codiicsa], a program that |
---|
314 | converts DocBook to AsciiDoc. |
---|
315 | - Qingping Hou has written http://houqp.github.com/asciidoc-deckjs/[an |
---|
316 | AsciiDoc backend for deck.js]. |
---|
317 | http://imakewebthings.github.com/deck.js/[deck.js] is a JavaScript |
---|
318 | library for building modern HTML presentations (slideshows). |
---|
319 | - The guys from O'Reilly Media have posted an |
---|
320 | https://github.com/oreillymedia/docbook2asciidoc[XSL Stylesheet to |
---|
321 | github] that converts DocBook to AsciiDoc. |
---|
322 | - Lex Trotman has written |
---|
323 | https://github.com/elextr/flexndex[flexndex], an index generator |
---|
324 | tool that be used with AsciiDoc. |
---|
325 | |
---|
326 | Please let me know if any of these links need updating. |
---|
327 | |
---|
328 | |
---|
329 | [[X6]] |
---|
330 | Documents written using AsciiDoc |
---|
331 | -------------------------------- |
---|
332 | Here are some documents I know of, if you know of more drop me a line |
---|
333 | and I'll add them to the list. |
---|
334 | |
---|
335 | - The book http://practicalunittesting.com/[Practical Unit Testing] by |
---|
336 | Tomek Kaczanowski was |
---|
337 | https://groups.google.com/group/asciidoc/browse_frm/thread/4ba13926262efa23[written |
---|
338 | using Asciidoc]. |
---|
339 | |
---|
340 | - The book http://oreilly.com/catalog/9781449397296[Programming iOS 4] |
---|
341 | by Matt Neuburg was written using AsciiDoc. Matt has |
---|
342 | http://www.apeth.net/matt/iosbooktoolchain.html[written an article] |
---|
343 | describing how he used AsciiDoc and other tools to write the book. |
---|
344 | |
---|
345 | - The book |
---|
346 | http://oreilly.com/catalog/9780596155957/index.html[Programming |
---|
347 | Scala] by Dean Wampler and Alex Payne (O'Reilly) was |
---|
348 | http://groups.google.com/group/asciidoc/browse_frm/thread/449f1199343f0e27[written |
---|
349 | using Asciidoc]. |
---|
350 | |
---|
351 | - The http://www.ncfaculty.net/dogle/fishR/index.html[fishR] website |
---|
352 | has a number of |
---|
353 | http://www.ncfaculty.net/dogle/fishR/bookex/AIFFD/AIFFD.html[book |
---|
354 | examples] written using AsciiDoc. |
---|
355 | |
---|
356 | - The Neo4j graph database project uses Asciidoc, and the output is |
---|
357 | published here: http://docs.neo4j.org/. The build process includes |
---|
358 | live tested source code snippets and is described |
---|
359 | http://groups.google.com/group/asciidoc/browse_thread/thread/49d570062fd3ff52[here]. |
---|
360 | |
---|
361 | - http://frugalware.org/[Frugalware Linux] uses AsciiDoc for |
---|
362 | http://frugalware.org/docs[documentation]. |
---|
363 | - http://www.cherokee-project.com/doc/[Cherokee documentation]. |
---|
364 | |
---|
365 | - Henrik Maier produced this professional User manual using AsciiDoc: |
---|
366 | http://www.proconx.com/assets/files/products/modg100/UMMBRG300-1101.pdf |
---|
367 | |
---|
368 | - Henrik also produced this folded single page brochure format |
---|
369 | example: |
---|
370 | http://www.proconx.com/assets/files/products/modg100/IGMBRG300-1101-up.pdf |
---|
371 | + |
---|
372 | See this |
---|
373 | http://groups.google.com/group/asciidoc/browse_thread/thread/16ab5a06864b934f[AsciiDoc |
---|
374 | discussion group thread] for details. |
---|
375 | |
---|
376 | - The |
---|
377 | http://www.kernel.org/pub/software/scm/git/docs/user-manual.html[Git |
---|
378 | User's Manual]. |
---|
379 | - 'Git Magic' + |
---|
380 | http://www-cs-students.stanford.edu/~blynn/gitmagic/ + |
---|
381 | http://github.com/blynn/gitmagic/tree/1e5780f658962f8f9b01638059b27275cfda095c |
---|
382 | - 'CouchDB: The Definitive Guide' + |
---|
383 | http://books.couchdb.org/relax/ + |
---|
384 | http://groups.google.com/group/asciidoc/browse_thread/thread/a60f67cbbaf862aa/d214bf7fa2d538c4?lnk=gst&q=book#d214bf7fa2d538c4 |
---|
385 | - 'Ramaze Manual' + |
---|
386 | http://book.ramaze.net/ + |
---|
387 | http://github.com/manveru/ramaze-book/tree/master |
---|
388 | - Some documentation about git by Nico Schottelius (in German) |
---|
389 | http://nico.schotteli.us/papers/linux/git-firmen/. |
---|
390 | - The http://www.netpromi.com/kirbybase_ruby.html[KirbyBase for Ruby] |
---|
391 | database management system manual. |
---|
392 | - The http://xpt.sourceforge.net/[*Nix Power Tools project] uses |
---|
393 | AsciiDoc for documentation. |
---|
394 | - The http://www.wesnoth.org/[Battle for Wesnoth] project uses |
---|
395 | AsciiDoc for its http://www.wesnoth.org/wiki/WesnothManual[Manual] |
---|
396 | in a number of different languages. |
---|
397 | - Troy Hanson uses AsciiDoc to generate user guides for the |
---|
398 | http://tpl.sourceforge.net/[tpl] and |
---|
399 | http://uthash.sourceforge.net/[uthash] projects (the HTML versions |
---|
400 | have a customised contents sidebar). |
---|
401 | - http://volnitsky.com/[Leonid Volnitsky's site] is generated using |
---|
402 | AsciiDoc and includes Leonid's matplotlib filter. |
---|
403 | - http://www.weechat.org/[WeeChat] uses AsciiDoc for |
---|
404 | http://www.weechat.org/doc[project documentation]. |
---|
405 | - http://www.clansuite.com/[Clansuite] uses AsciiDoc for |
---|
406 | http://www.clansuite.com/documentation/[project documentation]. |
---|
407 | - The http://fc-solve.berlios.de/[Freecell Solver program] uses |
---|
408 | AsciiDoc for its |
---|
409 | http://fc-solve.berlios.de/docs/#distributed-docs[distributed |
---|
410 | documentation]. |
---|
411 | - Eric Raymond's http://gpsd.berlios.de/AIVDM.html[AIVDM/AIVDO |
---|
412 | protocol decoding] documentation is written using AsciiDoc. |
---|
413 | - Dwight Schauer has written an http://lxc.teegra.net/[LXC HOWTO] in |
---|
414 | AsciiDoc. |
---|
415 | - The http://www.rowetel.com/ucasterisk/[Free Telephony Project] |
---|
416 | website is generated using AsciiDoc. |
---|
417 | - Warren Block has http://www.wonkity.com/~wblock/docs/[posted a |
---|
418 | number of articles written using AsciiDoc]. |
---|
419 | - The http://code.google.com/p/waf/[Waf project's] 'Waf Book' is |
---|
420 | written using AsciiDoc, there is an |
---|
421 | http://waf.googlecode.com/svn/docs/wafbook/single.html[HTML] and a |
---|
422 | http://waf.googlecode.com/svn/docs/wafbook/waf.pdf[PDF] version. |
---|
423 | - The http://www.diffkit.org/[DiffKit] project's documentation and |
---|
424 | website have been written using Asciidoc. |
---|
425 | - The http://www.networkupstools.org[Network UPS Tools] project |
---|
426 | http://www.networkupstools.org/documentation.html[documentation] is |
---|
427 | an example of a large documentation project written using AsciiDoc. |
---|
428 | - http://www.archlinux.org/pacman/[Pacman], the |
---|
429 | http://www.archlinux.org/[Arch Linux] package manager, has been |
---|
430 | documented using AsciiDoc. |
---|
431 | - Suraj Kurapati has written a number of customized manuals for his |
---|
432 | Open Source projects using AsciiDoc: |
---|
433 | |
---|
434 | * http://snk.tuxfamily.org/lib/detest/ |
---|
435 | * http://snk.tuxfamily.org/lib/ember/ |
---|
436 | * http://snk.tuxfamily.org/lib/inochi/ |
---|
437 | * http://snk.tuxfamily.org/lib/rumai/ |
---|
438 | |
---|
439 | - The http://cxxtest.com/[CxxTest] project (unit testing for C++ |
---|
440 | language) has written its User Guide using AsciiDoc. |
---|
441 | |
---|
442 | Please let me know if any of these links need updating. |
---|
443 | |
---|
444 | |
---|
445 | DocBook 5.0 Backend |
---|
446 | ------------------- |
---|
447 | Shlomi Fish has begun work on a DocBook 5.0 `docbook50.conf` backend |
---|
448 | configuration file, you can find it |
---|
449 | http://bitbucket.org/shlomif/asciidoc[here]. See also: |
---|
450 | http://groups.google.com/group/asciidoc/browse_thread/thread/4386c7cc053d51a9 |
---|
451 | |
---|
452 | |
---|
453 | [[X1]] |
---|
454 | LaTeX Backend |
---|
455 | ------------- |
---|
456 | An experimental LaTeX backend was written for AsciiDoc in 2006 by |
---|
457 | Benjamin Klum. Benjamin did a superhuman job (I admit it, I didn't |
---|
458 | think this was doable due to AsciiDoc's SGML/XML bias). Owning to to |
---|
459 | other commitments, Benjamin was unable to maintain this backend. |
---|
460 | Here's link:latex-backend.html[Benjamin's original documentation]. |
---|
461 | Incompatibilities introduced after AsciiDoc 8.2.7 broke the LaTeX |
---|
462 | backend. |
---|
463 | |
---|
464 | In 2009 Geoff Eddy stepped up and updated the LaTeX backend, thanks to |
---|
465 | Geoff's efforts it now works with AsciiDoc 8.4.3. Geoff's updated |
---|
466 | `latex.conf` file shipped with AsciiDoc version 8.4.4. The backend |
---|
467 | still has limitations and remains experimental (see |
---|
468 | link:latex-bugs.html[Geoff's notes]). |
---|
469 | |
---|
470 | It's probably also worth pointing out that LaTeX output can be |
---|
471 | generated by passing AsciiDoc generated DocBook through `dblatex(1)`. |
---|
472 | |
---|
473 | |
---|
474 | Patches and bug reports |
---|
475 | ----------------------- |
---|
476 | Patches and bug reports are are encouraged, but please try to follow |
---|
477 | these guidelines: |
---|
478 | |
---|
479 | - Post bug reports and patches to the |
---|
480 | http://groups.google.com/group/asciidoc[asciidoc discussion list], |
---|
481 | this keeps things transparent and gives everyone a chance to |
---|
482 | comment. |
---|
483 | - The email subject line should be a specific and concise topic |
---|
484 | summary. Commonly accepted subject line prefixes such as '[ANN]', |
---|
485 | '[PATCH]' and '[SOLVED]' are good. |
---|
486 | |
---|
487 | === Bug reports |
---|
488 | - When reporting problems please illustrate the problem with the |
---|
489 | smallest possible example that replicates the issue (and please test |
---|
490 | your example before posting). This technique will also help to |
---|
491 | eliminate red herrings prior to posting. |
---|
492 | - Paste the commands that you executed along with any relevant |
---|
493 | outputs. |
---|
494 | - Include the version of AsciiDoc and the platform you're running it |
---|
495 | on. |
---|
496 | - If you can program please consider writing a patch to fix the |
---|
497 | problem. |
---|
498 | |
---|
499 | === Patches |
---|
500 | - Keep patches small and atomic (one issue per patch) -- no patch |
---|
501 | bombs. |
---|
502 | - If possible test your patch against the current trunk. |
---|
503 | - If your patch adds or modifies functionality include a short example |
---|
504 | that illustrates the changes. |
---|
505 | - Send patches in `diff -u` format, inline inside the mail message is |
---|
506 | usually best; if it is a very long patch then send it as an |
---|
507 | attachment. |
---|
508 | - Include documentation updates if you're up to it; otherwise insert |
---|
509 | 'TODO' comments at relevant places in the documentation. |
---|
510 | |
---|