Re: Doc Tasks (was RE: docstrings in Guile!)

[Greg Harvey <Greg dot Harvey at thezone dot net>]

"Greg J. Badros" <gjb@cs.washington.edu> writes:

> Greg Harvey <Greg.Harvey@thezone.net> writes:
> 
> > "Greg J. Badros" <gjb@cs.washington.edu> writes:
> > 
> > > 
> > > Tables.  Figures.  
> > 
> > Both would be for the full manual. How are we going to show these
> > docstrings with tables in them by doing (procedure-documentation foo)?
> 
> |----------------------------|
> | Format       | Goodness    |
> |----------------------------|
> | SGML DocBook | *****       |
> | TeXInfo      | **          |
> |-----------------------------
>
> 
> :-)

I don't necessarily disagree with that (yeah, texinfo sure is ugly and
limited, but it does provide that one really useful thing; I'd slap
latex in somewhere over docbook, though >;'). Docbook may be all
things to all people, but I have never actually wanted to do anything
that latex couldn't.

> Tables are possible in ASCII, for sure.  Figures less so, but it'd be
> nice to stick with one format. 

Possible, yeah. Good idea, though... I dunno, I really don't want to
have to wade through a ton of ambitious attempts to present the guile
core through heiroglyphics to fix a bug.

> > Are we going to have to run guile in xwindows, with output to xdvi or
> > gv in order to get docstrings? Obviously not. Like I said, this isn't
> > the manual, this is the base documentation for procedures and
> > variables. The manual can be built around these; you don't want to get
> > a rendition of a cons cell if you do (procedure-documentation cons);
> > you want to know that cons takes two arguments and returns a cell
> > containing them.
> 
> But it sure would be great if for Scwm I could have a graphical browser
> that had the figures, too.

Yeah, but outside the coolness factor (guile, the only scheme that
requires a 3d accelerator to view documentation ;), we can really get
across all the information we need in this section of the
documentation with an extremely limited amount of markup
information. This also has the benefit of being uniform, so that
people who dislike marking up text in general (uhm... :) and the
ambitious, last great guile novel types don't end up producing two
wholly different styles of docstrings.

-- 
Greg