rtems/rtems-source-builder
1
0
Fork 0
mirror of https://git.rtems.org/rtems-source-builder synced 2024-10-09 07:15:10 +08:00
Code Issues Packages Projects Releases Wiki Activity
rtems-source-builder/source-builder/sb/asciidoc/examples/website/index.txt

511 lines
21 KiB
Plaintext
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink