Mailing List Archive

org-babel bug and python docs
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
Re: org-babel bug and python docs [ In reply to ]
On Tue, May 15, 2018 at 6:24 AM, Ben McGinnes <ben@adversary.org> wrote:

>
> 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.
> [...]
>
> 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.
>

As a third work-around option, have you tried to use '#+begin_example'
instead of '#+begin_src', for the code examples where the identation
is broken. The code coloring will be lost, but maybe the indentation will
be preserved.
Re: org-babel bug and python docs [ In reply to ]
On Tue, May 15, 2018 at 7:32 AM, Dashamir Hoxha <dashohoxha@gmail.com>
wrote:

> On Tue, May 15, 2018 at 6:24 AM, Ben McGinnes <ben@adversary.org> wrote:
>
>>
>> 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.
>> [...]
>>
>> 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.
>>
>
> As a third work-around option, have you tried to use '#+begin_example'
> instead of '#+begin_src', for the code examples where the identation
> is broken. The code coloring will be lost, but maybe the indentation will
> be preserved.
>

By the way, since I use org-mode in combination with Jekyll, I leave
coloring
up to Jekyll, like this:

#+BEGIN_EXPORT html
{ % highlight bash %}
#!/bin/bash

. . . . . . . . . . .

{ % endhighlight %}
#+END_EXPORT
Re: org-babel bug and python docs [ In reply to ]
On Tue, May 15, 2018 at 07:32:15AM +0200, Dashamir Hoxha wrote:
> On Tue, May 15, 2018 at 6:24 AM, Ben McGinnes <ben@adversary.org> wrote:
>>
>> Option two: port the whole thing to an XML format known to be capable
>> of handling technical documentation.
>
> As a third work-around option, have you tried to use
> '#+begin_example' instead of '#+begin_src', for the code examples
> where the identation is broken. The code coloring will be lost, but
> maybe the indentation will be preserved.

The same effect can be achieved by just not specifying the language
with begin_src. This is a sub-optimal approach in my opinion.


Regards,
Ben
Re: org-babel bug and python docs [ In reply to ]
On Tue, May 15, 2018 at 07:44:44AM +0200, Dashamir Hoxha wrote:
>
> By the way, since I use org-mode in combination with Jekyll, I leave
> coloring up to Jekyll, like this:

Nice, but the issue here is that we're not the ones who will be
generating the output, more often than not. For the most part the
output ought to be generated when GPGME is installed by end users and
the generation is for multiple output formats, which is why I haven't
merged the DITA version with master yet since it requires processing
XSLTs to produce the output in whatever format (mostly HTML 5 + CSS
sites or PDF, often via XSL-FO).

So expecting end users to have the DITA-OT installed (it's written in
Java) is a bit of a hard sell. So is expecting them to have the same
Jeckyll platform you have already configured. Though that might take
a little less convincing for end users in Linux-land, it's more likely
to go the other way for Windows users.

Now the DITA source could be used to generate that output without the
DITA-OT, but that would require someone re-implementing the standard
in something that's not Java and no one has done it yet. Well, not to
a complete enough extent to be terribly useful; there have been some
attempts with Python by ... erm, I think it's the XMLMind team, but
I'd need to check. Whereas the OT is the reference implementation and
is pretty complete.

For those interested, that (OASIS) standard is here:

https://dita.xml.org/

The DITA-OT is here (on GitHub):

https://www.dita-ot.org/


Regards,
Ben
Re: org-babel bug and python docs [ In reply to ]
On Tue, May 15, 2018 at 6:24 AM, Ben McGinnes <ben@adversary.org> wrote:

> 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 checked it out of curiosity, and it seems that there is a mix of tabs
and white-spaces on the source code.
https://dev.gnupg.org/source/gpgme/browse/master/lang/python/docs/GPGMEpythonHOWTOen.org;e54b110aec3165a32ff9551d0c5227b88aa3dd4f$617

I am not sure whether this is the cause of the problem, but usually
it is not recommended to have such a mix on source code.
I think that Emacs can be configured to convert automatically
tabs to white-spaces, but I don't know how this is done.