Re: [Chicken-users] documentation issues...
On Feb 17, 2008 12:52 PM, Alejandro Forero Cuervo <[EMAIL PROTECTED]> wrote: > > > what remains relevant is that its bloody hard to document anything > > even slightly nontrivial in it. > > While this is not my perception, I've heard this claim in the past. I > would like to see if Svnwiki can be improved in this area to make it > easier for you and others like you to use it. Care to give me a few > examples of concrete syntax forms that you think we should support and > what they should parse to? > > Thanks and happy editing! :-) > I'd like to add here that I think svnwiki does a pretty good job and has served us well. Thanks for making it available, Alejandro. And thanks for being there to fix and extend things when we need them (this and the fact that it is writen with chicken is reason enough to keep it). cheers, felix ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
> All the above is related to using a browser which is not suited to > the task. Use a light-weight browser that embeds a real editor like > vim or emacs or use firefox with the right plugin like > ViewWithSource. I hated Wikis before I found these two solutions. I don't think this addresses all the problems that most wikis have for strong-editing: the fact that you can't edit your documents offline (ie. you have to get online to load the edit page or preview your changes) and the fact that browsers are prone to crash and make you lose hours of work. I prefer using a real editor outside of Firefox or other browsers. Which, as I said in the other message I sent to the list, is what lead me to create Svnwiki in first place. Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
> id like to entitle this next rant 'why wikis are highly suboptimal > for documentation', if i may. Well, I mostly agree with the points you are raising, which I would summarize as 'having to edit text for hours using a web interface sucks' (even if you use plugins or special browsers so that you are actually using a real editor for textareas). On the other hand, I think wikis have the draw of lowering the barrier to making changes to the point where people reading documents begin contributing. The extent to which this happens varies greatly from one website to the next (and even for specific pages in a website), but there are several examples of why this can work greatly. I started Svnwiki back in 2004 because I wanted a wiki system but I was not willing to go through what you just did: editing something for hours on an extremely limited text-editor risking just losing everything because the connection went away. On the other hand, I wanted to lower the barrier to collaboration. I've been using Svnwiki for lots of websites since then and I'm mostly happy with the overall experience. I migrated my weblog http://azul.freaks-unidos.net/ to it so I can write my posts through Vim (my favorite editor), commit and call it a day. I even support weblogs of other people (http://wiki.freaks-unidos.net/weblogs) and installations such as http://fsfla.org/svnwiki or, obviously, Chicken's. Of course, there have been some problems in the past when I have added lots of features in small intervals of time and I have introduced some unstability. Furthermore, installing Svnwiki has a reputation of being hard, as you have to (1) set up an Svn repository and (2) set lots of properties on it. Thirdly, getting all the dependencies installed, while not rocket science, had some complexity that should be eliminated (some day I'll get of my lazy butt and turn the Svnwiki extensions into eggs of their own so that they can be installed with chicken-setup, finally solving this problem). Fourthly, there seem to be some infrequent errors with the use of sqlite involving concurrent accesses to the database, which I haven't really got to debug or try to solve. With all that said, 4 years later I'm mostly happy with the results. :-) That said, you seem to also mention another point which is that, to you, the wiki syntax we use seems to be limiting: > what remains relevant is that its bloody hard to document anything > even slightly nontrivial in it. While this is not my perception, I've heard this claim in the past. I would like to see if Svnwiki can be improved in this area to make it easier for you and others like you to use it. Care to give me a few examples of concrete syntax forms that you think we should support and what they should parse to? Thanks and happy editing! :-) Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
This is correct. In fact, I edit wiki pages almost exclusively in Emacs, commit them to SVN, and wait 30 seconds for the post-commit script to update the web page. I find that extremely convenient, particularly with my local installation of svnwiki. -Ivan Daishi Kato <[EMAIL PROTECTED]> writes: > Hi, > > Is it true that if you have svn write access, > you can just edit the wiki/* files and commit them, > which reflects to the web pages? > My understanding is that this is a nice feature of svnwiki. > > Well, my assumption is that developers use Emacs or Vim, > non-developers don't and developers could get the write access. > > Correct me if it's wrong. > > Daishi > ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
On Thu, Feb 14, 2008 at 6:07 PM, Daishi Kato <[EMAIL PROTECTED]> wrote: > Is it true that if you have svn write access, > you can just edit the wiki/* files and commit them, > which reflects to the web pages? > My understanding is that this is a nice feature of svnwiki. Yes, you're correct on this. And yes, it is a great feature. Graham ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
On Thu, 14 Feb 2008, a r wrote: BTW, I agree with elf that extracted function signatures (+ one line descriptions) could be useful for certain applications (editor/IDE support, interactive mode help etc.). This however has nothing to do with an end-user documentation. erm, thats not actually what i was saying. i would be generating the interpreter docs, ide/editor docs, pdf, html, texi, whatever docs all from the same single source file. a) its the least amount of work for the devel to keep track of. b) its easier (and more likely) to keep one thing up to date than to keep six things up to date. c) it ensures consistency in content (and some in format) between docs , and d) its easiest in terms of batch generation, methinks. the calling convention plus one line desc is commenting before every proc, macro, and var (although for vars ill sometimes just do it at the end of the line as a single line) in the source. its not enough to know everything thats going on, nor is it enough to get in the way of the code. the point of doing so is a) to remind myself whats going on if i have to go back to it and b) to make it easier for others who might read it to trace it without knowing anything about it beforehand. -elf ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
Hi, Is it true that if you have svn write access, you can just edit the wiki/* files and commit them, which reflects to the web pages? My understanding is that this is a nice feature of svnwiki. Well, my assumption is that developers use Emacs or Vim, non-developers don't and developers could get the write access. Correct me if it's wrong. Daishi At Thu, 14 Feb 2008 14:19:46 -0600, Jim Ursetto wrote: > > Select all in the preview window, cut and paste to Emacs or Vim, edit, and > paste the text back to the wiki. I do it all the time, and it solves every one > of these issues. (Modern browsers handle most of them, too.) You can also use > `svn up` for the import step, but the preview window is still preferable to > `svn ci` as you can see the result, unless you're making a small change or > like > to live dangerously. > > On 2/14/08, Elf <[EMAIL PROTECTED]> wrote: > > a) im stuck in a tiny window in a tiny screen with no real text manipulation > > abilities. > > b) theres no search and replace. theres no way of even killing lines off. > > c) cut and paste is fickle about where the mosue is, not where the cursor > > is. > > d) theres no undo. theres no redo. theres no means of even taking it > > offline > > effectively. > > e) and the real dealbreaker once i was 99.99% done and loading the > > preview... it froze in the middle of displaying. claimed it was done > > (ie, > > not a network error or something.) theres no buttons at the top to > > force > > a save or anything. meaning at 8.5 hours in, i had to start over almost > > from the beginning. > > > ___ > Chicken-users mailing list > Chicken-users@nongnu.org > http://lists.nongnu.org/mailman/listinfo/chicken-users > > ** > XREA.COM -Free Web Hosting- > http://www.xrea.com/ > ** ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
On Thu, Feb 14, 2008 at 9:28 PM, Stephen Eilert <[EMAIL PROTECTED]> wrote: > a r wrote: > > > > I don't want any API docs automatically generated from source code > > comments - when separated from the code these comments are just a pile > > of useless random notes. Documentation _must_ be written in separation > > from the code. Yes, it is an additional effort, bu if you can't afford > > it simply don't bother writing any documentation. > > > I think what is meant by "source code comments" is parseable comments in > the source code, intended for tools to generate and update documentation > automatically, possibly with their own tags to add semantics. Look up > Doxygen (http://en.wikipedia.org/wiki/Doxygen) and check out the example > source code and generated docs. Granted, that's not Scheme, but > hopefully that's enough to understand the idea. ** Yes, I meant Doxygen and similar tools. They inherently encourage a programmer to write a bad documentation. And there are several reasons for this: 1. limited space, 2. limited document editing resources (no tables, diagrams etc) 3. people generally write better documentation when they are not looking at the source code (it is simply easier to imagine what a user needs if you stop staring at your "cheat sheet"), 4. programmers who write Doxygen documentation feel relieved from writing good documentation (they have filled in all required forms after all). > It not as if such a tool is going to detect each and every comment > everywhere and create a useless pile of random comments. That would, > indeed, be useless. Usually, this type of documentation is brief, just > giving a general idea of what the function does, which arguments are > required (and what they mean) and the expected output. How's that > different from what's being done, for instance, in the sqlite3 egg? > (http://www.call-with-current-continuation.org/eggs/sqlite3.html) > > If you need more than that, then a "manual" is called for. Or even a > "tutorial". And that can and should be kept in some other location, > provided it is easily accessible. The problem is, that before plunging into API you should be able to find a description of the module itself. I have yet to see Doxygen generated docs that contain a "big picture", description of data structures, protocols, examples and an API summary (not just a plain list of functions). I really much more prefer reading a few paragraphs describing what the module is for rather than wading through the API reference. Look at SRFI documents - most of them are pretty good examples of how the documentation should look like. > If you keep them apart, you cannot see at a glance (let's say, while > adding features or fixing bugs) if the docs are out-of-date or if > someone forgot to comment something. Furthermore, the authors have no > need to look up documentation at all, so the documentation *will* become > outdated. It's the users that need it, and those aren't always familiar > with the code to spot the inconsistencies. I agree it is a tedious work. But don't cheat yourself you can skip this task by using some "magic". > Of course, you can keep the docs wherever you want, provided you have > enough minions you can slap to bring all of them up-to-date :) This is a common problem with the documentation, which it's not caused by tools but by people and policies, though. If you hate writing documentation you can always upload the commented source code to the web. IMHO (especially for scheme code) it is a better solution than using Doxygen or similar tools. BTW, I agree with elf that extracted function signatures (+ one line descriptions) could be useful for certain applications (editor/IDE support, interactive mode help etc.). This however has nothing to do with an end-user documentation. -r. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
a r wrote: I don't want any API docs automatically generated from source code comments - when separated from the code these comments are just a pile of useless random notes. Documentation _must_ be written in separation from the code. Yes, it is an additional effort, bu if you can't afford it simply don't bother writing any documentation. I think what is meant by "source code comments" is parseable comments in the source code, intended for tools to generate and update documentation automatically, possibly with their own tags to add semantics. Look up Doxygen (http://en.wikipedia.org/wiki/Doxygen) and check out the example source code and generated docs. Granted, that's not Scheme, but hopefully that's enough to understand the idea. ** It not as if such a tool is going to detect each and every comment everywhere and create a useless pile of random comments. That would, indeed, be useless. Usually, this type of documentation is brief, just giving a general idea of what the function does, which arguments are required (and what they mean) and the expected output. How's that different from what's being done, for instance, in the sqlite3 egg? (http://www.call-with-current-continuation.org/eggs/sqlite3.html) If you need more than that, then a "manual" is called for. Or even a "tutorial". And that can and should be kept in some other location, provided it is easily accessible. If you keep them apart, you cannot see at a glance (let's say, while adding features or fixing bugs) if the docs are out-of-date or if someone forgot to comment something. Furthermore, the authors have no need to look up documentation at all, so the documentation *will* become outdated. It's the users that need it, and those aren't always familiar with the code to spot the inconsistencies. Of course, you can keep the docs wherever you want, provided you have enough minions you can slap to bring all of them up-to-date :) Stephen "Statistics are like humans. Torture them enough and you can make them admit anything you want" ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
On Thu, 14 Feb 2008, a r wrote: Hi, Just a few comments from a Chicken user. I really like searchable, accessible and editable documents on the web. On the other hand, I have never used any docs shipped with eggs - it's simply to much hassle to browse the directories if I can type two words in Google. Wiki docs (and eggs concept) were the two main features that attracted me to Chicken, BTW. i like searchable webdocs for browsing. i also like searchable docs in the interpreter. and i like the ability to generate arbitrary formats (say, pdf of the whole manual). if (use/require/require-extension/load/etc) loaded documentation into the interpreter automatically (or there was some flag to determine if it should do it, or something along these lines), this would be more useful imho in the general sense even than webdocs, provided it was generically searchable and well indexed. (the previous statement should in no way be taken to mean that i think webdocs should be removed or obsoleted, cause theyre obviously both popular and highly used. i know im on the site a dozen times a day most days.) the problem with web-only docs is that retranslation generally is unpleasant, and primitives to make documenting this sort of project easy are sorely lacking. I don't want any API docs automatically generated from source code comments - when separated from the code these comments are just a pile of useless random notes. Documentation _must_ be written in separation from the code. Yes, it is an additional effort, bu if you can't afford it simply don't bother writing any documentation. im in total agreement with you on this one :) -elf ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
Hi, Just a few comments from a Chicken user. I really like searchable, accessible and editable documents on the web. On the other hand, I have never used any docs shipped with eggs - it's simply to much hassle to browse the directories if I can type two words in Google. Wiki docs (and eggs concept) were the two main features that attracted me to Chicken, BTW. I don't want any API docs automatically generated from source code comments - when separated from the code these comments are just a pile of useless random notes. Documentation _must_ be written in separation from the code. Yes, it is an additional effort, bu if you can't afford it simply don't bother writing any documentation. -r. On Thu, Feb 14, 2008 at 7:54 PM, Elf <[EMAIL PROTECTED]> wrote: > > id like to entitle this next rant 'why wikis are highly suboptimal for > documentation', if i may. > > approximately 9 hours ago, i noticed that the documentation that i had > changed in the http wikidoc wasnt generating correctly. (for those > wondering for future endeavours, its not possible at the moment to > do nested tables directly. or tables with any wiki-markup at all. or > any other markup. or ... you get the idea.) > > running through all those hoops only took about 2 hours before i realised > that no markup would work inside existing markup. luckily, theres the > scheme tag, to allow embedded evaluation of expressions. (and again, for > those wondering, yes, the entire thing is generated via about 90 calls > to (display) with static strings.) > > so we're about 4 hours in now, and things work about 95% of the way. its not > handling margins properly and its not aligning text as specified. no biggie, > right? > > this took the following 5 hours. and theres absolutely no reason why it > should have taken more than 30 mins from the beginning, but im more than > willing to allow for strange edge cases taking a bit longer. > > so why did it take so long? > a) im stuck in a tiny window in a tiny screen with no real text manipulation > abilities. > b) theres no search and replace. theres no way of even killing lines off. > c) cut and paste is fickle about where the mosue is, not where the cursor > is. > d) theres no undo. theres no redo. theres no means of even taking it > offline > effectively. > e) and the real dealbreaker once i was 99.99% done and loading the > preview... it froze in the middle of displaying. claimed it was done (ie, > not a network error or something.) theres no buttons at the top to force > a save or anything. meaning at 8.5 hours in, i had to start over almost > from the beginning. > > now, if we're going to be doing a hackathon with a focus (so far) on > documentation and participation, how long do you think it will be before > people get sufficiently frustrated that they throw up their hands and leave? > > wikis are not a viable solution for documentation that rarely requires > editing and even more rarely needs editing by the world at large. > > they are an excellent means of handling bugtracking, issue requests, > public discussion, docs that DO get edited frequently or randomly, etc. > > they are not an excellent means of documenting a project. > > > i am not in any way trying to criticise the excellent work done by > alejandro in creating the wiki, nor mario in his tireless maintenance of > the wiki site, nor am i in any way advocating for the removal of web docs, > nor saying that the wiki sucks, nor am i criticisng those who think > that everything should be through the wiki. > > i am recounting the reality of the last half day of my life. i am trying > to raise what i consider to be a legitimate question on the wisdom > and prudence of continuing to force a system to operate far beyond its > original intent in design, and whether massively expanding its role is > really such a good idea. > > -elf > > > > ___ > Chicken-users mailing list > Chicken-users@nongnu.org > http://lists.nongnu.org/mailman/listinfo/chicken-users > ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
w3m has massive display issues in general, eespecially with tables. elinks never seems to work on my machine. i dont know why. i also hate the elinks entry format. i use lynx and a very custom stripped-down ancient version of mozilla. i (stupidly) used mozilla, cause wikis in general dont get on well with lynx. (however, i just did a test, and its actually significantly easier to edit the wiki in lynx than it is in mozilla. which is an impressive feat, given the general track record of editing wikis in lynx.) -elf On Thu, 14 Feb 2008, Jim Ursetto wrote: Elf, Not to prolong this discussion further, but w3m is lightweight and automatically shells out to your editor of choice for forms, and works fine with the wiki. I'm sure elinks works similarly. On 2/14/08, Elf <[EMAIL PROTECTED]> wrote: in a brief response to other posts: im not on a machine thats capable of running firefox, and emacs would exceed its memory and space many times over, k? also, i tried copying things over, but that didnt work so well... the mouse is incredibly fickle, as stated, and its way bigger than the cut buffer could handle. its also entirely unstructured, and whitespace matters in subtle ways (try putting an extra few spaces at the end of a section and see what happens, for example), and given the mouse being flaky enough as it is, i didnt want to spend oodles of time erasing accidental pastes. :) ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
Thanks for the script Peter, I had been looking for a way to generate local html from svnwiki source for ages (particularly while developing eggdoc-svnwiki). The complexity and dependencies weren't worth figuring it out, though. To this point w3m or cut/paste has worked acceptably. On 2/14/08, Peter Bex <[EMAIL PROTECTED]> wrote: > I use this little script, I think Mario gave to me. > > #!/usr/pkg/bin/csi -s > > (use stream-wiki) ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
Elf, Not to prolong this discussion further, but w3m is lightweight and automatically shells out to your editor of choice for forms, and works fine with the wiki. I'm sure elinks works similarly. On 2/14/08, Elf <[EMAIL PROTECTED]> wrote: > in a brief response to other posts: im not on a machine thats capable of > running firefox, and emacs would exceed its memory and space many times > over, k? also, i tried copying things over, but that didnt work so well... > the mouse is incredibly fickle, as stated, and its way bigger than the > cut buffer could handle. its also entirely unstructured, and whitespace > matters in subtle ways (try putting an extra few spaces at the end of a > section and see what happens, for example), and given the mouse being flaky > enough as it is, i didnt want to spend oodles of time erasing accidental > pastes. :) ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
On Thu, Feb 14, 2008 at 02:19:46PM -0600, Jim Ursetto wrote: > Select all in the preview window, cut and paste to Emacs or Vim, edit, and > paste the text back to the wiki. I do it all the time, and it solves every one > of these issues. (Modern browsers handle most of them, too.) You can also use > `svn up` for the import step, but the preview window is still preferable to > `svn ci` as you can see the result, unless you're making a small change or > like > to live dangerously. How primitive! :) I use this little script, I think Mario gave to me. #!/usr/pkg/bin/csi -s (use stream-wiki) (define (read-wiki text) (with-output-to-string (lambda () (write-stream (wiki->html (string->stream text) stream-null "" (constantly stream-null) (lambda (name tail) tail) (make-hash-table) (make-html-header 1) (constantly stream-null) (constantly #t) (make-hash-table) (lambda (url) (string-append "?page=" (stream->string url (let ((args (command-line-arguments))) (when (null? args) (print "usage: wiki2html.scm ") (exit 1)) (print "http://galinha.ucpel.tche.br/common-css\"/>" That way you can generate a simple preview locally. You don't even need network access if you download the CSS and modify the stylesheet link. 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 pgp0XHSg37bNs.pgp Description: PGP signature ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
to respond to my own post, peter pointed out (nicely) that im an idiot who hadnt heard of svnwiki that (surprise!) uses svn to grab the pages for local editing. so my usability comments are probably not as relevant. what remains relevant is that its bloody hard to document anything even slightly nontrivial in it. in a brief response to other posts: im not on a machine thats capable of running firefox, and emacs would exceed its memory and space many times over, k? also, i tried copying things over, but that didnt work so well... the mouse is incredibly fickle, as stated, and its way bigger than the cut buffer could handle. its also entirely unstructured, and whitespace matters in subtle ways (try putting an extra few spaces at the end of a section and see what happens, for example), and given the mouse being flaky enough as it is, i didnt want to spend oodles of time erasing accidental pastes. :) -elf On Thu, 14 Feb 2008, Elf wrote: id like to entitle this next rant 'why wikis are highly suboptimal for documentation', if i may. approximately 9 hours ago, i noticed that the documentation that i had changed in the http wikidoc wasnt generating correctly. (for those wondering for future endeavours, its not possible at the moment to do nested tables directly. or tables with any wiki-markup at all. or any other markup. or ... you get the idea.) running through all those hoops only took about 2 hours before i realised that no markup would work inside existing markup. luckily, theres the scheme tag, to allow embedded evaluation of expressions. (and again, for those wondering, yes, the entire thing is generated via about 90 calls to (display) with static strings.) so we're about 4 hours in now, and things work about 95% of the way. its not handling margins properly and its not aligning text as specified. no biggie, right? this took the following 5 hours. and theres absolutely no reason why it should have taken more than 30 mins from the beginning, but im more than willing to allow for strange edge cases taking a bit longer. so why did it take so long? a) im stuck in a tiny window in a tiny screen with no real text manipulation abilities. b) theres no search and replace. theres no way of even killing lines off. c) cut and paste is fickle about where the mosue is, not where the cursor is. d) theres no undo. theres no redo. theres no means of even taking it offline effectively. e) and the real dealbreaker once i was 99.99% done and loading the preview... it froze in the middle of displaying. claimed it was done (ie, not a network error or something.) theres no buttons at the top to force a save or anything. meaning at 8.5 hours in, i had to start over almost from the beginning. now, if we're going to be doing a hackathon with a focus (so far) on documentation and participation, how long do you think it will be before people get sufficiently frustrated that they throw up their hands and leave? wikis are not a viable solution for documentation that rarely requires editing and even more rarely needs editing by the world at large. they are an excellent means of handling bugtracking, issue requests, public discussion, docs that DO get edited frequently or randomly, etc. they are not an excellent means of documenting a project. i am not in any way trying to criticise the excellent work done by alejandro in creating the wiki, nor mario in his tireless maintenance of the wiki site, nor am i in any way advocating for the removal of web docs, nor saying that the wiki sucks, nor am i criticisng those who think that everything should be through the wiki. i am recounting the reality of the last half day of my life. i am trying to raise what i consider to be a legitimate question on the wisdom and prudence of continuing to force a system to operate far beyond its original intent in design, and whether massively expanding its role is really such a good idea. -elf ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
Select all in the preview window, cut and paste to Emacs or Vim, edit, and paste the text back to the wiki. I do it all the time, and it solves every one of these issues. (Modern browsers handle most of them, too.) You can also use `svn up` for the import step, but the preview window is still preferable to `svn ci` as you can see the result, unless you're making a small change or like to live dangerously. On 2/14/08, Elf <[EMAIL PROTECTED]> wrote: > a) im stuck in a tiny window in a tiny screen with no real text manipulation > abilities. > b) theres no search and replace. theres no way of even killing lines off. > c) cut and paste is fickle about where the mosue is, not where the cursor > is. > d) theres no undo. theres no redo. theres no means of even taking it > offline > effectively. > e) and the real dealbreaker once i was 99.99% done and loading the > preview... it froze in the middle of displaying. claimed it was done > (ie, > not a network error or something.) theres no buttons at the top to > force > a save or anything. meaning at 8.5 hours in, i had to start over almost > from the beginning. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] documentation issues...
Thu, 14 Feb 2008 11:54:51 -0800 (PST), elf wrote: > so why did it take so long? > a) im stuck in a tiny window in a tiny screen with no real text manipulation > abilities. > b) theres no search and replace. theres no way of even killing lines off. > c) cut and paste is fickle about where the mosue is, not where the cursor > is. > d) theres no undo. theres no redo. theres no means of even taking it offline > effectively. > e) and the real dealbreaker once i was 99.99% done and loading the > preview... it froze in the middle of displaying. claimed it was done (ie, > not a network error or something.) theres no buttons at the top to force > a save or anything. meaning at 8.5 hours in, i had to start over almost > from the beginning. All the above is related to using a browser which is not suited to the task. Use a light-weight browser that embeds a real editor like vim or emacs or use firefox with the right plugin like ViewWithSource. I hated Wikis before I found these two solutions. Ciao Sven pgpKJjAGwygzr.pgp Description: PGP signature ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
[Chicken-users] documentation issues...
id like to entitle this next rant 'why wikis are highly suboptimal for documentation', if i may. approximately 9 hours ago, i noticed that the documentation that i had changed in the http wikidoc wasnt generating correctly. (for those wondering for future endeavours, its not possible at the moment to do nested tables directly. or tables with any wiki-markup at all. or any other markup. or ... you get the idea.) running through all those hoops only took about 2 hours before i realised that no markup would work inside existing markup. luckily, theres the scheme tag, to allow embedded evaluation of expressions. (and again, for those wondering, yes, the entire thing is generated via about 90 calls to (display) with static strings.) so we're about 4 hours in now, and things work about 95% of the way. its not handling margins properly and its not aligning text as specified. no biggie, right? this took the following 5 hours. and theres absolutely no reason why it should have taken more than 30 mins from the beginning, but im more than willing to allow for strange edge cases taking a bit longer. so why did it take so long? a) im stuck in a tiny window in a tiny screen with no real text manipulation abilities. b) theres no search and replace. theres no way of even killing lines off. c) cut and paste is fickle about where the mosue is, not where the cursor is. d) theres no undo. theres no redo. theres no means of even taking it offline effectively. e) and the real dealbreaker once i was 99.99% done and loading the preview... it froze in the middle of displaying. claimed it was done (ie, not a network error or something.) theres no buttons at the top to force a save or anything. meaning at 8.5 hours in, i had to start over almost from the beginning. now, if we're going to be doing a hackathon with a focus (so far) on documentation and participation, how long do you think it will be before people get sufficiently frustrated that they throw up their hands and leave? wikis are not a viable solution for documentation that rarely requires editing and even more rarely needs editing by the world at large. they are an excellent means of handling bugtracking, issue requests, public discussion, docs that DO get edited frequently or randomly, etc. they are not an excellent means of documenting a project. i am not in any way trying to criticise the excellent work done by alejandro in creating the wiki, nor mario in his tireless maintenance of the wiki site, nor am i in any way advocating for the removal of web docs, nor saying that the wiki sucks, nor am i criticisng those who think that everything should be through the wiki. i am recounting the reality of the last half day of my life. i am trying to raise what i consider to be a legitimate question on the wisdom and prudence of continuing to force a system to operate far beyond its original intent in design, and whether massively expanding its role is really such a good idea. -elf ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
