From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Thomas S. Dye" Subject: Re: [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code Date: Fri, 28 May 2010 08:08:37 -1000 Message-ID: <88DCAA98-9A9A-4010-807F-2430121BAF22@tsdye.com> References: <87sk5c8497.fsf@gmail.com> <4BFFE4A7.9070300@ccbr.umn.edu> <878w746mul.fsf@gmail.com> <4BFFEE4F.5010608@ccbr.umn.edu> Mime-Version: 1.0 (Apple Message framework v936) Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes Content-Transfer-Encoding: 7bit Return-path: Received: from [140.186.70.92] (port=52271 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OI3zH-0001Yg-Up for emacs-orgmode@gnu.org; Fri, 28 May 2010 14:08:54 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OI3z9-0003kp-Ng for emacs-orgmode@gnu.org; Fri, 28 May 2010 14:08:46 -0400 Received: from oproxy2-pub.bluehost.com ([67.222.39.60]:50982 helo=outbound-mail-360.bluehost.com) by eggs.gnu.org with smtp (Exim 4.69) (envelope-from ) id 1OI3z9-0003jh-GA for emacs-orgmode@gnu.org; Fri, 28 May 2010 14:08:43 -0400 In-Reply-To: <4BFFEE4F.5010608@ccbr.umn.edu> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org 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