Re: [O] :noweb header argument

[Thomas S. Dye]

Hi Eric,

Eric Schulte <address@hidden> writes:

> address@hidden (Thomas S. Dye) writes:
>
>> Hi Seb,
>>
>> "Sebastien Vauban" <address@hidden> writes:
>>
>>> Hi Thomas,
>>>
>>> Thomas S. Dye wrote:
>>>> Is there a difference between :noweb tangle and :noweb no?
>>>
>>> Yes: ":noweb no" is the default, and must *not expand* anything.
>>>
>>>> Based on the documentation and some limited testing, I made the following
>>>> table.
>>>>
>>>> *** :noweb parameters
>>>>
>>>> | param  | eval | tangle | export |
>>>> |--------+------+--------+--------|
>>>> | yes    | +    | +      | +      |
>>>> | no     | -    | +      | -      |
>>>
>>> It should be "-", "-", "-" here, if "-" means "no expansion".
>>>
>>
>> Hmm, the manual entry for :noweb no says "However, noweb references will
>> still be expanded during tangling."  You're right, though, :noweb no
>> doesn't expand noweb references during tangling.  I'll work up a manual
>> patch. 
>>
>
> Great, I'll apply your documentation patch.
>
>>
>>
>>>> | tangle | -    | +      | -      |
>>>> |--------+------+--------+--------|
>>>> | need   | +    | +      | -      |
>>>>
>
> What should the name for such an option be?
>

Andreas' suggestion, :noweb no-export, seems right to me.

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

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!

All the best,
Tom

>
> Cheers,
>
>>
>>>
>>> Find attached the 2 PDF I had written (in 2009) for comparing NoWeb's
>>> rendering of blocks and Babel's rendering. See
>>> http://lists.gnu.org/archive/html/emacs-orgmode/2009-12/msg00170.html.
>>>
>>> Some time after that, we had block names in the HTML/PDF output, but not
>>> anymore.
>>>
>>> Best regards,
>>>   Seb
>>
>> All the best,
>> Tom

-- 
Thomas S. Dye
http://www.tsdye.com