Re: docstring work

[Neil Jerram]

>>>>> "Martin" == Martin Grabmueller <address@hidden> writes:

    Martin> If you read bug-guile, you have seen the bunch of
    Martin> docstrings I have already send in; if not you could have a
    Martin> look at the archives.  It would be nice if someone could
    Martin> review them, especially if he/she is a native speaker.
    Martin> Technically I got the docstrings correct (I hope), but
    Martin> grammatically...

Right, I will do this review.  According to the libguile ChangeLog in
CVS, there is an entry for a docstring patch from you on 2001-01-29,
for docstrings in struct.c.  Are there other patches that are pending
in bug-guile?
 
    >> I also have ideas on extending the docstring mechanism to cover
    >> more stuff, and to support i18n.  If you're interested, let me
    >> know and I'll pull together a description.

    Martin> That would be very nice.

Here goes.  This is all IMO, of course.

1. It would be nice to extend the C snarfing macros to cover things
other than primitive procedures, e.g. macros, symbols, hooks and
concepts.

Imagine...

guile> (help 'threads)
Threads are a concept provided by the (guile) module.

 - concept: Threads
     Threads enable an application to run multiple lines of execution
     apparently in parallel. ...

     Guile presents a consistent interface to threads that is
     independent of the underlying implementation.

     For further details, see `begin-thread'.

Libguile already contains a lot of conceptual documentation, in the
form of extended comments, that could be used for such docstrings.

I believe that SCWM already has something like this, so we check out
how SCWM does it.


2. Currently the only snarfed docstrings come from the C code for
libguile.  Documentation for Scheme-defined procedures is extracted
from the lambda body, where the first expression of the lambda body is
a string.

I think we should also support snarfing docstrings from Scheme module
files.  Instead of:

(define (purify-module! module)
  "Removes bindings in MODULE which are inherited from the (guile) module."
  ...)

we would use a format like:

;;; Removes bindings in @var{module} which are inherited from the
;;; (guile) module.
(define (purify-module! module)
  ...)

Advantages are:
- reducing the occupancy of loaded Scheme code
- collecting the snarfed docstrings together in a form amenable for
  translation.

Docstrings snarfed in this way would be stored in per-module doc
files, which brings me on to ...


3. Currently there is only one doc file -- guile-procedures.txt --
which is the result of snarfing C docstrings from libguile.  Once we
have snarfed docstrings coming from Scheme files as well, I think that
docstrings should be organised by module and per-module doc files
located in the same filesystem hierarchy as the module files
themselves.  Doc files would be named according to module name.  So
guile-procedures.txt, which contains docstrings for the (guile)
module, would become guile.doc and be installed at
<prefix>/share/guile/<version>/guile.doc.

This fits well with the way that name lookup works in (ice-9 session):
the procedures here know the module that a name belongs to.


4. Doc files can be translated into other languages.  We should
support translated doc files by

- defining where they should installed:
  e.g. <prefix>/share/guile/<version>/<locale>/guile.doc

- modifying the look up code to try a path with the current locale in
  before the path without locale.


5. Performance improvements.  Currently, to look up 10 docstrings in
guile-procedures.txt, we open and read through guile-procedures.txt 10
times.  Some caching work here may be worthwhile.


Best regards,
        Neil