org-babel bug and python docs
ben at adversary.org
Tue May 15 06:24:44 CEST 2018
So I've discovered an annoying bug (as if there's any other
kind) in org-mode's babel output.
Specifically that babel appears to break Python code examples in which
there are nested indent blocks. It's fine with the first level of
indentation, but does not honour subsequent levels of indentation.
I'm tracking that here:
Obviously I'll have to follow that up with org-mode devs directly, but
it does leave us with a quandary. Specifically it makes the HOWTO I
wrote in March somewhat less helpful than it first appeared.
I am unthrilled by this, to say the least.
In the mean time, a work-around was required and I figured I had two
Option one: port the whole thing to reStructuredText, which is used
for Python documentation more generally (including the official docs).
Option two: port the whole thing to an XML format known to be capable
of handling technical documentation.
Both had advantages, but I opted for the second one. The reasons
being that while reStructuredText itself is great; most methods of
generating output for it involve Sphinx and while Sphinx is very
usable, how to put this, it wouldn't know standards compliance and any
form of markup validation if it tripped over it.
So I selected something I've ranted about either here or over on
gnupg-users in the past: DITA XML. I finished porting the HOWTO to
that a short while ago and its currently commited to the
ben/howto-dita branch in the GPGME repo, but not (yet) merged with
I've also used it to generate a webhelp style site and put that here
so you can see why it's so good for things like this:
The HOWTO is actually an ideal size for this kind of demonstration,
it's big enough to show some of the advantages, without being so big
as to make the porting effort too much of a chore.
I also put the metrics report for that build over here:
It shows all sorts of little stats like which XML elements were used,
how many times and so on.
Most importantly, though, unlike the output generated from the
org-mode file, the example code is correctly formatted (such that end
users can just copy and paste from the web page), without losing
It's also searchable. Even though it's a static site. I guess
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 228 bytes
Desc: not available
More information about the Gnupg-devel