Re: HTML as GNAT source

Re: HTML as GNAT source

[Lionel Draghi]

Robert C. Leif, Ph.D. wrote:
>
> To: Robert I. Eachus et al.
> From: Bob Leif, Ph.D.
>
> Using HTML for source text (code) would greatly improve Ada environments.
> It would then be possible to create cross-references between the
> documentation and the source text (code). Thus if I had a requirement in my
> documentation, I could make a link in my source to it. This would permit
> the references in both the source and the documentation to be updated.
>
I agree that it could be (it will be :-) a great improvement.
I daily dream that, in my code, some reference to a
problem report, appears whit a different color. I click on it,
and xemacs open me a new frame containing the problem report.

It's only a dream, but reality is not so far. hTML is a simple and
widely
used technology, so for others tools involved in the developpment
process, there is no real problem. No doubt that Robert's initiative
regarding Ada code will be successfull, but an immediate first step
could be to process html markers in Ada comment. I think this will
cause compiler no special problem.
What we only need is an elisp gourou to merge Ada and html mode :-)

________________________________________________________________________
Lionel Draghi              01 45 28 88 50          17, rue Simon Dereure
                                                  93 110 Rosny-sous-Bois

Re: HTML as GNAT source/Knuth's Web

[Nick Roberts]

Who remembers Don Knuth's 'Web'?  This was a wonderful idea (IMHO!), in
which pieces of the source code (of any programming language) of a program
were embedded in a text document (TEX or whatever) which also contained the
documentation for the code.

The trick was that the pieces were named, and other pieces could be
embedded, macro-like, into a piece of code, by name.  I tried this idea out
myself, in my youth (many moons ago...), and I liked it.  Two special
programs were needed: one to 'spin' the web document into a file suitable
for printing (or browsing or whatever); one to 'tangle' the web document to
produce the source code for compilation.

Knuth coined the deliberately perjorative phrase "literate programming" for
this techinique.  Once you got used to it, the results could be very neat! 
The best thing about it (and I suppose the worst too) was that it
practically forced you to properly document your program as you wrote it.

In an industry which highly valued the production of good quality software,
this idea would have been a breakthrough.  Needless to say, in reality it
never caught on!

-- 

== Nick Roberts ================================================
== Croydon, UK                       ===========================
==                                              ================
== Proprietor, ThoughtWing Software                   ==========
== Independent Software Development Consultant            ======
== Nick.Roberts@dial.pipex.com                              ====
== Voicemail & Fax +44 181-405 1124                          ===
==                                                            ==
==           I live not in myself, but I become               ==
===          Portion of that around me; and to me             ==
====         High mountains are a feeling, but the hum        ==
=======      Of human cities torture.
===========                             -- Byron [Childe Harold]

Re: HTML as GNAT source/Knuth's Web

[Samuel Mize]

In article <01bd3364$2c898c80$LocalHost@xhv46.dial.pipex.com>,
Nick Roberts <Nick.Roberts@dial.pipex.com> wrote:
>Who remembers Don Knuth's 'Web'?

I rememeber it.  I read his example program, and found the amount
of text surrounding the simplest items excessive and confusing,
the style of cross-reference harder to follow, and the program
overall harder to read than normal Ada code.  

In all fairness, I was seeing his program presented as a written
document.  The programs I work on are large systems, and I do a
lot of navigation with cross-reference tables, find and grep.
Perhaps his overall tool suite would provide similar help, but
it didn't seem to me a particularly better way to organize code.

Obviously, other people felt differently:

>This was a wonderful idea (IMHO!)

Some of his ideas were certainly worth using.  For instance:

- his format encouraged you to discuss the program and its design;

- (if I recall right) his book-like organization included a table of
  contents and an index;

- his format broke the program into subsections in which, as in a
  well-written technical document, only one subject is covered.

>Knuth coined the deliberately perjorative phrase "literate programming" for
>this techinique.

I assume from your discussion that you mean it was deliberately
perjorative toward OTHER techniques.

I've actually seen some very good examples of literate programming
in Ada.  (I HOPE I've created some of them.)  Not in terms of using
a web/spider tool, but in terms of writing in a literate style.

To take the points listed above in the same order:

- we don't generally put the design document into the code (or
  vice versa), but we do follow the design or amend it to reflect
  the code.  Ada code, well written, is fairly self-documenting
  at the line-of-code level, so my comments tend to be blocks of
  text that explain blocks of code, as opposed to:

        N := N + X; -- increment N by X

- Various tools provide indexing and cross-referencing to a great
  degree in Ada.  Also, packages can be used not only to control
  namespaces, but to provide a fairly clear top-level organization
  (although in all fairness, they too often are not used this way);

- the use of packages, contained and child packages, and textual
  division with formalized comment blocks provides a good way to
  break the program into cohesive subsections.  Ada 95 improves
  this over Ada 83 by allowing declarations to be freely intermixed,
  so you can declare all related items together.

>The best thing about it (and I suppose the worst too) was that it
>practically forced you to properly document your program as you wrote it.

Nah.  I could write a program using his tools that had virtually
no documentation, not even meaningful identifiers.

The point to the tool, as I understood it, was to promote the idea
of literate programming in WHATEVER tool system YOU were using.  It's
kind of like Pascal, which was originally intended purely as a way to
give students good coding habits.  If Mr. Knuth had higher hopes for
the specific tool he developed, they didn't pan out -- but I didn't
observe any concerted effort to market it, either (maybe I missed it).

>In an industry which highly valued the production of good quality software,
>this idea would have been a breakthrough.  Needless to say, in reality it
>never caught on!

I think it had an impact, and that it also reflected some trends that
were already crystallizing in the industry.  Of course, I'm immersed
in the Defense/aerospace part of the industry, where (at least some)
people already consider reliability and maintainability to be worth
paying for, unlike some companies.  Not to name any major PC OS vendors.

I wouldn't claim that his ideas have suffused the industry, but they
haven't gone totally ignored, although the tool he built generally has.

Best,
Sam Mize

-- 
Samuel Mize -- smize@imagin.net -- Team Ada
Fight Spam - see http://www.cauce.org/
Personal net account - die gedanken sind frei

Re: HTML as GNAT source/Knuth's Web

[W. Wesley Groleau x4923]

> Who remembers Don Knuth's 'Web'?  This was a wonderful idea (IMHO!), 
> ....

> The best thing about it (and I suppose the worst too) was that it
> practically forced you to properly document your program as you 
> wrote it.

Correction: It ALLOWED you to document your program as you wrote it.
Is there anyone here who has NEVER seen an uncommented program?

-- 
----------------------------------------------------------------------
    Wes Groleau, Raytheon Systems Company, Fort Wayne, IN USA
Member of Technical Staff - AFATDS                 Tool-smith Wanna-be
                    wwgrol AT pseserv3.fw.hac.com

        Don't send advertisements to this domain unless asked!  
         All disk space on fw.hac.com hosts belongs to either 
       Raytheon Systems Company or the United States government.  
     Using email to store YOUR advertising on them is trespassing!
----------------------------------------------------------------------