chicken-users
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Chicken-users] Re: new egg documentation bootstrap


From: Derrell Piper
Subject: [Chicken-users] Re: new egg documentation bootstrap
Date: Thu, 17 Dec 2009 18:12:52 -0500
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/23.1 (darwin)

felix winkelmann <address@hidden> writes:

> A somewhat more constructive response: there should be a single documentation
> format. I personally would prefer wiki pages, but eggdoc is prefered by some
> extension-authors. One approach would be to include the .html in the egg,
> but that needs to be generated from the wiki page (in case the egg is
> documented in wiki-format), and there is no official tool for doing that
> (there is a hack in the chicken git repo, called "wiki2html", which does
> a not particularly nice but usable job for that).

Obviously there should be a single documentation format.  I don't think
it should be the wiki, or maybe I mean, this wiki.  Here's why...

I'm working on documentation for my first egg.  As background, I've been
a LaTex user since 1980 or so and like it.  I have no problem with
markup languages.  I also think markdown is a thing of beauty.  I hate
XML, HTML, and SGML with a passion.  Well that's not really true, I
don't *hate* them, I just think that they were never designed for humans
to manipulate directly.  I curse every time I have to type </anything>.

As a user, I really liked Chicken 3's approach to documentation.  I
loved having nicely formatted (eggdoc) documentation locally cached via
chicken-setup, always there, ready for me.  Not having this now sucks,

At some level I understand the promise of the wiki but I also think they
all mostly suck.  I don't think the seductive allure of 1,000,000
monkeys compensates for prose that becomes a testament to multiple
personality disorder with each subsequent revision.  There's still
something to be said for proper review by subject-matter experts, which
in this context means the egg author(s).  That said, it's cool that the
Chicken manual is editable in the wiki and sync'd to svn.  Given that
felix wanted help and prefers the wiki, that's the right place for it.

So looking at 4, it seemed like the Chicken community was wanting to go
wiki, so I decided I would stuff a '(doc-from-wiki) ' in my .meta and
try it out.  Change is good.  Well I'm just about done with that page
and I have enough of an opinion now to seriously regret that choice.

For one thing, the svnwiki lag sucks.  You make an edit and then you
have to wait an indeterminate amount of time before you can see the
change.  This is complete anathema to the way I write documentation.
We're all one with the REPL here, so the 'why' should be obvious.
Besides, I live in emacs.  Why do I have to edit in this little weird
box with almost none of my normal keymap?

As an aside, I'm using Safari on OS X.  After I click, "Save", there's
something that says, "Checking status..." next to some graphic of blocks
that never does anything more.  Perhaps that's supposed to be giving me
more feedback, but if it is, it's not working.  I have no way to tell
when the wiki actually gets updated.  So I'm constantly having to
refresh the page to see if the change is there or not.  I'm also sick of
having to answer stupid math questions to click "save".  Can't you cache
a "there's a real human on the other end" cookie?  This would have taken
me no time whatsoever in emacs.

I'm going to finish the wiki page but then covert my doc to eggdoc and
be done with it.

AFAIC, TeX solved these problems with DVI years ago and looks gorgeous
too, which sadly used to be a relevant attribute of documentation.

Derrell, in curmudgeon mode apparently





reply via email to

[Prev in Thread] Current Thread [Next in Thread]