Re: [Orgmode] [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code

[Eric Schulte]

Hi Erik,

explanation below

Erik Iverson <address@hidden> 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