Re: Doc organization (Re: Around again, and docs lead role)

[Rob Browning]

Neil Jerram <address@hidden> writes:

> To me, if defeats the whole object of Guile if catering for this case
> means that it is harder to improve Guile and its docs for the other
> 99% of cases.  To avoid this happening, I suggest that we could solve
> this problem by a mechanism that links Scheme code into a library or
> executable at build time.  This could be something like unexec (in
> which case the source would already have been read and stored in tree
> code), or it could be a linker tool that just dumps plain source code
> into the binary - as though it was a big const char[], but more
> convenient to use at build time.

That could be interesting.  To some extent how we decide to handle
compilation will factor in here.

If you thought large static scm fragments, were likely to be common, I
guess one thing that might make hacking easier would be an easy way to
do something equivalent to #include <foo.scm>, i.e. a way you could
hack the scheme part as a scheme file, but then have the code end up
incorporated in and evaled by the .so file.  Of course I guess anyone
could hack something like that up if they needed to with a makefile
and appropriate use of "cat"...

Actually, I've been playing around with code that would make something
like this possible (as a dumb example):

  (define (double x)
    (c-syntax
      (if ("SCM_INUMP" x)
          (return (* x x))
          (return ("scm_apply" ("scm_lookup" "+") x x)))))

and that already works for

  (%function "main" int ((int argc) ((%array (* char)) argv))
    ("printf" "Hello world\\n"))

etc. (i.e. a C s-expression representation), but I'm not sure how
likely it is that anyone else would find it amusing.  I can think of a
few possible uses for such a construction (g-wrap, auto-ffi,
"c-side"-macros, scm-to-C-compiler-back-end, c equiv of inline-asm),
but I'm still not sure it's really worthwhile.  I might comment more
later if I remain intrigued...

> Embedded Scheme is OK for small code fragments, otherwise as just
> suggested above.  As far as dynamic content is concerned, is there any
> kind of dynamic Scheme content that can't be generated and then eval'd
> by a chunk of static Scheme code?  (I don't think so, if it could be
> generated by a chunk of static C code.)

Not sure.  As long as you're not limited to eval_str -- i.e. as long
as you have eval_form, then perhaps not.

> Absolutely.  I think that data substructure manipulation functions
> like scm_cons, SCM_CAR and SCM_CDR, should be included in the
> documented C API.

Sure, but I was wondering what else might be needed.  Of course I'm
not sure I have a clear idea of what kind of things might be
omitted...

> Now that I've been involved for some time, I'm pretty sure that any
> extra work will be insignificant compared to the long term cost of not
> having the right overall focus and structure.  So I wouldn't worry
> about the work yet.

Focus is good.

-- 
Rob Browning
rlb @defaultvalue.org, @linuxdevel.com, and @debian.org
Previously @cs.utexas.edu
GPG starting 2002-11-03 = 14DD 432F AE39 534D B592  F9A0 25C8 D377 8C7E 73A4