Re: Source Text Tools

[Tim Teulings <tim@edge.ping.de>]

Hallo!

> The really nice thing here is that this kind of data structure is very
> useful for a large number of purposes.  Each of the following tools
> can be built upon its information:

[...]

A number of these tools (printy printer, autodocumentation tool, code
beautifier) are already implemented as part of VisualOberon. However
they are hacked quick and dirty and their scanner/parser is very
simple.

> o To which declaration is a doc comment attached?  For procedures this
> is simple, the comment is placed after the header but in front of the
> first local declaration.  How is this handled for the other kinds of
> declarations? 

The autodoc program has a little bit different aproach. Commands for an
object are allways in front of an object. For module this means before
the MODULE keyword, for procedures before the PROCEDURE keyword, for
record before the record keyword. This worked well and did not uglified
the source. I don't like the idea of putting the comment *after* the
header (e.hg. after the PROCEDURE keyword or after the RECORD keyword)
just for estethic reasons.

If you also want to comment member variables, varibales constants etc...
putting the comment before the keyword will not work, you have to put
it after it. I strongly urge you to at least support this style, or I will
have to change a huge amount fo sources to change this!

> o Are free floating comments, i.e., comments not attached to a
> declaration, permitted and how are they dealt with?

Autodoc scanns a keyword and then goes back the list of token searching
for a comment. If another keyword apear the search will be stoped. As a
result, autodoc comments somewhere in the text will be ignored. If want
to print them out you are very close to literate programming ;-)

> o Should there be special commands available to refer to other
> declarations from within a comment?  E.g. a procedure doc comment
> could refer to its parameter `foo' as @oparam{foo}, and to a type
> `Bar' as @otype{Bar}.  This kind of reference tags allow consistency
> checks (does the referenced declaration exist? is it of the correct
> kind?) and permit to insert hyper-links when translating to HTML.

The problem with this aproch is, that you end implementing all keyword
html or latex has. Tables and list will soon per to be nice stuff
implemented. You can restrict yourself to a *very* limited set of
options or drop the idea of makeing your own language and use an
existing one. for autodoc I planed to yuse SGML together with the
SGML-Tools. This will allow you a huge number of formatting stuff while
beeing able to generate a huge number of document types without doing
it all for yourself.

I'm sory that this mean that my selfwritten tools will be droped. But
your aproach is of course the better one. But as told above I hope that
the final solution will enable me to change tools without changing the
whole source tree.

-- 
Gru...
       Tim.