Re: Doc Tasks

["Greg J. Badros" <gjb at cs dot washington dot edu>]

Gregg Reynolds <greynolds@greynolds.com> writes:

> 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.

All sounds good... these would be great contributions!

> 	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

Makefile.am has a rule for guile-procedures.txt to do just that.

> 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.

Righto;  the web page you've since found is a step in that direction
(though it is not based on the actual source, just on how people edit it.

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

Great!  I see you've updated the page at:

http://upintheair.cs.washington.edu/guile-doc-status/guile-doc-status.pl

so we'll be looking forward to the patch when you can get it to us.
Thanks!

> 	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.

Let us know what we can do to help you win that argument.  These are
battles that we need to win for Guile to advance.

>  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.

This might go a long way towards making Guile useful for the
text-processing tasks that I still use Perl for...  I'm all for seeing
where this goes (but your other suggestions seem more immediately
beneficial).

> Sound reasonable?  

Definitely!

Greg