Re: primitive documentation conventions

[Maciej Stachowiak <mstachow@mit.edu>]

I've just caught up on the whole documentation threads on the guile
and scwm-discuss lists. I am posting on both lists with my thoughts
because I think cooperation in this area would be extremely
beneficial.

I would like to suggest first off that we should design and implement
the scwm documentation extraction system with the intention of it
being eventually incorporated in Guile, perhaps with some changes.

Here are some things I think are important for this goal:

* Implementation language: the final version of the document extractor
should be written in Guile. Scwm could ship with a perl script without
_too_ much embarassment, but it would probably be a poor idea for
Guile :-)

* Output: We should, for now at least, output each of DocBook SGML,
TexInfo, and an on-disk documentation string database. When we can
generate TexInfo from DocBook, we can drop the second of these. I
think DocBook is clearly becoming the de facto free software standard,
and with good reason. TexInfo must be supported because it is still
the GNU standard. And it would be nice for users to still be able to
access documentation interactively from within an interpeter.

* How to get at docstrings for functions written in C: I suggest that
we try for a system where they are not kept in core straight off. We'll
have to make _some_ kind of changes anyway to support docstrings for
procedures written in C at all, anyway, so we may as well do it
right. It's necessary to be a bit careful here and add some special
flag to the procedure object to indicate wether it has an on-disk
docstring, and if so, in which file. If we just always look things up
by the symbol name, we will lose if the primitives get redefined, or
if something else gets defined as a primitive.

* Syntax in the source files: This is really two separate questions,
namely how to specify documentation in C files, and how to do it in
Scheme files. 

** For C files, there are two alternatives that are, IMO, more or less
equally acceptable. One is to use specially distinguished comments,
the other is to add an extra string parameter to SCM_PROC which
guile-snarf would ignore, but which the doc extractor would use for
it's own purposes. Jim Blandy seemed suspcious of the concept of
looking through the comments; however, I'm not sure it is that
bad. It's certainly more expandable to documenting concepts and
specially distinguished variables, and not just procedures.

** For Scheme files, we could use either the existing docstring
mechanism or use comments. Given Jim's comments, I'd suggest we just
go for regular docstrings, since that is the syntax we'll want to use
eventually. One possibility is to never worry about docstrings in
Scheme files, and just make sure that the compiler generates the right
thing for the doc extractor, when it is sufficiently mature to use
regularly on all installed Scheme files.

* Markup: We may want extra markup in the docs in addition to the
presumably automatically generated function signature. If this is ever
supported, I suggest we use DocBook tags, as opposed to TexInfo or
worse yet, something ad-hoc. It seems to me that DocBook->TexInfo is
likely to be the easier translation, and if there's ever a DocBook
system tht generates texi automatically, we won't have to worry about
it ourselves at all.


Comments, anyone?

 - Maciej