emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Erik Iverson <eriki@ccbr.umn.edu>
To: Eric Schulte <schulte.eric@gmail.com>
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 11:24:47 -0500	[thread overview]
Message-ID: <4BFFEE4F.5010608@ccbr.umn.edu> (raw)
In-Reply-To: <878w746mul.fsf@gmail.com>


>> 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

  reply	other threads:[~2010-05-28 16:24 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2010-05-28 14:55 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 [this message]
2010-05-28 18:08       ` Thomas S. Dye
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=4BFFEE4F.5010608@ccbr.umn.edu \
    --to=eriki@ccbr.umn.edu \
    --cc=emacs-orgmode@gnu.org \
    --cc=schulte.eric@gmail.com \
    /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).