Re: exporting documents w/ babel results w/o evaluating babel blocks

[Nick Dokos <ndokos@gmail.com>]

"Charles C. Berry" <ccberry@ucsd.edu> writes:

> TL;DR: Org babel headers give excellent control over what gets run,
> when it gets run, and how. Users should use them. Don't reset
> `org-export-babel-evaluate'.
>
> ...
>
>> I think one of the main points of confusion in this thread still has
>> to do with why o-e-b-e switches what gets exported. If no code/results
>> are run/added/removed/modified as you mention, it doesn't speak to why
>> code export is always done for o-e-b-e = nil, but not otherwise. This
>> suggests babel is doing more than "executing code;" it's somehow
>> influencing what makes it into the export document. At least for me,
>> that was an unexpected interpretation of "everything babel does is
>> switched off."
>
> Babel is a fairly complicated beast.
>

We can all agree on that :-)

> If you want to grok what it is doing during export, you could instrument 
> `org-export-as' (do `(info "(elisp) Edebug")' if you need to know about 
> this), export something with babel code in it, and step thru to just 
> before the line `(org-export-execute-babel-code)'. At that point have a 
> look at the temp buffer the exporter is working in. (IIRC, it will have 
> <2> suffixed to the name of the buffer from which you started the export.) 
> Then do one more step to run the babel code and look again - be sure it is 
> *still* the buffer named with the *<2> format that you are inspecting now. 
> You will see what it is that Babel has done.
>
> In particular, a src block with no results initially, but with
> `:exports results' as a header will be gone, but results will now be
> seen.
>

I see.

> A src block that is has `#+begin-src emacs-lisp :exports code' will
> survive, but the header arg will be gone. So, transcoders in the
> exporter will not see the header arg.
>

I see.

>>
>> In fact, I just had an idea... I have o-e-b-e set to always, but just
>> turned org-confirm-babel-evaluate to on (I typically have it off). If
>> export the above and type "no" to make sure the code block is not
>> executed I do *not* get the code in the document. I think this
>> confirms that babel's responsibilities include *what* plain text in
>> .org the exporter formats into the output format.
>>
>> My suggestion would be to create a different variable to handle
>> formatting vs. execution unless things were designed this way? It
>> seems from all the comments that the majority of users expect the
>> time-heavy *code* not to be run at each export but still prefer the
>> blocks to behave as they intended.
>
> This is what `:eval never-export' was created for.
>
>> Theoretically, with all of my
>> results generated (e.g. into .pdf, .png, etc. plots; ascii tables,
>> whatever) shouldn't I be able to have o-e-b-e set to whatever and get
>> the same document? My document no longer depends on any of the code...
>> so I don't need it run, but the exported document will behave like
>> :exports both instead of :exports results just from turning babel off.
>>
>
> It sounds simple, but babel has a lot woven into it and getting the 
> behavior you suggest by setting variables like o-e-b-e in emacs without 
> breaking things is tricky. Consider what happens when you have something 
> like:
>
> #+BEGIN_SRC emacs-lisp :var x=abc() :noweb yes :exports both
> <<format-some-code(y=x)>>
> #+END_SRC
>
> With o-e-b-e nil, what should happen? If nothing runs, x does not get set 
> because abc() does not run, nor does the noweb code substitution take 
> place because that requires the `format-some-code' src-block to run. If 
> only some things `ought to' be run, how does the program decide which 
> ones?
>
> Currently, the user can fine tune what is run and what is not during
> export using Babel headers. Let babel run and the headers will sort
> out the rest.

Thanks for the explanation: it certainly helped me understand somewhat
better what is happening. This is a fairly complicated set of
interactions however, and it *is* confusing: in the long run, babel
should be simplified; in particular, settings should be as orthogonal as
possible (global as well as header setting, although I realize that's
easier said than done - and backward compatibility might have to go
by the wayside in order for this to be accomplished).

>
> Frankly, I do not see why users would want to mess with o-e-b-e except
> in unusual cases - like debugging a complicated document, where having
> Babel changing things around could just make things harder.
>

OK - but then users need guidance that says "don't do that!". Can we add a
big warning to the doc for o-e-b-e?

> If there is a use case for a capability that is not well supported by
> existing headers it would be good to have an example.
>

There's the use case that John describes: I've evaluated everything,
checked everything, I'm ready for export, I don't want babel to touch
the results - and I have a million blocks, so I'd rather have a global
setting than go in with individual headers.

If you've covered this in a previous reply, please ignore me: I've only
paid intermittent attention to the thread, so apologies for missing a
big chunk of what has gone on before in the thread.

In any case, although I'm not happy about the state of things, I
understand better why they are as they are.

Thanks!
--
Nick