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] |
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)