Re: Documentation

[Neil Jerram]

>>>>> "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