Menu

#159 misc documentation issues

closed-invalid
clisp (524)
5
2003-05-12
2003-04-29
No

Hi,

here's a collection of small and larger issues

0
http://cvs2.cons.org/ftp-area/clisp/snapshots/impnotes/
is hard to use these days because the table of contents
page seems missing, and having nothing but next+prev
for navigation is unusable.
The header says on every page:
"CLISP Implementation Notes [user.header.content]"
which looks strange

1 sys::dynload-modules is not documented and (at least
on Linux) seems
to need no -fPIC, but rather cc -shared -o <name>.so
<name>.o

2
ftp://ftp2.cons.org/pub/lisp/clisp/snapshots/impnotes/w
ildcard.html
shows "untitled document" and "@newindex {fn}" (and
"generated by texi2html")

3 module chapter is not UNIX only. link-kit is. Need to
restructure
sections to document part that is portable across all
CLISP platforms
and the UNIX-specific link-kit shell script and way of
building
modules.

4 document foo.c file creation from foo.lisp when using
FFI forms

5 *parse-namestring-dot-file* is not documented

6 SOCKET-WAIT return value is not documented

7 "All SOCKET:SOCKET-STREAMs are :IO streams"
It's unclear how socket-shutdown breaks this. It sounds
as if
output-stream-p will always return T, even after
shutdown :output.
Isnt't it so that the stream's flags are modified and
the rd_byte
slots are replaced by the error signaling rd_by_dummy?

"so it will work for any CLISP STREAM which is based on
a
file handle, e.g., file/pipe/socket and
EXT:*KEYBOARD-INPUT*."
-> sockets only on UNIX. On MS-Windows and Amiga, they
are different
objects, and read() write() must not be called on them.

Regards,
Jörg Höhle

Discussion

  • Sam Steingold

    Sam Steingold - 2003-04-29

    Logged In: YES
    user_id=5735

    0. fixed.
    1. sys::* are not use functions and as such are never
    mentioned in impnotes.
    the user interface is to be created and documented.
    I suggest :shared-library option to :def-call-out
    2. I know nothing about texinfo syntax. fix this yourself.
    3. you write a doc on how to use modules without clisp-link,
    including whether it is possible to use clisp-link on mingw.
    4. what do you mean? see <impnotes.html#compile-file>
    5. did you even bother to look at NEWS?!

    <file:///usr/local/src/clisp/current/doc/impnotes.html#name-type-split>
    6.fixed.
    7.clarified.
    8.I guess you are talking about socket-status (you are vague!).
    I believe it works on files and pipes on win32 also. try it
    and fix it.

     
  • Jörg Höhle

    Jörg Höhle - 2003-04-30

    Logged In: YES
    user_id=377168

    First, thanks for all the fixes. Here are the remaining
    points.

    1. dynload-modules has nothing to do with FFI/def-call-out.
    It exists all by itself (based on the module feature of
    CLISP), e.g. to load my fast-vector-position patch/module.
    As such, it needs to be put into EXT and documented.
    Would you prefer another function signature than the current
    one?
    (ext:dynload-modules "/foo/bar/fastseq.so" '("fastseq"))

    5. Sorry. It's probably via NEWS that I read about it. I
    don't know why/how my search for dot-file in *.html or *.xml
    went wrong.

    3,8 ...later

     
  • Sam Steingold

    Sam Steingold - 2003-04-30

    Logged In: YES
    user_id=5735

    dynload-modules requires --with-dynamic-modules.
    should that option be the default?
    it is also somewhat deficient in that it does not work with
    arbitrary *.so
    and on win32.
    will you fix these?

     
  • Jörg Höhle

    Jörg Höhle - 2003-05-05

    Logged In: YES
    user_id=377168

    Ad 1. Dynload-modules is as is: it loads what CLISP calls
    external modules, per definition those with a
    module_xy_subr_tab etc. I will not fix that. It has its
    uses, enough to warrant an entry in impnotes.
    I believe it cannot be made to work on win32 this way. A
    .dll is very different from a .so: a full executable and
    address set vs. an incomplete object file, waiting to be
    linked against something to resolve references.

    That option should not be the default if it disables using a
    register for STACK. I believe general performance here to be
    more important than seldom use.

    But who measured the current perf. impact of e.g.
    with-statistics etc.?

     
  • Sam Steingold

    Sam Steingold - 2003-05-05

    Logged In: YES
    user_id=5735

    1. please write the doc yourself - you use it and I don't.
    if you want, you can check it in yourself,
    but _please_ first make sure it validates.
    if you want, you can send the doc to clisp-list
    and I will put it in.

    2. performance: this register is disabled under gcc3 anyway.
    you can test, e.g., "time make check" and post the results.

    3. I doubt the usability of this feature,
    unless you make __all__ modules dynamically loaded
    by __default__, i.e., -K full would start a base image
    and load the other stuff.

    4. I think it would be _much_ more useful to be able to do
    > (dlopen "foo.so" '("fun_1" "fun_2"))
    > (def-call-out fun-1 (:name "fun_1") ...)

     
  • Sam Steingold

    Sam Steingold - 2003-05-12
    • status: open --> closed
     
  • Sam Steingold

    Sam Steingold - 2003-05-12
    • status: closed --> closed-invalid
     
  • Sam Steingold

    Sam Steingold - 2003-05-12

    Logged In: YES
    user_id=5735

    if you have any more doc issues, let us discuss them on
    clisp-list

     

Log in to post a comment.