Hi,
I think most of the advantages are already mentioned but I'll leave my
experience also.
Since I needed a tool that would allow me to write documentation for the
projects I developed I tested several markup languages and ended up with
either going for Docbook or AsciiDoc. Being a programmer and a teacher I
needed something that could be used in either creating software
documentation and manuals/exercises for students.
It also needed to be free software, platform independent (I use OS X,
GNU Linux and sometimes MS Windows) and easily tracked by source control
tool. I've had some problems with XML in Subversion where conflicts
would arise often when the XML was too complex, this was the first thing
against Docbook.
In the end, AsciiDoc allows me to have complete control over the output,
I can even convert to DocBook if I need to (and I do it to create PDF
files), I can create great looking documents with little effort.
I don't need any particular tool to edit the files, a simple text editor
can be used to create a complex document or just make some adjustments.
With Docbook I spent a lot of time looking for some editor that would
help me ease the task of editing my documents, it was adding another
layer of complexity and affecting my portability.
It works great with Subversion and Git and I can keep a record of every
thing I changed in the documents, and until now I haven't had a single
conflict with multiple users editing documents.
AsciiDoc markup is really easy to read, even without generating a
processed output, anyone can read a document in plain text and
understand the general structure and content. I can even share the
source code (AsciiDoc file and images) for the programming manuals and
exercises I create allowing other teachers to use my materials and just
copy+paste the contents to their tool of choice.
Support is great :D.
The mailing list offers a nice way to get help, the FAQ and
documentation offer a simple, searchable, place to read on how to use
the tool and I don't need a 700 page book to understand how AsciiDoc works.
Docbook must have it's advantages but I could find none that would fit
my needs, AsciiDoc is just simple (to work with, to learn, to setup),
non-intrusive, and powerful (convert to many other formats including
Docbook) enough to allow me to create any of the docs I need.
Regards,
Sérgio Lopes
--
https://www.plesform.com - Gestão de formação simples e eficaz.
http://www.staysimple.net - Um CMS simples para o site do seu negócio.
http://sourceforge.net/projects/sandscape - WTactics no browser.
--
You received this message because you are subscribed to the Google Groups
"asciidoc" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/asciidoc?hl=en.
