felix winkelmann <[email protected]> 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 testiment 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 crumudgeon mode apparently _______________________________________________ Chicken-users mailing list [email protected] http://lists.nongnu.org/mailman/listinfo/chicken-users
