Re: [Texmacs-dev] literate programming for TeXmacs

[David MENTRE]

Hello Felix,

Felix Breuer <address@hidden> writes:

> * One advantage of generating source code from documentation is that
> source code snippets can be reordered in the process. And I think this
> is rather important. If you are writing Java for example then you would
> have a single line of code containing "class Foo {" somewhere in your
> TeXmacs document, then all kind of method definitions with
> corresponding documentation and finally a lone "};".

I'm still undetermined about this code re-ordering facility. On the one
hand, as you underlined it, it seems necessary for object oriented
code. On the other hand, I feel this system as a poor-man macro system,
which is quite fragile and is prone to trigger vicious bugs.

Personally, I'm using noweb without any re-ordering for more than two
years and I'm quite satisfied with this approach (except for
object-oriented code, as you said). Keeping the original source code
order is important to me: the reference artifact should be the source
code.

> * While texmacs' markup is readable, I don't think it is *that* readable.
> Having a large chunks of commented texmacs markup in source files would
> make them less readable, IMO.

Yes, I thought of it and it is a major impediment to my approach. :(

> * Implementing lp this way does not gain anything with regard to TeXmacs
> sessions.

I did not thought about sessions.

> * I don't work with IDE's or other integrated build environments, so having
> a lp tool that works well with them is not important to me,
> personally.

Never say never. ;-)

> The advantage I see in your approach is that it might be very easy to
> implement, possibly without touching TeXmacs' interna. The biggest
> obstacle to implementing the system you propose as an external tool is
> that a chunk of verbatim text when saved in .tm format uses all kinds
> of escape sequences and such. (< and > obviously have to be escaped)

Wouldn't be possible to add to TeXmacs internal data structure a "raw"
data type that should be never interpreted by TeXmacs rendering engine?

> How would you implement the system you propose? As an external tool
> or as a special "export as..." format within TeXmacs?

I was thinking of a texmacs plugin that would recognise file.tm.c files
and do proper processing on them. But right now, I'm more at the
specification level. ;)

> Hm... the way I see it, the two following things might be useful to
> have.
>
> * Give TeXmacs itself the ability to rearrange snippets of verbatim
> text on the fly (i.e. to tangle code snippets). This could be roughly
> what I have done in LP4TeXmacs, only that it would be implemented in
> TeXmacs itself, so it could be used to generate code for interactive
> sessions as well.

Yes, this capability might be useful, for your suggested purpose or
another one (see below).

> * Implement a special import and export method that reads and writes
> the entire document in .tm format with the exception that all lines
> are commented (using the language specific syntax for commenting)
> except for the contents of some special purpose primitves which
> are exported verbatim.

yes.

> The rub is that these two would _not_ work well together unless TeXmacs
> also had the ability to untangle, which is where the difficulties lie.
>
> All in all, I have to give the whole thing more thought.

So do I. :)

> But it is definitely a good idea to simply "save a document with
> TeXmacs markup as comments" instead of generating source files from
> TeXmacs documents.

Thanks.

Another suggestion (without thinking much about it): use two documents,
the original source file and a texmacs .tm document, and include
references (as language comment, e.g. /* TMREF:Noh8ohti */) in the
language source file so that texmacs can tangle/untangle the code, using
information stored in the second texmacs document. Advantage: it
wouldn't clutter the source code with big chunks of texmacs code.

Another suggestion along the same line: instead of tangling code from LP
document, tangle LP document from source code and some additional
information (e.g. a texmacs master document). Original code order is
preserved (e.g for a developer that don't want to use the LP system) and
the developer using texmacs-LP can reorder code chunks at will. I have
no idea how the link between source code part and the texmacs part can
be maintained. :)

I need to setup an example and simulate my approach on it.

Best wishes,
d.
-- 
pub  1024D/A3AD7A2A 2004-10-03 David MENTRE <address@hidden>
 5996 CC46 4612 9CA4 3562  D7AC 6C67 9E96 A3AD 7A2A