Re: Literate Programming

[Stephen Leake <stephen_leake@stephe-leake.org>]

Yannick Duch�ne Hibou57 <yannick_duchene@yahoo.fr> writes:

> Thanks for this constructive reply
>
> Before I go on, I have to say that I exploring solutions in the same
> spirit of a previous thread I've opened about Ada and UML. After some
> attempts, I did not felt fully at ease with UML and Ada for the time,
> so I'm still trying to evaluate and envisage other possible solutions.
>
> On 7 sep, 10:38, Stephen Leake <stephen_le...@stephe-leake.org> wrote:
>> As I understand it, that can be considered a meta-language, that mixes
>> LaTeX and Ada source in one file, and provides tools to split them out
>> into files that the relevant compilers will accept.
>
> Yes and no, not exactly. This split a program in parts with markups,
> and makes multiple views on an overall. Multiple views are possible
> because of the ability to make reference to these parts. I.e. a view
> is made of a particular organization of some parts which are
> introduced into it via references (a part does not belong to a
> particular view, except with CodeBrowser which is different).

I was assuming you were talking about integrating a particular
implementation of literate programming into GPS.

If you are starting from scratch, here is what I would do:

Store the parts in the files that their normal tools accept, and add a
viewing tool, with some metadata.

For example, if we are talking about Ada code with LaTeX
documentation, then we have some .ads, .adb, and .tex files. The
literate programming viewer then adds some .lit files that provide the
information about how to weave the Ada and LaTeX files together.

You'll need some special comments in the Ada code to mark parts. The
LaTeX parts can simply be kept each in one file, or add some part
comments to that as well.

> The basic idea in literate, is that the implementation approach is not
> the same as the understanding approach. 

Right.

> A fundamental function of literate, is called tangling. This is the
> function which take one view which purpose is to be the implementation
> view and combines parts as referenced in this view, to make up the
> implementation. It produce an output which is the implementation
> expected by the language.

In the approach I outlined above, tangling is a null operation. The
opposite (which I think is called "weaving"?) is needed; combining
parts from normal language files into a view appropriate for
understanding.

Using a tangling tool means you loose traceability from the compiler
errors to the real source (unless we get an enhanced Source_Reference
pragma); that makes the tool useless, in my opinion.

On the other hand, LaTeX already has almost everything you need to do
the weaving; the only thing missing is a variety of "include file
bytes <start> .. <finish>" macro, where <start> and <finish> are
comment tags in an Ada (or other language) source file. I would not be
surprised if such a macro is already available. No need to add
a new viewing tool.

> But there are other way to do. Leo does that in that way, while
> CodeBrowser does that in a different way, which does not requires
> tangling (I don't wish to tell more about differences between Leo and
> CodeBrowser, to keep these wordings enough short).

I'd like to understand the different approaches.

>> What, exactly, is missing from GPS?
>
> Markup driven folding (nodes), that's all, and may be the ability to
> follow links to these folders/nodes

I don't know what you mean by "folding" or "nodes". To me, it sounds
like what I've described above :).

Navigating among source files is crucial.

> This is just one particular folk, basically, human readable
> documentations in literate is just comments, and weither or not it
> is formated, is not a particular focus. This can simply be Ada
> comments. There is not requirement at all for it to be LaTex. This
> can range from raw text to anything one may wish.

Ok. The approach I outlined is language neutral, for both the
understanding view and the compiling view language. I just assumed
LaTeX because Knuth used it for the original literate programming
tool, and I'm not aware of a better markup language for writing
documents. 

>> You can't preserve the navigation facilities, treating the
>> literate file as the source; pragma Source_Reference only changes the
>> file name, not the line numbers. That's a GNAT limitation; you could
>> petition them for a more powerful Source_Reference pragma (but you'd
>> probably have to come up with some money to get it).
>
> I don't bother about it and I'm not requiring anything any way, I'm
> just talking and seeking for knowledge about a particular subject (and
> seeking for solutions).

This is a fatal mistake. If a tool that generates Ada code does not
support editing that Ada code in the original form, both to fix
compiler errors and to do typical maintenance, then the original
form will not be kept up to date, and ultimately the tool will not be
used.

Any solution to literate programming must support navigation from
compiler errors to original source.

>> I don't know for sure, but I bet there's an Emacs mode for literate
>> programming :). I know there is support in general for "multiple modes
>> in a single buffer", for JavaScript embedded in html.
>
> I'm not running UNIX.

Ok. But I didn't mention UNIX. 

Ah; you are assuming Emacs only runs on Unix flavors; that's not true.
It runs on Mac, Lynx, Android, and (what's that other OS?) oh yes,
Windows.

Emacs is, and always will be, the One True Editor :). http://xkcd.com/378/

-- 
-- Stephe