* [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code
@ 2010-05-28 14:55 Eric Schulte
2010-05-28 15:43 ` Erik Iverson
0 siblings, 1 reply; 9+ messages in thread
From: Eric Schulte @ 2010-05-28 14:55 UTC (permalink / raw)
To: Org Mode
Hi,
The insertion of automatically generated comments in tangled source code
is now controlled by the new `org-babel-tangle-w-comments' variable.
Setting this variable to non-nil will allow org-babel to insert comments
for those languages with comment support.
This changes the default behavior. The default value for this variable
is nil -- previously these comments were always inserted, now they are
only inserted after setting `org-babel-tangle-w-comments' to a non-nil
value.
Best -- Eric
,----[commit ff58dacc7ca83c07cd6a57eccda3a55e20019d95]
| babel: `org-babel-tangle-w-comments' controls comment insertion in tangled code
|
| * contrib/babel/lisp/org-babel-tangle.el (org-babel-spec-to-string):
| The insertion of automatically generated comments into tangled code
| is now customizable through the `org-babel-tangle-w-comments'
| variable.
`----
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code
2010-05-28 14:55 [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code Eric Schulte
@ 2010-05-28 15:43 ` Erik Iverson
2010-05-28 15:47 ` Erik Iverson
2010-05-28 15:57 ` Eric Schulte
0 siblings, 2 replies; 9+ messages in thread
From: Erik Iverson @ 2010-05-28 15:43 UTC (permalink / raw)
To: Eric Schulte; +Cc: Org Mode
Eric Schulte wrote:
> Hi,
>
> The insertion of automatically generated comments in tangled source code
> is now controlled by the new `org-babel-tangle-w-comments' variable.
> Setting this variable to non-nil will allow org-babel to insert comments
> for those languages with comment support.
Can you briefly elaborate on what this means? I'm used to seeing, when
I tangle an R file, something like:
##
[[file:~/private/R-org-babel/test.org::*cube%20lets%20go%20to%20the][block-2]]
cube <- function(x) {
# a test comment
x * x * x * x
}
## block-2 ends here
So, you mean that all three of the comments would no longer appear by
default? Or you mean that only my inline function comment would not
appear?
One more idea I had was that it might be interesting to be able to
maintain properties for headlines that indicate the headline/body should
be included as a comment in a specific source file. The reason I say
this is that even if I write my code in org-mode, and in effect comment
the code using org-mode constructs like headlines and free text, someone
who just wants the tangled file might want to see comments, for example,
function headers or something like that.
Any thoughts on that?
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code
2010-05-28 15:43 ` Erik Iverson
@ 2010-05-28 15:47 ` Erik Iverson
2010-05-28 15:57 ` Eric Schulte
1 sibling, 0 replies; 9+ messages in thread
From: Erik Iverson @ 2010-05-28 15:47 UTC (permalink / raw)
To: Eric Schulte; +Cc: Org Mode
> ##
> [[file:~/private/R-org-babel/test.org::*cube%20lets%20go%20to%20the][block-2]]
>
>
> cube <- function(x) {
> # a test comment
> x * x * x * x
> }
> ## block-2 ends here
>
> So, you mean that all three of the comments would no longer appear by
> default? Or you mean that only my inline function comment would not
> appear?
Re-reading your post, I think maybe perhaps only my inline comment would
*appear*. If this is true, I like the idea.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code
2010-05-28 15:43 ` Erik Iverson
2010-05-28 15:47 ` Erik Iverson
@ 2010-05-28 15:57 ` Eric Schulte
2010-05-28 16:24 ` Erik Iverson
1 sibling, 1 reply; 9+ messages in thread
From: Eric Schulte @ 2010-05-28 15:57 UTC (permalink / raw)
To: Erik Iverson; +Cc: Org Mode
Hi Erik,
explanation below
Erik Iverson <eriki@ccbr.umn.edu> writes:
> Eric Schulte wrote:
>> Hi,
>>
>> The insertion of automatically generated comments in tangled source code
>> is now controlled by the new `org-babel-tangle-w-comments' variable.
>> Setting this variable to non-nil will allow org-babel to insert comments
>> for those languages with comment support.
>
> Can you briefly elaborate on what this means? I'm used to seeing,
> when I tangle an R file, something like:
>
> ## [[file:~/private/R-org-babel/test.org::*cube%20lets%20go%20to%20the][block-2]]
>
> cube <- function(x) {
> # a test comment
> x * x * x * x
> }
> ## block-2 ends here
>
what was previously exported as
will now be exported as
--8<---------------cut here---------------start------------->8---
cube <- function(x) {
# a test comment
x * x * x * x
}
--8<---------------cut here---------------end--------------->8---
unless the `org-babel-tangle-w-comments' variable is set to a non-nil
value.
>
> So, you mean that all three of the comments would no longer appear by
> default? Or you mean that only my inline function comment would not
> appear?
>
The outer two comments of
## [[file:~/private/R-org-babel/test.org::*cube%20lets%20go%20to%20the][block-2]]
and
## block-2 ends here
will not appear. Your own comments inside of the source-code block will
still appear. Is that clear? Thanks for pointing out the insufficient
explanation.
>
> One more idea I had was that it might be interesting to be able to
> maintain properties for headlines that indicate the headline/body
> should be included as a comment in a specific source file. The reason
> I say this is that even if I write my code in org-mode, and in effect
> comment the code using org-mode constructs like headlines and free
> text, someone who just wants the tangled file might want to see
> comments, for example, function headers or something like that.
>
> Any thoughts on that?
Yes, that sounds like a good idea.
Maybe we should allow either exporting just the headlines of the
org-mode file or exporting the entire org-mode file -- possibly after an
ASCII export -- this would have the effect of prefixing every line in
the org-mode file behind a comment *except* for the tangled source-code
blocks.
Implementation wise I'm not sure how easy/difficult this would be, but I
definitely think it's worth looking into.
Have I understood your suggestion?
Best -- Eric
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code
2010-05-28 15:57 ` Eric Schulte
@ 2010-05-28 16:24 ` Erik Iverson
2010-05-28 18:08 ` Thomas S. Dye
0 siblings, 1 reply; 9+ messages in thread
From: Erik Iverson @ 2010-05-28 16:24 UTC (permalink / raw)
To: Eric Schulte; +Cc: Org Mode
>> One more idea I had was that it might be interesting to be able to
>> maintain properties for headlines that indicate the headline/body
>> should be included as a comment in a specific source file. The reason
>> I say this is that even if I write my code in org-mode, and in effect
>> comment the code using org-mode constructs like headlines and free
>> text, someone who just wants the tangled file might want to see
>> comments, for example, function headers or something like that.
>>
> Maybe we should allow either exporting just the headlines of the
> org-mode file or exporting the entire org-mode file -- possibly after an
> ASCII export -- this would have the effect of prefixing every line in
> the org-mode file behind a comment *except* for the tangled source-code
> blocks.
>
> Implementation wise I'm not sure how easy/difficult this would be, but I
> definitely think it's worth looking into.
>
> Have I understood your suggestion?
Yes, your idea about prefixing every line in the org file behind a
comment except for the tangled code was the initial idea in my head. I
then thought that there may be several different languages of code in an
org-mode file, and even if there is only one language, the tangling of
that file could be generating multiple source files, for example, one
per function. In addition, some of the org-mode material I have in my
file might not relate to a commented source file, per se. For example,
the org-mode file where I maintain my source for a function might have
links to emails discussing the implementation, or internal dialogs
relating to alternative approaches that were abandoned.
So, I thought it might be neat to have some way of specifying which
subtrees would be a part of the comments for a source file, and for
which tangled file. My guess as the easiest way to do that would be
through properties. That is, you'd set a property for (sub)tree like,
for example:
:PROPERTIES:
:SrcComment: Yes
:SrcCommentTangleFile: cube.R
:SrcCommentCharacter: ##
:END:
These (sub)trees would then appear as comments in their respective
tangled source files in whatever order they appear in the org-mode file.
Why am I suggesting this?
People obviously like commented code. Writing a function in org-babel,
I am in effect using org-mode as the commenting system. Giving someone
who does not use Emacs an org-mode file to see how something was
implemented is not going to fly, to say the least :). Giving them the
tangled version of the code along with, say, an HTML export of the
org-mode buffer is a good start. But if they're used to reviewing code
in the typical, "just send me the source file" manner, they would
appreciate comments in the code. This is one way they could be
automatically generated from org-mode/org-babel, which is, in my mind,
the ideal.
As I'm sure you have plenty to do, I would be happy to take a look at
this. I'll give the requisite "I'm just getting started with elisp ..."
warning though. :)
Thanks!
Erik
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code
2010-05-28 16:24 ` Erik Iverson
@ 2010-05-28 18:08 ` Thomas S. Dye
2010-05-28 18:41 ` Erik Iverson
0 siblings, 1 reply; 9+ messages in thread
From: Thomas S. Dye @ 2010-05-28 18:08 UTC (permalink / raw)
To: Erik Iverson; +Cc: Org Mode
Hi Erik,
If the proposed functionality places comments in the source code in
whatever order they appear in the org-mode file, then the result will
likely frustrate literate programming efforts that rearrange code
blocks on tangling.
Another way to get pieces of the org-mode file into the source file as
comments might be with a little helper function, org-babel-copy-
subtree-to-commented-code. The source blocks could be named so the
literate programming facilities of org-babel could work with them.
All the best,
Tom
On May 28, 2010, at 6:24 AM, Erik Iverson wrote:
>
>>> One more idea I had was that it might be interesting to be able to
>>> maintain properties for headlines that indicate the headline/body
>>> should be included as a comment in a specific source file. The
>>> reason
>>> I say this is that even if I write my code in org-mode, and in
>>> effect
>>> comment the code using org-mode constructs like headlines and free
>>> text, someone who just wants the tangled file might want to see
>>> comments, for example, function headers or something like that.
>>>
>
>> Maybe we should allow either exporting just the headlines of the
>> org-mode file or exporting the entire org-mode file -- possibly
>> after an
>> ASCII export -- this would have the effect of prefixing every line in
>> the org-mode file behind a comment *except* for the tangled source-
>> code
>> blocks.
>> Implementation wise I'm not sure how easy/difficult this would be,
>> but I
>> definitely think it's worth looking into.
>> Have I understood your suggestion?
>
> Yes, your idea about prefixing every line in the org file behind a
> comment except for the tangled code was the initial idea in my
> head. I then thought that there may be several different languages
> of code in an org-mode file, and even if there is only one language,
> the tangling of that file could be generating multiple source files,
> for example, one per function. In addition, some of the org-mode
> material I have in my file might not relate to a commented source
> file, per se. For example, the org-mode file where I maintain my
> source for a function might have links to emails discussing the
> implementation, or internal dialogs relating to alternative
> approaches that were abandoned.
>
> So, I thought it might be neat to have some way of specifying which
> subtrees would be a part of the comments for a source file, and for
> which tangled file. My guess as the easiest way to do that would be
> through properties. That is, you'd set a property for (sub)tree
> like, for example:
>
> :PROPERTIES:
> :SrcComment: Yes
> :SrcCommentTangleFile: cube.R
> :SrcCommentCharacter: ##
> :END:
>
> These (sub)trees would then appear as comments in their respective
> tangled source files in whatever order they appear in the org-mode
> file.
>
> Why am I suggesting this?
>
> People obviously like commented code. Writing a function in org-
> babel, I am in effect using org-mode as the commenting system.
> Giving someone who does not use Emacs an org-mode file to see how
> something was implemented is not going to fly, to say the least :).
> Giving them the tangled version of the code along with, say, an HTML
> export of the org-mode buffer is a good start. But if they're used
> to reviewing code in the typical, "just send me the source file"
> manner, they would appreciate comments in the code. This is one way
> they could be automatically generated from org-mode/org-babel, which
> is, in my mind, the ideal.
>
> As I'm sure you have plenty to do, I would be happy to take a look
> at this. I'll give the requisite "I'm just getting started with
> elisp ..." warning though. :)
>
> Thanks!
> Erik
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code
2010-05-28 18:08 ` Thomas S. Dye
@ 2010-05-28 18:41 ` Erik Iverson
2010-05-28 19:17 ` Thomas S. Dye
0 siblings, 1 reply; 9+ messages in thread
From: Erik Iverson @ 2010-05-28 18:41 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: Org Mode
Thomas S. Dye wrote:
> Hi Erik,
>
> If the proposed functionality places comments in the source code in
> whatever order they appear in the org-mode file, then the result will
> likely frustrate literate programming efforts that rearrange code blocks
> on tangling.
Yes, thank you for pointing that out.
>
> Another way to get pieces of the org-mode file into the source file as
> comments might be with a little helper function,
> org-babel-copy-subtree-to-commented-code. The source blocks could be
> named so the literate programming facilities of org-babel could work
> with them.
I'm not following this; could you provide a minimal pseudo-example of
how you see this working in practice?
Thanks!
Erik
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code
2010-05-28 18:41 ` Erik Iverson
@ 2010-05-28 19:17 ` Thomas S. Dye
2010-06-17 3:57 ` Eric Schulte
0 siblings, 1 reply; 9+ messages in thread
From: Thomas S. Dye @ 2010-05-28 19:17 UTC (permalink / raw)
To: Erik Iverson; +Cc: Org Mode
Hi Erik,
I am *not* a programmer so expect considerable chaff for every kernel
of wheat (no wheat guaranteed).
I would pass the function an org-mode link then write out the contents
pointed at by the link inside a named code block, with each line
preceded by an optional comment character. If this were written in a
general way, then it would be possible to include comments from any
link--on-line manuals, standards, blogs, etc.--in addition to notes in
the org-mode file.
If it were written in a very general way, with a transformation
function responsible for adding the comment character, then a variety
of transformations might be possible.
I've followed the list long enough to recognize that musings like mine
are often met by the response that org-mode already does this. For
all I know, it does!
All the best,
Tom
On May 28, 2010, at 8:41 AM, Erik Iverson wrote:
>
>
> Thomas S. Dye wrote:
>> Hi Erik,
>> If the proposed functionality places comments in the source code in
>> whatever order they appear in the org-mode file, then the result
>> will likely frustrate literate programming efforts that rearrange
>> code blocks on tangling.
>
> Yes, thank you for pointing that out.
>
>> Another way to get pieces of the org-mode file into the source file
>> as comments might be with a little helper function, org-babel-copy-
>> subtree-to-commented-code. The source blocks could be named so the
>> literate programming facilities of org-babel could work with them.
>
> I'm not following this; could you provide a minimal pseudo-example
> of how you see this working in practice?
>
> Thanks!
> Erik
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code
2010-05-28 19:17 ` Thomas S. Dye
@ 2010-06-17 3:57 ` Eric Schulte
0 siblings, 0 replies; 9+ messages in thread
From: Eric Schulte @ 2010-06-17 3:57 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: Org Mode
Just to make sure we don't lose these idea, I've posed them up in the
babel dev repo
http://eschulte.github.com/babel-dev/PROPOSED-tangle-entire-org-mode-file-in-comments.html
Best -- Eric
"Thomas S. Dye" <tsd@tsdye.com> writes:
> Hi Erik,
>
> I am *not* a programmer so expect considerable chaff for every kernel
> of wheat (no wheat guaranteed).
>
> I would pass the function an org-mode link then write out the contents
> pointed at by the link inside a named code block, with each line
> preceded by an optional comment character. If this were written in a
> general way, then it would be possible to include comments from any
> link--on-line manuals, standards, blogs, etc.--in addition to notes in
> the org-mode file.
>
> If it were written in a very general way, with a transformation
> function responsible for adding the comment character, then a variety
> of transformations might be possible.
>
> I've followed the list long enough to recognize that musings like mine
> are often met by the response that org-mode already does this. For
> all I know, it does!
>
> All the best,
> Tom
>
> On May 28, 2010, at 8:41 AM, Erik Iverson wrote:
>
>>
>>
>> Thomas S. Dye wrote:
>>> Hi Erik,
>>> If the proposed functionality places comments in the source code in
>>> whatever order they appear in the org-mode file, then the result
>>> will likely frustrate literate programming efforts that rearrange
>>> code blocks on tangling.
>>
>> Yes, thank you for pointing that out.
>>
>>> Another way to get pieces of the org-mode file into the source file
>>> as comments might be with a little helper function, org-babel-copy-
>>> subtree-to-commented-code. The source blocks could be named so the
>>> literate programming facilities of org-babel could work with them.
>>
>> I'm not following this; could you provide a minimal pseudo-example
>> of how you see this working in practice?
>>
>> Thanks!
>> Erik
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2010-06-17 3:57 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2010-05-28 14:55 [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code Eric Schulte
2010-05-28 15:43 ` Erik Iverson
2010-05-28 15:47 ` Erik Iverson
2010-05-28 15:57 ` Eric Schulte
2010-05-28 16:24 ` Erik Iverson
2010-05-28 18:08 ` Thomas S. Dye
2010-05-28 18:41 ` Erik Iverson
2010-05-28 19:17 ` Thomas S. Dye
2010-06-17 3:57 ` Eric Schulte
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).