On Wed, 14 Mar 2012 10:58:08 +0000 Sérgio Lopes <[email protected]> wrote:
Hello, > 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. I'm in a similar boot...in the planning stage for an open-source project - multi-platform desktop app - for which we'd need to write decent user's manual. We'll probably do the project using D programming language, but its' documentation tool is probably not fit for writing general documentation. When we were considering to code the project in Python, using reST/Sphinx seemed be logical choise, but now we stumbled upon few projects using AsciiDoc and wonder how would you compare it with reST/Sphinx? We want format which is friendly for keeping under DVCS, easy for writing with the ability to get nice HTML output which can be invoked from within application itself, as well as quality PDF output (possibly to be tweaked and/or imported into LyX). Having rich semantics (chapters, sections,...tables, hyperlinking, pictures, tables...) is also something we'd like to have as well as ability to have decent syntax highlighting of the snippets of the source code. Let me say, that, in general I'm not big fan of DocBook (abandoned it as author's source format some years ago when attempting to use EpcEdit editor), but, based on what I've seen so far, that by writing AsciiDoc one is not forced to deal with Docbook format, although we wonder how easy/stable/supported is the toolchain in order to produce desire output formats? It seems that reST/Sphinx is more simpler? At the end, let me say that Linux is our native developing platform, but we want to be able generate docs on Windows & Mac OS without too much fiddling. So, any pro/cons for AsciiDoc vs reST/Sphinx for non-python project? Sincerely, Gour -- Whatever action a great man performs, common men follow. And whatever standards he sets by exemplary acts, all the world pursues. http://atmarama.net | Hlapicina (Croatia) | GPG: 52B5C810
signature.asc
Description: PGP signature
