Re: [O] [ANN] Convert Org-mode file to Source-code file

[Thorsten Jolitz]

Eric Schulte <address@hidden> writes:

> How does this differ from ":tangle yes :comments org"?

I wasn't actually aware (or forgot about) the :comments argument in
Babel when I wrote the conversion function (that is renamed to
'outorg-convert-org-to-outshine' now to better reflect its purpose).

> e.g.,
>
> #+Property: tangle yes
> #+Property: comments org
>
> * This is the top
>
> #+begin_src sh :shebang #!/bin/bash
>   echo "##this file will cat itself"
>   echo ""
> #+end_src
>
> Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec
> hendrerit tempor tellus. Donec pretium posuere tellus. Proin quam
> nisl, tincidunt et, mattis eget, convallis nec, purus. Cum sociis
> natoque penatibus et magnis dis parturient montes, nascetur ridiculus
> mus. Nulla posuere. Donec vitae dolor. Nullam tristique diam non
> turpis. Cras placerat accumsan nulla. Nullam rutrum. Nam vestibulum
> accumsan nisl.
>
> | a       | table |
> | in      | the   |
> | tangled | file  |
>
> #+begin_src sh
>   cat $0
> #+end_src
>
> tangles to
>
>
> #!/bin/bash
>
> # This is the top
>
> echo "##this file will cat itself"
> echo ""
>
> # Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec
> # hendrerit tempor tellus. Donec pretium posuere tellus. Proin quam
> # nisl, tincidunt et, mattis eget, convallis nec, purus. Cum sociis
> # natoque penatibus et magnis dis parturient montes, nascetur ridiculus
> # mus. Nulla posuere. Donec vitae dolor. Nullam tristique diam non
> # turpis. Cras placerat accumsan nulla. Nullam rutrum. Nam vestibulum
> # accumsan nisl.
>
> # | a       | table |
> # | in      | the   |
> # | tangled | file  |
>
> cat $0

in your example file the main difference is that

,--------------------
| > * This is the top
`--------------------

becomes

,--------------------
| > # This is the top
`--------------------

which is not an outshine header, thus the outline structure is lost in
the tangled file.

But it would really be nice if the conversion from Org to Outshine could
be done with the existing 'Babel Toolkit'. On the other hand, since my
conversion function seems to work alright now (bugreports welcome!), it
would not make much sense to invest time into make Babel do the same
thing.

I see the following problems with Babel:

1. (from your example I deduce that) outline structure is not conserved
in the comment sections, thus the tangles files won't work with outshine.

2. the overriding of header args cause problems with files that set
(e.g. code block specific) :tangle or :comment args themnselves, that
then override buffer wide args.

3. an outshine file is a file in a certain programming language
major-mode. 'outorg-convert-org-to-outshine' outcomments everything
else, including property-drawers, org comments, or souce-blocks from
other languages, so that the whole Org-file is preserved. I'm not sure
how this works when tangling with :comments org?

Maybe just check if it works with a real world .org file? The best one I
can think of is

,----------------------------------
| http://doc.norang.ca/org-mode.org
`----------------------------------

since it covers so many aspects of Org-mode.

So I downloaded it and added this at the front

,-----------------------------------------------------------------------
| [...]
| #+EXPORT_EXCLUDE_TAGS: noexport
|
| #+PROPERTY: tangle yes
| #+PROPERTY: comments org
|
| Org-mode is a fabulous organizational tool originally built by Carsten
| Dominik that operates on plain text files.  Org-mode is part of Emacs.
| [...]
`-----------------------------------------------------------------------

and then did

1.

,----------
| C-c C-v t
`----------

The tangled file org-mode.el does not at all look as expected, it rather
seems the added properties have been completely ignored. Is it possible
to squeeze Org-Babel such that the tangled file looks like the result of

2.

,----------------------------------------------------------
| M-: (outorg-convert-org-to-outshine "emacs-lisp-mode"
|        "~/junk/org-mode.org" "~/junk/org-mode-outorg.el")
`----------------------------------------------------------

This seems to convert the full Org file to Outshine, and when I do M-#
M-# then on the Outshine file, I see the same Org-file as before in the
*outorg-edit-buffer*, as intended. (almost, see the PS).

PS

One thing on my list for outorg is better handling of src-block header
args for the code-sections. Until now, I viewed it from the perspective
of a source-code file (e.g. emacs-lisp), and it was no problem to
surround the code parts simply with

#+begin_src emacs-lisp
 <<code>>
#+end_src

and assume that the users use Org-mode properties for persistantly specifying
export options. So when going back from Org to Outshine, I simply deleted the

,-------------------------
|#+begin_src emacs-lisp
|#+end_src
`-------------------------

lines.

But now, from the perspective of converting existing Org-files to Outshine,
this does not look like such a good idea anymore, since I delete important
header info from the original file (although I want to conserve all info that
exists in the file, just transform it to a different state).

So here is a RFC:
What would be best way to conserve the header info from source-blocks of the
major-mode language of the outshine buffer (all the other blocks are
conserved anyway)?

1. simply outcomment and uncomment the header lines instead of deleting them?
   Very easy, but looks a bit ugly ... but leaves the original file untouched.
2. transform them into #+HEADER or #+HEADERS lines (whats the difference?)?
   This would be my favorite, but changes the original file a bit (visible,
   when transforming back from Outshine to Org).
3. transform them into properties inside property drawers. Nice, but not able
   to reflect code-block-specific headers.

> Thorsten Jolitz <address@hidden> writes:
>
>> Hi List,
>>
>> it is now possible to convert existing Org-mode files with
>> source-blocks into machine-executable source-code files, using the
>> following function from `outorg.el':
>>
>> #+begin_src emacs-lisp
>> (defun outorg-convert-org-file-to-source-code
>>   (&optional mode infile outfile BATCH)
>>   "Convert an existing Org-mode file into an Outshine buffer.
>>
>> If MODE is non-nil, the Outshine buffer will be put in this
>> major-mode, otherwise the major-mode of the language of the first
>> source-code block in the Org-mode buffer will be used.
>>
>> If INFILE is non-nil, the specified Org-mode file will be visited
>> and its buffer converted, otherwise the current buffer will be
>> converted.
>>
>> If OUTFILE is non-nil, the converted Outshine buffer will be saved in this
>> file. Its the user's responsability to make sure that OUTFILE's
>> file-extension is suited for the major-mode of the Outshine buffer to be
>> saved. When in doubt, consult variable  `auto-mode-alist' for associations
>> between file-extensions and major-modes.
>>
>> If BATCH is non-nil (and OUTFILE is non-nil, otherwise it makes
>> no sense), the new Outshine file is saved and its buffer
>> deleted."...)
>> #+end_src
>>
>> Usage example:
>>
>> ,----------------------------------------------------------------
>> | (outorg-convert-org-file-to-source-code
>> |    "emacs-lisp-mode" "~/junk/test.org" "~/junk/test.el" 'BATCH)
>> `----------------------------------------------------------------
>>
>> I'm not sure about the general use case for this, but I do have my
>> uses for it, so I announce it here because it might serve others too.
>>
>> PS
>> This is *not* about tangling, try it out to see the (big) difference.

--
cheers,
Thorsten