Ada and Literate Programming

Ada and Literate Programming

[Thomas Preymesser]

Hi.

Is anyone doing literate programming with Ada?

I don't have specific questions or problems but would be interested in
examples from other people's work to improve my techniques.

-Thomas

-- 
-- WWW: Standard:       http://www3.cybercities.com/t/thopre/
--      experimentell:  http://mitglied.tripod.de/thopre/
-- For my always up-to-date contact information, click here: http://www.planetall.com/main.asp?cid=1679268
-- noch 239 Tage bis zum neuen Jahrtausend

Re: Ada and Literate Programming

[Robert Dewar]

In article <8f6iue$pu5$1@news.fas.harvard.edu>,
  Thomas Preymesser <tp@odn.de> wrote:
> Hi.
>
> Is anyone doing literate programming with Ada?

Seeing as the substance of literate programming is very little
more than writing code that is properly documented, I would
hope that everyone is doing literate programming in Ada. The
very fact that this needed to be identified as a special
technique and given a special name is a bit appalling. The
idea of programs that are illiterate and cannot be read is
frightening to me.

If you mean the use of tools that allow the documentation to
be extracted in convenient form, yes many people are using
many tools for that.

A favorite technique of Jean Ichbian was to use Microsoft WORD
to prepare source programs, with all the "literate" text as
hidden text, so to generate the output for the compiler. you
just generate ASCII with hidden text not displayed. Worked
very nicely!


>
> I don't have specific questions or problems but would be
interested in
> examples from other people's work to improve my techniques.
>
> -Thomas
>
> --
> -- WWW: Standard:       http://www3.cybercities.com/t/thopre/
> --      experimentell:  http://mitglied.tripod.de/thopre/
> -- For my always up-to-date contact information, click here:
http://www.planetall.com/main.asp?cid=1679268
> -- noch 239 Tage bis zum neuen Jahrtausend
>


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Ada and Literate Programming

[Iain Truskett]

On 8 May 2000 22:51:29 +0100, Robert Dewar <robert_dewar@my-deja.com>
wrote:
[...]
> Seeing as the substance of literate programming is very little more
> than writing code that is properly documented, I would hope that
> everyone is doing literate programming in Ada. The very fact that this
> needed to be identified as a special technique and given a special
> name is a bit appalling. The idea of programs that are illiterate and
> cannot be read is frightening to me.

Mind you, LP *does* have the important feature of not requiring your
code to be linear. i.e. the code can be organised to suit the
documentation rather than the documentation being organised to fit the
code.

Very important, particularly in the case of error handling since
otherwise your error handling can distract the reader from the substance
of what your code is meant to be doing.

cheers,
-- 
iain.                                                <http://eh.org/~koschei/>

Re: Ada and Literate Programming

[Georg Bauhaus]

Robert Dewar (robert_dewar@my-deja.com) wrote:

: Seeing as the substance of literate programming is very little
: more than writing code that is properly documented,

Well some people in c.l.literate would strongly object.
Noweb, by default, produces no pretty printing of source lines,
though you can plug in a filter. But the main points of LP have
often been said to be these:

- a way of reordering pieces of code according to the way you
  prefer thinking about them, not in the sequence the computer
  needs its sources, without using subprograms.
  (much of this can be done using declare and pragma Inline in Ada,
  I suppose)

- automatic and semiautomatic indexing of identifiers or anything
  you wish.

If the compiler supports repeated [[#line]] directives, in the Ada case
repeated occurences of [[pragma Source_Reference]] in one source file,
working with WEBs can be fun :)

@ An ad hoc scrambled eggs non-exciting example of noweb code, hardly working
at best, just to give an impression. Here is the main routine, having some
vague similarities with a FSM, hobbyist's work, mind you.
(If you are reading the WEB sources: Note that [[<<]] does not introduce
Ada labels.)
<<test.adb>>=
<<with some used units>>
procedure Test is
   Symbol: Character;  -- one symbol from input
begin
   loop
      <<read a symbol and switch state>>
   end loop;
end Test;

@ Now read [[input symbols]], one by one, and according to whether a
symbol is a digit, a letter, or something else, go on and further
distinguish what needs to be done for each character in its category.
<<read a symbol and switch state>>=
Text_IO.Get(Symbol);
if Is_Digit(Symbol) then
   <<cases for digits>>
elsif Is_Letter(Symbol) then
   <<cases for letters>>
else
   <<cases for other characters>>
end if;

@ You are maybe thinking about digits already (because they appear
first in the above conditional), but first, I have to tell you
about letters, because then some things about digits will become
clear more easily.

Characters are categorized to be vowels, consonants, punctuation,
candidates for the start of a sentecnce, ...
<<cases for letters>>=
case Symbol is
   when 'a' .. 'z' =>
      -- ...
      null;
   when 'A'|'E'|'I'|'O'|'U' =>
      -- ...
      null;
   when '.'|',' =>
      -- ...
      null;
   when others =>
      -- ...
      raise Programmer_s_Error;
end case;

@ So, here is the promised section about digits.
Digits can either be [[< 5]] or otherwise [[< 9]] ...
In that case ...
<<cases for digits>>=
case Symbol is
   when '0'|'1'|'2'|'3'|'4' =>
      -- ...
      null;
   when '5'|'6'|'7'|'8'|'9' =>
      -- ...
      null;
   when others =>
      -- ...
      raise Programmer_s_Error;
end case;

@ Some symbols remain. Each of these has a special meaning.
For example, [['*']] introduces a comment iff it is the
first character on a line,...
<<cases for other characters>>=
  -- ...
  null;

@ Maybe unexpectedly, the list of units this program needs, appears in
The End. :)
<<with some used units>>=
with Ada.Characters.Handling, Ada.Text_IO;
use Ada.Characters.Handling, Ada;

><snip><
Now here is the same untangled, i.e. with original comments included.
Note that this is not what you would work with.

-- An ad hoc scrambled eggs non-exciting example of noweb code, hardly working
-- at best, just to give an impression. Here is the main routine, having some
-- vague similarities with a FSM, hobbyist's work, mind you.
-- (If you are reading the WEB sources: Note that [[<<]] does not introduce
-- Ada labels.)
--
-- <test.adb>=
-- Maybe unexpectedly, the list of units this program needs, appears in
-- The End. :)
--
-- <with some used units>=
with Ada.Characters.Handling, Ada.Text_IO;
use Ada.Characters.Handling, Ada;
procedure Test is
   Symbol: Character;  -- one symbol from input
begin
   loop
      -- Now read [[input symbols]], one by one, and according to whether a
      -- symbol is a digit, a letter, or something else, go on and further
      -- distinguish what needs to be done for each character in its category.
      --
      -- <read a symbol and switch state>=
      Text_IO.Get(Symbol);
      if Is_Digit(Symbol) then
         -- So, here is the promised section about digits.
         -- Digits can either be [[< 5]] or otherwise [[< 9]] ...
         -- In that case ...
         --
         -- <cases for digits>=
         case Symbol is
            when '0'|'1'|'2'|'3'|'4' =>
               -- ...
               null;
            when '5'|'6'|'7'|'8'|'9' =>
               -- ...
               null;
            when others =>
               -- ...
               raise Programmer_s_Error;
         end case;

      elsif Is_Letter(Symbol) then
         -- You are maybe thinking about digits already (because they appear
         -- first in the above conditional), but first, I have to tell you
         -- about letters, because then some things about digits will become
         -- clear more easily.
         --
         -- Characters are categorized to be vowels, consonants, punctuation,
         -- candidates for the start of a sentecnce, ...
         --
         -- <cases for letters>=
         case Symbol is
            when 'a' .. 'z' =>
               -- ...
               null;
            when 'A'|'E'|'I'|'O'|'U' =>
               -- ...
               null;
            when '.'|',' =>
               -- ...
               null;
            when others =>
               -- ...
               raise Programmer_s_Error;
         end case;

      else
         -- Some symbols remain. Each of these has a special meaning.
         -- For example, [['*']] introduces a comment iff it is the
         -- first character on a line,...
         --
         -- <cases for other characters>=
           -- ...
           null;

      end if;

   end loop;
end Test;

Hope this wasn't too long (though so much is missing ...;-).

-# Georg Bauhaus

Re: Ada and Literate Programming

[Ray Blaak]

sb463ba@unidui.uni-duisburg.de (Georg Bauhaus) writes:
[WEB example deleted]

My personal opinion is eek! I much prefer to work with the code directly and
let it speak for itself. This WEB style of programming seems very tedious and
overkill. 

The important documentation that is not readily apparent from the code
describes overall design architectures and strategies. Point by point
explanations of the code is usually unnecessary and too much work to write and
maintain.

-- 
Cheers,                                        The Rhythm is around me,
                                               The Rhythm has control.
Ray Blaak                                      The Rhythm is inside me,
blaak@infomatch.com                            The Rhythm has my soul.

Re: Ada and Literate Programming

[john green]

Robert Dewar <robert_dewar@my-deja.com> writes:

> In article <8f6iue$pu5$1@news.fas.harvard.edu>,
> A favorite technique of Jean Ichbian was to use Microsoft WORD
> to prepare source programs, with all the "literate" text as
> hidden text, so to generate the output for the compiler. you
> just generate ASCII with hidden text not displayed. Worked
> very nicely!
Wow! -- what a great idea -- so I can combine source,
documentation and macro viruses in the same file ;-)

-j
-- 
J.J.Green, Dept. Applied Math. University of Sheffield, UK
http://www.arbs.demon.co.uk

Re: Ada and Literate Programming

[Ted Dennison]

In article <8f6iue$pu5$1@news.fas.harvard.edu>,
  Thomas Preymesser <tp@odn.de> wrote:
> Hi.
>
> Is anyone doing literate programming with Ada?

There used to be an Ada 83 version of Web. I don't think there is one
for Ada 95.

Its something I'd like to see, as the concept of keeping source code
and documentation in the same file is very attractive to me.

> I don't have specific questions or problems but would be interested in
> examples from other people's work to improve my techniques.

If that's what you want, then http://www.adapower.com is the place to
go.

--
T.E.D.

http://www.telepath.com/~dennison/Ted/TED.html


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Ada and Literate Programming

[Robert Dewar]

In article <39171625@pfaff.ethz.ch>,
  Ted Dennison <dennison@telepath.com> wrote:

> Its something I'd like to see, as the concept of keeping
> source code and documentation in the same file is very
> attractive to me.

To me too, but I think it is better to keep it in straight
monospaced text. Yes, this means you can't make such pretty
pictures or use elegant fonts, but what you can do is to
maintain it with exactly the same editors, configuration
management and versioning tools etc as you use for the source,
increasing the chance that it is kept up to date as the
source is changed.


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Ada and Literate Programming

[Sven Utcke]

Robert Dewar <robert_dewar@my-deja.com> writes:

> In article <39171625@pfaff.ethz.ch>,
>   Ted Dennison <dennison@telepath.com> wrote:
> 
> > Its something I'd like to see, as the concept of keeping
> > source code and documentation in the same file is very
> > attractive to me.
> 
> To me too, but I think it is better to keep it in straight
> monospaced text. Yes, this means you can't make such pretty
> pictures or use elegant fonts, but what you can do is to
> maintain it with exactly the same editors, configuration
> management and versioning tools etc as you use for the source,
> increasing the chance that it is kept up to date as the
> source is changed.

But of course this is just (one of) the point(s) about literate
programming, to give you the tools that allow you to include pretty
pictures and elegant fonts _within_ your source-code.  Maybe you
should have a look at the FAQ in comp.programming.literate?

Sven
-- 
 _    _  _____           Artificial Intelligence Unit
| |  | |/ /_ _|                                           University of Hamburg
| |__| ' < | |  phone:      +49 (0)40 42883-2576         Vogt-Koelln-Strasse 30
|____|_|\_\___| fax  :      +49 (0)40 42883-2572                D-22527 Hamburg
          http://kogs-www.informatik.uni-hamburg.de/~utcke/home.html

Re: Ada and Literate Programming

[Robert Dewar]

In article <%X5S4.4606$Ip.157706@cac1.rdr.news.psi.ca>,
  Sven Utcke <utcke@tu-harburg.de> wrote:
> But of course this is just (one of) the point(s) about
> literate programming, to give you the tools that allow you to
> include pretty pictures and elegant fonts _within_ your
> source-code.  Maybe you should have a look at the FAQ in
> comp.programming.literate?

I won't learn anything there that I don't know (in fact I
had a look, and it is all standard stuff!)

My whole point is that in practice I think it is a bad
idea to put "pretty pictures and elegant fonts" within
the source code.

Why?

Two reasons

1. Some people will get distracted and get more interested in
the pictures and the fonts than in the information therein
(I am reminded of the beautifully formatted GNARL documentation
here :-)

2. The pretty pictures will be far harder to keep up to date
with the code, and people will fail in this attempt, resulting
in the worst of all bugs -- out of date comments.

Yes, in the ideal world, we would have an integrated tool set
that everyone knew well that would enable nice WYSIWYG editing
of such pictures, all tied into a configuration management
system etc etc. But in practice, this is very difficult to
get to happen.

As anyone who sees my code knows (check for example g-spipat.ads
in the GNAT sources). I am rather fanatic on good documentation.
I would love to be able to make nice pictures and use pleasant
to read fonts in this documentation, but I simply don't see
practical systems that support this today.


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Ada and Literate Programming

[Robert Dewar]

In article <%X5S4.4606$Ip.157706@cac1.rdr.news.psi.ca>,
  Sven Utcke <utcke@tu-harburg.de> wrote:
> But of course this is just (one of) the point(s) about
> literate programming, to give you the tools that allow you to
> include pretty pictures and elegant fonts _within_ your
> source-code.  Maybe you should have a look at the FAQ in
> comp.programming.literate?

I won't learn anything there that I don't know (in fact I
had a look, and it is all standard stuff!)

My whole point is that in practice I think it is a bad
idea to put "pretty pictures and elegant fonts" within
the source code.

Why?

Two reasons

1. Some people will get distracted and get more interested in
the pictures and the fonts than in the information therein
(I am reminded of the beautifully formatted GNARL documentation
here :-)

2. The pretty pictures will be far harder to keep up to date
with the code, and people will fail in this attempt, resulting
in the worst of all bugs -- out of date comments.

Yes, in the ideal world, we would have an integrated tool set
that everyone knew well that would enable nice WYSIWYG editing
of such pictures, all tied into a configuration management
system etc etc. But in practice, this is very difficult to
get to happen.

As anyone who sees my code knows (check for example g-spipat.ads
in the GNAT sources). I am rather fanatic on good documentation.
I would love to be able to make nice pictures and use pleasant
to read fonts in this documentation, but I simply don't see
practical systems that support this today.


Sent via Deja.com http://www.deja.com/
Before you buy.

Re: Ada and Literate Programming

[Norman Ramsey]

In article <8f6iue$pu5$1@news.fas.harvard.edu>,
Thomas Preymesser  <tp@odn.de> wrote:
>Is anyone doing literate programming with Ada?

In 1986 I was using Spidery Web with Ada.
I think the support is still available on CTAN.

Today I would use noweb :-)
-- 
Norman Ramsey
http://www.eecs.harvard.edu/~nr