Org-mode outside Org-mode

Org-mode outside Org-mode

[Thorsten Jolitz]

Hi List, 

there is a now a tutorial on Worg describing the recently announced new
libraries for using (concepts and functionality of) Org-mode when
outside Org-mode:

,-----------------------------------------------------------
| http://orgmode.org/worg/org-tutorials/org-outside-org.html
`-----------------------------------------------------------

Besides using the 'well-known' orgstruct-minor-mode, you can now:

- use outline-minor-mode with *outshine.el* extensions and structure
  your file with outshine-style headlines, giving your source-code files
  the look&feel of Org-mode files. Should work in any major-mode.

- use *outorg.el* to edit complete subtrees or the whole file as
  Org-mode in a temporary Org-mode edit-buffer. Depends on outshine.

- use *navi-mode.el* to open an occur-like indirect buffer for
  super-fast navigation and structure-editing (as well as other common
  actions on subtrees) in the associated original-buffer - all with
  one-key commands in a read-only buffer. A kind of customizable
  remote-control for the original-buffer with many views combining
  headline and keyword searches and easy switching between the
  associated buffers. Depends somehow on outshine too, but to a much
  lesser degree than outorg.el

And of course you have Francois Pinard's *poporg.el* and can (completely
independent from orgstruct or outshine):

- edit atomic comment-sections (anywhere in a source-code buffer, no
  matter what major-mode) in a temporary Org-mode edit-buffer. Thus,
  while *outorg* gives you a whole subtree with headline and source-code
  blocks in a temporary Org-mode edit-buffer, *poporg* gives you only
  the comment-string near point and nothing else, so that both libraries
  complement each other really well in their usage.

For more details see the tutorial on Worg.

-- 
cheers,
Thorsten

Re: Org-mode outside Org-mode

[Thomas S. Dye]

Aloha Thorsten,

What a joy to find the following bit on Worg!

    To sum it up in one sentence: Outline with Outshine outshines
    Outline

All the best,
Tom

-- 
Thomas S. Dye
http://www.tsdye.com

Re: Org-mode outside Org-mode

[Samuel Wales]

Great write-up, Thorsten.

There is a whole other set of options also.  I don't know if they are
close enough for you to include, but it's worth pointing them out.

These are in the general category of Org annotations.  Instead of
editing Org in a temporary buffer, you use a real, permanent Org file
(can include an agenda file).

There are two types of options: those that allow you to use Org to
annotate external files without changing those files, and those that
allow you to annotate external files by putting persistent markers in
them.

In both types, you can in principle do C-c ' to get to your Org agenda
files location from your external files, and the same thing in
reverse.

The existing mechanisms include org-pua.el, org-registry.el, and
org-annotate.el.

In principle, you should be able to annotate web pages in w3m.el and
dired entries and info notes also.

To me, there is a lot of possibility here.

It should also be possible to put an ID marker in an external file,
which corresponds exactly to the Org IDs in a canonical entry in your
agenda files.  Then C-c ' can bounce between the external file and
your agenda file.

Samuel

-- 
The Kafka Pandemic: http://thekafkapandemic.blogspot.com

The disease DOES progress.  MANY people have died from it.  ANYBODY
can get it.  There is NO hope without action.  This means YOU.

Re: Org-mode outside Org-mode

[Thorsten Jolitz]

Samuel Wales <samologist@gmail.com> writes:

> Great write-up, Thorsten.

thanks

> There is a whole other set of options also.  I don't know if they are
> close enough for you to include, but it's worth pointing them out.
>
> These are in the general category of Org annotations.  Instead of
> editing Org in a temporary buffer, you use a real, permanent Org file
> (can include an agenda file).
>
> There are two types of options: those that allow you to use Org to
> annotate external files without changing those files, and those that
> allow you to annotate external files by putting persistent markers in
> them.
>
> In both types, you can in principle do C-c ' to get to your Org agenda
> files location from your external files, and the same thing in
> reverse.
>
> The existing mechanisms include org-pua.el, org-registry.el, and
> org-annotate.el.
>
> In principle, you should be able to annotate web pages in w3m.el and
> dired entries and info notes also.
>
> To me, there is a lot of possibility here.

> It should also be possible to put an ID marker in an external file,
> which corresponds exactly to the Org IDs in a canonical entry in your
> agenda files.  Then C-c ' can bounce between the external file and
> your agenda file.

please see my recent post about 'navi-mode' for Org-mode buffers.
'navi-mode' actually is a kind of permanent associated buffer tightly
coupled to the original Org-mode or source code buffer. It uses markers
to allow bouncing between the associated 'twin-buffers', but non of the
libraries you mention. However, I worked out my own system to ensure
that the *Navi* buffer is always up-to-date after modifying the
original-buffer, and to locate point at a logical position in the
navi-buffer even when the view (on the original-buffer has changed
drastically).

The temporary editing of source-code in Org-mode buffers is inspired by
org-src.el (or Org Babel), its very fast and convenient, just like
editing source-code blocks in Org-mode. 

Just try it out, maybe it is similar to what you imagine (only with
different implementation). 

-- 
cheers,
Thorsten

Re: Org-mode outside Org-mode

[Samuel Wales]

Hi Thorsten,

IIUC, I don't think this is related.  The idea is not to edit source
code in Org buffers, and it is not to use a Navi buffer or to do
navigation.

The idea is to be in my-lisp.el, and do C-c ', and get to a canonical
entry in my-org.org, then do C-c ' again and get back to my-lisp.el.

The navi buffer seems like it wouldn't do that.

Samuel

-- 
The Kafka Pandemic: http://thekafkapandemic.blogspot.com

The disease DOES progress.  MANY people have died from it.  ANYBODY
can get it.  There is NO hope without action.  This means YOU.

Re: Org-mode outside Org-mode

[Thorsten Jolitz]

Samuel Wales <samologist@gmail.com> writes:

Hi Samuel,
   
> IIUC, I don't think this is related.  The idea is not to edit source
> code in Org buffers, and it is not to use a Navi buffer or to do
> navigation.
>
> The idea is to be in my-lisp.el, and do C-c ', and get to a canonical
> entry in my-org.org, then do C-c ' again and get back to my-lisp.el.
>
> The navi buffer seems like it wouldn't do that.

that sounds like a different idea. I have heard about programming
environments that keep comments and source-code in two different (but
sync'd) files to minimize distraction from the source code - maybe a
possible use case for your idea?

-- 
cheers,
Thorsten

Re: Org-mode outside Org-mode

[Eric Schulte]

[-- Attachment #1: Type: text/plain, Size: 641 bytes --]

Thorsten Jolitz <tjolitz@gmail.com> writes:

> Samuel Wales <samologist@gmail.com> writes:
>
> Hi Samuel,
>    
>> IIUC, I don't think this is related.  The idea is not to edit source
>> code in Org buffers, and it is not to use a Navi buffer or to do
>> navigation.
>>
>> The idea is to be in my-lisp.el, and do C-c ', and get to a canonical
>> entry in my-org.org, then do C-c ' again and get back to my-lisp.el.
>>

That could be handy.  For jumping back and for by function name, the
following simple implementation might be sufficient.  It relies on file
local variables to know which src and Org-mode files are related to each
other.


[-- Attachment #2: org-src-jump.el --]
[-- Type: application/emacs-lisp, Size: 1330 bytes --]

[-- Attachment #3: Type: text/plain, Size: 55 bytes --]


Cheers,

-- 
Eric Schulte
http://cs.unm.edu/~eschulte

Re: Org-mode outside Org-mode

[Bastien]

Eric Schulte <schulte.eric@gmail.com> writes:

> That could be handy.

Indeed!  Nice hack to add to Worg, or even to contrib/?

Don't hesitate to spread the word :)

-- 
 Bastien

Re: Org-mode outside Org-mode

[Samuel Wales]

On 4/6/13, Eric Schulte <schulte.eric@gmail.com> wrote:
>>> The idea is to be in my-lisp.el, and do C-c ', and get to a canonical
>>> entry in my-org.org, then do C-c ' again and get back to my-lisp.el.

> That could be handy.  For jumping back and for by function name, the
> following simple implementation might be sufficient.  It relies on file
> local variables to know which src and Org-mode files are related to each
> other.

Interesting implementation, thanks for coding it.

I was thinking about Org ID instead of local variables.

In the Org file, you have an entry with an Org ID and a property with
the source file location.

In the source file, you have a marker in a comment like this:

  ;; $[id 12345]

Where 12345 is an automatically-generated Org ID in the typical unique format.

The job of C-c ' in the source file is to search for the nearest ID
marker, then go to the entry that has that ID in the Org file.  The
job of C-c ' in the Org file is to get the Org ID, then search for the
marker that contains it in the source file.

Then the Org ID mechanism finds the Org file without requiring local variables.

(Or, of course, for read-only files, a bookmark-like mechanism can be
used to keep a database of search strings, indexed by the ID, to find
the location.  This means no need for Org ID in the source file and no
need for local variables.  But the ID method is more robust.)

Samuel

-- 
The Kafka Pandemic: http://thekafkapandemic.blogspot.com

The disease DOES progress.  MANY people have died from it.  ANYBODY
can get it.  There is NO hope without action.  This means YOU.

Re: Org-mode outside Org-mode

[Samuel Wales]

On 4/5/13, Thorsten Jolitz <tjolitz@gmail.com> wrote:
> that sounds like a different idea. I have heard about programming
> environments that keep comments and source-code in two different (but
> sync'd) files to minimize distraction from the source code - maybe a
> possible use case for your idea?

Yes.  The purpose for keeping them separate is to have one of them be
a complete Org file.

-- 
The Kafka Pandemic: http://thekafkapandemic.blogspot.com

The disease DOES progress.  MANY people have died from it.  ANYBODY
can get it.  There is NO hope without action.  This means YOU.

Re: Org-mode outside Org-mode

[Thorsten Jolitz]

Samuel Wales <samologist@gmail.com> writes:

> On 4/5/13, Thorsten Jolitz <tjolitz@gmail.com> wrote:
>> that sounds like a different idea. I have heard about programming
>> environments that keep comments and source-code in two different (but
>> sync'd) files to minimize distraction from the source code - maybe a
>> possible use case for your idea?
>
> Yes.  The purpose for keeping them separate is to have one of them be
> a complete Org file.

If you structure your Emacs Lisp files the 'outshine way', you can
convert them into complete Org files fast and easily using 'outorg.el'.
Use

 ,----------
 | C-u C-c '
 `----------

from inside the elisp buffer, or 

,------
| C-u e
`------

in the associated *Navi:my-elisp-file* buffer. 

Both bindings call '(outorg-edit-as-org &optional ARG)' with ARG and
thus act on the complete buffer, not only the subtree at point.

Therefore, whenever you want to edit text, your Emacs Lisp source code
buffer becomes a (complete or partial) Org-mode buffer in a second,
while you are in emacs-lisp-mode most of the time when its about editing
code - only enhanced with Org-mode's look&feel by the activation of
'outline-minor-mode' with 'outshine.el' extensions.

When its not about whole Org-mode buffers or whole subtrees (with
headlines and code-blocks), but just about atomic comment-strings to be
edited in Org-mode buffers, then 'poporg.el' is the tool of choice.

-- 
cheers,
Thorsten

Re: Org-mode outside Org-mode

[Samuel Wales]

Hi Thorsten,

On 4/12/13, Thorsten Jolitz <tjolitz@gmail.com> wrote:
> If you structure your Emacs Lisp files the 'outshine way', you can
> convert them into complete Org files fast and easily using 'outorg.el'.

No, we are talking about different things.

With what I am talking about, you can:

  - put your Org notes in your main Org agenda files exactly where you want them
  - efficiently use planning information to create daily/weekly agenda entries
  - bounce to and from the exact location in your source code to the
exact Org entry

Therefore, the category of tools I suggested to you -- which consists
of annotation-like mechanisms -- is a completely different way of
tackling the problem of dealing with source code and Org
simultaneously.

Yet it is a way of dealing with them simultaneously, which is the
reason I suggested putting them in your document also, if you felt
like it.

I believe that your outshine and outorg methods cannot do all of those things.

Therefore, I believe that they do not solve the same problems at all.

Samuel

-- 
The Kafka Pandemic: http://thekafkapandemic.blogspot.com

The disease DOES progress.  MANY people have died from it.  ANYBODY
can get it.  There is NO hope without action.  This means YOU.

Re: Org-mode outside Org-mode

[Samuel Wales]

Hi Eric,

Here is old not-working not-finished code that I abandoned.  But it
illustrates the goal.

Samuel

===

Maybe something like:

  - In source file, C-c ' to go to Org entry associated with nearest ID marker
    - C-u C-c ' to create ID marker and create its Org entry in your Org file
      - when it is created, you can refile it wherever
  - C-c ' in Org entry to go to associated source file ID marker

;; this is quick and dirty code
;;
;; it is brittle to store a file path.  it is much better to
;; incorporate ID markers into the Org ID system, then Org will
;; find the file using org-id-goto.  to tell the system where you
;; keep your source files, set a variable.
;;
;; doing so will eliminate the need to store a pathname property.
;;
;; maybe this can be refactored with detangling markers.
;;
;; see also annotation, which requires no marker, but is more
;; brittle and does not indicate that you have an annotation.
;; this should be merged with that.
(defconst alpha-org-id-pair-file-property "ID-pair-file")
(defun alpha-org-bounce-id-pair ()
  "The opposite of Org Babel.  C-c ' in source code to document
it in Org.  Same in documentation to go to source code."
  (interactive)
  (let ((id (org-id-get)))
    (if id
        (org-id-goto id)
      (let ((source (org-entry-get nil alpha-org-id-pair-file-property)))
        (find-file source)
        (re-search-forward id)
        (forward-line 1)))))
(defun* alpha-org-bounce-or-insert-id-pair (&key (comment ";; "))
  "Bounce to the other end of, or create, a (notes, ID
marker) pair.

Suppose you are editing an Emacs Lisp source code file.  You can
bounce between a special entry in your Org agenda file
\(e.g. notes.org\) and your external file \(e.g. file.el\)."
  (interactive)
  (let ((id (org-id-new "id-pair")))
    (save-excursion
      (alpha-org-insert-id-marker id :comment comment))
    (org-capture nil)))
(defun* alpha-org-insert-id-marker (id &key comment)
  "Insert an ID marker."
  (insert
   (concat (when comment comment)
           "$[id "
           id
           ;; (when link (concat " :link " link))
           ;; ;; (org-insert-link)
           ;; (when label (concat " :label \"" label "\""))
           "]"))
  (forward-line -1)
  (funcall indent-line-function))

On 4/6/13, Eric Schulte <schulte.eric@gmail.com> wrote:
> That could be handy.  For jumping back and for by function name, the
> following simple implementation might be sufficient.  It relies on file
> local variables to know which src and Org-mode files are related to each
> other.

-- 
The Kafka Pandemic: http://thekafkapandemic.blogspot.com

The disease DOES progress.  MANY people have died from it.  ANYBODY
can get it.  There is NO hope without action.  This means YOU.

Re: Org-mode outside Org-mode

[Alexander Vorobiev]

[-- Attachment #1: Type: text/plain, Size: 4284 bytes --]

First of all, thank you for the tutorial and the code! Outshine has become
a major component of my workflow, I use it in all my source code buffers
(sql, R, elisp).

I have one question/proposal regarding key bindings. Outshine binds TAB
to outshine-cycle-subtree which only does something useful (calls
outshine-cycle)
when the point is on a header line, otherwise it prints a message. TAB is
used
 heavily in various source code -related modes (yasnippets, smart-tab, etc.
http://www.emacswiki.org/emacs/TabCompletion is a great source for those) -
the
behavior which I don't want to lose. There is some support of other TAB
behaviors in
outline-cycle but it is not used (and it ignores the user-defined bindings).

A while back I wrote a macro (based on the advice in
http://stackoverflow.com/a/2494384/973603) which allows to activate minor
mode
bindings when a condition is true and fall back to previous bindings
otherwise:

(defmacro define-key-with-fallback (keymap key def condition &optional
mode)
 "Define key with fallback. Binds KEY to definition DEF in keymap KEYMAP,
the
  binding is active when the CONDITION is true. Otherwise turns MODE off
and
  re-enables previous definition for KEY. If MODE is nil, tries to recover
it by
  stripping off \"-map\" from KEYMAP name."
  `(define-key ,keymap ,key (lambda () (interactive)
     (if ,condition ,def
       (let* ((,(if mode mode
                     (let* ((keymap-str (symbol-name keymap))
                               (mode-name-end (- (string-width keymap-str)
4)))
                        (if (string= "-map" (substring keymap-str
mode-name-end))
                          (intern (substring keymap-str 0 mode-name-end))
                          (error "Could not deduce mode name from keymap
name (\"-map\" missing?)")))) nil)
                 (original-func (key-binding ,key)))
           (call-interactively original-func))))))

So now I can just do

(define-key-with-fallback outline-minor-mode-map (kbd "TAB") (outline-cycle
1) (outline-on-heading-p))

and have my yasnippets and smart indentation/completion active again. My
question is am I reinventing
the wheel? Is there a function/macro in org-mode or elsewhere that would
allow me define key bindings
with fallback?

Thanks again,
Alex


On Fri, Mar 15, 2013 at 10:39 AM, Thorsten Jolitz <tjolitz@gmail.com> wrote:

>
> Hi List,
>
> there is a now a tutorial on Worg describing the recently announced new
> libraries for using (concepts and functionality of) Org-mode when
> outside Org-mode:
>
> ,-----------------------------------------------------------
> | http://orgmode.org/worg/org-tutorials/org-outside-org.html
> `-----------------------------------------------------------
>
> Besides using the 'well-known' orgstruct-minor-mode, you can now:
>
> - use outline-minor-mode with *outshine.el* extensions and structure
>   your file with outshine-style headlines, giving your source-code files
>   the look&feel of Org-mode files. Should work in any major-mode.
>
> - use *outorg.el* to edit complete subtrees or the whole file as
>   Org-mode in a temporary Org-mode edit-buffer. Depends on outshine.
>
> - use *navi-mode.el* to open an occur-like indirect buffer for
>   super-fast navigation and structure-editing (as well as other common
>   actions on subtrees) in the associated original-buffer - all with
>   one-key commands in a read-only buffer. A kind of customizable
>   remote-control for the original-buffer with many views combining
>   headline and keyword searches and easy switching between the
>   associated buffers. Depends somehow on outshine too, but to a much
>   lesser degree than outorg.el
>
> And of course you have Francois Pinard's *poporg.el* and can (completely
> independent from orgstruct or outshine):
>
> - edit atomic comment-sections (anywhere in a source-code buffer, no
>   matter what major-mode) in a temporary Org-mode edit-buffer. Thus,
>   while *outorg* gives you a whole subtree with headline and source-code
>   blocks in a temporary Org-mode edit-buffer, *poporg* gives you only
>   the comment-string near point and nothing else, so that both libraries
>   complement each other really well in their usage.
>
> For more details see the tutorial on Worg.
>
> --
> cheers,
> Thorsten
>
>
>
>

[-- Attachment #2: Type: text/html, Size: 5689 bytes --]

Re: Org-mode outside Org-mode

[Thorsten Jolitz]

Alexander Vorobiev <alexander.vorobiev@gmail.com> writes:

Hi Alexander, 

> First of all, thank you for the tutorial and the code! Outshine has become
> a major component of my workflow, I use it in all my source code buffers (sql,
> R, elisp).

Thanks, I use it in all my elisp and PicoLisp buffers too, and I'm happy
that it works for you too. 

Only with 'old-school' elisp buffers with '^;;;+ ' headlines there is
still one major headache with long lines of only ';' like this:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

that make the regexp matcher enter endless backtracking. I haven't found
a solution yet how to fontify the headlines in a different way (-> first
match the headline regexp, then calculate the headline level).

> I have one question/proposal regarding key bindings. Outshine binds TAB
> to outshine-cycle-subtree which only does something useful (calls
> outshine-cycle) 
> when the point is on a header line, otherwise it prints a message. TAB is used
>  heavily in various source code -related modes (yasnippets, smart-tab, etc. 
> http://www.emacswiki.org/emacs/TabCompletion is a great source for those) -
> the 
> behavior which I don't want to lose. There is some support of other TAB
> behaviors in 
> outline-cycle but it is not used (and it ignores the user-defined bindings).


That very same problem made me hate yasnippet ...
I think thats a very good proposal.

> A while back I wrote a macro (based on the advice in 
> http://stackoverflow.com/a/2494384/973603) which allows to activate minor mode
> bindings when a condition is true and fall back to previous bindings
> otherwise:

I copied your macro to outshine.el (hope thats ok with you, I credit
you), but had errors at start-up so I modified it slightly:

,-----------------------------------------------------------------------------------
| ;; copied from Alexander Vorobiev
| ;; http://www.mail-archive.com/emacs-orgmode@gnu.org/msg70648.html
| (defmacro outshine-define-key-with-fallback
|   (keymap key def condition &optional mode)
|  "Define key with fallback.
| Binds KEY to definition DEF in keymap KEYMAP, the binding is
| active when the CONDITION is true. Otherwise turns MODE off and
| re-enables previous definition for KEY. If MODE is nil, tries to
| recover it by stripping off \"-map\" from KEYMAP name."
|   `(define-key ,keymap ,key (lambda () (interactive)
|      (if ,condition ,def
|        (let* ((,(if mode mode
|                      (let* ((keymap-str (symbol-name keymap))
|                                (mode-name-end (- (string-width keymap-str) 4)))
|                         (if (string= "-map" (substring keymap-str mode-name-end))
|                           (intern (substring keymap-str 0 mode-name-end))
|                           (message "Could not deduce mode name from keymap name"))
|                                  ;; (\\"-map\\" missing?)")
|                         )) nil)
|                  (original-func (key-binding ,key)))
|            (call-interactively original-func))))))
`-----------------------------------------------------------------------------------


This is what I get now if I press 'C-h k' and then TAB in an outshine buffer:

,---------------------------------------------------------------------------
| TAB (translated from <tab>) runs the command (lambda nil (interactive) (if
| (outline-on-heading-p) (outline-cycle 1) (let* ((outline-minor-mode nil)
| (original-func (key-binding (kbd "TAB")))) (call-interactively
| original-func)))), which is an interactive Lisp function.
| 
| It is bound to TAB.
| 
| (anonymous)
`---------------------------------------------------------------------------

This is still in a private branch and not merged with the master, it
seems to work, but could you check the macro and the message if they
look alright before merging it with master?

> So now I can just do
>
> (define-key-with-fallback outline-minor-mode-map (kbd "TAB") (outline-cycle 1)
> (outline-on-heading-p)) 

I applied that to several bindings in outshine.el that might conflict
with other libraries now. 

> and have my yasnippets and smart indentation/completion active again. My
> question is am I reinventing 
> the wheel? Is there a function/macro in org-mode or elsewhere that would allow
> me define key bindings
> with fallback?

I would be interested in this too, since I like to have the
M-<arrow-key> navigation keys from 'outline-mode-easy-bindings' in
Org-mode too, but they conflict with some org-table bindings. 

-- 
cheers,
Thorsten

Re: Org-mode outside Org-mode

[Thorsten Jolitz]

Alexander Vorobiev <alexander.vorobiev@gmail.com> writes:

Hi Alexander, 

> A while back I wrote a macro (based on the advice in 
> http://stackoverflow.com/a/2494384/973603) which allows to activate
> minor mode bindings when a condition is true and fall back to previous
> bindings otherwise:

I just pushed a new version of outshine.el on github (and updated the
Org-mode outside Org-mode article on Worg). I use a modified version of
your macro to bind TAB, M-<left-arrow> and M-<right-arrow>. I still
'take over' BACKTAB and M-<up-arrow> and M-<down-arrow> in outshine.el,
since the associated functions are usefull anywhere in an outshine
buffer.

Thanks for the tip and the code!

-- 
cheers,
Thorsten

Re: Org-mode outside Org-mode

[Thorsten Jolitz]

Samuel Wales <samologist@gmail.com> writes:

Hi Samuel,

>> If you structure your Emacs Lisp files the 'outshine way', you can
>> convert them into complete Org files fast and easily using 'outorg.el'.

> With what I am talking about, you can:
>
>   - put your Org notes in your main Org agenda files exactly where you want them
>   - efficiently use planning information to create daily/weekly agenda entries
>   - bounce to and from the exact location in your source code to the
> exact Org entry
>
> Therefore, the category of tools I suggested to you -- which consists
> of annotation-like mechanisms -- is a completely different way of
> tackling the problem of dealing with source code and Org
> simultaneously.
>
> Yet it is a way of dealing with them simultaneously, which is the
> reason I suggested putting them in your document also, if you felt
> like it.

I think I missed this mail. When you have a worked out system for such
a tool-chain, it would definitely be nice to describe it in the
'Org-mode outside Org-mode' tutorial on Worg. Maybe even giving the
whole thing a name like 'Source-file annotation with Org-mode' or so. 

Feel free to add a new item for this in the tutorial. When you don't
have write access to Worg, you could send it to me and I add it to the
article. 

-- 
cheers,
Thorsten