diff options
Diffstat (limited to 'source-builder/sb/asciidoc/examples/website/index.txt')
| -rw-r--r-- | source-builder/sb/asciidoc/examples/website/index.txt | 510 |
1 files changed, 0 insertions, 510 deletions
diff --git a/source-builder/sb/asciidoc/examples/website/index.txt b/source-builder/sb/asciidoc/examples/website/index.txt deleted file mode 100644 index 1967b2d..0000000 --- a/source-builder/sb/asciidoc/examples/website/index.txt +++ /dev/null @@ -1,510 +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. - -'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. - |