Re: Scheme documentation question

[Tel <telford@eng.uts.edu.au>]

> Excellent point.  But why couldn't you have a convention about what
> these tokens look like?  In Emacs, they have implemented a notation
> for specifying calling conventions that uses a form called
> 'interactive'.  In runnable code, 'interactive' is a function that
> does nothing.  You could have a form called 'docstring' that worked
> similarly in guile, that supported internationalization, and that had
> the documentation inside of defining forms.

Because it is a more complicated way of going about the same thing
as just having a form called (document-function blah blah) and
another called (document-variable blah blah). I use scheme because
I believe that simple is best, the only reason I'm not using Java
for all of my scripting is that when it came to a decision, scheme
seemed easier to link to.

I know how the docstrings work in emacs and the mechanism seems to me
to be based on special case programming which usually implies sacrificing
the future for the present.

> > You might decide to have a function that returns docstrings but your
> > parser is set to look for strings and doesn't know whether this
> > function is designed to return a string or whether there is no
> > documentation and this function is part of the real definition.
> 
> Does my proposal addresses this valid point?  I think docstrings
> should be right in the source, and that with some creativity, no
> generality will be lost.

Yes, your proposal will do everything that a standard top level
expression will do so why not do it the easy way and use a top
level expression. Is it more fun to walk with a millstone hanging from
your neck or to realise that it is round and roll the thing along?

Because of the strange belief that forcing people to combine a function
definition with the documentation is better than letting them put it
near if they like or further away if they like, everyone has to go
about life the hard way -- this way of thinking is something I spend
my life avoiding.

	- Tel