* Re: A tool for creating source code files from example and src blocks in org files
@ 2009-06-03 13:27 Eric H. Neilsen, Jr.
0 siblings, 0 replies; 6+ messages in thread
From: Eric H. Neilsen, Jr. @ 2009-06-03 13:27 UTC (permalink / raw)
To: emacs-orgmode
Chris,
Yes, I am also unhappy with the use of numbering to order chunks, but
the traditional LP mechanism of using substitution of named chunks has
some major flaws I have not figured out how to address.
The basic problem is that it can be used as a mechanism for code reuse,
probably will be if it is present. This is not necessary (code reuse
like this probably means poor use of the code reuse mechanisms of the
programming language in any case), hides the fact that the code is
reused from debugging and performance tools that rely on the source
code, and makes the task of untangling much harder, and impossible to
completely automate. Consider a program in which the same chunk appears
twice in the tangled source code. Using a debugger, you find a bug in
the chunk. You fix it in the source code, but only in one place. You
then find another bug, or even the same bug in a different guise, and
fix it differently in the other appearance. What is the untangler
supposed to do with the result? Which new version do you want? Do you
want the changes merged? Do you actually want both versions, and if so,
how does it edit the org-mode document to include them?
Yes, I know, from an LP purists point of view, the untangler is an
abomination. Unfortunately, few (if any) code development tools
(debuggers, performance analyzers, etc.) support debugging or analysis
of source code embedded in CWEB, noweb, or org-mode text files. This, to
me, is a deal-breaker. With an untangle command, I can write my code in
an org-mode file, tangle it and get emacs buffers with all C, headers,
makefiles, java, or whatever code in it, use emacs's extensive code
development tools (eg the emacs front end to gdb) to build and debug it,
and pull the source code back into the org-mode file when the bugs are
fixed. In fact, the code development tools do not even need to be
embedded in emacs; anything tools can look at a traditional source file
becomes useful.
There is an additional problem, although one that can be solved by "just
doing more work." At present, org-tangle can use the existing org-mode
export code to do all necessary weaving. org-mode, in turn, takes
advantage of the many independently supported modes for each language to
format them properly. If we introduce a new syntax (for substitution)
inside the literal blocks, it means that we will need an org-weave that
can properly format each language. I am not sure how practical this is;
I am certainly not that ambitious.
It may be a little while before my itself makes an appearance. Not only
do I need to wait for my employer to figure the legal stuff, I have also
received enough feedback that I want to address issues better before
anyone else is tempted to use the code.
-Eric
--
Eric H. Neilsen, Jr.
http://home.fnal.gov/~neilsen
^ permalink raw reply [flat|nested] 6+ messages in thread
* A tool for creating source code files from example and src blocks in org files
@ 2009-06-02 18:50 Eric H. Neilsen, Jr.
2009-06-03 8:53 ` Chris Gray
2009-06-16 14:03 ` Bastien
0 siblings, 2 replies; 6+ messages in thread
From: Eric H. Neilsen, Jr. @ 2009-06-02 18:50 UTC (permalink / raw)
To: emacs-orgmode
Hi,
First, thank you Carsten and others, for putting this thing together;
org-mode is the most useful tool I've run across in a long time.
I recently put together a few commands to create source code files from
SRC and EXAMPLE blocks in org-mode files. The original idea is to be
able to compile examples in my notes without needing to merge them into
a separate source file by hand. As I was writing it I realized this is
exactly the same tool one needs to turn org-mode into a literate
programming tool (see http://www.literateprogramming.com/ ), so I
adopted some of the nomenclature. (I tried literate programming a few
years ago, and gave up in frustration with the tools. I am tempted to
try again with org-mode.)
The two user level commands are org-tangle and org-untangle, best
explained through example. Running org-tangle in a buffer that looks
like this:
---------------------- begin /tmp/test.org ---------------------------
* Some file
Some text here
#+CHUNK file1.sh 1
#+BEGIN_SRC bash
echo "line 1"
echo "line 2"
#+END_SRC
more text
** Some subsection
#+CHUNK file1.sh 2
#+BEGIN_SRC bash
echo "line 5"
echo "line 6"
#+END_SRC
blah blah blah
#+CHUNK README.txt 1
#+BEGIN_EXAMPLE
text line 1
text line 2
text line 3
#+END_EXAMPLE
foo foo bar baz
#+CHUNK file1.sh 1.5
#+BEGIN_SRC bash
echo "line 3"
echo "line 4"
#+END_SRC
-------------- end /tmp/test.org ----------------
results in the creation of these two files, opened in emacs buffers:
------------- begin /tmp/file1.sh ----------------
# ORGCHUNK /tmp/test.org 1
echo "line 1"
echo "line 2"
# ORGCHUNK /tmp/test.org 1.5
echo "line 3"
echo "line 4"
# ORGCHUNK /tmp/test.org 2
echo "line 5"
echo "line 6"
------------- end /tmp/file1.sh ---------------------
and
------------ begin /tmp/README.txt -------------
text line 1
text line 2
text line 3
------------ end /tmp/README.txt ---------------
If you then edit file1.sh and run org-untangle in the buffer, changes to
it will overwrite the literal blocks in the org-mode file from whence
they came.
Is there any interest in this? My organization's rules for releasing
code to open source projects are being revised, but I am likely to be
able to do so under a BSD-like license. If there is interest, I will
push to try and figure out how to do this, and maybe even see if I can
do the assignment of copyright stuff needed for it to get under the main
umbrella (although I am not optimistic).
(If anyone feels like rewriting it, that would be even better; aside
from a fairly straightforward .emacs, this is my first ever lisp code,
so it is likely to need cleaning and refactoring.)
-Eric
--
Eric H. Neilsen, Jr.
http://home.fnal.gov/~neilsen
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: A tool for creating source code files from example and src blocks in org files
2009-06-02 18:50 Eric H. Neilsen, Jr.
@ 2009-06-03 8:53 ` Chris Gray
2009-06-16 14:03 ` Bastien
1 sibling, 0 replies; 6+ messages in thread
From: Chris Gray @ 2009-06-03 8:53 UTC (permalink / raw)
To: emacs-orgmode
Eric H. Neilsen, Jr. wrote:
> Hi,
> First, thank you Carsten and others, for putting this thing together;
> org-mode is the most useful tool I've run across in a long time.
> I recently put together a few commands to create source code files
> from SRC and EXAMPLE blocks in org-mode files. The original idea is to
> be able to compile examples in my notes without needing to merge them
> into a separate source file by hand. As I was writing it I realized
> this is exactly the same tool one needs to turn org-mode into a
> literate programming tool (see http://www.literateprogramming.com/ ),
> so I adopted some of the nomenclature. (I tried literate programming a
> few years ago, and gave up in frustration with the tools. I am tempted
> to try again with org-mode.)
I was just thinking that literate programming and org-mode would go
great together.
> The two user level commands are org-tangle and org-untangle, best
> explained through example. Running org-tangle in a buffer that looks
> like this:
> ---------------------- begin /tmp/test.org ---------------------------
> * Some file
> Some text here
> #+CHUNK file1.sh 1
I think using numbers to order the chunks is probably not the best
idea. When I wrote the one small program I wrote with literate
programming, I really liked being able to write pseudocode with the chunks
that get substituted. Like this (admittedly poor example):
def fib(n):
<<find fib_{n - 2}>>
<<find fib_{n - 1}>>
<<return the sum>>
<<find fib_{n - 2}>>=
f2 = fib(n - 2)
<<find fib_{n - 1}>>=
f1 = fib(n - 1)
<<return the sum>>=
return f2 + f1
> Is there any interest in this? My organization's rules for releasing
> code to open source projects are being revised, but I am likely to be
> able to do so under a BSD-like license. If there is interest, I will
> push to try and figure out how to do this, and maybe even see if I can
> do the assignment of copyright stuff needed for it to get under the
> main umbrella (although I am not optimistic).
If you put it in a git repo somewhere, I will put some time aside for
it.
Cheers,
Chris
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: A tool for creating source code files from example and src blocks in org files
2009-06-02 18:50 Eric H. Neilsen, Jr.
2009-06-03 8:53 ` Chris Gray
@ 2009-06-16 14:03 ` Bastien
2009-06-26 19:15 ` Eric Schulte
1 sibling, 1 reply; 6+ messages in thread
From: Bastien @ 2009-06-16 14:03 UTC (permalink / raw)
To: Eric H. Neilsen, Jr.; +Cc: emacs-orgmode
"Eric H. Neilsen, Jr." <neilsen@fnal.gov> writes:
> Is there any interest in this?
Yes. It's been a long time I want to use Org for literate programming,
I think it's just the right tool to do this.
Please send any code we can test!
> (If anyone feels like rewriting it, that would be even better; aside
> from a fairly straightforward .emacs, this is my first ever lisp code,
> so it is likely to need cleaning and refactoring.)
I may help if I have some time.
--
Bastien
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: A tool for creating source code files from example and src blocks in org files
2009-06-16 14:03 ` Bastien
@ 2009-06-26 19:15 ` Eric Schulte
2009-06-27 20:31 ` Eric Schulte
0 siblings, 1 reply; 6+ messages in thread
From: Eric Schulte @ 2009-06-26 19:15 UTC (permalink / raw)
To: Bastien; +Cc: emacs-orgmode
Bastien <bastienguerry@googlemail.com> writes:
> "Eric H. Neilsen, Jr." <neilsen@fnal.gov> writes:
>
>> Is there any interest in this?
>
> Yes. It's been a long time I want to use Org for literate programming,
> I think it's just the right tool to do this.
>
> Please send any code we can test!
>
>> (If anyone feels like rewriting it, that would be even better; aside
>> from a fairly straightforward .emacs, this is my first ever lisp code,
>> so it is likely to need cleaning and refactoring.)
>
> I may help if I have some time.
I have started re-implementing this as part of org-babel [1], please
checkout the "tangle" branch [2] of org-babel for source-code and more
information.
Cheers -- Eric
Footnotes:
[1] http://github.com/eschulte/org-babel/tree/master
[2] http://github.com/eschulte/org-babel/tree/tangle
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: A tool for creating source code files from example and src blocks in org files
2009-06-26 19:15 ` Eric Schulte
@ 2009-06-27 20:31 ` Eric Schulte
0 siblings, 0 replies; 6+ messages in thread
From: Eric Schulte @ 2009-06-27 20:31 UTC (permalink / raw)
To: Bastien; +Cc: emacs-orgmode
"Eric Schulte" <schulte.eric@gmail.com> writes:
> Bastien <bastienguerry@googlemail.com> writes:
>
>> "Eric H. Neilsen, Jr." <neilsen@fnal.gov> writes:
>>
>>> Is there any interest in this?
>>
>> Yes. It's been a long time I want to use Org for literate programming,
>> I think it's just the right tool to do this.
>>
>> Please send any code we can test!
>>
>>> (If anyone feels like rewriting it, that would be even better; aside
>>> from a fairly straightforward .emacs, this is my first ever lisp code,
>>> so it is likely to need cleaning and refactoring.)
>>
>> I may help if I have some time.
>
> I have started re-implementing this as part of org-babel [1], please
> checkout the "tangle" branch [2] of org-babel for source-code and more
> information.
>
This tangle implementation has now reached an initial level of
functionality. It is able to extract blocks from an org-mode file by
language and by session (which has a specific meaning in org-babel) and
create source-code files.
This doesn't yet have support for fine-grained control for inserting
into specific locations of source-code files, and I'm not familiar
enough with literate programming to know the best way to structure such
support.
This is now merged into the master branch of org-babel. To give it a
try, open the test-tangle.org file in the base of the repo, and run
`org-babel-tangle'.
Best -- Eric
>
> Cheers -- Eric
>
> Footnotes:
> [1] http://github.com/eschulte/org-babel/tree/master
>
> [2] http://github.com/eschulte/org-babel/tree/tangle
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2009-06-27 20:31 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2009-06-03 13:27 A tool for creating source code files from example and src blocks in org files Eric H. Neilsen, Jr.
-- strict thread matches above, loose matches on Subject: below --
2009-06-02 18:50 Eric H. Neilsen, Jr.
2009-06-03 8:53 ` Chris Gray
2009-06-16 14:03 ` Bastien
2009-06-26 19:15 ` Eric Schulte
2009-06-27 20:31 ` Eric Schulte
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).