org-babel bug and python docs

[Ben McGinnes]

Hello,
	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:

https://dev.gnupg.org/T3977

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
options:

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
master.

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:

http://files.au.adversary.org/crypto/gpgme-python-howto/webhelp/index.html

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:

http://files.au.adversary.org/crypto/gpgme-python-howto/metrics/gpgme-python-howto-20180515-135345-report.html

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
syntax highlighting.

It's also searchable.  Even though it's a static site.  I guess
javascript is useful for something after all.


Regards,
Ben
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 228 bytes
Desc: not available
URL: <https://lists.gnupg.org/pipermail/gnupg-devel/attachments/20180515/c44dda75/attachment.sig>