Daphne Preston-Kendal <xxxxxx@nonceword.org> writes:

> Documentation will be attached as an identifier property (a la SRFI 213).
> This means everything can be documented – not only procedures but macros,
> variables, record types and associated procedures, etc. etc.
>
> There is an implementation to show how simple this idea could be at
> <https://codeberg.org/scheme/r7rs/wiki/Identifier-property-use-cases>.
> (This is only a sketch.)
>
> This solution also means that a manual page could be generated for a whole
> library, etc., during compilation of the library itself by attaching special
> expand-time behaviour to the ‘documentation’ macro. The sketch above doesn’t
> include this, but it would be easy enough to do with a
> (current-documentation-exporter) parameter containing a procedure that’s called
> when documentation is defined, or similar.

Sounds good.

> If this does happen, it will be specified in the Batteries, because the core
> mechanism of identifier properties is already there in the Foundations. (This is
> one Battery that implementations will likely want to adopt into their cores, so
> that Foundations procedures etc. have interactive documentation available.)

Can this be put into a SRFI, rather than being promised (maybe) for when
Batteries is ready? A few implementations have ad-hoc documentation
abilities, but if one wants to write portable, documented Scheme code
then they are out of luck.

> Primarily in order to make it easier to include examples within the
> documentation which themselves include strings, but also for other longer string
> literals, I proposed a nestable #" … "# string notation comparable to #| … |#.
> But I consider the value of this questionable. Emacs Lisp and Common Lisp have
> both got on perfectly well for the better part of 50 years without this.
>
> As ever, I am not dictator of WG2 and all of these things are still open for
> debate. My sense is that we have informal consensus for the identifier property
> based solution, but my #" … "# idea was just a strawman proposal and hasn’t been
> extensively debated beyond a few minutes’ idle chat on IRC.

There is no way to know of these consensuses without being involved with
WG2 on IRC, which most of the Scheme programmers are not. I think it
would be good if these ideas were communicated outside the group. I
don't know the best way of doing that (besides SRFIs).