Literate Programming

Literate Programming

[Hibou57 (Yannick Duchêne)]

Hi all good friends :p

Like a lot of people here, I've enjoyed the GPS environnement and
mainly the ability to have refactoring functionalities (to globally
rename an intentity in one step) integrated in the editor, along with
the ability to jump to a definition (type, package, and the like) with
a right-click on an entity in the source. This is the hot spot I like
in GPS.

But there is also another way of doing things which I like very much
and even more for a long : this is named “ Literate Programming ”

For some time I used Leo ( http://personalpages.tds.net/~edream/front.html
) and in nearest times, I used CodeBrowser and had paricipated in a
part of its developpement ( http://code-browser.sourceforge.net/ )
which allow a kind of literate programming and which I had use mainly
for a big JvaScript application (literate programming helps as well
with language which does not provide any real structuring facilities)

That's all nice so far, with just a dark point : what you have with
one, you do not have it with the other (I would not want to turn
neurotic :p )

So I was wondering if someone has ever heard about some extentions to
GPS which would give it literate programming facilities.

Or else, if it does not exist, I think I will simply try to integrate
some of the GPS tools (which comes as command line tools as well I
believe) into CodeBrowser (I've got my own fork of CodeBrowser).

Please to read you soon :)

Yannick

Re: Literate Programming

[Stephen Leake]

"Hibou57 (Yannick Duchêne)" <yannick_duchene@yahoo.fr> writes:

> But there is also another way of doing things which I like very much
> and even more for a long : this is named “ Literate Programming ”

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.

> So I was wondering if someone has ever heard about some extentions to
> GPS which would give it literate programming facilities.

What, exactly, is missing from GPS?

You have the ability to run external tools, to do the splitting.

I guess syntax colorization is confused; it needs to know when to
apply LaTeX, when to apply Ada.

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 prefer using separate LaTeX and Ada files, and referencing one from
the other appropriately. That preserves all the navigation facilities
in both languages. If you include the relative file name in a comment,
Emacs can easily navigate between the files; I don't know if GPS will
do that.

As you say, one of the prime features of literate programming is
providing structure for unstructured languages. Ada doesn't need that :).

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.

-- 
-- Stephe

Re: Literate Programming

[Yannick Duchêne Hibou57]

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).

The basic idea in literate, is that the implementation approach is not
the same as the understanding approach. A quick image could be to
point that when one figure out how something works, his/her wordings
may introduce B before A, while the implementation may requires A to
be defined before B (different process, different requirements). This
is just an example, just think about the idea that the understanding
process is not the same as the implementation process.

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.

Let say you have two parts in you program (to keep it simple), which
are A and B. There may be one ore more understanding view making
references to A and B, and there is an implementation view, which
stand for the program construction. This view will make reference to A
and B in the desired order, I mean the order expected by the language
and the compiler. The tangling command appends content of A and B to
create the program construct.

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).

> > So I was wondering if someone has ever heard about some extentions to
> > GPS which would give it literate programming facilities.
>
> 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
This is just a matter of layout and UI, not at all a matter of GPS
functionalities targeting Ada and the build process.

> You have the ability to run external tools, to do the splitting.
This is exactly the opposite which is needed.

> I guess syntax colorization is confused; it needs to know when to
> apply LaTeX, when to apply Ada.
Dear, you can keep simple minds and forget about LaTex formatting ;)
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.

> 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).

> I prefer using separate LaTeX and Ada files, and referencing one from
> the other appropriately. That preserves all the navigation facilities
> in both languages. If you include the relative file name in a comment,
> Emacs can easily navigate between the files; I don't know if GPS will
> do that.
You bring something very interesting in the area. I was also precisely
too thinking about how to make reference to a document from GPS in an
Ada source. I was wondering if there is already a standardized comment
syntax for it. I've noticed that in GPS, comments whose content does
start start with a space (or the two spaces which the Ada world seems
to prefer), then it is colorized differently. So I was thinking there
may be some convention for type of comments (or perhaps this is only
intended to SPARK language shipped in comments and to nothing else).

If there is a way to give a reference to a document and to be able to
open it from GPS with a simple click or menu command, this may be
nice. I was thinking this is perhaps possible with scripting, although
I do not know a lot about scripting GPS. But I was mainly wondering
about what the format of this kind of comments should and weither or
not such a kind of comments (standing for an URI to a document) has
already been standardized of not.

> As you say, one of the prime features of literate programming is
> providing structure for unstructured languages. Ada doesn't need that :).
The same way Ada is not only useful for very big project and project
where preserving humans life matter and can be useful as well for
smaller project, the same way, literate is not only useful for flawed
languages (I apologize, I mean targeting some area only). As I said
before, I was back to this idea I was not fully satisfied with UML
(which I did not already left anyway... I'm still seeking).

> 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.

>
> --
> -- Stephe

Thanks Stephe

Re: Literate Programming

[Jean-Pierre Rosen]

Yannick Duch�ne Hibou57 a �crit :

[Lot of interesting stuff about literate programming deleted]

> The basic idea in literate, is that the implementation approach is not
> the same as the understanding approach. A quick image could be to
> point that when one figure out how something works, his/her wordings
> may introduce B before A, while the implementation may requires A to
> be defined before B (different process, different requirements). This
> is just an example, just think about the idea that the understanding
> process is not the same as the implementation process.
> 
> 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.
> 
This looks a lot like what HOOD (and HOOD tools) do: diagrams and
documentation for understanding, separate pieces for the code. Then the
tool can extract documentation and/or programs, by extracting the pieces
and providing the glue.

Do you think we could advertise HOOD as literate programming ;-) ?
-- 
---------------------------------------------------------
           J-P. Rosen (rosen@adalog.fr)
Visit Adalog's web site at http://www.adalog.fr

Re: Literate Programming

[AdaMagica]

On 8 Sep., 09:09, Jean-Pierre Rosen <ro...@adalog.fr> wrote:
...
> Do you think we could advertise HOOD as literate programming ;-) ?

If you take "undeline nouns and make them objects and underline verbs
and make them operations" literally - yes ;-)

Re: Literate Programming

[Yannick Duchêne Hibou57]

On 8 sep, 09:09, Jean-Pierre Rosen <ro...@adalog.fr> wrote:
> This looks a lot like what HOOD (and HOOD tools) do: diagrams and
> documentation for understanding, separate pieces for the code. Then the
> tool can extract documentation and/or programs, by extracting the pieces
> and providing the glue.
HOOD is similar ? I just know the name of HOOD, but not what is
really.

But isn't HOOD a method too ? Do you mean it can be used without its
method ?

To tell more, what makes me a bit wrong with UML is that it seems
difficult to me to map UML <-> Ada. There so called prototypes, but
once prototypes are all over the place, this is finally not UML any
more, and it may be better to look for something else.

I just know a significant amount of Ada users like HOOD, but I do not
know HOOD. I may have a deeper look at it finally... as soon as today.

> Do you think we could advertise HOOD as literate programming ;-) ?
If it is, and if it not to lie about what HOOD is, well, why not.
Perhaps HOOD and literate has a common ancestor ;)

Just about to advertise HOOD as literate, I'm just afraid that
literate is not very famous either (what is famous today is to do
things as quick as possible, and anything involving some more works is
not welcome)

Thanks to have pointed about HOOD in this context, I may discover
something I did not suspected before.

Re: Literate Programming

[Martin]

On Sep 8, 12:04 pm, Yannick Duchêne Hibou57 <yannick_duch...@yahoo.fr>
wrote:
>
> I just know a significant amount of Ada users like HOOD, ...

I'd question that...

...I've never met anyone who liked HOOD - irrespective of whether they
liked Ada or not.

Cheers
-- Martin

Re: Literate Programming

[Yannick Duchêne Hibou57]

On 8 sep, 14:14, Martin <martin.do...@btopenworld.com> wrote:
> I'd question that...
>
> ...I've never met anyone who liked HOOD - irrespective of whether they
> liked Ada or not.
>
> Cheers
> -- Martin

I've just noticed that the word “ Ada ” as an occurence frequency in
web page where the word “ HOOD ” appears. So let say HOOD users like
Ada (I may have made a wrong short-cut asserting the other way first,
but this one is probably true enough).

So to be more formal, we do not have Ada <=> HOOD, but we have HOOD =>
Ada (confusion of <=> and => is a common mistake of beginners with
formal logic).

Re: Literate Programming

[Martin]

On Sep 8, 5:30 pm, Yannick Duchêne Hibou57 <yannick_duch...@yahoo.fr>
wrote:
> On 8 sep, 14:14, Martin <martin.do...@btopenworld.com> wrote:
>
> > I'd question that...
>
> > ...I've never met anyone who liked HOOD - irrespective of whether they
> > liked Ada or not.
>
> > Cheers
> > -- Martin
>
> I've just noticed that the word “ Ada ” as an occurence frequency in
> web page where the word “ HOOD ” appears. So let say HOOD users like
> Ada (I may have made a wrong short-cut asserting the other way first,
> but this one is probably true enough).
>
> So to be more formal, we do not have Ada <=> HOOD, but we have HOOD =>
> Ada (confusion of <=> and => is a common mistake of beginners with
> formal logic).

:-)

There was a time (mid, to late 80's) when HOOD/Ada was used together
quite a bit. They were both 'mandated' tools on EuroFighter. We took a
look at the HOOD tools and promptly dumped it in favour of Teamwork/
RTSA-OOD (the Ward-Mellor variety), which stood up pretty well, once
the method => teamwork mapping had been done.

Cheers
-- Martin

Re: Literate Programming

[Stephen Leake]

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

Re: Literate Programming

[Jean-Pierre Rosen]

AdaMagica a �crit :
 > If you take "undeline nouns and make them objects and underline verbs
> and make them operations" literally - yes ;-)
Well, this is not HOOD, it is Booch. HOOD is derived from Booch, but
there is *a lot* more to it...

-------------
Yannick Duch�ne Hibou57 a �crit :
> HOOD is similar ? I just know the name of HOOD, but not what is
> really.
Have a look at the book (http://www.adalog.fr/hoodbook.htm), or register
for a HOOD training at adalog ;-)

> But isn't HOOD a method too ? Do you mean it can be used without its
> method ?
HOOD is a method supported by tools. The method includes various steps,
each with documentation requirements. All documents (including code) are
managed together by the tool, and the tool extracts programs, design
documents, etc from the common data base.

To be honnest, the method has been made more flexible in recent
versions, and you never know how users use a tool...

-------------
Martin a �crit :
>> I just know a significant amount of Ada users like HOOD, ...
>
> I'd question that...
>
> ...I've never met anyone who liked HOOD - irrespective of whether they
> liked Ada or not.

Then we have not met the same people. HOOD was designed as method for
Ada (later extended to other languages), and the mapping is very natural.

> There was a time (mid, to late 80's) when HOOD/Ada was used together
> quite a bit.
And is still used in space, air and railway transportation.

> They were both 'mandated' tools on EuroFighter. We took a
> look at the HOOD tools and promptly dumped it in favour of Teamwork/
> RTSA-OOD (the Ward-Mellor variety), which stood up pretty well, once
> the method => teamwork mapping had been done.
Of course, we are talking about HOOD 4, which has gone a long way since
the 80's. If your only experience of HOOD dates from the mid 80's, it's
like blaming Ada for the inconsistencies in the preliminary document of
July 1980 ;-)
-- 
---------------------------------------------------------
           J-P. Rosen (rosen@adalog.fr)
Visit Adalog's web site at http://www.adalog.fr