Re: [O] :noweb header argument

[Sebastien Vauban]

Hi Thomas, Eric(s) and all,

Thomas S. Dye wrote:
> Eric Schulte <address@hidden> writes:
>> address@hidden (Thomas S. Dye) writes:
>>> "Sebastien Vauban" <address@hidden> writes:
>>>> Thomas S. Dye wrote:
>>>>>
>>>>> | tangle | -    | +      | -      |
>>>>> |--------+------+--------+--------|
>>>>> | need   | +    | +      | -      |
>>
>> What should the name for such an option be?
>
> Andreas' suggestion, :noweb no-export, seems right to me.

Or "all-but-export" which would show that there is expansion going on in all
"modes" but for export?

Anyway, I don't really care, as long as it's rather intuitive and well
documented. And I'm sure both will be true very soon.

>>>>> I think it might be good to have a parameter that expands noweb
>>>>> references on evaluation and tangling, but leaves them alone during
>>>>> export. This way the code block would be fully functional, but wouldn't
>>>>> duplicate code during export (when the noweb references are to other
>>>>> code blocks in the same document).
>>>>
>>>> I'd find that interesting as well, but then the names of the code blocks
>>>> must be visible again (in HTML and PDF exports), something that has
>>>> disappeared over time.
>>>
>>> Alternatively for LaTeX, some way to wrap exported code blocks in
>>> a \begin{listing} ... \end{listing} environment, complete with caption and
>>> label. This way the code block name could appear in the caption, and with
>>> \listoflistings, in the document frontmatter as well.

Thanks for your sample. It shows we really lack key features to be as good in
HTML as Org is in LaTeX:

- bibliography
- acronyms
- listing of images, code, etc.

>> As I recall this was originally implemented and then later removed because
>> it was causing more confusion and problems than it was worth. I hope it
>> hasn't crossed the line of existence more than once. At some point it
>> should be placed behind a user-customizable variable, preferably something
>> like `org-babel-export-code-format' which defaults to something like
>> "%code" but could be augmented to something like "Block Name: *%name*\n
>> %code". It is not immediately clear if such a variable should have
>> different values for different export backends or (likely preferable)
>> should expand into Org-mode text *before* export.
>
> I think you're right about getting this done early in the process. I've been
> thinking only about LaTeX export because that is my immediate goal--not a
> good design perspective.
>
> Perhaps I could help by specifying what I'm trying to do? I'd like to write
> an article or book about particular statistical analyses. I want this also
> to be a piece of reproducible research so readers of the book can follow
> along and perhaps analyze data of their own. I'd like to write a code block
> once and then use it in the following ways: 1) evaluate and return the
> results of analyses; 2) export as a floating listing so I can refer to it in
> discussions of implementation; and 3) tangle to a source code file that can
> be used as the basis for a package that can be used outside of Org mode.
>
> 1) is easy with #+call: With the :wrap header argument that we've
> partially implemented, I can mark the results off in whatever environment I
> like, which is a wonderful bit of flexibility. Different kinds of results
> can be presented distinctively.
>
> 2) is partially there--the code itself is handled nicely by minted and
> I'm able to make it look as good as I want. What I'm lacking now is an easy
> way to identify the code block. Seb's suggestion that the header lines be
> included is one way, though Eric F.'s point about the special characters
> tripping up LaTeX is well taken. It might be some work to get an
> intermediate representation that can be exported to all the targets. My
> alternate idea, which is to wrap the code block in an environment to which I
> can attach a caption and a label, is the LaTeX approach and might not work
> as well for other export targets.

I use HTML export more and more, and would be sad if the solution wasn't
targeted at all to HTML as well.

I see rare cases where I wouldn't want to see the code name: if they have a
name, most of the time, it's because they are referenced one or multiple times
from elsewhere and you'd better be able to display that information to the
reader of your LP/RR document.

Without knowing what it implies, I'd find an extra option rather sexy,
something such as:

#+OPTIONS:   H:4 num:nil noweb-names:t

The real question is: should we be able to turn that off for some code blocks?
Not sure, but difficult to answer that it's totally unwanted.

> 3) I don't have much experience with this but I believe the tangling
> apparatus does everything I might want. I remember some discussion on the
> list a while back about using Org mode for writing R packages. I'll need to
> follow up on that to see how far that effort got. Ideally, I'd tangle the
> full R package, but it might prove easier to tangle the source code and then
> use R tools to work out documentation (although that sounds like duplicated
> effort, now that I write it out).
>
> Sorry to go on and on. I do much of my writing in Org mode now, somewhat
> unexpectedly. There are still some rough spots, where I can't seem to get
> the control I exercise in LaTeX (though these often enough turn out to be my
> own ignorance). On the other hand, I'm way more productive than I've ever
> been, and am able to accomplish new and interesting things. Org mode rocks!

Your experience to go from "parts of embedded LaTeX in Org" to "a full Org
that converts everything to LaTeX as I want (and gives me HTML export as well"
will certainly prove useful and bring new ideas on the table, IIUC.

Best regards,
  Seb

-- 
Sebastien Vauban