diff options
Diffstat (limited to 'website/index.txt')
| -rw-r--r-- | website/index.txt | 478 |
1 files changed, 0 insertions, 478 deletions
diff --git a/website/index.txt b/website/index.txt deleted file mode 100644 index c1d5db1..0000000 --- a/website/index.txt +++ /dev/null @@ -1,478 +0,0 @@ -AsciiDoc Home Page -================== -// Web page meta data. -:keywords: AsciiDoc, DocBook, EPUB, PDF, ebooks, slideshow, slidy, man page -:description: AsciiDoc is a text document format for writing notes, + - documentation, articles, books, ebooks, slideshows, + - web pages, man pages and blogs. AsciiDoc files can be + - translated to many formats including HTML, PDF, EPUB, + - man page. - - -.{revdate}: AsciiDoc {revnumber} Released -************************************************************************ -Read the link:CHANGELOG.html[CHANGELOG] for release highlights and a -full list of all additions, changes and bug fixes. Changes are -documented in the updated link:userguide.html[User Guide]. See the -link:INSTALL.html[Installation page] for downloads and and -installation instructions. -************************************************************************ - -Introduction ------------- -{description} - -AsciiDoc.py is a legacy processor for this syntax, handling an older -rendition of AsciiDoc. As such, this will not properly handle the -https://projects.eclipse.org/projects/technology.asciidoc[current AsciiDoc specification]. -It is suggested that unless you specifically require the AsciiDoc.py -toolchain, you should find a processor that handles the modern AsciiDoc -syntax. - -AsciiDoc.py is highly configurable: both the AsciiDoc source file syntax -and the backend output markups (which can be almost any type of -SGML/XML markup) can be customized and extended by the user. - -AsciiDoc.py is free software and is licensed under the terms of the 'GNU -General Public License version 2' (GPLv2). - -TIP: The pages you are reading were written using AsciiDoc, to view -the corresponding AsciiDoc source click on the *Page Source* menu item -in the left hand margin. - - -Overview and Examples ---------------------- -You write an AsciiDoc document the same way you would write a -normal text document, there are no markup tags or weird format -notations. AsciiDoc files are designed to be viewed, edited and -printed directly or translated to other presentation formats using -the asciidoc(1) command. - -The asciidoc(1) command translates AsciiDoc files to HTML, XHTML and -DocBook markups. DocBook can be post-processed to presentation -formats such as HTML, PDF, EPUB, DVI, LaTeX, roff, and Postscript -using readily available Open Source tools. - -Example Articles -~~~~~~~~~~~~~~~~ -- This XHTML version of the - link:asciidoc.css-embedded.html[AsciiDoc User Guide] - was generated by AsciiDoc from - link:asciidoc.txt[this AsciiDoc file]. - -- Here's the link:asciidoc.html[same document] created by first - generating DocBook markup using AsciiDoc and then converting the - DocBook markup to HTML using 'DocBook XSL Stylesheets'. - -- The User Guide again, this time a - link:chunked/index.html[chunked version]. - -- AsciiDoc generated this link:article-standalone.html[stand-alone - HTML file] containing embedded CSS, JavaScript and images from this - link:article.txt[AsciiDoc article template] with this command: - - asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt - -- The same link:article.txt[AsciiDoc article template] generated - link:article-html5-toc2.html[this HTML 5] (the 'toc2' attribute puts - a table of contents in the left margin) from this command: - - asciidoc -b html5 -a icons -a toc2 -a theme=flask article.txt - -- The same link:article.txt[AsciiDoc article template] produced - this link:article.html[HTML file] and this - link:article.pdf[PDF file] via DocBook markup generated by AsciiDoc. - -[[X7]] -Example Books -~~~~~~~~~~~~~ -AsciiDoc markup supports all the standard DocBook frontmatter and -backmatter sections (dedication, preface, bibliography, glossary, -index, colophon) plus footnotes and index entries. - -- This link:book.txt[AsciiDoc book] produced link:book.html[this HTML - file] using the 'DocBook XSL Stylesheets'. -- The link:asciidoc.pdf[PDF formatted AsciiDoc User Guide] was - generated from asciidoc(1) DocBook output. -- The link:asciidoc.epub[EPUB formatted AsciiDoc User Guide] was - generated using link:a2x.1.html[a2x]. -- This link:book.epub[EPUB formatted book skeleton] was generated - using link:a2x.1.html[a2x]. -- This link:book-multi.txt[multi-part AsciiDoc book] produced - link:book-multi.html[this HTML file] using the 'DocBook XSL - Stylesheets'. - -Example UNIX Man Pages -~~~~~~~~~~~~~~~~~~~~~~ -HTML formatted AsciiDoc man pages -link:asciidoc.1.css-embedded.html[with stylesheets] and -link:asciidoc.1.html[without stylesheets] were generated by AsciiDoc -from link:asciidoc.1.txt[this file]. - -This link:asciidoc.1[roff formatted man page] was generated from -asciidoc(1) DocBook output using `xsltproc(1)` and DocBook XSL -Stylesheets. - -[[X8]] -Example Slideshows -~~~~~~~~~~~~~~~~~~ -The https://www.w3.org/Talks/Tools/Slidy2/[Slidy] backend generates -HTML slideshows that can be viewed in any web browser. What's nice is -that you can create completely self contained slideshows including -embedded images. - -- Here is the link:slidy.html[slidy backend documentation] slideshow - and here is it's link:slidy.txt[AsciiDoc source]. -- An link:slidy-example.html[example slidy slideshow] and the - link:slidy-example.txt[AsciiDoc source]. - -Example Web Site -~~~~~~~~~~~~~~~~ -The link:README-website.html[AsciiDoc website] is included in the -AsciiDoc distribution (in `./website/` and `./docs/`) as an example website -built using AsciiDoc. See `./website/README-website.txt`. - -More examples -~~~~~~~~~~~~~ -- See below: <<X6,'Documents written using AsciiDoc'>>. -- Example link:newtables.html[Tables]. - - -eBook Publication ------------------ -The two most popular open eBook formats are -https://en.wikipedia.org/wiki/EPUB[EPUB] and PDF. -The AsciiDoc link:a2x.1.html[a2x] toolchain wrapper makes it easy to -link:publishing-ebooks-with-asciidoc.html[publish EPUB and PDF eBooks -with AsciiDoc]. See also <<X7,example books>> and -link:epub-notes.html[AsciiDoc EPUB Notes]). - - -Blogpost weblog client ----------------------- -https://srackham.wordpress.com/blogpost-readme/[blogpost] is a -command-line weblog client for publishing AsciiDoc documents to -https://wordpress.org/[WordPress] blog hosts. It creates and updates -weblog posts and pages directly from AsciiDoc source documents. - - -Source code highlighter ------------------------ -AsciiDoc includes a link:source-highlight-filter.html[source code -highlighter filter] that uses -https://www.gnu.org/software/src-highlite/[GNU source-highlight] to -highlight HTML outputs. You also have the option of using the -https://pygments.org/[Pygments] highlighter. - - -[[X3]] -Mathematical Formulae ---------------------- -You can include mathematical formulae in AsciiDoc XHTML documents using -link:asciimath.html[ASCIIMath] or link:latexmathml.html[LaTeXMathML] -notation. - -The link:latex-filter.html[AsciiDoc LaTeX filter] translates LaTeX -source to an image that is automatically inserted into the AsciiDoc -output documents. - -AsciiDoc also has 'latexmath' macros for DocBook outputs -- they are -documented in link:latexmath.pdf[this PDF file] and can be used in -AsciiDoc documents processed by `dblatex(1)`. - - -Editor Support --------------- -- An AsciiDoc syntax highlighter for the Vim text editor is included in Vim. -+ -.Syntax highlighter screenshot -image::images/highlighter.png[height=400,caption="",link="images/highlighter.png"] - -- Dag Wieers has implemented an alternative Vim syntax file for - AsciiDoc which can be found here - https://github.com/dagwieers/asciidoc-vim. -- David Avsajanishvili has written a source highlighter for AsciiDoc - files for https://wiki.gnome.org/Projects/GtkSourceView[GtkSourceView] - (used by https://wiki.gnome.org/Apps/Gedit[gedit] and a number of - other applications). The project is hosted here: - https://launchpad.net/asciidoc-gtk-highlight -- AsciiDoc resources for the Emacs editor can be found on the - https://www.emacswiki.org/emacs/AsciiDoc[AsciiDoc page] at the - https://www.emacswiki.org/emacs/EmacsWiki[Emacs Wiki]. -- Christian Zuckschwerdt has written a - https://github.com/zuckschwerdt/asciidoc.tmbundle[TextMate bundle] - for AsciiDoc. - - -Try AsciiDoc on the Web ------------------------ -Thaddée Tyl has written an online live editor named -https://espadrine.github.io/AsciiDocBox/[AsciiDocBox] to try AsciiDoc in -your browser. - -You can use https://gist.asciidoctor.org/[DocGist] to preview AsciiDoc -files hosted on GitHub, Dropbox, and other services. DocGist also -features a real-time collaboration mode. - -[[X2]] -External Resources and Applications ------------------------------------ -Here are various useful resources, feel free to open a pull request to -add additional ones: - -- Check the link:INSTALL.html#X2[installation page] for packaged versions - of AsciiDoc. -- https://asciidoctor.org/[Asciidoctor] provides a modern, compliant, and - substantially faster implementation of the AsciiDoc processor written - in Ruby. This implementation can also be run on the JVM (with - AsciidoctorJ) or using JavaScript (with Asciidoctor.js). The - Asciidoctor project now maintains the official definition of the - AsciiDoc syntax. -- Alex Efros has written an HTML formatted - https://powerman.name/doc/asciidoc[AsciiDoc Cheatsheet] using AsciiDoc. - The Asciidoctor project also provides a comprehensive - https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc - syntax quick reference]. However, the syntax supported by Asciidoctor differs - slightly, see - https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/#updated-and-deprecated-asciidoc-syntax[this page] - for more details. -- The http://remips.sourceforge.net/[ReMIPS] project website has been - built using AsciiDoc. -- Here are some link:asciidoc-docbook-xsl.html[DocBook XSL Stylesheets - Notes]. -- Karl Mowatt-Wilson has developed an http://ikiwiki.info/[ikiwiki] - plugin for AsciiDoc which he uses to render - http://mowson.org/karl[his website]. The plugin is available - http://www.mowson.org/karl/colophon/[here] and there is some - discussion of the ikiwiki integration - http://ikiwiki.info/users/KarlMW/discussion/[here]. -- Glenn Eychaner has - http://groups.google.com/group/asciidoc/browse_thread/thread/bf04b55628efe214[reworked - the Asciidoc plugin for ikiwiki] that was created by Karl Mowson. -- David Hajage has written an AsciiDoc package for the - http://www.r-project.org/[R Project] (R is a free software - environment for statistical computing). 'ascii' is available on - 'CRAN' (just run `install.packages("ascii")` from R). Briefly, - 'ascii' replaces R results in AsciiDoc document with AsciiDoc - markup. More information and examples here: - http://eusebe.github.com/ascii/. -- Jared Henley has written - https://jared.henley.id.au/software/awb/[AsciiDoc - Website Builder]. 'AsciiDoc Website Builder' (awb) is a Python - program that automates the building of of a website written in - AsciiDoc. All you need to write is the AsciiDoc source plus a few - simple configuration files. -- Filippo Negroni has developed a set of tools to facilitate 'literate - programming' using AsciiDoc. The set of tools is called - http://eweb.sourceforge.net/[eWEB]. -- https://vanderwijk.info/[Ivo's blog] describes a - https://ditaa.sourceforge.net/[ditaa] filter for AsciiDoc which converts - https://en.wikipedia.org/wiki/ASCII_art[ASCII art] into graphics. -- https://github.com/gollum/gollum[Gollum] is a git-powered wiki, it - supports various formats, including AsciiDoc. -- Gregory Romé has written an - https://github.com/gpr/redmine_asciidoc_formatter[AsciiDoc plugin] - for the https://www.redmine.org/[Redmine] project management - application. -- Paul Hsu has started a - https://github.com/paulhsu/AsciiDoc.CHT.userguide[Chinese translation - of the AsciiDoc User Guide]. -- Dag Wieers has written - http://dag.wieers.com/home-made/unoconv/[UNOCONV]. 'UNOCONV' can - export AsciiDoc outputs to OpenOffice export formats. -- Ed Keith has written - https://sourceforge.net/projects/codeextactor.berlios/[Code Extractor], - it extracts code snippets from source code files and - inserts them into AsciiDoc documents. -- Ryan Tomayko has written an number of - https://github.com/rtomayko/adoc-themes[themes for AsciiDoc]. -- Lex Trotman has written - https://github.com/elextr/codiicsa[codiicsa], a program that - converts DocBook to AsciiDoc. -- Qingping Hou has written https://houqp.github.io/asciidoc-deckjs/[an - AsciiDoc backend for deck.js]. - http://imakewebthings.com/deck.js/[deck.js] is a JavaScript - library for building modern HTML presentations (slideshows). -- The guys from O'Reilly Media have posted an - https://github.com/oreillymedia/docbook2asciidoc[XSL Stylesheet to -github] that converts DocBook to AsciiDoc. -- Lex Trotman has written - https://github.com/elextr/flexndex[flexndex], an index generator - tool that be used with AsciiDoc. -- Michael Haberler has created a - https://code.google.com/archive/p/asciidoc-diag-filter/[blockdiag filter - for AsciiDoc] which embeds http://blockdiag.com/en/[blockdiag] images in - AsciiDoc documents. -- Dan Allen has written a - https://github.com/mojavelinux/asciidoc-bootstrap-docs-backend[Bootstrap - backend] for AsciiDoc. -- Steven Boscarine has written - https://github.com/StevenBoscarine/JavaAsciidocWrapper[Maven wrapper for AsciiDoc]. -- Christian Goltz has written - https://github.com/christiangoltz/shaape[Shaape], an Ascii art to - image converter for AsciiDoc. -- Eduardo Santana has written an - https://github.com/edusantana/asciidoc-highlight[Asciidoc Highlight - for Notepad++]. -- https://www.geany.org/[Geany] 1.23 adds document structure support - for AsciiDoc. - -Please let me know if any of these links need updating. - - -[[X6]] -Documents written using AsciiDoc --------------------------------- -Here are some documents I know of, if you know of more drop me a line -and I'll add them to the list. - -- The book http://practicalunittesting.com/[Practical Unit Testing] by - Tomek Kaczanowski was - https://groups.google.com/group/asciidoc/browse_frm/thread/4ba13926262efa23[written - using Asciidoc]. - -- The book - https://www.oreilly.com/library/view/programming-ios-4/9781449397302/[Programming iOS 4] - by Matt Neuburg was written using AsciiDoc. Matt has - https://www.apeth.net/matt/iosbooktoolchain.html[written an article] - describing how he used AsciiDoc and other tools to write the book. - -- The book - https://www.oreilly.com/library/view/programming-scala/9780596801908/[Programming - Scala] by Dean Wampler and Alex Payne (O'Reilly) was - http://groups.google.com/group/asciidoc/browse_frm/thread/449f1199343f0e27[written - using Asciidoc]. - -- The Neo4j graph database project uses Asciidoc, and the output is - published here: https://neo4j.com/docs/. The build process includes - live tested source code snippets and is described - http://groups.google.com/group/asciidoc/browse_thread/thread/49d570062fd3ff52[here]. - -- https://frugalware.org/[Frugalware Linux] uses AsciiDoc for - https://frugalware.org/docs[documentation]. -- http://www.cherokee-project.com/doc/[Cherokee documentation]. - -- Henrik Maier produced this professional User manual using AsciiDoc: - http://www.proconx.com/assets/files/products/modg100/UMMBRG300-1101.pdf - -- Henrik also produced this folded single page brochure format - example: - http://www.proconx.com/assets/files/products/modg100/IGMBRG300-1101-up.pdf -+ -See this -http://groups.google.com/group/asciidoc/browse_thread/thread/16ab5a06864b934f[AsciiDoc -discussion group thread] for details. - -- The - https://mirrors.edge.kernel.org/pub/software/scm/git/docs/user-manual.html[Git - User's Manual]. -- 'Git Magic' + - http://www-cs-students.stanford.edu/~blynn/gitmagic/ + - https://github.com/blynn/gitmagic -- 'CouchDB: The Definitive Guide' + - https://docs.couchdb.org/en/stable/ + - https://groups.google.com/g/asciidoc/c/pg9ny7r4Yqo -- 'Ramaze Manual' + - http://book.ramaze.net/ + - http://github.com/manveru/ramaze-book -- The https://github.com/manveru/KirbyBase[KirbyBase for Ruby] - database management system manual. -- The http://xpt.sourceforge.net/[*Nix Power Tools project] uses - AsciiDoc for documentation. -- The http://www.wesnoth.org/[Battle for Wesnoth] project uses - AsciiDoc for its http://www.wesnoth.org/wiki/WesnothManual[Manual] - in a number of different languages. -- Troy Hanson uses AsciiDoc to generate user guides for the - https://troydhanson.github.io/tpl/index.html[tpl] and - https://troydhanson.github.io/uthash/index.html[uthash] projects - (the HTML versions have a customised contents sidebar). -- https://weechat.org/[WeeChat] uses AsciiDoc for - https://weechat.org/doc/[project documentation]. -- https://github.com/Clansuite/Clansuite[Clansuite] uses AsciiDoc for - project documentation. -- The https://github.com/shlomif/fc-solve[Freecell Solver program] uses - AsciiDoc for its - https://fc-solve.shlomifish.org/[distributed documentation]. -- Eric Raymond's http://gpsd.berlios.de/AIVDM.html[AIVDM/AIVDO - protocol decoding] documentation is written using AsciiDoc. -- Warren Block has http://www.wonkity.com/~wblock/docs/[posted a - number of articles written using AsciiDoc]. -- The https://gitlab.com/ita1024/waf/[Waf project's] - https://waf.io/book/['Waf Book'] is written using AsciiDoc. -- The http://www.diffkit.org/[DiffKit] project's documentation and - website have been written using Asciidoc. -- The http://www.networkupstools.org[Network UPS Tools] project - http://www.networkupstools.org/documentation.html[documentation] is - an example of a large documentation project written using AsciiDoc. -- http://www.archlinux.org/pacman/[Pacman], the - http://www.archlinux.org/[Arch Linux] package manager, has been - documented using AsciiDoc. -- Suraj Kurapati has written a number of customized manuals for his - Open Source projects using AsciiDoc: - - * http://snk.tuxfamily.org/lib/detest/ - * http://snk.tuxfamily.org/lib/ember/ - * http://snk.tuxfamily.org/lib/inochi/ - * http://snk.tuxfamily.org/lib/rumai/ - -- The http://cxxtest.com/[CxxTest] project (unit testing for C++ - language) has written its - http://cxxtest.com/guide.html[User Guide] using AsciiDoc. -- The https://docs.fedoraproject.org/[Fedora Docs] - website is generated using AsciiDoc. - -[[X1]] -LaTeX Backend -------------- -An experimental LaTeX backend was written for AsciiDoc in 2006 by -Benjamin Klum. Benjamin did a superhuman job (I admit it, I didn't -think this was doable due to AsciiDoc's SGML/XML bias). Due to -other commitments, Benjamin was unable to maintain this backend. -Here's link:latex-backend.html[Benjamin's original documentation]. -Incompatibilities introduced after AsciiDoc 8.2.7 broke the LaTeX -backend. - -In 2009 Geoff Eddy stepped up and updated the LaTeX backend, thanks to -Geoff's efforts it now works with AsciiDoc 8.4.3. Geoff's updated -`latex.conf` file shipped with AsciiDoc version 8.4.4. The backend -still has limitations and remains experimental (see -link:latex-bugs.html[Geoff's notes]). - -It's probably also worth pointing out that LaTeX output can be -generated by passing AsciiDoc generated DocBook through `dblatex(1)`. - - -Patches and bug reports ------------------------ -Patches and bug reports are are encouraged, but please try to follow -these guidelines: - -- Post bug reports and PRs to the - https://github.com/asciidoc/asciidoc-py3[asciidoc-py3] repository. -- Post questions about using AsciiDoc or AsciiDoc syntax to the - http://groups.google.com/group/asciidoc[asciidoc discussion list], - this keeps things transparent and gives everyone a chance to - comment. - -=== Bug reports -- When reporting problems please illustrate the problem with the - smallest possible example that replicates the issue (and please test - your example before posting). This technique will also help to - eliminate red herrings prior to posting. -- Paste the commands that you executed along with any relevant - outputs. -- Include the version of AsciiDoc and the platform you're running it - on. -- If you can program please consider writing a patch to fix the - problem. - -=== Pull Requests -- Keep pull requests small and atomic (one issue per PR) -- no patch - bombs. -- If possible test your PR against the current master. -- If your PR adds or modifies functionality include a short example - that illustrates the changes. -- Include documentation updates if you're up to it; otherwise insert - 'TODO' comments at relevant places in the documentation. - |