:noweb header argument

:noweb header argument

[Thomas S. Dye]

Hi Eric,

Is there a difference between :noweb tangle and :noweb no?  Based on the
documentation and some limited testing, I made the following table.

*** :noweb parameters

| param  | eval | tangle | export |
|--------+------+--------+--------|
| yes    | +    | +      | +      |
| no     | -    | +      | -      |
| tangle | -    | +      | -      |
|--------+------+--------+--------|
| need   | +    | +      | -      |

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

In any case, I'll fix the documentation (which incompletely describes
:noweb no) when I have this figured out.

All the best,
Tom

-- 
T.S. Dye & Colleagues, Archaeologists
735 Bishop St, Suite 315, Honolulu, HI 96813
Tel: 808-529-0866, Fax: 808-529-0884
http://www.tsdye.com

Re: :noweb header argument

[Sebastien Vauban]

[-- Attachment #1: Type: text/plain, Size: 1405 bytes --]

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

> | tangle | -    | +      | -      |
> |--------+------+--------+--------|
> | need   | +    | +      | -      |
>
> 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.

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

-- 
Sebastien Vauban

[-- Attachment #2: ecm-babel-org.pdf --]
[-- Type: application/pdf, Size: 78164 bytes --]

[-- Attachment #3: ecm-noweb.pdf --]
[-- Type: application/pdf, Size: 96058 bytes --]

Re: :noweb header argument

[Andreas Leha]

"Sebastien Vauban"
<wxhgmqzgwmuf@spammotel.com> writes:

[...]

>> 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.
+1 for both

1) the :noweb no-export or similar 
2) and the possibility to include source block names in export

- Andreas

Re: :noweb header argument

[Eric S Fraga]

"Sebastien Vauban" <wxhgmqzgwmuf@spammotel.com> writes:

[...]

> Some time after that, we had block names in the HTML/PDF output, but not
> anymore.

I've been wondering about this for some time.  The appearance of source
code block names in exported latex output comes and goes in what appears
to me as a random process!  Personally, I don't want these names
exported *ever* as they cause problems with latex, my usual target,
especially because the # sign is interpreted by latex as an argument to
a macro which typically doesn't make sense.

My most recent use of exporting code blocks has not included the names,
so I'm happy.  However, only a couple of weeks ago, the names were
exported.  That was for a different file so maybe my settings were
different?

It would be nice to have some clarity on when names will appear or not
and how this can be controlled.  I've looked at the manual but have not
found any reference to how code block names are treated on export.  Any
pointers would be most welcome!

Thanks,
eric

PS - apologies for possibly hijacking this thread.

-- 
: Eric S Fraga (GnuPG: 0xC89193D8FFFCF67D) in Emacs 24.0.92.1
: using Org-mode version 7.8.03 (release_7.8.03.67.g56c73)

Re: :noweb header argument

[Thomas S. Dye]

Hi Seb,

"Sebastien Vauban" <wxhgmqzgwmuf@spammotel.com> 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. 


>> | tangle | -    | +      | -      |
>> |--------+------+--------+--------|
>> | need   | +    | +      | -      |
>>
>> 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.

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

Re: :noweb header argument

[Eric Schulte]

tsd@tsdye.com (Thomas S. Dye) writes:

> Hi Seb,
>
> "Sebastien Vauban" <wxhgmqzgwmuf@spammotel.com> 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?

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

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

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/

Re: :noweb header argument

[Thomas S. Dye]

Hi Eric,

Eric Schulte <eric.schulte@gmx.com> writes:

> tsd@tsdye.com (Thomas S. Dye) writes:
>
>> Hi Seb,
>>
>> "Sebastien Vauban" <wxhgmqzgwmuf@spammotel.com> 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

Re: :noweb header argument

[Sebastien Vauban]

Hi Thomas, Eric(s) and all,

Thomas S. Dye wrote:
> Eric Schulte <eric.schulte-KK0ffGbhmjU@public.gmane.org> writes:
>> tsd-P0awH739Ni4AvxtiuMwx3w@public.gmane.org (Thomas S. Dye) writes:
>>> "Sebastien Vauban" <wxhgmqzgwmuf-geNee64TY+gS+FvcfC7Uqw@public.gmane.org> 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

Re: :noweb header argument

[Eric S Fraga]

"Sebastien Vauban" <wxhgmqzgwmuf@spammotel.com> writes:

> Hi Thomas, Eric(s) and all,

Hi Sebastien,

[...]

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

I agree although this doesn't preclude target specific customisation
variables; it just means that each target would have to have its own
variable.  Maybe less aesthetically pleasing than a single org
intermediary but possibly easier to use...

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

Well, my case is the opposite!  I seldom want the names in the exported
output.  That's partly because I tend to name *every* code
block.  First, I use yasnippet to insert code blocks and it prompts for
the name; second, I find it good practice as I never know if or when I
might actually want to refer to the code block so naming as I go along
is most convenient; third, most importantly, it makes it possible to
jump to code blocks quickly in a large file!

> Without knowing what it implies, I'd find an extra option rather sexy,
> something such as:
>
> #+OPTIONS:   H:4 num:nil noweb-names:t

I would be happy with this!

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

It would be nice but, at least for my use case, not necessary.

-- 
: Eric S Fraga (GnuPG: 0xC89193D8FFFCF67D) in Emacs 24.0.90.1
: using Org-mode version 7.8.03 (release_7.8.03.76.ga9c15)

Re: :noweb header argument

[Eric Schulte]

[-- Attachment #1: Type: text/plain, Size: 1267 bytes --]

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

I've just pushed up a minor code change which makes customization of the
format of exported code blocks possible.  I've added a new customization
variable named `org-babel-exp-code-template' which can be used to
specify the text which replaces code block bodies during export.  The
default value of this variable specifies the existing export behavior.
The attached Org-mode file demonstrates this variable in action.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: export-names.org --]
[-- Type: text/x-org, Size: 842 bytes --]

#+Title: Custom code block export formats

- Example code block
  #+Name: foo
  #+BEGIN_SRC sh :bar baz
    echo qux
  #+END_SRC

- Evaluate this block to export (shows the export of the name).
  #+Name: do-export-name
  #+BEGIN_SRC emacs-lisp :results silent
    (let ((org-babel-exp-code-template
           "\n=%name=:\n#+BEGIN_SRC %lang%flags\n%body\n#+END_SRC"))
      (org-export-as-html nil))
  #+END_SRC

- Evaluate this block to export (shows the export of header arguments).
  #+Name: do-export-header-arguments
  #+BEGIN_SRC emacs-lisp :results silent
    (let ((org-babel-exp-code-template
           "Header arguments for =%name=.
    | header  | value    |
    |---------+----------|
    | bar     | %bar     |
    | results | %results |\n#+BEGIN_SRC %lang%flags\n%body\n#+END_SRC"))
      (org-export-as-html nil))
  #+END_SRC

[-- Attachment #3: Type: text/plain, Size: 2063 bytes --]


I imagine that this variable would likely be customized on a
file-by-file basis using "file local variables".

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

Sounds like a very cool project.  If this will be public I would love to
link to it from [1] when it is complete.

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

This new solution replaces the code block with Org-mode text before
export.  This should be the most flexible as arbitrary #+HTML and
#+LATEX lines can be used in Org-mode.

Best,

Footnotes: 
[1]  http://orgmode.org/worg/org-contrib/babel/uses.html

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/

Re: :noweb header argument

[Thomas S. Dye]

Eric Schulte <eric.schulte@gmx.com> writes:

>>>> 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.
>>>
>
> I've just pushed up a minor code change which makes customization of the
> format of exported code blocks possible.  I've added a new customization
> variable named `org-babel-exp-code-template' which can be used to
> specify the text which replaces code block bodies during export.  The
> default value of this variable specifies the existing export behavior.
> The attached Org-mode file demonstrates this variable in action.
>
>
> #+Title: Custom code block export formats
>
> - Example code block
>   #+Name: foo
>   #+BEGIN_SRC sh :bar baz
>     echo qux
>   #+END_SRC
>
> - Evaluate this block to export (shows the export of the name).
>   #+Name: do-export-name
>   #+BEGIN_SRC emacs-lisp :results silent
>     (let ((org-babel-exp-code-template
>            "\n=%name=:\n#+BEGIN_SRC %lang%flags\n%body\n#+END_SRC"))
>       (org-export-as-html nil))
>   #+END_SRC
>
> - Evaluate this block to export (shows the export of header arguments).
>   #+Name: do-export-header-arguments
>   #+BEGIN_SRC emacs-lisp :results silent
>     (let ((org-babel-exp-code-template
>            "Header arguments for =%name=.
>     | header  | value    |
>     |---------+----------|
>     | bar     | %bar     |
>     | results | %results |\n#+BEGIN_SRC %lang%flags\n%body\n#+END_SRC"))
>       (org-export-as-html nil))
>   #+END_SRC
>
>
> I imagine that this variable would likely be customized on a
> file-by-file basis using "file local variables".
>
>>>
>>> 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.
>>>
>
> Sounds like a very cool project.  If this will be public I would love to
> link to it from [1] when it is complete.
>
>>>
>>> 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.
>
> This new solution replaces the code block with Org-mode text before
> export.  This should be the most flexible as arbitrary #+HTML and
> #+LATEX lines can be used in Org-mode.
>
> Best,
>
> Footnotes: 
> [1]  http://orgmode.org/worg/org-contrib/babel/uses.html

Hi Eric,

Many thanks.  This works like a charm.  It is deeply satisfying to find
my code block names in the book's "List of listings".

I really appreciate your attention to these details.

All the best,
Tom


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

Re: :noweb header argument

[Eric Schulte]

tsd@tsdye.com (Thomas S. Dye) writes:

> Eric Schulte <eric.schulte@gmx.com> writes:
>
>>>>> 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.
>>>>
>>
>> I've just pushed up a minor code change which makes customization of the
>> format of exported code blocks possible.  I've added a new customization
>> variable named `org-babel-exp-code-template' which can be used to
>> specify the text which replaces code block bodies during export.  The
>> default value of this variable specifies the existing export behavior.
>> The attached Org-mode file demonstrates this variable in action.
>>
>>
>> #+Title: Custom code block export formats
>>
>> - Example code block
>>   #+Name: foo
>>   #+BEGIN_SRC sh :bar baz
>>     echo qux
>>   #+END_SRC
>>
>> - Evaluate this block to export (shows the export of the name).
>>   #+Name: do-export-name
>>   #+BEGIN_SRC emacs-lisp :results silent
>>     (let ((org-babel-exp-code-template
>>            "\n=%name=:\n#+BEGIN_SRC %lang%flags\n%body\n#+END_SRC"))
>>       (org-export-as-html nil))
>>   #+END_SRC
>>
>> - Evaluate this block to export (shows the export of header arguments).
>>   #+Name: do-export-header-arguments
>>   #+BEGIN_SRC emacs-lisp :results silent
>>     (let ((org-babel-exp-code-template
>>            "Header arguments for =%name=.
>>     | header  | value    |
>>     |---------+----------|
>>     | bar     | %bar     |
>>     | results | %results |\n#+BEGIN_SRC %lang%flags\n%body\n#+END_SRC"))
>>       (org-export-as-html nil))
>>   #+END_SRC
>>
>>
>> I imagine that this variable would likely be customized on a
>> file-by-file basis using "file local variables".
>>
>>>>
>>>> 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.
>>>>
>>
>> Sounds like a very cool project.  If this will be public I would love to
>> link to it from [1] when it is complete.
>>
>>>>
>>>> 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.
>>
>> This new solution replaces the code block with Org-mode text before
>> export.  This should be the most flexible as arbitrary #+HTML and
>> #+LATEX lines can be used in Org-mode.
>>
>> Best,
>>
>> Footnotes: 
>> [1]  http://orgmode.org/worg/org-contrib/babel/uses.html
>
> Hi Eric,
>
> Many thanks.  This works like a charm.  It is deeply satisfying to find
> my code block names in the book's "List of listings".
>
> I really appreciate your attention to these details.
>

Great to hear, Thanks Tom.

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/

Re: :noweb header argument

[Eric S Fraga]

Eric Schulte <eric.schulte@gmx.com> writes:

[...]

> I've just pushed up a minor code change which makes customization of the
> format of exported code blocks possible.  I've added a new
> customization

I'm coming late to this but just wanted to say thanks!  This is very
nice indeed.

-- 
: Eric S Fraga (GnuPG: 0xC89193D8FFFCF67D) in Emacs 24.0.92.1
: using Org-mode version 7.8.03 (release_7.8.03.147.g3c4a)

Re: :noweb header argument

[Yagnesh Raghava Yakkala]

Eric S Fraga <e.fraga@ucl.ac.uk> writes:

> Eric Schulte <eric.schulte@gmx.com> writes:
>
> [...]
>
|> I've just pushed up a minor code change which makes customization of the
|> format of exported code blocks possible.  I've added a new
|> customization
>
> I'm coming late to this but just wanted to say thanks!  This is very
> nice indeed.

Yes, this is very useful.
now I can simply put
(setq org-babel-exp-code-template
 "``` %lang %name
%body
```")

to have source code highlighted with Pygments in Jekyll site generation
instead of placing an export-hook to clean all "<pre>" elements which is
very much error prone.

--
YYR

Re: :noweb header argument

[Eric Schulte]

>>>>> | tangle | -    | +      | -      |
>>>>> |--------+------+--------+--------|
>>>>> | need   | +    | +      | -      |
>>>>>
>>
>> What should the name for such an option be?
>>
>
> Andreas' suggestion, :noweb no-export, seems right to me.
>

Me too,

I've just pushed up a patch adding a "no-export" option to the :noweb
header argument.  If I could be so bold as to impose on you for a
correlate documentation patch... :)

-- 
Eric Schulte
http://cs.unm.edu/~eschulte/

Re: :noweb header argument

[Eric S Fraga]

Eric Schulte <eric.schulte@gmx.com> writes:

> tsd@tsdye.com (Thomas S. Dye) writes:

[...]

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

There is some precedence for having target specific customisations, even
if that is not a pretty approach.  As an example that has come up
recently, and one that I was just using a few minutes ago (!), we have

,----[ C-h v org-export-latex-timestamp-markup RET ]
| org-export-latex-timestamp-markup is a variable defined in `org-latex.el'.
| Its value is "\\hfill Action created or updated: %s"
| Original value was "\\textit{%s}"
| 
| Documentation:
| A printf format string to be applied to time stamps.
| 
| You can customize this variable.
| 
| [back]
`----

Although I can see the benefit of a generic intermediate step, I am of
the belief that target specific markups are going to be more powerful
and likely more useful...

Just my two ¢.

-- 
: Eric S Fraga (GnuPG: 0xC89193D8FFFCF67D) in Emacs 24.0.92.1
: using Org-mode version 7.8.03 (release_7.8.03.73.gd2b3d)