Jonathan Corbet <corbet@xxxxxxx> writes: > Asciidoc is a credible solution to the formatted documentation problem, > but it's not the only such; I'd like to be sure that we pick the right > one. I worry that asciidoc seems to be aimed mostly at small documents, > and that the project itself seems a little lifeless - it's not a good > sign when your main page's link to the repository has been dead for a long > time. (Asciidoctor seems more active, with the Github folks behind it, > but that means bringing Ruby into the picture). I was surprised when one of the asciidoctor developers said that asciidoc itself was 'in maintenance mode for existing users'. I've tried asciidoctor but never got it to the point where I was happy with the results. Having two tools using the same nominal format doesn't seem like a great idea to me. It's also clear from my hacking in asciidoc that docbook is the expected target for that tool. I've managed to make direct HTML output usable, but LaTeX doesn't work at all. Something which focuses on direct HTML (and ePub) output would be pretty nice. > An alternative we haven't really looked at yet is ReStructuredText (or > "RST") and the Sphinx system (sphinx-doc.org) built on top of it. RST is > YA simple markup scheme, remarkably similar to Markdown or Asciidoc; > Sphinx is a fairly sophisticated documentation system that uses RST. I've installed debian's python3-sphinx package; it looks like it doesn't have a huge dependency chain below it, which is a nice change. I translated a fairly long document from asciidoc to rst using pandoc by using the docbook output from asciidoc -- pandoc doesn't have a native asciidoc reader, only a writer. The result didn't totally suck, although I haven't messed with fixing the css or using a different theme at all. http://keithp.com/~keithp/altusmetrum-sphinx/altusmetrum.html I installed the sphinxcontrib.fulltoc extension so that the whole TOC was visible from each section; this made navigating a lot easier. Having search included (if you have javascript) seems like a nice feature. > Like asciidoc, Sphinx is Python-based, so it adds little to the toolchain > requirements there. Having functional native latex output means that even PDF generation is lighterweight though. > It produces integrated, multi-file HTML natively, > with a TOC, an index, cross-file cross references, and more. It can make > things like function indexes. It claims output in epub, docbook, and man > (I've not yet messed with those). The path to PDF is via latex; clearly > the docbook path could be used too. I've tried epub and latex backends; epub seems just fine (it's just html, after all). LaTeX works, and generates functional PDF, but I'm going to have to spend a bunch of time making it looks nice. http://keithp.com/~keithp/altusmetrum-sphinx/AltusMetrum.pdf > So can we discuss? I'm not saying we have to use Sphinx, but, should we > choose not to, we should do so with open eyes and good reasons for the > course we do take. What do you all think? Having spent the afternoon playing with it, I'm definitely impressed. I've spent a ton of time getting asciidoc to generate html and pdf that I can tolerate; far too much of that involved hacking XML files related to the docbook backend. Pros * Credible HTML output without docbook * Credible PDF output without docbook. * Constructs a unified set of documents across multiple files. * Written in Python (2 or 3) * PanDoc already supports rst for both input and output. So, if we get bored with RST, we've got a way out. Cons * Table formatting doesn't seem as sophisticated as asciidoc Questions * Conditional text appears to be harder to manage (I haven't managed to make it work at all). * Takes over a directory making building more than one document in a directory hard/impossible? The config file must be named 'conf.py'? -- -keith
Attachment:
signature.asc
Description: PGP signature
