[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation
From: |
Neil Jerram |
Subject: |
Re: Documentation |
Date: |
05 Mar 2001 21:59:03 +0000 |
User-agent: |
Gnus/5.0808 (Gnus v5.8.8) Emacs/20.5 |
>>>>> "Michael" == Michael Livshin <address@hidden> writes:
Michael> I've chewed on the subject some more...
Michael> * generally, when thinking up such things, it would be
Michael> wise (IMHO) to pretend that Guile already has a compiler.
Michael> this is because, despite the mounting evidence to the
Michael> contrary ;), I still believe that we are going to have
Michael> one. so introducing hairy stuff that helps the current
Michael> interpreter-only situation but is useless with a compiler
Michael> should be done with extreme caution or not done at all.
Michael> * so let's see again what problems with docstrings we
Michael> want to solve:
Michael> 0) Emacs is not cooperative enough.
Michael> 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. But this annoyance could be overcome by writing docstrings
like this:
(define/documented (make-foo bar)
"\
Make and return a new foo using the template @var{bar}."
...)
We just need to persuade Emacs not to fill back onto the `"\' line.
So perhaps we don't even need a new string syntax.
Michael> 1) docstrings take up memory.
Michael> 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.
Michael> and it is trivially solved by a compiler. if it turns
Michael> out to be a real problem, it *can* be solved with that
Michael> read-macro/database trick.
Agreed; there are several possibilities here. One would be a read
option that would cause the reader always to discard literal values
that can't normally be returned. I think you're right that we don't
really need to solve this part of the problem now.
Michael> so, while the trick can be employed, I don't think it
Michael> nesessarily should be employed. and anyway it shouldn't
Michael> be *mandated*.
Michael> * now, to address your points:
Michael> 1. no, I don't think the load time should be affected
Michael> very much, at least I don't see any reason to be afraid
Michael> of that. especially if the #{...}# things (or whatever
Michael> syntax is decided on) are just read in as strings.
Yes, agreed.
Michael> 2. what problems do you have in mind that such general
Michael> read-time database functionality would solve?
Nothing in particular. I just thought there was a nice fit there with
Keisuke's work.
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!
- #:documentation-filter
plus syntax:
- define/documented
- lambda/documented
and perhaps an option for people who want their `define' and
`lambda' to automatically be `/documented'
- writing the documentation filter code to handle stuff like makeinfo
and i18n.
Do we have an agreed approach then?
Regards,
Neil
Re: Documentation, Jorgen 'forcer' Schaefer, 2001/03/01