Re: Ada and Literate Programming

[Robert Dewar <robert_dewar@my-deja.com>]

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.