diff options
Diffstat (limited to 'doc/asciidoc/examples/website/index.txt')
| -rw-r--r-- | doc/asciidoc/examples/website/index.txt | 510 |
1 files changed, 510 insertions, 0 deletions
diff --git a/doc/asciidoc/examples/website/index.txt b/doc/asciidoc/examples/website/index.txt new file mode 100644 index 0000000..1967b2d --- /dev/null +++ b/doc/asciidoc/examples/website/index.txt @@ -0,0 +1,510 @@ +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. + +'Stuart Rackham' +************************************************************************ + +Introduction +------------ +{description} + +AsciiDoc 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 is free software and is licenced 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 http://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 `./examples/website/`) as an example website +built using AsciiDoc. See `./examples/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 +http://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 +---------------------- +http://srackham.wordpress.com/blogpost-readme/[blogpost] is a +command-line weblog client for publishing AsciiDoc documents to +http://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 +http://www.gnu.org/software/src-highlite/[GNU source-highlight] to +highlight HTML outputs. You also have the option of using the +http://pygments.org/[Pygments] highlighter. + + +[[X3]] +Mathematical Formulae +--------------------- +You can include mathematical formulae in AsciiDoc XHTML documents using +link:asciimathml.html[ASCIIMathML] or link:latexmathml.html[LaTeXMathML] +notation. + +The link:latex-filter.html[AsciiDoc LaTeX filter] translates LaTeX +source to a PNG 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 the + AsciiDoc distribution (see 'Appendix F' of the 'AsciiDoc User Guide' for + details). ++ +.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 + http://svn.rpmforge.net/svn/trunk/tools/asciidoc-vim/. +- David Avsajanishvili has written a source highlighter for AsciiDoc + files for http://projects.gnome.org/gtksourceview/[GtkSourceView] + (used by http://projects.gnome.org/gedit/[gedit] and a number of + other applications). The project is hosted here: + https://launchpad.net/asciidoc-gtk-highlight +- Florian Kaufman has written 'adoc-mode.el' -- a major-mode for + editing AsciiDoc files in Emacs, you can find it + http://code.google.com/p/sensorflo-emacs/[here]. +- The http://xpt.sourceforge.net/[*Nix Power Tools project] has + released an http://xpt.sourceforge.net/tools/doc-mode/[AsciiDoc + syntax highlighter for Emacs]. +- Terrence Brannon has written + http://github.com/metaperl/asciidoc-el[AsciiDoc functions for + Emacs]. +- Christian Zuckschwerdt has written a + https://github.com/zuckschwerdt/asciidoc.tmbundle[TextMate bundle] + for AsciiDoc. + + +Try AsciiDoc on the Web +----------------------- +Andrew Koster has written a Web based application to interactively +convert and display AsciiDoc source: +http://andrewk.webfactional.com/asciidoc.php + + +[[X2]] +External Resources and Applications +----------------------------------- +Here are resources that I know of, if you know of more drop me a line +and I'll add them to the list. + +- Check the link:INSTALL.html#X2[installation page] for packaged versions + of AsciiDoc. +- Alex Efros has written an HTML formatted + http://powerman.name/doc/asciidoc[AsciiDoc Cheatsheet] using + Asciidoc. +- Thomas Berker has written an + http://liksom.info/blog/?q=node/114[AsciiDoc Cheatsheet] in Open + Document and PDF formats. +- The http://www.wikimatrix.org/[WikiMatrix] website has an excellent + http://www.wikimatrix.org/syntax.php[web page] that compares the + various Wiki markup syntaxes. An interesting attempt at Wiki markup + standardization is http://www.wikicreole.org/[CREOLE]. +- Franck Pommereau has written + http://www.univ-paris12.fr/lacl/pommereau/soft/asciidoctest.html[Asciidoctest], + a program that doctests snippets of Python code within your Asciidoc + documents. +- 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, + the source can be downloaded from + http://dl.dropbox.com/u/11256359/asciidoc.pm +- 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.package("ascii")` from R). Briefly, + 'ascii' replaces R results in AsciiDoc document with AsciiDoc + markup. More information and examples here: + http://eusebe.github.com/ascii/. +- Pascal Rapaz has written a Python script to automate AsciiDoc + website generation. You can find it at + http://www.rapazp.ch/opensource/tools/asciidoc.html. +- Jared Henley has written + http://jared.henley.id.au/software/awb/documentation.html[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. +- Brad Adkins has written + http://dbixjcl.org/jcl/asciidocgen/asciidocgen.html[AsciiDocGen], a + web site generation and deployment tool that allows you write your + web site content in AsciiDoc. The + http://dbixjcl.org/jcl/asciidocgen/asciidocgen.html[AsciiDocGen web + site] is managed using 'AsciiDocGen'. +- 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]. +- http://vanderwijk.info/2009/4/23/full-text-based-document-generation-using-asciidoc-and-ditaa[Ivo's + blog] describes a http://ditaa.sourceforge.net/[ditaa] filter for + AsciiDoc which converts http://en.wikipedia.org/wiki/ASCII_art[ASCII + art] into graphics. +- http://github.com/github/gollum[Gollum] is a git-powered wiki, it + supports various formats, including AsciiDoc. +- Gregory Romé has written an + http://github.com/gpr/redmine_asciidoc_formatter[AsciiDoc plugin] + for the http://www.redmine.org/[Redmine] project management + application. +- Paul Hsu has started a + http://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 http://codeextactor.berlios.de/[Code + Extractor], it extracts code snippets from source code files and + inserts them into AsciiDoc documents. +- The http://csrp.iut-blagnac.fr/jmiwebsite/home/[JMI website] hosts + a number of extras for AsciiDoc and Slidy written by Jean-Michel + Inglebert. +- Ryan Tomayko has written an number of + http://tomayko.com/src/adoc-themes/[themes for AsciiDoc] along with + a http://tomayko.com/src/adoc-themes/hacking.html[script for + combining the CSS files] into single CSS theme files for AsciiDoc + embedded CSS documents. +- Ilya Portnov has written a + https://gitorious.org/doc-building-system[document building system + for AsciiDoc], here is + http://iportnov.blogspot.com/2011/03/asciidoc-beamer.html[short + article in Russian] describing it. +- Lex Trotman has written + https://github.com/elextr/codiicsa[codiicsa], a program that + converts DocBook to AsciiDoc. +- Qingping Hou has written http://houqp.github.com/asciidoc-deckjs/[an + AsciiDoc backend for deck.js]. + http://imakewebthings.github.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. + +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 http://oreilly.com/catalog/9781449397296[Programming iOS 4] + by Matt Neuburg was written using AsciiDoc. Matt has + http://www.apeth.net/matt/iosbooktoolchain.html[written an article] + describing how he used AsciiDoc and other tools to write the book. + +- The book + http://oreilly.com/catalog/9780596155957/index.html[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 http://www.ncfaculty.net/dogle/fishR/index.html[fishR] website + has a number of + http://www.ncfaculty.net/dogle/fishR/bookex/AIFFD/AIFFD.html[book + examples] written using AsciiDoc. + +- The Neo4j graph database project uses Asciidoc, and the output is + published here: http://docs.neo4j.org/. The build process includes + live tested source code snippets and is described + http://groups.google.com/group/asciidoc/browse_thread/thread/49d570062fd3ff52[here]. + +- http://frugalware.org/[Frugalware Linux] uses AsciiDoc for + http://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 + http://www.kernel.org/pub/software/scm/git/docs/user-manual.html[Git + User's Manual]. +- 'Git Magic' + + http://www-cs-students.stanford.edu/~blynn/gitmagic/ + + http://github.com/blynn/gitmagic/tree/1e5780f658962f8f9b01638059b27275cfda095c +- 'CouchDB: The Definitive Guide' + + http://books.couchdb.org/relax/ + + http://groups.google.com/group/asciidoc/browse_thread/thread/a60f67cbbaf862aa/d214bf7fa2d538c4?lnk=gst&q=book#d214bf7fa2d538c4 +- 'Ramaze Manual' + + http://book.ramaze.net/ + + http://github.com/manveru/ramaze-book/tree/master +- Some documentation about git by Nico Schottelius (in German) + http://nico.schotteli.us/papers/linux/git-firmen/. +- The http://www.netpromi.com/kirbybase_ruby.html[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 + http://tpl.sourceforge.net/[tpl] and + http://uthash.sourceforge.net/[uthash] projects (the HTML versions + have a customised contents sidebar). +- http://volnitsky.com/[Leonid Volnitsky's site] is generated using + AsciiDoc and includes Leonid's matplotlib filter. +- http://www.weechat.org/[WeeChat] uses AsciiDoc for + http://www.weechat.org/doc[project documentation]. +- http://www.clansuite.com/[Clansuite] uses AsciiDoc for + http://www.clansuite.com/documentation/[project documentation]. +- The http://fc-solve.berlios.de/[Freecell Solver program] uses + AsciiDoc for its + http://fc-solve.berlios.de/docs/#distributed-docs[distributed + documentation]. +- Eric Raymond's http://gpsd.berlios.de/AIVDM.html[AIVDM/AIVDO + protocol decoding] documentation is written using AsciiDoc. +- Dwight Schauer has written an http://lxc.teegra.net/[LXC HOWTO] in + AsciiDoc. +- The http://www.rowetel.com/ucasterisk/[Free Telephony Project] + website is generated using AsciiDoc. +- Warren Block has http://www.wonkity.com/~wblock/docs/[posted a + number of articles written using AsciiDoc]. +- The http://code.google.com/p/waf/[Waf project's] 'Waf Book' is + written using AsciiDoc, there is an + http://waf.googlecode.com/svn/docs/wafbook/single.html[HTML] and a + http://waf.googlecode.com/svn/docs/wafbook/waf.pdf[PDF] version. +- 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 User Guide using AsciiDoc. + +Please let me know if any of these links need updating. + + +DocBook 5.0 Backend +------------------- +Shlomi Fish has begun work on a DocBook 5.0 `docbook50.conf` backend +configuration file, you can find it +http://bitbucket.org/shlomif/asciidoc[here]. See also: +http://groups.google.com/group/asciidoc/browse_thread/thread/4386c7cc053d51a9 + + +[[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). Owning to 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 patches to the + http://groups.google.com/group/asciidoc[asciidoc discussion list], + this keeps things transparent and gives everyone a chance to + comment. +- The email subject line should be a specific and concise topic + summary. Commonly accepted subject line prefixes such as '[ANN]', + '[PATCH]' and '[SOLVED]' are good. + +=== 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. + +=== Patches +- Keep patches small and atomic (one issue per patch) -- no patch + bombs. +- If possible test your patch against the current trunk. +- If your patch adds or modifies functionality include a short example + that illustrates the changes. +- Send patches in `diff -u` format, inline inside the mail message is + usually best; if it is a very long patch then send it as an + attachment. +- Include documentation updates if you're up to it; otherwise insert + 'TODO' comments at relevant places in the documentation. + |