Doc Tasks

[Gregg Reynolds <greynolds at greynolds dot com>]

Good Morning Guile-ites,

Here's what I'll be working on in the near future:

	I18n stuff, since my personal interest in this area is strong.  I'm
going over the "mltext" and "mbapi" stuff from the docs directory, but
haven't looked at the code itself yet.  Planning to docstringify the
source if necessary, and if I find the time, to add some exposition on
"characters", the various jargons (ab)used to wrestle with them, and how
to keep it all straight.  I've also got some text api ideas in this area
that I may at least document if not implement - depends on what the code
looks like.  I know somebody out there has been doing stuff on text
buffers; is there a URL?  I'm very gung-ho for language-neutral and
fully-localizable texttechnology, so anybody else out there with similar
interests should email me.

	Printability.  I was able to print out a few of the texi files in /doc,
but a bunch of them don't build.  I'll take a look and see about either
fixing them qua texi files or (morelikely) slapping them into a Docbook
file.  I need print in order to edit, so this is a relatively high
priority for me.  I'd like be able to say "make pdf" and have *all* the
doco magically appear in pdf files in doc/pdf, or something like that.

	Overall doc design.  It's kind of messy at the moment;  I need to read
it all carefully in order to get a big-picture view of exactly where the
project is w/r/t docs.  Then I'll probably have some suggestions for
divide-and-conquer modularization.  I imagine using Docbook will be
helpful in this respect, since (I believe) it makes it relatively easy
to distribute editorial work (using external entities) but still
maintain an overall structure.

	Docstringification Status.  Somewhere in the texi files I saw a list of
undocumented primitives, and Greg Harvey's qdocs has a bunch of doco,
and guile-procedures.txt looks like the catenation of the *.doc files,
though I don't see where this happens.  All this should be cleaned up so
there is one place to look to find current status.  With docbook, it
should be possible to treat guile-procedures.txt as an external entity
within some kind of "docstatus.sgml" file, so make can generate an
up-to-date status doc in e.g. html automatically.

	Finally, actual docstringification.  I'll start at the end
(alphabetically) and work backwards.  That means I'll start at
"weaks.c".

	Last but not least, I found a copy of "The Art of MOP" at the local
bookstore, so when I get to goops I might be able to contribute some
doco on MOP.

Also, this will be nights/weekends work for me; but there is a non-zero
likelihood that I'll be able to convince my superiors at word to use
guile as the extension language in an upcoming project.  Last time I
lost out to the Python advocate.

 Just remembered another area I'll probably work on eventually: 
different string-handling "personalities".  In particular Rexx and
Icon.  It would be a Good Thing, IMO, if people who already know these
other string-oriented language were able to transfer their skills
more-or-less directly to a Guile environment.  Scheme equivalents of the
constructs in those languages would be a good start, but it might be
Nice to Have the ability to use the syntax of the original languages, at
least for stringy stuff.  In other words, it may not be necessary to
support an entire language personality in order to win over users.

Sound reasonable?  

-gregg