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

["Thomas S. Dye" <tsd@tsdye.com>]

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