This is the mail archive of the guile@cygnus.com mailing list for the guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Guile documentation



IMHO, one of the larger problems with the project so far is the lack
of and/or quality of documentation (here meaning the reference
material) on guile. This is almost inevitable in volunteer projects, I
know, but I think one important step could be to reorganize the way
documentation is handled. This mail contains some modest suggestions
to get the discussion started.

I think that the route to world peace, happiness and better
documentation lies in moving the documentation into the (C) source
files, and the create the reference manual from a skeleton (also
containing overviews and larger-scale documentation) by extracting the
documentation from the source and converting it in some appropriate
way.

While this obviously will put the documentation in risk of appearing
fragmented, there are some real benefits:

- having documentation next to the code it documents makes it a *lot*
  easier to maintain in the longer run, especially when a potentially
  larger body of loosely coupled developers are working on the
  sources.

- makes sure that all functions appears in the manual. Having an empty
  entry is better than no entry at all.

- could work as a platform for also providing the bulk of the
  documentation on-line (ie. in the interpreter).

The idea is to extend on the `(define (foo x) "This functions takes X" x)' 
type of documenting functions to also work from the C level, and then
to have some tool/script to extract the documentation strings and
merge them with the manual skeleton to produce the actual manual.

Step one is to provide the necessary source code infrastructure, step
two to do the tool to extract documentation and convert it to texinfo
and step three to reorganize the manual to both extract the skeleton
and move existing back into the C files.

Wrt. to infrastructure, I think we need the following:

- A new C macro SCM_XPROC that takes an extra documentation string
  (unless one could rewrite SCM_PROC to take an optional argument) and
  stores this as a property of the symbol.

- Another new C macro SCM_PACKAGE, more on this below.

- Extending variable definitions `(define foo 123)' to allow an extra
  documentation string ala emacs' defvar. This could be done either by
  extending `define' or by making a new macro `define-variable' (which
  could then work like defvar, ie. not overwriting an existing value).

- Perhaps doing the above for records as well, by making wrapper
  macros in the style of CL's defstruct.

As hinted above, I propose a new concept called a `package'. A package
would be something in between a real module and a compilation unit (C
file). Most packages would be defined by just a single C file.

The idea behind packages is to provide a hook that allow a larger
scale facility to be introduced. One example could be found in
`async.c'. There would then be an `async-package' (or some such) which
would hold a documentation string given a higher level introduction to
the concept of asyncs. This would be accessible both to the
texinfo-manual generation process and online in the interpreter.

(Packages could also later be used to structure a demand-loading
process where most of the guile core would loaded only as necessary.)

In my vision, packages would be defined through the SCM_PACKAGE macro
mentioned above. This would take a name (and perhaps a symbol for
exporting it to the scheme level) and a documentation string. It would
work like `define-module' in that it would sit at the top of each C
file, and several files could be collected into the same package by
each using the same name.


Another thing to consider is to allow, at least somewhere down the
road, documentation to contain SGML/TeXinfo formatting.


None of all this is rocket-science, but if we can agree on some sort
of conventions, I think it can help us improving the overall quality
of the documentation in the long run.



---------------------------+--------------------------------------------------
Christian Lynbech          | Telebit Communications A/S                       
Fax:   +45 8628 8186       | Fabrik 11, DK-8260 Viby J
Phone: +45 8628 8177 + 28  | email: chl@tbit.dk --- URL: http://www.telebit.dk
---------------------------+--------------------------------------------------
Hit the philistines three times over the head with the Elisp reference manual.
                                        - petonic@hal.com (Michael A. Petonic)