[PATCH] :wrap header documentation

[tsd@tsdye.com (Thomas S. Dye)]

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

Hi Eric,

Attached please find a first draft of a patch for the manual entry
documenting a :wrap header argument.

All the best,
Tom


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Manual patch --]
[-- Type: text/x-patch, Size: 2528 bytes --]

From 4e3a66a4fbfd8d6914fbfd3924981ae5c526aa4a Mon Sep 17 00:00:00 2001
From: Thomas Dye <dk@poto.myhome.westell.com>
Date: Wed, 11 Jan 2012 16:06:17 -1000
Subject: [PATCH] * doc/org.texi: added documentation for :wrap

---
 doc/org.texi |   12 +++++++++++-
 1 files changed, 11 insertions(+), 1 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index f619c90..7ca797b 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -715,6 +715,7 @@ Specific header arguments
 * rownames::                    Handle row names in tables
 * shebang::                     Make tangled files executable
 * eval::                        Limit evaluation of specific code blocks
+* wrap::                        Mark source block evaluation results
 
 Miscellaneous
 
@@ -13007,6 +13008,7 @@ argument in lowercase letters.  The following header arguments are defined:
 * rownames::                    Handle row names in tables
 * shebang::                     Make tangled files executable
 * eval::                        Limit evaluation of specific code blocks
+* wrap::                        Mark source block evaluation results
 @end menu
 
 Additional header arguments are defined on a language-specific basis, see
@@ -13865,7 +13867,7 @@ Setting the @code{:shebang} header argument to a string value
 first line of any tangled file holding the code block, and the file
 permissions of the tangled file are set to make it executable.
 
-@node eval,  , shebang, Specific header arguments
+@node eval, wrap, shebang, Specific header arguments
 @subsubsection @code{:eval}
 The @code{:eval} header argument can be used to limit the evaluation of
 specific code blocks.  The @code{:eval} header argument can be useful for
@@ -13890,6 +13892,14 @@ If this header argument is not set then evaluation is determined by the value
 of the @code{org-confirm-babel-evaluate} variable see @ref{Code evaluation
 security}.
 
+@node wrap, , eval, Specific header arguments
+@subsubsection @code{:wrap}
+The @code{:wrap} header argument is used to mark the results of source block
+evaluation.  The header argument can be passed a string that typically will
+be appended to @code{#+BEGIN_} and @code{#+END_}, which will then be used to
+wrap the results.  An exception to this rule is the string @code{drawer},
+which instead wraps the results in an Org mode drawer.
+
 @node Results of evaluation, Noweb reference syntax, Header arguments, Working With Source Code
 @section Results of evaluation
 @cindex code block, results of evaluation
-- 
1.7.5.4


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


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

> Eric Schulte <eric.schulte@gmx.com> writes:
>
>> Achim Gratz <Stromeko@nexgo.de> writes:
>>
>>> tsd@tsdye.com (Thomas S. Dye) writes:
>>>> The attached patch defines a new header argument, :special, which wraps
>>>> the results of Org babel source block execution in a #BEGIN_ ... #+END_
>>>> block.  The block name is taken from a new variable
>>>> org-babel-wrap-special, which is initialized as "results".
>>>
>>> What is the rationale for feeding the block name via a configuration
>>> variable rather then a value to the header argument ":special"?
>>>
>>>
>>> Regards,
>>> Achim.
>>
>> Attached is an alternate patch and an example of its use.  This patch
>> introduces a ":wrap" header argument which accepts an optional value
>> used to specify the name of the block with which to wrap results.  If
>> this looks workable we could push it up once it gets some documentation
>> and tests.
>>
>> Cheers,
>>
>>
>> #+Title: demonstrating the new :wrap header argument
>>
>> #+begin_src emacs-lisp :wrap schulte
>>   '((1 2)
>>     (3 4))
>> #+end_src
>>
>> #+results:
>> #+BEGIN_schulte
>> | 1 | 2 |
>> | 3 | 4 |
>> #+END_schulte
>
> Hi Eric,
>
> Thanks for the :wrap header argument.  It works for me.
>
> The attached patch on top of your patch looks for :wrap drawer, and puts
> the result in a drawer, rather than wrapping the results in #+begin
> ... #+end.
>
> What I'm trying to do is make :results wrap obsolete.
>
> Also, note that with the :wrap header argument, :results org and
> :results latex are both redundant.  I'm not sure how you want to handle
> this--whether to leave them in place or remove them.
>
> I'll volunteer to work on the documentation.
>
> All the best,
> Tom

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