RE: [OpenJade-devel] Here again

[Didier PH M. <ma...@ne...>]

Hello Yann,

Yann said:
Well, those IDEs you mention are not AFAIK litprog-aware.  What would
be needed is such an IDE.  I've recently noticed LEO, which is a
cross-platform one, supporting noweb and cweb.  I suspect it may be a
bit primitive in the code-editing area, but it may be useful
nonetheless.

http://sourceforge.net/projects/leo/

Didier replies:
Yann, the tools I mentioned are working, debugged and quite
sophisticated for editing, debugging, compiling. The last thing we need
with openjade is to debug our development tools in addition to debug the
openjade code. 

Here is my suggestion for the code documentation:
a) a set of web pages included in sourceforge
b) a web page for each major functional block (ex: DSSSL interpreter,
SGML parser, DTD parser, DSSSL source code parser, etc...). The page
document what this functional block is doing and list the files
involved. It would be even better is the classes are related to each
other in a UML drawing. Two kind of schema would be useful 1) class
relations, 2) class interaction. Said differently a static relationship
and dynamic behavior description.
c) Text comments inserted in the source code that describes what the
class is doing.

This would be enough to help the developers, no additional overhead
involved.

The last thing we should do is to turn off people who want to do some
coding. I still remember, the modifications I had to do to the code
before we posted that to sourceforge. The last thing I wanted to get
were roadblocks.

In may last 25 years managing software projects I learned that
simplicity has its virtues. 

By the way, if I remember well the difficulties Matthias and me
encountered in the past with the openjade code, was a good documentation
of the major modules (ex: DSSSL interpreter, SGML parser, DTD parser,
etc...) and their interface or class. I remember that we wanted to
publish only the SGML DTD parser as a unit but got not enough time to do
so. So, by showing the OPenjade code as a collection of modules, we will
accomplish tremendous progresses.

This said, I am not opposed to literate programming, Simply that actual
tools are not adapted to it, that we barely have the time to develop one
(since we have to maintain openjade). 

Why not move a baby step at a time and move from small accomplishable
goals to small accomplishable goals to finally end up where we want to
go.

If eventually we discover a simple and efficient way to use literate
programming it would be better to use DSSSL doesn't it? Here is a like
to our friend Norman Walsh tool:
http://xml.coverpages.org/walshLiterateDProg.html, Notice that a DSSSL
style sheet is an SGML document but most style sheets do not include any
markups. This is because of the DTD we are using in OpenJade. This is
because DSSSL code is contained in CDATA element. However, When we
experimented to use the same technique we where using with DSSSL and
Docbook with C++ code we encountered a problem with ">" and "<"
characters. Unless you redefine the begin tag and end tag in the SGML
declaration you have difficulties in SGML or XML with expressions like :
if a > b then .... Imagine having to encode with & all these
expressions. This is not what I call productivity improvements or a good
way to convince programmers to join the OpenJade team. By the way, why
Linux is not using XML or SGML literate programming. Simply because the
leaders do not want to include roadblocks to code programming
volunteers. The last thing we want to do is to punish them for
developing in the openjade project. However, if tools as sophisticated
as the professional coding tools allows to include literate programming
in an efficient way, then I am for it, otherwise, let not make things
more complex than they are. Programming is not an easy task and we
should minimize the roadblocks.

Cheers
Didier PH Martin