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.
#SNIPPET-END
=== conc
(conc X ...)
Returns a string with the string-represenation of all arguments
concatenated together.
Examples:
enscript highlight=scheme
(conc alejandro forero cuervo)
= alejandroforerocuervo
/enscript
{{conc}} could be implemented as:
enscript highlight=scheme
(define (conc . args)
(apply string-append (map -string args)) )
/enscript
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?)
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
procedure(length l)/procedure
Returns the length of list {{l}}.
examples
(length '(1 . 2))
= 1.5
/examples
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/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
procedure(length l)/procedure
Returns the length of list {{l}}.
examples
(length '(1 . 2))
= 1.5
/examples
That looks fine to me. If you're considering an XML markup, I'd
suggest procedure lib=library(length l)/procedure, 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
refmap/ref, refsum/ref and refstring-length/th 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 highlight enscript=bash?
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?)
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
procedure(length l)/procedure
Returns the length of list {{l}}.
examples
(length '(1 . 2))
= 1.5
/examples
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?)
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/wikipediatemplate=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/wikipediatemplate=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?)
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?)
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?)
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). wink 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?)
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?)
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?)
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?)
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?)
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?)
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?)
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
