chicken-users
[Top][All Lists]
Advanced

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

Re: [Chicken-users] Re: new egg documentation bootstrap


From: Peter Bex
Subject: Re: [Chicken-users] Re: new egg documentation bootstrap
Date: Fri, 18 Dec 2009 10:26:00 +0100
User-agent: Mutt/1.4.2.3i

On Thu, Dec 17, 2009 at 06:12:52PM -0500, Derrell Piper wrote:
> 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. 

That's assuming a whole lot of people edit a whole lot of text.
In practice, most updates are of a "typo and other kinds of mistakes"
fixing nature.  In case of really big edits, it's best to check with
the author first, if it were only to verify you're not making any
mistakes yourself.

> There's still something to be said for proper review by subject-matter
> experts, which in this context means the egg author(s).

I've written huge slabs of text to document big pieces of previously
undocumented code not written by me (sxml-transforms and ssax, notably).
Who says users can't become subject matter experts on the subject of
their favorite eggs?

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

Indeed.

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

The fact that that doesn't work is a failure of the installation tools.
This (doc-from-wiki and fetching the HTML from the wiki) worked
perfectly with Chicken 3.

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

Yes, the svnwiki software is extremely slow and has caused lots of
headaches in the past.  Ivan and I are working on a replacement wiki
software which is going to completely replace svnwiki.  We decided to
do this because svnwiki is not only inherently slow (it uses a
stream-based parser which we believe cannot be made to go fast) in
parsing but is also very hard to maintain.  I think only its author
fully groks the code, and he has more or less decided to leave the
Chicken community.  So, while svnwiki has served us well, it is now
time to move on.

We haven't announced this yet because we're still working on some
details, but I think this is the time to announce it more publicly.
The software I'm referring to is named "qwiki", documented here:
http://chicken.wiki.br/eggref/4/qwiki

> Besides, I live in emacs.  Why do I have to edit in this little weird
> box with almost none of my normal keymap?

You don't.  One of the things about svnwiki which I always loved is
that you can just make a checkout of its files, edit them locally and
commit, all without ever opening your browser!

> 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 don't really understand that graphic either.  I'm not even sure it
conveys any information.  I guess it's just svnwiki's version of a
"spinner" or "throbber" graphic.

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

Unfortunately, that's the case.  Qwiki is already fast enough to click
save and update the page in more-or-less realtime.

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

Again, you *can* just use 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.

One of the goals of qwiki is to be backend-independent, so you can write
your wiki code once and have it output HTML, TeX, roff, whatever other
format you can think of.  svnwiki can also do this, but nobody
understands the code enough and there's no documentation on how to write
a backend :)

Cheers,
Peter
-- 
http://sjamaan.ath.cx
--
"The process of preparing programs for a digital computer
 is especially attractive, not only because it can be economically
 and scientifically rewarding, but also because it can be an aesthetic
 experience much like composing poetry or music."
                                                        -- Donald Knuth




reply via email to

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