Re: Documentation (was Re: [Chicken-users] How to use prelude?)
Am Dienstag, den 30.05.2006, 14:19 -0500 schrieb Alejandro Forero Cuervo: > > So why not xml at the end? At least as the canonical format. > > Because wiki format is easier for humans to work with. I thought I made that clear: what's human readable should IMHO be decided based on personal preferences, task at hand etc. Example: my dad is about 70 years and kowns latex. I'd love to share pages with him. But I forgot latex. What I mean: the syntax to use should be chooses at the very moment you start editing. Because there's no one-size-fits-all especially not when it comes to syntax. Therefore I'd consider it very wise to carefully isolate the syntax decision (in user interface) from the data format definition. I could not even vote on wiki syntax (if there was a poll at all) since I would want at least two options. The other side: What's to be stored "for ever" should not have to be converted again. Under absolutely no circumstances. (Why? Have you ever heard of legal issues? How do you keep your timestamps and checksum when you convert you data?) If you want svn/wiki to be useful as a proof of authorship for instance, it would be smart to attach tamper proof timestamps and author notices with the context's SHA1 - under germany law. And if you want it to be useful for german layers document management, well, there's another law: use XML, ZIP, TIFF. OK, this doesn't have to bother you. I just want to say: the data format decision can easily exclude a lot of users. Also eventually there's going to be such a huge amount of data to convert when the data format support dies off, that there's no chance to select which data to retain and convert and which to drop. We've seen this proprietary data format trap in the 80th. As a result XML emerged. Even in 2000 I made my money still from helping people out of that trap (and in that case they even made the trap themself, i.e., they defined the data format, which they suddenly could no longer read - a kind of problem only possible in large enough corporations ;-). > I know there are editors for XML, but I don't think they can compare > with the ease of use of typing wiki-syntax in one's favorite text > editor. Since, as you point out, one can convert from wiki-format to > XML and back, I don't see much gain in storing things inside the > Subversion repository in XML. Things live “svn diff” would break. That's why I suggested to think about a line format based XML. But than again: the first thing I tell my clients: once you've got so much data and your software suddenly stops working. What's than? If there's a small programm with close to no dependencies converting that proprietary/private line based format into XML...great. We've got a cheap exit strategy. Let's continue. Who's going to document the syntax. And why invent yet another tag set? There's dockbook, there's tei, there's this topic something of ibm, where I lost the reference (but which I'd recommend most). A lot of effort went into these tag sets. Ignoring them is costly. And how many wiki syntax's is one willing to learn? What's abut the entry barrier and learning curve? > I guess the reason to use wiki instead of XML is the same reason to > store programs in Scheme (and Java, C, Perl, Python, Haskell, etc.) > code rather than XML as their canonical form. > > I think the canonical format should be the one that is easier for > humans to work with (since (1) we expect humans to work on this a lot > and (2) we can easily convert to formats that machines can work with). Definately no. The human editable format is a matter of taste like the editor of choice is a matter of taste. And a matter of the task and hand. If I suddenly understand that a svg editor could help me to lay out the programm structure of a large system and then convert that layout with a few function calls into an actual programm, why should I use the emacs I'm used to? No. I'm just gaining this experience, when this tie between literal syntax and respective tools and the abstract syntax tree in the head is broken. That's a becoming a new freedom to me. > > This had the added advantage, that the tagset to be used and the > > wiki syntax are independent decisions to make. > > If you choose to store everything in XML and then let people convert > to wiki, edit and convert back to XML, you still need your wiki format > to reflect the semantics of your document. Sure, the specific names > of tags can be different, but that is also true if you make wiki your > canonical format: you can always convert to XML and transform it to a > different schema. So I fail to see what the advantage is. I don't really get that. If I have an extensible, backward compatible extensible data format, be it reference syntax xml, sxml or a diff friendly line base xml (which are all xml info set compatible, short xml) I'm at the safe site. Users enjoy the freedom to choose an suitable edit syntax. System level can at
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
> A "smart-link" for SRFI docs would be nice, so one could write > something like, "see ((srfi-1)) for details" and get a proper link to > the official SRFI doc. Good idea. :-) svnwiki supports user-defined (wiki-specific) linktypes. I added one for the SRFI documents: [[srfi:40]] gets expanded to "SRFI 40" linked to the appropriate URL. You can see the list of types of links at: http://chicken.freaks-unidos.net/xsvnwiki-linktypes Feel free to define new ones. :-) Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
> So why not xml at the end? At least as the canonical format. Because wiki format is easier for humans to work with. I know there are editors for XML, but I don't think they can compare with the ease of use of typing wiki-syntax in one's favorite text editor. Since, as you point out, one can convert from wiki-format to XML and back, I don't see much gain in storing things inside the Subversion repository in XML. Things live “svn diff” would break. I guess the reason to use wiki instead of XML is the same reason to store programs in Scheme (and Java, C, Perl, Python, Haskell, etc.) code rather than XML as their canonical form. I think the canonical format should be the one that is easier for humans to work with (since (1) we expect humans to work on this a lot and (2) we can easily convert to formats that machines can work with). > This had the added advantage, that the tagset to be used and the > wiki syntax are independent decisions to make. If you choose to store everything in XML and then let people convert to wiki, edit and convert back to XML, you still need your wiki format to reflect the semantics of your document. Sure, the specific names of tags can be different, but that is also true if you make wiki your canonical format: you can always convert to XML and transform it to a different schema. So I fail to see what the advantage is. Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
Am Dienstag, den 30.05.2006, 11:35 -0500 schrieb Alejandro Forero Cuervo: > > But if this is to be the official documentation source, I'm a little > > concerned about the lack of semantic cues. For example, in the snippet > > above, the same markup is used for both the example and the sample > > implementation; and the procedure signature is "weakly marked up" > > using whitespace. Personally, I'd like to see a more explict, semantic > > markup, particularly for key elements like procedure signatures. (I > > assume the syntax is extensible, maybe Alejandro could add some tags > > to address this.) > > I will certainly add some tags. I absolutely agree with you. > > I'll probably use a format based in tags (ala XML), something along > the lines of: So why not xml at the end? At least as the canonical format. Not that I'd especially like xml, but it seems to be the only format, which is going to live for a long time (since it's making it's way into legislation already). (By canonical I mean: I could imagine an encoding, which plays nicer with text diffs for instance... and store that encoding in svn. Or sxml if you want.) I'd recomment to store some xml. Then use XML editors (like nvu) if you like. And those who like plain text editors more (like me) can get a wiki style markup on the fly. This had the added advantage, that the tagset to be used and the wiki syntax are independent decisions to make. Example: this is the template of the askemos wiki http://askemos2.tc-mw.de/A849640f672ed0df0958abc0712110f3c/template?template=source near the top there's a link to view with a wikipedia style wiki markup (I failed to get the lalr tool parse the original syntax, any help apreciated ;-) http://askemos2.tc-mw.de/A849640f672ed0df0958abc0712110f3c/template?media-type=text/wikipedia&template=source Sure since that' the template it's not exactly a good example of wiki syntax, since all the xsl and embedded Scheme is droped. I'm not using the first view for template editing. The wiki syntax with a more documentation type of page: http://askemos2.tc-mw.de/A849640f672ed0df0958abc0712110f3c/AskemosServer?media-type=text/wikipedia&template=source and I'm using the wiki syntax there. just my $0.02 /Jörg ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
On May 30, 2006, at 9:35 AM, Alejandro Forero Cuervo wrote:
But if this is to be the official documentation source, I'm a little
concerned about the lack of semantic cues. For example, in the
snippet
above, the same markup is used for both the example and the sample
implementation; and the procedure signature is "weakly marked up"
using whitespace. Personally, I'd like to see a more explict,
semantic
markup, particularly for key elements like procedure signatures. (I
assume the syntax is extensible, maybe Alejandro could add some tags
to address this.)
I will certainly add some tags. I absolutely agree with you.
I'll probably use a format based in tags (ala XML), something along
the lines of:
List length
(length l)
Returns the length of list {{l}}.
(length '(1 . 2))
=> 1.5
I'll probably do this by making it possible to define wiki-specific
tags whose definition is a Scheme function mapping the text between
the opening and closing tag to “lower-level” wiki language. These
definitions will probably live in a file on the wiki and get executed
by the sandbox egg.
What tags would you suggest? Examples, procedure, syntax? Hmm.
Possibly tags similar to eggdoc macros: procedure, macro, symbol-
table, ...
Thanks for your suggestions, Graham. You've raised a very valid
point.
Alejo.
http://azul.freaks-unidos.net/
___
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: Documentation (was Re: [Chicken-users] How to use prelude?)
On 5/30/06, Alejandro Forero Cuervo <[EMAIL PROTECTED]> wrote:
> But if this is to be the official documentation source, I'm a little
> concerned about the lack of semantic cues. [snip]
I will certainly add some tags. I absolutely agree with you.
I'll probably use a format based in tags (ala XML), something along
the lines of:
List length
(length l)
Returns the length of list {{l}}.
(length '(1 . 2))
=> 1.5
That looks fine to me. If you're considering an XML markup, I'd
suggest (length l), where @lib
specifies the library or egg: an empty or missing @lib should indicate
"unknown" and built-ins should explicitly specify lib="library", IMO.
It's verbose, but it's explicit. What do you think?
What tags would you suggest? Examples, procedure, syntax? Hmm.
Good question. :-) Procedures, parameters, syntax/macros,
example-code, definitely. I don't think "sample-implementation" really
deserves its own tag; in hindsight, that was a weak argument.
How about a procedure-reference, as in "In the example below, we use
map, sum and string-length to
calculate the total length of the strings." That implies an index,
though.
Possibly a "command-line" tag, to show shell sessions? Maybe that's
just ?
A "smart-link" for SRFI docs would be nice, so one could write
something like, "see ((srfi-1)) for details" and get a proper link to
the official SRFI doc.
That's all I can think of! Really, I think (procedure parameter syntax
example) is an excellent starting point.
Graham
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
> But if this is to be the official documentation source, I'm a little
> concerned about the lack of semantic cues. For example, in the snippet
> above, the same markup is used for both the example and the sample
> implementation; and the procedure signature is "weakly marked up"
> using whitespace. Personally, I'd like to see a more explict, semantic
> markup, particularly for key elements like procedure signatures. (I
> assume the syntax is extensible, maybe Alejandro could add some tags
> to address this.)
I will certainly add some tags. I absolutely agree with you.
I'll probably use a format based in tags (ala XML), something along
the lines of:
List length
(length l)
Returns the length of list {{l}}.
(length '(1 . 2))
=> 1.5
I'll probably do this by making it possible to define wiki-specific
tags whose definition is a Scheme function mapping the text between
the opening and closing tag to “lower-level” wiki language. These
definitions will probably live in a file on the wiki and get executed
by the sandbox egg.
What tags would you suggest? Examples, procedure, syntax? Hmm.
Thanks for your suggestions, Graham. You've raised a very valid
point.
Alejo.
http://azul.freaks-unidos.net/
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
On 5/29/06, felix winkelmann <[EMAIL PROTECTED]> wrote:
On 5/29/06, Graham Fawcett <[EMAIL PROTECTED]> wrote:
>
> I was just thinking about what's happening now in the Python
> community. A well-known Python developer dumped all of the official
> documentation into a Wiki / content management system, and the
> community is busy filling in gaps, and adding new information.
Actually, Alejandro suggested this already - there is an unofficial manual:
http://wiki.freaks-unidos.net/chicken%20scheme%20manual
Now, I have absolutely no problem with this. There is just one catch: I don't
want to maintain two versions of the manual, and we definitely need something
that can be installed locally.
Looking at Alejandro's wiki, it looks like the first issue is easily
resolved: the wiki pages are stored in a subversion repository, and
can be edited either through the Web or via subversion patches. That's
a nice feature.
Personally, I would suggest that we use
http://galinha.ucpel.tche.br/coop, since it's internal format can be converted
relatively easily to/from other formats.
I also like the coop format; however, the current "freaks-manual" uses
a more traditional Wiki format. Here's a snippet, the documentation
for the (conc) procedure.
#<
(conc "alejandro" "forero" "cuervo")
=> "alejandroforerocuervo"
{{conc}} could be implemented as:
(define (conc . args)
(apply string-append (map ->string args)) )
This procedure is specific of Chicken; other Scheme implementations
might not include it.
SNIPPET-END
This is a fairly standard Wiki markup and is quite simple to learn.
But if this is to be the official documentation source, I'm a little
concerned about the lack of semantic cues. For example, in the snippet
above, the same markup is used for both the example and the sample
implementation; and the procedure signature is "weakly marked up"
using whitespace. Personally, I'd like to see a more explict, semantic
markup, particularly for key elements like procedure signatures. (I
assume the syntax is extensible, maybe Alejandro could add some tags
to address this.)
So, Felix -- local editing is available. Assuming a good wiki->texinfo
procedure, what do you think of the wiki markup?
Graham
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
At Mon, 29 May 2006 03:12:06 -0700 (PDT), Dan wrote: > > Just a small observation -- the propensity for long, > complicated URL's isn't a win. Typing the full > www.call/cc.org is a pain; the galinha site is also > not something I can memorize, and the same goes for > the united freaks site. I like the call/cc site because I can always remember it - it's just the R5RS procedure name, nothing else. For PLT I can never remember the site name (without looking it's either got PLT somewhere in it or DrScheme, I think), and I know Scheme48 is very short but can't remember if it's s48.org or scheme48.org or scheme-48.org. In fact, call/cc is the *only* Scheme site that I don't use either a bookmark or Google for, and typing "call" is always enough for auto-completion. My two cents... -- Alex ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
> >>>I don't think it would make much of a difference, though (which is > >>>why I'm not buying them myself). > >> > >>call/cc would make a difference w/ search engines. > > > >How so? Lots of people searching "call/cc" instead of > >"call-with-current-continuation", is that what you mean? > > Yes. I believe that of all people getting to our hypothetical call-cc from search engines, those searching "call/cc" would be a ridiculously small portion when compared with the rest (those searching "chicken scheme" or "scheme implementation" or any other similar query). Also, search engines use a lot more information for prioritizing results other than the domain name. I still don't think it would make much of a difference, search engines considered. Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
On May 29, 2006, at 12:09 PM, Alejandro Forero Cuervo wrote: I don't think it would make much of a difference, though (which is why I'm not buying them myself). call/cc would make a difference w/ search engines. How so? Lots of people searching "call/cc" instead of "call-with-current-continuation", is that what you mean? Yes. Alejo, curious. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
On 5/29/06, Alejandro Forero Cuervo <[EMAIL PROTECTED]> wrote: > >Now, I have absolutely no problem with this. There is just one > >catch: I don't want to maintain two versions of the manual, and we > >definitely need something that can be installed locally. > >Personally, I would suggest that we use > >http://galinha.ucpel.tche.br/coop, since it's internal format can > >be converted relatively easily to/from other formats. What we need > >is a texi generator. (any volunteers?) > > I'll volunteer a few cycles, though I don't use streams and I know > Alejandro is fond of them, hope that's not a barrier to entry. :-) > I'll need to brush up on my texinfo, though, it's been a while. Well, here is how I would recommend you do this. The stream-wiki egg separates the parsing of wiki format from the actual generation of output. The wiki->html function is defined as follows: [snip] Thanks for the clues Alejandro! I'll take a look at the code and try to get something working in the next week. Graham ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
> >Now, I have absolutely no problem with this. There is just one > >catch: I don't want to maintain two versions of the manual, and we > >definitely need something that can be installed locally. > >Personally, I would suggest that we use > >http://galinha.ucpel.tche.br/coop, since it's internal format can > >be converted relatively easily to/from other formats. What we need > >is a texi generator. (any volunteers?) > > I'll volunteer a few cycles, though I don't use streams and I know > Alejandro is fond of them, hope that's not a barrier to entry. :-) > I'll need to brush up on my texinfo, though, it's been a while. Well, here is how I would recommend you do this. The stream-wiki egg separates the parsing of wiki format from the actual generation of output. The wiki->html function is defined as follows: (define (wiki->html str . rest) (stream-delay (let-optionals rest ( . ) (wiki-parse (html-driver . ) . The html-driver call creates a "driver" for generating output. A "driver for generating output" is just a table with a lot of functions that the wiki-parse function will be calling to generate HTML. Just like html-driver there's also latex-driver that generates parseable LaTeX code from a wiki file (it is 85% complete: on some constructs such as images just generates some "[[Images not supported in LaTeX mode]]" text) and odf-driver (20% complete, doesn't really work right now) and texi-driver (which I made a long time ago but I have never used, I would guess it is around 30% complete, but I could be off by a big margin). And there are some other drivers that instead of generating output accumulate some information and return it (links-driver, tags-driver). Based on the latex-driver my wiki system can generate PDF files. I haven't enabled this for the Chicken wiki, but you can see an example for another wiki that it handles here: http://bogowiki.org/transmilenio.pdf So you can see where I'm going. I would recommend you check the texi-driver implementation and, comparing its functions with those in html-driver, make sure they generate their output properly. To do that, you'll have to use streams, the whole output generation is based on them. :-/ Though the examples in html-driver should be more than enough to figure out how to do it. Once texi-driver works, it will be fairly easy to add a caller for it to svnwiki (and we would end up having a "Texi" link in the pages right next to "Edit", "Tags", "History", etc.; clicking it would download the current article in Texi format). A quick note on my experience using streams instead of strings of characters: it is ssslllooowww. It uses a lot of conses and closures which are discarded right away, which triggers a lot of garbage collections, which makes everything slow. And they force you to fill your code with string->stream and stream->string everywhere (but I might take a shot at solving that soon). On the other hand, programming with them is a real pleassure, as you get to write everything in a purely functional manner, without requiring lots of memory. :-) Your help would be greatly appreciated, Graham! Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
> I now we're living in the age of delicious, but typing a good URL is > always the fastest. No, local bookmarks don't cut it -- there's > already too many of them. > > Maybe it's just me, but I'd love shorter, memorable URL's. Dan, I'm think if you buy us some shorter, memorable, domains, the admins of call/cc, freaks-unidos and ghallina would gladly configure our software to have them work. :-) I don't think it would make much of a difference, though (which is why I'm not buying them myself). Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
On Mon, 29 May 2006 03:12:06 -0700 (PDT) Dan <[EMAIL PROTECTED]> wrote: > Just a small observation -- the propensity for long, > complicated URL's isn't a win. Typing the full > www.call/cc.org is a pain; the galinha site is also > not something I can memorize, and the same goes for > the united freaks site. Just for the sake of curiosity and documentation of "weird" things: - galinha is chicken in portuguese; - ucpel stands for "Universidade Católica de Pelotas" or, in english, "Catholic University of Pelotas"; - tche is a network to which UCPel is connected (http://www.tche.br). It's a network which connects some universities of the south of Brazil to the Internet. "Tche" is a kind of slang used in some cities of the south of Brazil, specially in Rio Grande do Sul, state where Pelotas is located -- I guess it's derived from "che", a spanish word. - br means Brazil (or Brasil, which is Brazil in portuguese). I don't think it will make any difference to the memorization of the URL. Just to explain why the address is such a funny string. :-) Best wishes, Mario ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
On 5/29/06, Dan <[EMAIL PROTECTED]> wrote: Just a small observation -- the propensity for long, complicated URL's isn't a win. Typing the full www.call/cc.org is a pain; the galinha site is also not something I can memorize, and the same goes for the united freaks site. You could always use tinyurl.com, and a few easily-remembered mnemonics: call-with-current-continuation.org --> http://tinyurl.com/a3nvm "a three-nippled vole mouse" the coop --> http://tinyurl.com/krzrq "kick raging zebra, run quickly" freaks wiki --> http://tinyurl.com/gkw5d "good kind wiki, five dollars" (the bad-kind ones are a dime a dozen) freaks manual --> http://tinyurl.com/jket4 "juicy kumquat equals tomatoes four" (the time-honoured nutritional maxim). Graham ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
On 5/29/06, felix winkelmann <[EMAIL PROTECTED]> wrote: On 5/29/06, Graham Fawcett <[EMAIL PROTECTED]> wrote: > > I was just thinking about what's happening now in the Python > community. A well-known Python developer dumped all of the official > documentation into a Wiki / content management system, and the > community is busy filling in gaps, and adding new information. I > realize that the Python community is a a few orders of magnitude > larger than Chicken's, but perhaps opening up the docs for community > editing might alleviate the burden from Felix and the core developers? > Actually, Alejandro suggested this already - there is an unofficial manual: http://wiki.freaks-unidos.net/chicken%20scheme%20manual This is a great idea. I'll go read everything at Alejandro's site ;-) and see if I can contribute anything. Now, I have absolutely no problem with this. There is just one catch: I don't want to maintain two versions of the manual, and we definitely need something that can be installed locally. Personally, I would suggest that we use http://galinha.ucpel.tche.br/coop, since it's internal format can be converted relatively easily to/from other formats. What we need is a texi generator. (any volunteers?) I'll volunteer a few cycles, though I don't use streams and I know Alejandro is fond of them, hope that's not a barrier to entry. :-) I'll need to brush up on my texinfo, though, it's been a while. Graham ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
On 5/29/06, Peter Bex <[EMAIL PROTECTED]> wrote: I agree with Brandon that the call/cc URL is easy to remember (especially if you read the Baker paper) but it is a bit long :) If someone wants to register that url, I have no objection, but personally I'd like to address more important problems... (felix) ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
On Mon, May 29, 2006 at 03:12:06AM -0700, Dan wrote: > Just a small observation -- the propensity for long, > complicated URL's isn't a win. Typing the full > www.call/cc.org is a pain; the galinha site is also > not something I can memorize, and the same goes for > the united freaks site. Hmmm.. callcc.org is still available. Perhaps felix should register it and have it point to the other domain. > I now we're living in the age of delicious, but typing > a good URL is always the fastest. No, local bookmarks > don't cut it -- there's already too many of them. > > Maybe it's just me, but I'd love shorter, memorable > URL's. I agree with Brandon that the call/cc URL is easy to remember (especially if you read the Baker paper) but it is a bit long :) 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 pgpXRmTlKTIi0.pgp Description: PGP signature ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
Just a small observation -- the propensity for long, complicated URL's isn't a win. Typing the full www.call/cc.org is a pain; the galinha site is also not something I can memorize, and the same goes for the united freaks site. I now we're living in the age of delicious, but typing a good URL is always the fastest. No, local bookmarks don't cut it -- there's already too many of them. Maybe it's just me, but I'd love shorter, memorable URL's. -- Dan __ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
> I realize that the Python community is a a few orders of magnitude > larger than Chicken's, but perhaps opening up the docs for community > editing might alleviate the burden from Felix and the core > developers? That's precisely what I think. Having a wiki could help improve the quality of our documentation significantly. On May the 23th I started one: http://chicken.freaks-unidos.net/ The contents of the wiki are stored in the wiki/ sub directory of the eggs' Subversion repository (which means that anyone with access to the repository can checkout a copy, work on them locally and then commit changes). There are more details about this: http://chicken.freaks-unidos.net/svn%20checkout I plan to move the documentation for most of my eggs to it. You can see an example of an egg I've been documenting there: http://chicken.freaks-unidos.net/stream-ldif For the sake of coherency I also wrote some guidelines on how to document eggs, which are, of course, open to discussion: http://chicken.freaks-unidos.net/eggs%20guidelines I created a page for users of Chicken Scheme. Right now it feels a little lonely, only listing me, but I would like to invite others to join: http://chicken.freaks-unidos.net/users Of course, the wiki engine is run by Chicken. More documentation about it is available here: http://wiki.freaks-unidos.net/svnwiki So I want to invite you all to start contributing to the wiki. I think it could turn out to be a very useful resource and make using Chicken even more pleasant than it already is. Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: Documentation (was Re: [Chicken-users] How to use prelude?)
On 5/29/06, Graham Fawcett <[EMAIL PROTECTED]> wrote: I was just thinking about what's happening now in the Python community. A well-known Python developer dumped all of the official documentation into a Wiki / content management system, and the community is busy filling in gaps, and adding new information. I realize that the Python community is a a few orders of magnitude larger than Chicken's, but perhaps opening up the docs for community editing might alleviate the burden from Felix and the core developers? Actually, Alejandro suggested this already - there is an unofficial manual: http://wiki.freaks-unidos.net/chicken%20scheme%20manual Now, I have absolutely no problem with this. There is just one catch: I don't want to maintain two versions of the manual, and we definitely need something that can be installed locally. Personally, I would suggest that we use http://galinha.ucpel.tche.br/coop, since it's internal format can be converted relatively easily to/from other formats. What we need is a texi generator. (any volunteers?) cheers, felix ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Documentation (was Re: [Chicken-users] How to use prelude?)
On 5/28/06, felix winkelmann <[EMAIL PROTECTED]> wrote: On 5/28/06, Peter Bex <[EMAIL PROTECTED]> wrote: > On Sun, May 28, 2006 at 12:31:14PM +0200, felix winkelmann wrote: > > > Adding a quote in front of the define doesn't work either as that expands > > > to (quote (define with-x #t)) > > > > Try "'...'" (one pair of double-quotes for scheme, and one pair of single > > quotes for the shell). > > It would be nice if you could document this in the manual. Yes, there are a lot of things that should be mentioned there... ;-) I was just thinking about what's happening now in the Python community. A well-known Python developer dumped all of the official documentation into a Wiki / content management system, and the community is busy filling in gaps, and adding new information. I realize that the Python community is a a few orders of magnitude larger than Chicken's, but perhaps opening up the docs for community editing might alleviate the burden from Felix and the core developers? Just a thought, Graham ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
