[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation
From: |
Rob Browning |
Subject: |
Re: Documentation |
Date: |
12 May 2001 14:50:12 -0500 |
User-agent: |
Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7 |
(Sorry for the late reply. I'm catching up on the last bits today
from when I (re)joined a while back. Also, if this has been fully
resolved since, just take my comments as commentary :>)
Neil Jerram <address@hidden> writes:
> 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.
And this has the distinct added advantage of not making the function
definitions *much* harder to parse by a non-Guile Scheme.
With #{}# any other reader would just choke on the definition, and it
would be difficult to fix (aside from just deleting the docs. With
either a string, or the stuff I think Marius had mentioned (i.e. a
special form:
(define (foo bar)
(doc :some-info ...
:some-more-info ...
:body "\
...)
I believe it should be possible to just write a standard R5RS macro to
drop (or rewrite) all the docs.
> 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.
And I think it's probably a solvable problem, at least on systems
where we have demand paging, or can manage to put the documentation in
optionally loadable sub-files.
--
Rob Browning <address@hidden> PGP=E80E0D04F521A094 532B97F5D64E3930
- Re: Documentation,
Rob Browning <=