Asciidoc is installed using you distribution or systems package manager i.e for MacPorts on OSX:
$ sudo port install asciidoc
Substitute port with apt-get, aptitude, yum or whatever the package manager on your system is. Now that asciidoc is installed, simply start writing your document, blog or book in a text file in your favorite editor. Open it and paste the following text.
= My first Asciidoc
:author: <your name>
:toc:
== Introduction
When you're ready to release or upload. Generate an neat looking document using the command:
.Generating an asciidoc
[source,sh]
asciidoc my.first.asciidoc;
To see the document that you have just created, simply follow the document's instructions and run the command, with your document name obviously.
$ asciidoc my.first.asciidoc
The following renders like this using the standart asciidoc theme:
To get started quickly with asciidoc Powerman has created cheat sheet, use this to see some of the things you can do. one of the things not included in the cheat sheet is the fact that asciidoc allows you to execute scripts on the command line.
This is extremely useful when writing technical documentation where you'll need to include information like realtime directory contents information or reporting logged in users directly in your document.
Adding a shell command ensures that the command is run when the document is being generated, every time the document is generated. Add the following to your document.
.Listing asciidoc's present in the current directory
[source,sh]
----
sys::[ls *.asciidoc]
----
Now, instead of rendering the actual command, asciidoc executes the command and renders the result. In this case the normal output of the /ls *.asciidoc/ command.
As you can see I have 2 asciidoc files in my current directory. If I wanted to I could include the filter.asciidoc file in the one I'm currently writing. Allowing the file filters.asciidoc to be included. Add the following text to your asciidoc file:
Adding the next document after this line
:leveloffset: 1
include::filters.asciidoc[]
:leveloffset: 0
And were back in the original document.
The include::<filename>[] statement is where the magic happens. This is the line that includes the filter.asciidoc file. The included file doesn't have to be an asciidoc document, any file can be used.
The :leveloffset:1 is needed for asciidoc to treat the included document as headers in its header level. After the include statement we simply pop the header level bask with :leveloffset:0 And were back in the original document.
Notice how the included document is present with in the Adding ... and were back in text. A very useful feature when you have more than one person working on documentation. As this avoids numbers of document merges when you're working on separate files in a team.
Did you notice the cool graphics that was included in the document? This graphic is rendered by an asciidoc plugin called Ditaa. There are several plugins available for asciidoc, some these can be found on the asciidoc plugin page.
Each of the plugins have installation instructions and usage information included. Here's an example of the ditaa plugin. First download the ditaa.zip file. Then install it to your local users ~/.asciidoc directory.
$ mv Downloads/asciidoc-ditaa-filter-master.zip Downloads/ditaa-filter-master.zip
$ asciidoc --filter install Downloads/ditaa-filter-master.zip
The ditaa plugin is the one rendering the image displayed in the my.first.asciidoc. Here's how it's done. Create a new file called filter.asciidoc and fill it with these contents.
= Asciidoc filters exmple
:author: John Dideriksen
:toc:
== testing various filters on the MacPort edition
The following document is used to test some of the asciidoc plugins for drawing, all examples have been taken from the authors plugin documentation page.
=== Ditaa
["ditaa"]
---------------------------------------------------------------------
+--------+ +-------+ +-------+
| | --+ ditaa +--> | |
| Text | +-------+ |diagram|
|Document| |!magic!| | |
| {d}| | | | |
+---+----+ +-------+ +-------+
: ^
| Lots of work |
+-------------------------+
---------------------------------------------------------------------
stops here
As you can see ditaa renders the graphic from an ascii image. This is really useful since you do not have to worry about opening a new program and maintain a separate drawing.
If your documentation is under source control you can easily track the changes in the diagrams for the documentation, just like any other changes. Ditaa is just one of many filters you can install in asciidoc, aafigure is another example of a filter.
You can list your installed asciidoc filters using the command:
$ asciidoc --filter list
/opt/local/etc/asciidoc/filters/code
/opt/local/etc/asciidoc/filters/graphviz
/opt/local/etc/asciidoc/filters/latex
/opt/local/etc/asciidoc/filters/music
/opt/local/etc/asciidoc/filters/source
/Users/cannabissen/.asciidoc/filters/ditaa
Notice, that asciidoc comes with a set of preinstalled plugins that you can use at your will. You remove an installed filter with the command:
$asciidoc --filter remove ditaa
No comments:
Post a Comment