Re: Source Text Tools

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

Hallo!

> I don't understand this.  But with my proposed rule above _all_ doc
> comments are attached to a declaration, which solves the problem in a
> way.

Free floating comments make no sense in my opinion. If you cannot
attach a comment to declaration you just drop it. Autodocs are not for
commenting full source code (we will then use an existing literate
programming system like web (or do one ourself)) but interfaces.
Automatically generating man pages and that stuff is the goal.

> > Hmm... I'm not sure about this one.  I think I'd have to see an example of
> > how you think these kinds of commands should be used.  Are these specialized
> > @ref commands?

You will refer to the comment of another method/class by using a link
to the class. What you propose is a workaround for using macros in
documentation. Neat, but a whole without ground (see LP).


> 1. Description is plain ASCII formatted
Bad.

> 2. Description is formatted for texinfo
texInfo is not that powerfull. Exspecially placing link everywhere you
like like you can do in HTML is ugly. Links cannot be place correctly
everywhere in free floating text. Don't exspect teXInfo syntax to be
easily convertable to TeXInfo everytime.

> 3. Description is formatted with additional @oxxx commands

> > The texinfo commands that I use the most and find the most useful (besides
> > the structuring commands like @node, @chapter, @menu, etc.) are mainly for
> > formatting and cross referencing.  


> Judging from my own experience with texinfo the above list is
> complete.  I don't see any easy mechanisms for automatical formatting.
> E.g. one could try to identify the names of Oberon-2 entities in
> descriptions and assign formats to them based on this information.
> But this can't be done with 100% success.  Therefore I would prefer
> explicit markers.

I don't like the idea of explicit formatter, exspecially for links. I
propose the above mentioned idea of automatic link generation. I
already use a tool at work wich does explizit linking. I has been found
out that this takes a lot of time and does not work well. We are
searching for a tool that does implicit linking. We are sure that this
be great time saver. Automatic linking will give the formatter also
more freedom for formats not implementing links or only a restricted
set. Howver automatic linking needs more CPU time. I also propose a more
restricted and implicit formatting set. I'm not sure about this, but it
may be an alternative. Since formatting of O2 stuff will be done
automatically you no "@var{}"-stuff and that like. As result the
standard formatters known from the internet "*bold*, /italic/ and
_underline_ are only necessary. Also list can be detected by putting a
"-" before it. You can use "*" for numbered and "-" for unnummbered
list. Section will be deteced by special keywords. Simple tabe will
work similar, complex ones of course not.

PARAMETER
a:
  Parameter a
b:
  Parameter b *must* be valid.

-- 
Gru...
       Tim.