Re: Documentation

[Michael Livshin]

Neil Jerram <address@hidden> writes:

> >>>>> "moi" == Michael Livshin <address@hidden> writes:
> 
>     moi>   0) Emacs is not cooperative enough.
> 
>     moi>   a different string syntax should solve that.
> 
> Agreed.  In fact, I did a little more experimentation, and found that
> Emacs fills multiline strings in Scheme mode quite nicely.  The only
> slight annoyance is the indentation and quotation mark at the
> beginning, which tend to make the first line of the documentation too
> short.

actually, the main annoyance I was thinking of is the fontification.
docstrings look quite unappealing all in one (in my case green) color.
different delimiters would make it possible to do texinfo-mode-like
fontification or something similarly pretty.

>     moi>   1) docstrings take up memory.
> 
>     moi>   I don't believe this to be a serious problem, actually.
> 
> No, but others may do, and I think we should take their opinion into
> consideration.

... and not do anything about it. ;))))

> Just to pull everything together in one place, I think that the other
> pieces of the puzzle are:
> 
> - the Scheme-level interface that I described, namely:
>         - documentation-string
>         - documentation-properties (better name for `meta-info')
>         - document!

this looks good, except I probably would like there to be an
<object-documentation> class, which would have the docstring and the
various properties as the slots.  just feels more orderly to me, and
also helps cut down on the syntax.  all you would need is a procedure
with setter called `documentation'.

>         - #:documentation-filter
>   plus syntax:
>         - define/documented
>         - lambda/documented
>   and perhaps an option for people who want their `define' and
>   `lambda' to automatically be `/documented'

personally I think that the CL-like "ambiguous" convention is just
fine...

> - writing the documentation filter code to handle stuff like makeinfo
>   and i18n.
> 
> Do we have an agreed approach then?

I'm really of the opinion that it's much harder to write the docs in
the first place than to later reformat them any way one pleases. ;)

-- 
===  ALL USERS PLEASE NOTE  ========================

The garbage collector now works.  In addition a new, experimental garbage
collection algorithm has been installed.  With SI:%DSK-GC-QLX-BITS set to 17,
(NOT the default) the old garbage collection algorithm remains in force; when
virtual storage is filled, the machine cold boots itself.  With SI:%DSK-GC-
QLX-BITS set to 23, the new garbage collector is enabled.  Unlike most garbage
collectors, the new gc starts its mark phase from the mind of the user, rather
than from the obarray.  This allows the garbage collection of significantly
more Qs.  As the garbage collector runs, it may ask you something like "Do you
remember what SI:RDTBL-TRANS does?", and if you can't give a reasonable answer
in thirty seconds, the symbol becomes a candidate for GCing.  The variable
SI:%GC-QLX-LUSER-TM governs how long the GC waits before timing out the user.