Re: [Chicken-users] Comprehensive documentation rewrite
Elf scripsit: That's true, I should have said that the different licenses might become an issue if you are distributing several eggs together. Though I am not overly worried about GPL violations in distributions of machine-generated C code, so that might be a sensible exception clause to add GPLed eggs. I can't, in general, distribute such generated code without the Scheme source, however, as generated code is not the preferred form of the work for making modifications to it; i.e. it is not source at all in the eyes of the GPL. And adding an exception to the egg helps not at all if the underlying dependency is itself GPLed. -- John Cowan [EMAIL PROTECTED] http://www.ccil.org/~cowan Charles li reis, nostre emperesdre magnes, Set anz totz pleinz ad ested in Espagnes. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
Yes, you are right that you have to distribute the Scheme code, I realized that last night after going home. If that wasn't the case, you could simply distribute generated assembly code for everything. As for GPL-ed dependencies, what I meant was that you could ask the author(s) of any GPL-ed eggs to make an exception for the particular purposes of your project, similar to the approach taken by Debian. -Ivan John Cowan [EMAIL PROTECTED] writes: I can't, in general, distribute such generated code without the Scheme source, however, as generated code is not the preferred form of the work for making modifications to it; i.e. it is not source at all in the eyes of the GPL. And adding an exception to the egg helps not at all if the underlying dependency is itself GPLed. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Wed, Feb 13, 2008 at 09:18:20AM +0100, felix winkelmann wrote: I like the idea of being able to put the documentation into the code; something like Doxygen is needed for Scheme. I think it's not the first time such an idea has been proposed, but I don't know much about what has been tried. In my experience separating the documentation from the code leads in the end to more consistent information. I've seen too much doxygen generated documentation heaps with no obvious start or beginning. Yeah, and the same goes for the horrible hack known as rdoc. Rdoc is basically Doxygen without semantic markup. Another problem of 'rdoc-like' documentation is that you end up having to wade through piles and piles of documentation in the code when you're looking for something. Just look at the Rails code, some classes start with several *pages* of text. Sometimes even functions have pages of text preceding them. It makes reading the code awfully hard. Besides, even with so much documentation, stuff is *still* not documented properly and it's often hard to find docs on stuff because it's all hidden away. Another effect is that documentation is structured to fit the doc-generating tool, instead of being easy to access for users. Docs are hard to maintain and code is hard to maintain when you stick them all in one big pile. I happen to like svnwiki syntax. It's easy to use, non-obstructive and we have all the infrastructure to convert it into other formats. I like it too, but it's not rich enough to express the semantics. However, with the proper extensions to the syntax this problem can be fixed. Besides, all these doc overhauls just eat up developer time... That's why there shouldn't be all these doc overhauls, there should be just one, resulting in proper documentation. 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 pgpsX7qAaAolg.pgp Description: PGP signature ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Feb 12, 2008 10:16 PM, Shawn Rutledge [EMAIL PROTECTED] wrote: On Feb 12, 2008 10:13 AM, Tobia Conforto [EMAIL PROTECTED] wrote: My idea is to devise a smart document format, preferably s-expr based (maybe SSAX-based if nothing better comes to mind) and convert every piece of Chicken API documentation to that format: both for eggs and for the base system. This includes any relevant SRFIs that are part of Chicken or of some eggs. I like the idea of being able to put the documentation into the code; something like Doxygen is needed for Scheme. I think it's not the first time such an idea has been proposed, but I don't know much about what has been tried. In my experience separating the documentation from the code leads in the end to more consistent information. I've seen too much doxygen generated documentation heaps with no obvious start or beginning. Another effect is that documentation is structured to fit the doc-generating tool, instead of being easy to access for users. I happen to like svnwiki syntax. It's easy to use, non-obstructive and we have all the infrastructure to convert it into other formats. Besides, all these doc overhauls just eat up developer time... cheers, felix ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Feb 13, 2008 9:44 AM, Peter Bex [EMAIL PROTECTED] wrote: Docs are hard to maintain and code is hard to maintain when you stick them all in one big pile. Absolutely. Besides, all these doc overhauls just eat up developer time... That's why there shouldn't be all these doc overhauls, there should be just one, resulting in proper documentation. I think the *-wiki overhaul is good, but let's not change to yet another representation, whether semantically richer or not (and I still don't know what that really means). cheers, felix ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Feb 13, 2008 1:18 AM, felix winkelmann [EMAIL PROTECTED] wrote: In my experience separating the documentation from the code leads in the end to more consistent information. I've seen too much doxygen generated documentation heaps with no obvious start or beginning. Well that's not the purpose... it's API documentation, not a tutorial. At my job for example we are required to write specs, but I still like to have the structured comments and the generated documentation from them. The specs tend to be wrong or out-of-date unless you spend extra days updating them. Management thinks in terms of a waterfall process: you do design, then you code. But when you code, you find problems in the design, so it has to evolve. Updating formal specs at the same time makes the whole process slower, but I nearly always manage to keep my in-code comments up-to-date. And when I write Scheme I sometimes write ordinary comments with at least a one-line description of what the function does, and whatever constraints there are on the parameters (if it's not obvious from the name of the parameter). I just wish those comments were parseable. Another effect is that documentation is structured to fit the doc-generating tool, instead of being easy to access for users. It needs to be searchable. Doxygen doesn't give you that because it would involve some back-end code rather than just HTML. I happen to like svnwiki syntax. It's easy to use, non-obstructive and we have all the infrastructure to convert it into other formats. Well the comments could be structured like that and the same parser could be re-used to generate the HTML. (Although personally as wiki's go I'm partial to MediaWiki syntax.) Besides, all these doc overhauls just eat up developer time... I would like to have some method of putting parseable comments in the Scheme code. Doesn't mean it has to replace other forms of documentation... but isn't something like this available? If the PLT Scheme people are thinking about it, maybe we could borrow some code. (OK I should look into it rather than just making suggestions... but I can't promise how soon I will get around to it) ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Feb 13, 2008 1:44 AM, Peter Bex [EMAIL PROTECTED] wrote: Another problem of 'rdoc-like' documentation is that you end up having to wade through piles and piles of documentation in the code when you're looking for something. Just look at the Rails code, some classes start with several *pages* of text. Sometimes even functions have pages of text preceding them. It makes reading the code awfully hard. That sounds like something that could be fixed in your editor, in theory... e.g. the emacs mode could elide such comments to one line by default, and then you can unfold it if you want to see the whole thing. I'm not an emacs user though. (Maybe some day...) Besides, all these doc overhauls just eat up developer time... That's why there shouldn't be all these doc overhauls, there should be just one, resulting in proper documentation. It's better to work smart, not hard. That means start by building the tools, to minimize the tedium. A good example (outside the software domain) would be the human genome project... But if you do it the hard way, then you will be even less inclined to ever do it again, even if the result was suboptimal and still needs improvement. Quality results from continuous improvement, not a one-pass get it right and call it done. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Wed, 13 Feb 2008, Shawn Rutledge wrote: snip That's why there shouldn't be all these doc overhauls, there should be just one, resulting in proper documentation. It's better to work smart, not hard. That means start by building the tools, to minimize the tedium. A good example (outside the software domain) would be the human genome project... But if you do it the hard way, then you will be even less inclined to ever do it again, even if the result was suboptimal and still needs improvement. Quality results from continuous improvement, not a one-pass get it right and call it done. not always true. tex was better before the cycle of 'continuous improvements', for something in this problem domain. i dont know where the idea that anyone was proposing a be-all-and-end-all of documentation systems came from, but its getting aggravating. i proposed the following concepts: a) felix is retiring/has retired. we need something to lessen the learning curve for people being able to contribute. b) the eggs and core use multiple incompatible documentation systems, making it difficult to have any semblance of consistency in terms of look-and-feel and in terms of quality. additionally, the range of functionalities between systems is very large, making it trivial to do some things and impossible to do others. this does not lead to maintainable or readable docs. c) the only help available in the interpreter is so far out of date as to be useless. this is a major inhibiting factor in terms of new growth and usability. d) there are many concerns (in the sense of interested parties) who want documentation available in different ways and with different formats, often with different properties and goals. e) the systems currently in place have major drawbacks, including ease of use, ease of maintenance, and simplicity. e) it is feasible to find a solution to these problems. moreover, it is not difficult to solve 98% of it at once. (this is in reference only to documentation, not felix stepping down.) all that is required is a sufficiently flexible set of primitives that constrain their inputs. no-one is trying for a perfect system, nor even necessarily for something highly general. this is a specific project for a specific implementation of a specific language. the goal atm is not even something for all scheme (whatever that means these days). the goal is for a workable system with no learning curve that people can and will use easily that can generate the documentation desired with consistent presentation and semantics. this is a problem that has been occupying me for several months at this point. i was hoping to have a concrete semiformal proposal by tonight. ive been a bit sidetracked with other things, so it probably wont be complete until tomorrow. the proposal is intended as an rfc with a little code to back it up, so that when some form of agreement is reached, there wont be a delay before it can be used. -elf ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Feb 13, 2008 12:04 PM, Elf [EMAIL PROTECTED] wrote: not always true. tex was better before the cycle of 'continuous improvements', The early development was before my time, but I don't think TeX emerged fully-formed. Knuth came up with that version scheme where he adds digits to pi for each new version (expressing the idea that it more accurately conforms to the ideal with each rev), and even pays people to find bugs in his code (which says to me that he believes in continuous improvement). And it was arguably further improved by some of the forks, like LaTeX. Then Knuth invented literate programming. I have some respect for the idea, even though some of the uses and implementations can be unwieldy and the ideals are a bit high-minded - the kernel of the idea seems to me a good one, and has been inspiring for others. I find Doxygen extremely useful, and don't understand why such a large number of developers who write C++ or Java can agree on such a system, while Scheme people seem to think it's weird to put any kind of special comment syntax in the code. Some code could maybe be considered self-documenting, and some not. i dont know where the idea that anyone was proposing a be-all-and-end-all of documentation systems came from, but its getting aggravating. i proposed the following concepts: I agree with all your concepts, and look forward to your proposal. All I'm hoping for as a starting point is a way to write parseable comments that can be converted into API docs. The other stuff can be added later; a be-all documentation system cannot be expected to emerge fully formed either. I will always think of separate documentation files as being fundamentally an adjunct... if you want to write a tutorial, sure it ought to be separate, but that's not where you start; you'd typically write it after the code. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Wed, 13 Feb 2008, Shawn Rutledge wrote: snip All I'm hoping for as a starting point is a way to write parseable comments that can be converted into API docs. The other stuff can be added later; a be-all documentation system cannot be expected to emerge fully formed either. I will always think of separate documentation files as being fundamentally an adjunct... if you want to write a tutorial, sure it ought to be separate, but that's not where you start; you'd typically write it after the code. im all for putting two lines giving the calling convention and a one-second description above each procedure, macro, and variable. im all for having inline comments on difficult bits. im all for putting a header giving some basic data and a minichangelog. thats where it ends for me, though. i am not for generating full-fledged documentation in a variety of formats by doing comment parsing. besides making the code infinitely harder to read and get around in, it restricts documentation to ONLY making sense for programming objects. meaning that when you start having to search for the code amidst the essays, theres a problem. meaning that if you want to give some auxiliary info its not clear where it should go. meaning that if all that docs were supposed to do was to give me an api ref, it would be fine, but thats not reality. even if we ignore that aspect, from a technical standpoint its REALLY obnoxious. first, we have to handle everything as strings, to get it out of the comments. then we have to worry about parsing comments within comments (ie, what happens if youre working on a section but dont want it to be out but want to see how the rest is doing?). then we have to worry about which comment blocks are actual documentation vs inline comments (which is more trivial, but involves extra syntax). plus, we dont get any of the advantages of having a language capable of processing abstract nested syntax trees: we're reduced to awk. -elf ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
Sorry to interrupt this rather high-level discussion on semantics and stuffs with another of my pedestrian concerns, but when you do all this wonderful work, could you be a little more specific as to what license the eggs are under? For 98% I can tell from looking inside the doc page, but for a few of the older ones I'm left wondering whether you mean version 1, 2 or what when it says (L)GPL under license... for example 'make'... is that LGPL-1 or what... Ideally, the license info in the main eggs unlimited page would include the GPL version. No, this is not purely because of laziness on my part :) Cheers, Leo ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
heya. to the best of my knowledge most of the currently maintained eggs are BSD licenced, not (L)GPLvN (except for Ivan's). since theyve mostly been ported from elsewhere, or are library bindings, it should be fairly easy to see the dates of creation or what the licence of the bound lib is... -elf On Wed, 13 Feb 2008, Leonardo Valeri Manera wrote: Sorry to interrupt this rather high-level discussion on semantics and stuffs with another of my pedestrian concerns, but when you do all this wonderful work, could you be a little more specific as to what license the eggs are under? For 98% I can tell from looking inside the doc page, but for a few of the older ones I'm left wondering whether you mean version 1, 2 or what when it says (L)GPL under license... for example 'make'... is that LGPL-1 or what... Ideally, the license info in the main eggs unlimited page would include the GPL version. No, this is not purely because of laziness on my part :) Cheers, Leo ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
Elf, do you mind not spreading incorrect information?
$ find . -wholename '*/trunk/*.meta' -exec grep GPL '{}' ';' | wc -l
43
$ find . -wholename '*/trunk/*.meta' -exec grep MIT '{}' ';' | wc -l
22
$ find . -wholename '*/trunk/*.meta' -exec grep SRFI '{}' ';' | wc -l
13
$ find . -wholename '*/trunk/*.meta' -exec grep -i Public Domain '{}' ';' |
wc -l
15
I maintain 26 eggs, 25 of which are licensed under the GPL. So there
are at least 18 other eggs under GPL/LGPL (most of them released
before GPL v3), 22 under the MIT license, 13 under the SRFI license,
15 released as public domain. And there are a handful in which the
license is listed as unknown, Open Source, Bremer license, and
Creative Commons.
-Ivan
Elf [EMAIL PROTECTED] writes:
to the best of my knowledge most of the currently maintained eggs
are BSD licenced, not (L)GPLvN (except for Ivan's). since theyve
mostly been ported from elsewhere, or are library bindings, it
should be fairly easy to see the dates of creation or what the
licence of the bound lib is...
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
i was only referring to currently maintained eggs, as i stated in the post,
and only to those with (L)GPL licensing. all i SAID was that most
currently maintained eggs are released under BSD, and how to find the
licence revision for the LGPL eggs that have been ported from elsewhere.
the LGPL ver is what seemed to matter from Leonadro's post, which is why
that was the issue i responded to. precisely where am i spreading
misinformation?
-elf
On Thu, 14 Feb 2008, Ivan Raikov wrote:
Elf, do you mind not spreading incorrect information?
$ find . -wholename '*/trunk/*.meta' -exec grep GPL '{}' ';' | wc -l
43
$ find . -wholename '*/trunk/*.meta' -exec grep MIT '{}' ';' | wc -l
22
$ find . -wholename '*/trunk/*.meta' -exec grep SRFI '{}' ';' | wc -l
13
$ find . -wholename '*/trunk/*.meta' -exec grep -i Public Domain '{}' ';' |
wc -l
15
I maintain 26 eggs, 25 of which are licensed under the GPL. So there
are at least 18 other eggs under GPL/LGPL (most of them released
before GPL v3), 22 under the MIT license, 13 under the SRFI license,
15 released as public domain. And there are a handful in which the
license is listed as unknown, Open Source, Bremer license, and
Creative Commons.
-Ivan
Elf [EMAIL PROTECTED] writes:
to the best of my knowledge most of the currently maintained eggs
are BSD licenced, not (L)GPLvN (except for Ivan's). since theyve
mostly been ported from elsewhere, or are library bindings, it
should be fairly easy to see the dates of creation or what the
licence of the bound lib is...
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
Well, it is simply not true. Source code with a non-BSD license that gets imported as an egg does not magically become BSD-licensed. There are also many eggs that are actively in use that are not licensed under the BSD. For example, most of the prerequisites of svnwiki are licensed under the GPL. Your statements are a gross mischaracterization of the situation. The GPL/LGPL versioning is a separate issue, and I would say that most eggs released under that license fall under the default GPL category of v2 or later, except for the eggs I maintain, which are GPL v3 or later for all but one. By the way, if the egg licenses are an issue for any distribution, then one might consider the Debian approach -- if the license for a particular package is incompatible with Debian, in many cases this is dealt with by approaching the author(s) of that package and asking them if it would be possible to issue a Debian-only open-source compatible license for that package. The inconsistent licenses for the eggs don't matter with Chicken, because the Chicken itself is not distributed together with any eggs, but this might become an issue for a Linux distribution. -Ivan Elf [EMAIL PROTECTED] writes: i was only referring to currently maintained eggs, as i stated in the post, and only to those with (L)GPL licensing. all i SAID was that most currently maintained eggs are released under BSD, and how to find the licence revision for the LGPL eggs that have been ported from elsewhere. the LGPL ver is what seemed to matter from Leonadro's post, which is why that was the issue i responded to. precisely where am i spreading misinformation? ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
Ivan == Ivan Raikov [EMAIL PROTECTED] writes: Ivan Well, it is simply not true. Source code with a non-BSD Ivan license that gets imported as an egg does not magically Ivan become BSD-licensed. There are also many eggs that are Ivan actively in use that are not licensed under the BSD. arbiter Relax! :) All he said was most eggs are BSD. Currently Eggs Unlimited lists 202 eggs as BSD, which is more than half, so Elf's statement is true. Which is not to say BSD is better or more encouraged by Chicken in any way. /arbiter To get back to the point, eggs that simply list themselves as (L)GPL should specify the version. The listing on Eggs Unlimited is intended, I think, to refer to the general style of license, so just plain GPL may be fine there, but some may want to argue GPLv3 is sufficiently different to warrant separating. -- Alex ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On 14/02/2008, Ivan Raikov [EMAIL PROTECTED] wrote: By the way, if the egg licenses are an issue for any distribution, then one might consider the Debian approach -- if the license for a particular package is incompatible with Debian, in many cases this is dealt with by approaching the author(s) of that package and asking them if it would be possible to issue a Debian-only open-source compatible license for that package. The inconsistent licenses for the eggs don't matter with Chicken, because the Chicken itself is not distributed together with any eggs, but this might become an issue for a Linux distribution. Which is kind of, but not really, why I asked for clearer information on the website. We don't have license limitations on gentoo, but I still have to specify what license each package is under... since we're on the subject, exactly what version of the LGPL are 'awk' and 'make' under? Leo ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
a general question for the public, as this is the second time in three days where this has happened: when did 'most' start meaning 'all'? i missed that communique. -elf On Thu, 14 Feb 2008, Ivan Raikov wrote: Well, it is simply not true. Source code with a non-BSD license that gets imported as an egg does not magically become BSD-licensed. There are also many eggs that are actively in use that are not licensed under the BSD. For example, most of the prerequisites of svnwiki are licensed under the GPL. Your statements are a gross mischaracterization of the situation. The GPL/LGPL versioning is a separate issue, and I would say that most eggs released under that license fall under the default GPL category of v2 or later, except for the eggs I maintain, which are GPL v3 or later for all but one. By the way, if the egg licenses are an issue for any distribution, then one might consider the Debian approach -- if the license for a particular package is incompatible with Debian, in many cases this is dealt with by approaching the author(s) of that package and asking them if it would be possible to issue a Debian-only open-source compatible license for that package. The inconsistent licenses for the eggs don't matter with Chicken, because the Chicken itself is not distributed together with any eggs, but this might become an issue for a Linux distribution. -Ivan Elf [EMAIL PROTECTED] writes: i was only referring to currently maintained eggs, as i stated in the post, and only to those with (L)GPL licensing. all i SAID was that most currently maintained eggs are released under BSD, and how to find the licence revision for the LGPL eggs that have been ported from elsewhere. the LGPL ver is what seemed to matter from Leonadro's post, which is why that was the issue i responded to. precisely where am i spreading misinformation? ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Feb 13, 2008 8:46 PM, Leonardo Valeri Manera [EMAIL PROTECTED] wrote: We don't have license limitations on gentoo, but I still have to specify what license each package is under... since we're on the subject, exactly what version of the LGPL are 'awk' and 'make' under? They are under the GPL, not the LGPL. The versions on my machine are under GPL Version 2, but newer versions may be under Version 3. G ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
We don't have license limitations on gentoo, but I still have to specify what license each package is under... since we're on the subject, exactly what version of the LGPL are 'awk' and 'make' under? for make, whatever version of lgpl was active in 2002, like it says on the webpage (or would say on plt's site, id imagine). ditteaux for awk. for loop, v2, like it says on the wiki page. -elf ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
i didnt say ANYTHING about how anything SHOULD be, at any point. brief synopsis: leonardo asked about which licence versions were associated with eggs, focusing primarily on the gpled eggs in the repo, and asked about how to obtain information relating to versions where it wasnt obvious. i responded and said that most currently maintained eggs are bsd, except for yours. this was not a criticism, merely a statement of fact. i then suggested methods to find which licences were valid for which eggs. in what way was anyone saying anything about how eggs are contributed, requirements of contribution, how anything should be, or any form of restriction or change to the status quo? -elf On Thu, 14 Feb 2008, Ivan Raikov wrote: One of the aspects of Chicken that appeals to me is the relative freedom we have in contributing eggs. The lack of strict requirements about license, documentation, etc., perhaps mirrors the minimalistic nature of Scheme itself (or R5RS, I should say). When somebody starts making statements about how all or most eggs are this and that, or how all or most eggs should become this or that, I get annoyed, because I am rather fond of the creative chaos of Chicken. So let's not have stupid arguments about most and all, but remember to leave some breathing room for everyone in the Chicken community. -Ivan Elf [EMAIL PROTECTED] writes: a general question for the public, as this is the second time in three days where this has happened: when did 'most' start meaning 'all'? i missed that communique. -elf ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
One of the aspects of Chicken that appeals to me is the relative freedom we have in contributing eggs. The lack of strict requirements about license, documentation, etc., perhaps mirrors the minimalistic nature of Scheme itself (or R5RS, I should say). When somebody starts making statements about how all or most eggs are this and that, or how all or most eggs should become this or that, I get annoyed, because I am rather fond of the creative chaos of Chicken. So let's not have stupid arguments about most and all, but remember to leave some breathing room for everyone in the Chicken community. -Ivan Elf [EMAIL PROTECTED] writes: a general question for the public, as this is the second time in three days where this has happened: when did 'most' start meaning 'all'? i missed that communique. -elf ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Feb 13, 2008 9:01 PM, Elf [EMAIL PROTECTED] wrote: On Wed, 13 Feb 2008, Graham Fawcett wrote: On Feb 13, 2008 8:46 PM, Leonardo Valeri Manera [EMAIL PROTECTED] wrote: We don't have license limitations on gentoo, but I still have to specify what license each package is under... since we're on the subject, exactly what version of the LGPL are 'awk' and 'make' under? They are under the GPL, not the LGPL. The versions on my machine are under GPL Version 2, but newer versions may be under Version 3.' erm, graham, the eggs unlimited page says lgpl for both and plt itself is lgpl (or was) Hah! I thought Leonardo meant the GNU tools, 'awk' and 'make'! Thanks, Graham ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On 14/02/2008, Graham Fawcett [EMAIL PROTECTED] wrote: On Feb 13, 2008 8:46 PM, Leonardo Valeri Manera [EMAIL PROTECTED] wrote: We don't have license limitations on gentoo, but I still have to specify what license each package is under... since we're on the subject, exactly what version of the LGPL are 'awk' and 'make' under? They are under the GPL, not the LGPL. The versions on my machine are under GPL Version 2, but newer versions may be under Version 3. Good thing I asked then, because it says LGPL on eggs unlimited, and they don't even have the short version of the license at the bottom. Leo ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Wed, 13 Feb 2008, Graham Fawcett wrote: On Feb 13, 2008 8:46 PM, Leonardo Valeri Manera [EMAIL PROTECTED] wrote: We don't have license limitations on gentoo, but I still have to specify what license each package is under... since we're on the subject, exactly what version of the LGPL are 'awk' and 'make' under? They are under the GPL, not the LGPL. The versions on my machine are under GPL Version 2, but newer versions may be under Version 3.' erm, graham, the eggs unlimited page says lgpl for both and plt itself is lgpl (or was) -elf ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
Then I don't understand what you mean by the peculiar phrase currently maintained. There are many eggs in the Chicken repository that work perfectly fine and are not BSD licensed. If one of those is discovered to have become broken because of changes in the core Chicken functionality, then it will probably be fixed, maybe by the original author, maybe by someone who is familiar with Chicken, or maybe by a user interested in using that egg. Saying that most currently maintained eggs are BSD licensed sounds as if the Chicken project officially only supports BSD eggs, and that's not the case at all -- for instance, I will happily work on fixing bugs in any egg in the Chicken repository, except for the ones marked obsolete. If that is not is the meaning you intended, then what is the meaning of this currently maintained construct? -Ivan Elf [EMAIL PROTECTED] writes: i didnt say ANYTHING about how anything SHOULD be, at any point. brief synopsis: leonardo asked about which licence versions were associated with eggs, focusing primarily on the gpled eggs in the repo, and asked about how to obtain information relating to versions where it wasnt obvious. i responded and said that most currently maintained eggs are bsd, except for yours. this was not a criticism, merely a statement of fact. i then suggested methods to find which licences were valid for which eggs. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
That's true, I should have said that the different licenses might become an issue if you are distributing several eggs together. Though I am not overly worried about GPL violations in distributions of machine-generated C code, so that might be a sensible exception clause to add GPLed eggs. -Ivan John Cowan [EMAIL PROTECTED] writes: Not only that, but if you want to deliver an application in C form, you have to license the application as a whole under the GPL iff it incorporates any GPLed egg. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
Ivan Raikov scripsit: The inconsistent licenses for the eggs don't matter with Chicken, because the Chicken itself is not distributed together with any eggs, but this might become an issue for a Linux distribution. Not only that, but if you want to deliver an application in C form, you have to license the application as a whole under the GPL iff it incorporates any GPLed egg. -- Newbies always ask: John Cowan Elements or attributes? http://www.ccil.org/~cowan Which will serve me best? [EMAIL PROTECTED] Those who know roar like lions; Wise hackers smile like tigers. --a tanka, or extended haiku ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
Elf scripsit: to the best of my knowledge most of the currently maintained eggs are BSD licenced, not (L)GPLvN (except for Ivan's). since theyve mostly been ported from elsewhere, or are library bindings, it should be fairly easy to see the dates of creation or what the licence of the bound lib is... The q-lang egg is GPLv2 with upgrade option, because that's the license of Q. -- John Cowan [EMAIL PROTECTED] http://www.ccil.org/~cowan Any day you get all five woodpeckers is a good day. --Elliotte Rusty Harold ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
actually, at least by my understanding, GPL in this case is particularly interesting legally. while the 'do linked GPL libs make the linked programs derivative works' question is still unknown, this is an instance of GPL'ed libs being linked in only explicitly by the user so when one uses the GPLed code, does it make that instance of chicken GPLed? -elf On Thu, 14 Feb 2008, Ivan Raikov wrote: That's true, I should have said that the different licenses might become an issue if you are distributing several eggs together. Though I am not overly worried about GPL violations in distributions of machine-generated C code, so that might be a sensible exception clause to add GPLed eggs. -Ivan John Cowan [EMAIL PROTECTED] writes: Not only that, but if you want to deliver an application in C form, you have to license the application as a whole under the GPL iff it incorporates any GPLed egg. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
We /already had this/. In the distant mists of time, we had something called 'eggdoc' which could convert to svnwiki format and Texinfo for proper navigation. But it was too hard to use, and it made community participation more difficult. It is an evolutionary dead end. It was a good decision to move away from it and to the wiki, even at the cost of some features. [You can see the pdfs from every egg available at the time here. http://3e8.org/zb/eggs/eggdoc-texinfo/output/pdf/ ] Since then I've developed my own hybrid eggdoc/wiki markup which is approximately ten thousand times easier to deal with than eggdoc, while maintaining about the same semantic load. But really, who hasn't? Parsers and doc formats are a dime a dozen; it's the infrastructure that counts. On 2/12/08, Tobia Conforto [EMAIL PROTECTED] wrote: Graham Fawcett wrote: In our audience, a regular user might not be averse to editing a sexpr. I really like the wiki philosophy, but I confess I'd much rather do semantic markup with sexprs than somewhat arbitrary wiki tags. A semantically rich sexpr-based documentation format that could be updated with your text editor and committed through svn, following branches, tags, etc. Imagine an online (and partly offline) help system where every symbol is a hyperlink, every procedure is tagged by interest (so you may browse at all the lambdas that have something to do with ports, and then with threads, filter out some unwanted eggs...) No more drowning in the sea of SRFI and was this in extra or in posix? ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
JFYI, PLT Scheme is in the midst of a similar documentation overhaul. Depending on what you think about the current intermediate state, you might see things you want to do or things that you want to avoid. We're taking the docs source live with the library sources approach. We haven't yet tried to put documentation inside the source, much, though that's an expected future step. New docs (work in progress): http://docs.plt-scheme.org/ Follow the Scribble link to get more information on the doc system. Follow the first link in the main body of the Scribble doc to see what scribbled documentation source looks like. Matthew ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Feb 12, 2008 10:13 AM, Tobia Conforto [EMAIL PROTECTED] wrote: My idea is to devise a smart document format, preferably s-expr based (maybe SSAX-based if nothing better comes to mind) and convert every piece of Chicken API documentation to that format: both for eggs and for the base system. This includes any relevant SRFIs that are part of Chicken or of some eggs. I like the idea of being able to put the documentation into the code; something like Doxygen is needed for Scheme. I think it's not the first time such an idea has been proposed, but I don't know much about what has been tried. The trouble with systems like Doxygen and JavaDoc is having to parse comments, which ordinarily are ignored. And an S-expr method provides some potential for other algorithmic purposes beyond the documentation itself. (Ideas will suggest themselves once the potential is there, no doubt.) There could start to be a coding standard/consensus just as there is with JavaDoc and Doxygen, that you write a comment block for every function, describing what it does, the parameters, etc. The author of an egg is probably often the most qualified to write the documentation; or else a close collaborator could write it (within the code) and commit to Subversion, right? So from one side the editable wiki is handy for random users that see problems with the docs and can quickly contribute the corrections, but from another, how many edits are really being done there? and it doesn't feel right to have the documentation exist separate from the code. Then it's more likely for the two to be out-of-sync. Maybe when someone edits the wiki, diffs could be sent to the author, for later insertion into the next version of the egg. But I think the regular documentation should be inline with the code, because it helps to encourage the good habit of keeping it up-to-date every time one makes a change to the code. (Sorry if I'm just stating the obvious...) ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
Hi Graham and folks, On Tue, 12 Feb 2008 13:34:02 -0500 Graham Fawcett [EMAIL PROTECTED] wrote: On 12 Feb 2008 15:54:32 -0200, Mario Domenech Goulart [EMAIL PROTECTED] wrote: Hi Tobia, On Tue, 12 Feb 2008 18:37:36 +0100 Tobia Conforto [EMAIL PROTECTED] wrote: Mario Domenech Goulart wrote: Would it be integrated to the wiki system? How much and what kind of integration do we need? It would be nice if a regular user could edit the documentation like he/she would do with the current wiki system. In our audience, a regular user might not be averse to editing a sexpr. I really like the wiki philosophy, but I confess I'd much rather do semantic markup with sexprs than somewhat arbitrary wiki tags. I have good tools for navigating sexprs. ;-) Most developers are already working in the svn repo. I would be more inclined to edit my egg's wiki page in the repo, rather than through the Web interface. Given that, the wiki really becomes more of a place for comments and typographic corrections, which might be better suited to a formal comments section at the bottom of the egg's documentation page. Personally, I've never modified the documentation of someone else's egg; perhaps if I saw a typo, but even then I would contact the author, in case they kept the documentation in a secondary form. I think the wiki system has a great value and it is one of the reasons why chicken has such a rich documentation and a nice user base. There are other things besides documentation of eggs and chicken that are also on the wiki (e.g., tips and tricks, code snippets, users pages etc). Those pages are not necessarily edited by developers and are very important for the project. If we want non-developers to edit pages, they'd need an svn account. This would either be impractical (an svn account for each contributing user) or would be another barrier for contributions. Eliminating one way of editing chicken docs (i.e., via web-browser) doesn't add anything, but makes contributions more difficult and less practical. I do frequently use the web interface for editing the wiki, for example -- specially when I'm using a machine with no svn client (most computers have a web-browser) or I when I just don't want to checkout the wiki tree, open a text editor, commit etc. It's true that developers are able to edit and probably would feel more confortable editing sexprs, but unfortunately (as far as I know), svnwiki doesn't understand sexprs as input language. A simple solution for those who want to edit sexprs locally would be implementing a simple sexpr-wiki translator and use it to generate input files for svnwiki. It would be a nice egg, BTW (maybe an output format eggdoc could generate). Best wishes, Mario ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On 12 Feb 2008 15:54:32 -0200, Mario Domenech Goulart [EMAIL PROTECTED] wrote: Hi Tobia, On Tue, 12 Feb 2008 18:37:36 +0100 Tobia Conforto [EMAIL PROTECTED] wrote: Mario Domenech Goulart wrote: Would it be integrated to the wiki system? How much and what kind of integration do we need? It would be nice if a regular user could edit the documentation like he/she would do with the current wiki system. In our audience, a regular user might not be averse to editing a sexpr. I really like the wiki philosophy, but I confess I'd much rather do semantic markup with sexprs than somewhat arbitrary wiki tags. I have good tools for navigating sexprs. ;-) Most developers are already working in the svn repo. I would be more inclined to edit my egg's wiki page in the repo, rather than through the Web interface. Given that, the wiki really becomes more of a place for comments and typographic corrections, which might be better suited to a formal comments section at the bottom of the egg's documentation page. Personally, I've never modified the documentation of someone else's egg; perhaps if I saw a typo, but even then I would contact the author, in case they kept the documentation in a secondary form. G ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
Mario Domenech Goulart wrote: Would it be integrated to the wiki system? How much and what kind of integration do we need? Supposing we translate the parts of the Wiki that contain API and/or egg documentation to this format, we may (or may not) provide a web form to edit said semantic documentation format directly. We may require the api or reference parts to be written in this format, committed to svn, and used to generate the various compiled references, while leaving free-form tutorials and random pieces of documentation on the wiki. Tobia ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
Graham Fawcett wrote: In our audience, a regular user might not be averse to editing a sexpr. I really like the wiki philosophy, but I confess I'd much rather do semantic markup with sexprs than somewhat arbitrary wiki tags. I have good tools for navigating sexprs. ;-) Most developers are already working in the svn repo. I would be more inclined to edit my egg's wiki page in the repo, rather than through the Web interface. Given that, the wiki really becomes more of a place for comments and typographic corrections, which might be better suited to a formal comments section at the bottom of the egg's documentation page. Well said. This is exactly the spirit I was trying to express. A semantically rich sexpr-based documentation format that could be updated with your text editor and committed through svn, following branches, tags, etc. Imagine an online (and partly offline) help system where every symbol is a hyperlink, every procedure is tagged by interest (so you may browse at all the lambdas that have something to do with ports, and then with threads, filter out some unwanted eggs...) No more drowning in the sea of SRFI and was this in extra or in posix? Also, every page, both indexes and detail pages alike, would be browsable by Chicken version (svn branch, that is.) Was this there in the old times of 3.0? Was the API different? Every procedure and/or every egg might have a comment section at the bottom. All the rest of the documentation that's not strictly API reference (such as tips tricks, examples, users' pages, generic docs...) they can stay where they are, but we can make the wiki and the new hyperdoc as seamless as possible, with matching visual styles, the same site navigation and facilities for cross-linking. Tobia ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Tue, 12 Feb 2008 18:13:56 +0100 Tobia Conforto [EMAIL PROTECTED] wrote: Mario Domenech Goulart wrote: From a known format, we can convert the wiki documentation to whatever format we need and even have an interactive documentation system. The current problem with the wiki documentation is that we don't have semantic markup. This is a good time to talk about a similar idea I've been having for a while. My idea is to devise a smart document format, preferably s-expr based (maybe SSAX-based if nothing better comes to mind) and convert every piece of Chicken API documentation to that format: both for eggs and for the base system. This includes any relevant SRFIs that are part of Chicken or of some eggs. It's quite a lot of text, but it shouldn't be too hard, if you're armed with a good text editor and regexes. This should make it relatively easy to generate any kind of documentation from a single, versioned source tree: - static, heavy-hyperlinked html with full indexes by symbol, by permuted symbol, by topic (tags), by egg... - dynamic html documentation, aka. API search engine on the site - texi (or whatever it is... I'm a Vim user so I wouldn't know :-) I'm ready to start working on this, if we agree it's a good thing, and after we've discussed the s-expr file format. I'm still just a Chicken user (not a hacker) but this job is certainly within my reach! Would it be integrated to the wiki system? Best wishes, Mario ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
On Feb 12, 2008 1:28 PM, Mark Fredrickson [EMAIL PROTECTED] wrote: Perhaps before we decide where data should live, what format, etc, we should come up with a list of requirements that we want to meet? Here's my attempt at cataloging what I've heard so far: 4. Users should be able to update data via wiki system [2] I have the utmost respect for the wiki developers and maintainers. But having said that, I don't think we should include it as a formal requirement. If it fits, great; if it doesn't, let's find something that solves the problem. Your other points look solid, Mark. G ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] Comprehensive documentation rewrite
Hi Tobia, On Tue, 12 Feb 2008 18:37:36 +0100 Tobia Conforto [EMAIL PROTECTED] wrote: Mario Domenech Goulart wrote: Would it be integrated to the wiki system? How much and what kind of integration do we need? It would be nice if a regular user could edit the documentation like he/she would do with the current wiki system. Supposing we translate the parts of the Wiki that contain API and/or egg documentation to this format, we may (or may not) provide a web form to edit said semantic documentation format directly. We may require the api or reference parts to be written in this format, committed to svn, and used to generate the various compiled references, while leaving free-form tutorials and random pieces of documentation on the wiki. Wouldn't it be simpler to extend svnwiki so it can understand some special tags? Best wishes, Mario ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
[Chicken-users] Comprehensive documentation rewrite
Mario Domenech Goulart wrote: From a known format, we can convert the wiki documentation to whatever format we need and even have an interactive documentation system. The current problem with the wiki documentation is that we don't have semantic markup. This is a good time to talk about a similar idea I've been having for a while. My idea is to devise a smart document format, preferably s-expr based (maybe SSAX-based if nothing better comes to mind) and convert every piece of Chicken API documentation to that format: both for eggs and for the base system. This includes any relevant SRFIs that are part of Chicken or of some eggs. It's quite a lot of text, but it shouldn't be too hard, if you're armed with a good text editor and regexes. This should make it relatively easy to generate any kind of documentation from a single, versioned source tree: - static, heavy-hyperlinked html with full indexes by symbol, by permuted symbol, by topic (tags), by egg... - dynamic html documentation, aka. API search engine on the site - texi (or whatever it is... I'm a Vim user so I wouldn't know :-) I'm ready to start working on this, if we agree it's a good thing, and after we've discussed the s-expr file format. I'm still just a Chicken user (not a hacker) but this job is certainly within my reach! Tobia ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
