[Openmcl-devel] Ways around the with-simple-restart bug?

[Dan Knapp]

> I can offer some help as well - i'm just not shure what sort of help 
> :-)
> I've OpenMCL (CVS) running on my Debian/GNU/Linux system for quite some
> time now (just modified Kevin Rosenberg's build setup for the Debian
> package). So i can offer testing on both Debian and MOSX-10.2 (never
> could justify to spend money on the OSX upgrade again ...).
> Any place i could contribute? (I'v quite some experience with XML 
> et.al.
> so i might have a closer look at the docs. Righ now i try to get manual
> into a recent printed version).

   What is it you're trying to do, exactly?  Frustration with the build 
process
of the docs?  Yeah, I never wrote up any step-by-step on that because so
far, only me and Gary have had to do it...  It's as simple as running 
make
in the top level of the docs tree, except that you have to have the 
right
tools installed.  They are listed in the makefile, so read it and see 
if that
helps.

   I haven't tested the docs with any target except html.  The stuff in 
the
xsl/ directory makes some customizations which are html-specific; 
probably
some of them are appropriate for a printed-book target and some are not.
If that's what you're trying to do, I can take a look at it and see 
what might
be required.


   If you're interested in helping with the docs, well, most of what I 
do is
editing for content and clarity, and only a small part is messing with 
xml.  I
would urge you to give your time first to getting a new distribution 
out the door,
since that's more important than the things I haven't gotten around to 
on
my to-do list...

   The offer of testing is also a good one, and will probably be useful.

   All that said, though, if you have experience with docbook or are 
willing to
learn, I definitely need to improve the speed of the build process.  
This
mostly consists of turning on profiling in the (documentation) makefile 
and
figuring out which standard stylesheets and DTDs it's pulling from the
network because it doesn't have them locally, and how I can make it find
the local copies.  Of course, it's not quite as simple as that because 
the files
which are installed on your local machine are not the same as the ones 
on
the server...  Perhaps modify the profiling to save its output to a file
somewhere that can be viewed on the live page...

   Once that's done - and only then, because doing it in the obvious way 
will
approximately double the time the docs take to build - there needs to be
a mechanism for persistently linking to a specific chapter from 
off-site, and
from on-site pages which aren't part of the Doc/ subdirectory.  The 
.html
filenames all change (well, except for the dictionary entries) when 
chapters
are added or moved, is the problem.

   Be sure you're using the same versions of docbook and the stylesheets 
as
are listed on the bottom of every page on the site.

   I also do have a list of things that need to be written.  I've 
appended it.
And then, I need to make editing passes through the whole thing to clean
up things like making sure symbols are listed as ccl: or ccl:: when 
they're
in the ccl package, ...

   And there was a request at one point for an OpenGL section (but I 
don't
have any information to base it on...), and I've been wanting to take 
the
stuff from the ccl/examples/ directory and integrate it with the docs 
and
write real tutorials about it, and there's a bunch of private 
parameters and
variables that are used to configure OpenMCL, which all ought to be
listed in some central place, ...

-- Dan Knapp


Useful information:
===================

The definitive list of symbols exported from CCL is in
ccl/lib/ccl-export-syms.lisp

Functions which should be documented:
=====================================

self
send
send/stret
(ccl::send-super)
(ccl::send-super/stret)
%send
%send/stret
%send-super
%send-super/stret
(ccl::make-objc-instance "WiErDclass")
(ccl::objc-to-lisp-classname string)
(ccl::lisp-to-objc-classname symbol)
(ccl::objc-to-lisp-message string)
(ccl::lisp-to-objc-message string)
(ccl::objc-to-lisp-init string)
(ccl::lisp-to-objc-init keyword-list)
(ccl::define-classname-translation ...)
(ccl::define-message-translation ...)
(ccl::define-init-translation ...)
(ccl::define-special-objc-word string)
(ccl::DEFINE-RETURNS-BOOLEAN-EXCEPTION "charValue")
(ccl::lisp-string-from-nsstring ...)
(ccl::lisp-string-from-nsstring-substring ...)
(CCL::DEFINE-VARIABLE-ARITY-MESSAGE)
slet
slet*
update-type-signatures
with-autorelease-pool and related

process-name (function, setf-able)
process-initial-form (function, read-only)
process-priority (function, setf-able)
process-total-run-time (function, read-only)
process-creation-time (function, read-only)
process-reset-and-enable (function, identical to reset then enable)
let-globally (macro, complicated...)
symbol-value-in-process (setf-able)

Write <refpurpose>s for:
========================

f_signal-external-process
[and lots and lots of other dictionary entries, too]

Do content edits on:
====================

 From the Sockets Dictionary:
f_make-socket
f_accept-connection
f_dotted-to-ipaddr
f_ipaddr-to-dotted
f_ipaddr-to-hostname
f_lookup-hostname
f_lookup-port
f_receive-from
f_send-to
f_shutdown
f_socket-os-fd
f_remote-host
f_remote-port
f_local-host
f_local-port
f_socket-address-family
f_socket-connect
f_socket-format
f_socket-type
c_socket-error
f_socket-error-code
f_socket-error-identifier
f_socket-error-situation
o_close
m_with-open-socket

 From the External-Program Dictionary:
f_run-program
f_signal-external-process
f_external-process-id
f_external-process-input-stream
f_external-process-output-stream
f_external-process-error-stream
f_external-process-status

Wishlist:
=========

Reformat the dictionary chapters of AMOP and include them in the docs
(this is explicitly permitted by their license).

Cleanup which somebody else should do:
======================================

The following symbols are exported from CCL but not defined anywhere:

clear-process-run-time
lock-not-owner

(end)