[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Orgmode] [babel] `org-babel-tangle-w-comments' controls comment ins
Thomas S. Dye
Re: [Orgmode] [babel] `org-babel-tangle-w-comments' controls comment insertion in tangled code
Fri, 28 May 2010 08:08:37 -1000
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,
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
I say this is that even if I write my code in org-mode, and in
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
ASCII export -- this would have the effect of prefixing every line in
the org-mode file behind a comment *except* for the tangled source-
Implementation wise I'm not sure how easy/difficult this would be,
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:
These (sub)trees would then appear as comments in their respective
tangled source files in whatever order they appear in the org-mode
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. :)
Emacs-orgmode mailing list
Please use `Reply All' to send replies to the list.