From: "Thomas S. Dye" <tsd@tsdye.com>
To: Erik Iverson <eriki@ccbr.umn.edu>
Cc: Org Mode <emacs-orgmode@gnu.org>
Subject: Re: [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code
Date: Fri, 28 May 2010 08:08:37 -1000 [thread overview]
Message-ID: <88DCAA98-9A9A-4010-807F-2430121BAF22@tsdye.com> (raw)
In-Reply-To: <4BFFEE4F.5010608@ccbr.umn.edu>
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
next prev parent reply other threads:[~2010-05-28 18:08 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
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 [this message]
2010-05-28 18:41 ` Erik Iverson
2010-05-28 19:17 ` Thomas S. Dye
2010-06-17 3:57 ` Eric Schulte
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=88DCAA98-9A9A-4010-807F-2430121BAF22@tsdye.com \
--to=tsd@tsdye.com \
--cc=emacs-orgmode@gnu.org \
--cc=eriki@ccbr.umn.edu \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).