Re: Source Text Tools

[Michael van Acken <KK120y2@mail.lvr.de>]

> Michael van Acken <mvacken@t-online.de> wrote:
> > 3. Description is formatted with additional @oxxx commands
> > PROCEDURE (list: List.List) Append* (node: List.Node);
> > (**
> > Adds node @opar{node} to the end of list list @opar{list}.  If
> > @opar{node} is of type @otype{List.NodeUp}, then its field
> > @ofield{List.NodeUp.up} is changed to refer to @opar{list}.
> > 
> > @empf{pre}: @opar{node} is not part of any list.  
> > *)
> 
> I liked this proposal most of the three.
> I think theres most to gain by using annotations that have 
> a meaning beyond mere formatting.
> In this spirit, perhaps pre/post condition lists are important 
> enough to have their own 'tag' rather than just using @empf ?

It should @emph instead of @empf.  My fault.

Good idea to give pre/post-conditions their own tag.  But then the
whole text of the condition should be placed inside such tag.  Using
Texinfo as example it would look like this:

@precond
@opar{node} is not part of any list.
@end precond

Clumsy, but it works :-)

> Other candidates for such tags are IN/OUT parameters, and some of 
> the annotations that were added to component pascal records and 
> methods.

Additional semantic properties are always available if you include
the referred declarations in the analysis.  E.g. it's simple to
distinguish between VAR parameters, value parameters, and receivers
when taking the procedure header into account, without further need
to split the tag @opar (or @oparam, or whatever) into further
subcategories.

> Has any consideration been given to separating the documentation
> from the module source? Personaly I find documentation in source
> mostly gets in the way while editing/reading and I much prefer 
> separate reference documents.

One true advantage of having the interface description in the module
itself is easier maintenance.  You only need to update a single file,
not separate module and description files.  An extreme example of
single text, two targets is Knuth's literal programming approach: he
derives both the program text and a book(!) from a single source
file.

I agree with you that people only interested in a module's interface,
but not in the source code itself, should be able to extract the
interface.  

> One last idea, how about designing an XML DTD for OOC 
> documentation files? XML seems to be catching on and it 
> sounds like it provides a reasonably simple framework for 
> this kind of project, instead of an ad-hoc design.

I got the same impression.  But then I have only listened to the
hype.  I don't have hard facts about XML, like its purpose, how it
works, its format, available tools for it, etc.  If someone would to
dig into this and come up with a detailed proposal based on XML I'm
sure we'll all agree with it.  Currently I favor the Texinfo-like
approach only because there is no better proposal.  But someone has
to do some hard work for this.  Who will do it?

-- mva