My previous email was rejected by SPAM Assassin.

On Mon, 27 May 2024 19:22:29 +0200
Jens Axel Søgaard <xxxxxx@soegaard.net> wrote:

>
> Not introducing new syntax has the added benefit that a documented
> program can run unaltered on an Scheme implementation
> that hasn't implemented the proposal yet.
>
> The usual approach is something like this:
>
>     (define (foo a b)
>         <some string literal documenting `foo`> ...
>         <actual body of `foo`>)
>
> The documentation system can then use the string literals to generate
> documentation in some format.
>
> For the record, since s-expressions can express anything, I don't think a
> new syntax is needed.

In LIPS I successfully use this approach and I have standard Scheme syntax
for the code. I don't need to introduce any new syntax.

I used those strings to generate the reference manual on LIPS website.

I think that the more important part of the SRFI should be a way to get the
docstrings back, so you can create tools that extract documentation.

Another thing that is missing is returning all names from environment.

In LIPS I exposed environment objects that could be introspected, but env
function that return list of symbols (that is another way to get the names in
LIPS) is also enough.

If this SRFI should help create documentation those two procedures could be
added (or something similar) (help and env)

(map (lambda (name)
       (list (cons 'name name)
             (cons 'doc (help name))))
     (env))

NOTE: this code doesn't work in LIPS, because of the way `help` is constructed
to be working in the REPL.

Writing documentation inside Scheme that support this would be much easier
then writing a tool that will parse scheme code (at least this is my
preferred way). It would also allow to create REPL for the implementation that
supports built documentation.

Better introspection (reflection) is one thing that I really miss in Scheme.

--
Jakub T. Jankiewicz, Senior Front-End Developer
https://jcubic.pl/me
https://lips.js.org
https://koduj.org