[Chicken-users] egg documentation

[Graham Fawcett]

Ivan raised a good point on the Hackathon1 page (where he asks that
people don't move his egg documentation out of the egg and into the
wiki, because it's a pain to deal with eggs that don't have a copy of
their docs in the egg directory itself).

It's good to have the wiki docs, and especially so with Toby's
excellent callcc.org site as a search interface. But it doesn't
address "local" documentation very well. We've done some work on
wiki->texi conversion, which is good, but it's not integrated with
chicken-setup in any way, and that's a drawback.

One can imagine pushing local docs into the wiki upon releasing a new
egg version; or adding an "include" mechanism to the wiki to pull in
external docs (though that would make search-indexing harder if not
done properly). Since the wiki is stored in the svn repository, there
are opportunities for svn-commit hooks to do some of the work, as well
as opportunities for a decent inclusion mechanism.

Before we venture too far into 'wikifying' all of the egg
documentation, if that's a hackathon goal, we should probably ensure
that we have a consistent documentation plan that ensures a local copy
of the docs is preserved in some form.

Personally, I'd love to have texi documentation, and (optionally) have
chicken-setup do the necessary work to pull egg docs into the 'info'
system. I'd never have to leave Emacs to look something up, and that
would (for me) be more efficient than keeping a callcc.org browser
open.

Graham

[Mario Domenech Goulart]

Hi Graham and folks,

Post by Graham Fawcett
Ivan raised a good point on the Hackathon1 page (where he asks that
people don't move his egg documentation out of the egg and into the
wiki, because it's a pain to deal with eggs that don't have a copy of
their docs in the egg directory itself).
It's good to have the wiki docs, and especially so with Toby's
excellent callcc.org site as a search interface. But it doesn't
address "local" documentation very well. We've done some work on
wiki->texi conversion, which is good, but it's not integrated with
chicken-setup in any way, and that's a drawback.
One can imagine pushing local docs into the wiki upon releasing a new
egg version; or adding an "include" mechanism to the wiki to pull in
external docs (though that would make search-indexing harder if not
done properly). Since the wiki is stored in the svn repository, there
are opportunities for svn-commit hooks to do some of the work, as well
as opportunities for a decent inclusion mechanism.
Before we venture too far into 'wikifying' all of the egg
documentation, if that's a hackathon goal, we should probably ensure
that we have a consistent documentation plan that ensures a local copy
of the docs is preserved in some form.
Personally, I'd love to have texi documentation, and (optionally) have
chicken-setup do the necessary work to pull egg docs into the 'info'
system. I'd never have to leave Emacs to look something up, and that
would (for me) be more efficient than keeping a callcc.org browser
open.

I think the best alternative would be having svnwiki tags to markup
chicken docs (which is possible).

Something like:

<procedure name="foo" args="bar baz" retval="string">
<description>This is foo</description>
</procedure>

[Mark Fredrickson]

This idea dove tails with discussion last week of providing docstrings
for lambdas. Felix pointed out that there is a hook to capture lambda
documentation. Will this work for documenting eggs, which might also
have data types, parameters, other info?

Texi seems like a reasonable standard to me, FWIW.

Cheers,
-M

Post by Mario Domenech Goulart
I think the best alternative would be having svnwiki tags to markup
chicken docs (which is possible).
<procedure name="foo" args="bar baz" retval="string">
<description>This is foo</description>
</procedure>

[Mario Domenech Goulart]

Hi Mark,

Post by Mark Fredrickson
This idea dove tails with discussion last week of providing docstrings
for lambdas. Felix pointed out that there is a hook to capture lambda
documentation. Will this work for documenting eggs, which might also
have data types, parameters, other info?

I'm not sure if that's a good way to provide full documentation for
eggs and chicken.

One of the problems I see is that there are other types of objects
besides lambdas.

The full documentation for eggs and chicken itself is more than the
documentation of procedures and other objects. There are examples,
authors, license sections etc, which are not source code.

I'm afraid merging two sources of documentation (from source code
files and, I guess, manually written doc files) can lead to confusion
and "kludgeness".

Best wishes,
Mario

[Peter Bex]

Post by Mario Domenech Goulart
Hi Mark,

Post by Mark Fredrickson
This idea dove tails with discussion last week of providing docstrings
for lambdas. Felix pointed out that there is a hook to capture lambda
documentation. Will this work for documenting eggs, which might also
have data types, parameters, other info?

I'm not sure if that's a good way to provide full documentation for
eggs and chicken.

I don't think so either.

Post by Mario Domenech Goulart
One of the problems I see is that there are other types of objects
besides lambdas.

Another problem is that docstrings are very limited in what you can put
in them. If you cram a tutorial in them, the source becomes unreadable
and if you keep it brief, where do you put the other docs?

Another thing is that docstrings are even less semantically rich than
the wiki. They're just plain text, no way to hyperref ('see also'),
no way to refer to arguments/function names etc.

If you have semantically rich content you could do really cool stuff
like making a context-sensitive help like you see in some modern IDEs
for other languages etc.

Post by Mario Domenech Goulart
The full documentation for eggs and chicken itself is more than the
documentation of procedures and other objects. There are examples,
authors, license sections etc, which are not source code.

Yep, that too.

Post by Mario Domenech Goulart
I'm afraid merging two sources of documentation (from source code
files and, I guess, manually written doc files) can lead to confusion
and "kludgeness".

I'm afraid of that too.

Cheers,
Peter

[Shawn Rutledge]

Post by Peter Bex

Post by Mario Domenech Goulart
One of the problems I see is that there are other types of objects
besides lambdas.

Everything should be able to have documentation comments (by which I
mean S-exprs), not just lambdas.

Post by Peter Bex
Another problem is that docstrings are very limited in what you can put
in them. If you cram a tutorial in them, the source becomes unreadable
and if you keep it brief, where do you put the other docs?

What's wrong with having longer docs be separate? What about coming
up with a consensus on a path where such docs will be stored, so that
within the documentation comments (which are part of the code) it's
possible to make links to stuff like that? e.g. (see (href
"eggs/myegg/tutorial")) would be analogous to a Doxygen @see
directive. When the doc comments (s-exprs) are parsed and the real
documentation is generated (HTML and whatever other forms) the links
can be translated to full paths or relative paths, whatever works.
And installing an egg should install the real documentation to a known
path like /usr/share/doc/chicken/eggs/myegg. If all the documentation
were in one place like that, we would not be needing to use the online
documentation so much, and it would be possible to work without a
network connection sometimes. (No doubt the bandwidth on callcc.org
is much higher than it needs to be, just because of the lack of this.)
A local index should be built too, or a local full-text search engine
could be used, so that the search feature of the wiki is also
replicated on every Chicken installation. Until we get around to that
part, it would at least be possible to make do with whatever your
usual local search engine is (Beagle, hyperestraier, swish++,
mnogosearch etc.) Linux machines often have Apache configured so that
http://localhost/doc goes to /usr/share/doc anyway. Some of them have
search engines set up for local documentation already, too.

[Tobia Conforto]

Mario Domenech Goulart wrote:

[Mario Domenech Goulart]

[Tobia Conforto]

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

[Mario Domenech Goulart]

Hi Tobia,

Post by Tobia Conforto

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.

Post by Tobia Conforto
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

[Mark Fredrickson]

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:

0. Data should not be duplicated. Duplicated data will get out of
date, fork, etc.
1. Data should be easy to translate into different formats
(potentially wiki, texi, SXML, HTML, man pages, others) [1]
2. Data should be available off-line.
3. Data should come with egg.
4. Users should be able to update data via wiki system [2]
5. Data should apply to more than just lambdas/procedures
6. Presentation of data (at least online) should be consistent

[1] For each format F, this requirement implies a mapping from data D
-> F. Do we also need a mapping from F -> D, so that if a user changes
F the original data can be updated?

[2] I think this is related to [1]. If we change the wiki (a
representation) does the original data change? Also, there are some
permissions and branching issues here if the document data is stored
in the egg. E.g. should all users get to update the wiki
documentation? Is the wiki branched such that documentation changes in
one branch do not inappropriately change other branches?

---

Other requirements?
-Mark

[Graham Fawcett]

Post by Mark Fredrickson
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?
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

[Graham Fawcett]

On 12 Feb 2008 15:54:32 -0200, Mario Domenech Goulart

Post by Mario Domenech Goulart
Hi Tobia,

Post by Tobia Conforto

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

[Mario Domenech Goulart]

Hi Graham and folks,

Post by Graham Fawcett
On 12 Feb 2008 15:54:32 -0200, Mario Domenech Goulart

Post by Mario Domenech Goulart
Hi Tobia,

Post by Tobia Conforto

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

[Tobia Conforto]

Post by Graham Fawcett
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

[Jim Ursetto]

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.

Post by Tobia Conforto

Post by Graham Fawcett
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?

[Shawn Rutledge]

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...)

[Matthew Flatt]

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

[felix winkelmann]

Post by Shawn Rutledge

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

[Peter Bex]

Post by felix winkelmann

Post by Shawn Rutledge
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.

Post by felix winkelmann
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.

Post by felix winkelmann
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.

Post by felix winkelmann
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

[felix winkelmann]

Post by Peter Bex
Docs are hard to maintain and code is hard to maintain when you stick them
all in one big pile.

Absolutely.

Post by Peter Bex

Post by felix winkelmann
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

[Shawn Rutledge]

Post by Peter Bex
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...)

Post by Peter Bex

Post by felix winkelmann
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".

[Elf]

On Wed, 13 Feb 2008, Shawn Rutledge wrote:
<snip>

Post by Shawn Rutledge

Post by Peter Bex
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

[Shawn Rutledge]

Post by Elf
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.

Post by Elf
i dont know where the idea that
anyone was proposing a be-all-and-end-all of documentation systems came from,

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.

[Elf]

Post by Kon Lovett
<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

[Leonardo Valeri Manera]

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

[Elf]

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

Post by Leonardo Valeri Manera
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

[Ivan Raikov]

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

Post by Elf
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]

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

Post by Ivan Raikov
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

Post by Elf
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...

[Ivan Raikov]

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

Post by Elf
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?

[Alex Shinn]

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.

[Leonardo Valeri Manera]

Post by Ivan Raikov
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

[Graham Fawcett]

On Feb 13, 2008 8:46 PM, Leonardo Valeri Manera

Post by Leonardo Valeri Manera
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

[Leonardo Valeri Manera]

Post by Graham Fawcett
On Feb 13, 2008 8:46 PM, Leonardo Valeri Manera

Post by Leonardo Valeri Manera
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

[Elf]

Post by Graham Fawcett
On Feb 13, 2008 8:46 PM, Leonardo Valeri Manera

Post by Leonardo Valeri Manera
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

[Graham Fawcett]

Post by Elf

Post by Graham Fawcett
On Feb 13, 2008 8:46 PM, Leonardo Valeri Manera

Post by Leonardo Valeri Manera
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

[Elf]

Post by Leonardo Valeri Manera
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

[Elf]

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

Post by Ivan Raikov
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

Post by Elf
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?

[Ivan Raikov]

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

Post by Elf
a general question for the public, as this is the second time in
when did 'most' start meaning 'all'? i missed that communique.
-elf

[Elf]

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

Post by Ivan Raikov
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

Post by Elf
a general question for the public, as this is the second time in
when did 'most' start meaning 'all'? i missed that communique.
-elf

[Ivan Raikov]

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

Post by Elf
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.

[Elf]

Post by Ivan Raikov
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.

ah. all that was meant by 'currently maintained' is that they were created
specifically for chicken and have new releases or enhancements periodically.
i was merely intending to distinguish the active chicken codebase from
artifacts ported over from PLT etc. (not to impugn them or their value
in any way, just to mark generations, so to speak.) this is why i referenced
you as the exception, since you actively release new original eggs with GPL.
it was not intended in any sort of derogatory or critical way.

Post by Ivan Raikov
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?

i was not, in any way, shape, form, or manner, trying to suggest or imply
any form of policy, theory of use, desirable state, restriction, set of
actions, preferences, goals, or any matter relating to chicken's development,
developers, or users. i was only trying to offer assistance to a specific
question on how to find licence versions. my apologies if this was not
the perception.

-elf

[John Cowan]

Post by Ivan Raikov
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.

[Ivan Raikov]

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

Post by John Cowan
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.

[Elf]

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

Post by Ivan Raikov
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

Post by John Cowan
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.

[John Cowan]

Post by Ivan Raikov
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.

[Ivan Raikov]

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

Post by John Cowan
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]

Post by Elf
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.

[Shawn Rutledge]

Post by felix winkelmann
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.

Post by felix winkelmann
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.

Post by felix winkelmann
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.)

Post by felix winkelmann
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)

[Ozzi]

This is perhaps a different concern, but I wonder if there would be value in
designating certain eggs as "part of" Chicken, and holding these eggs to a
stricter standard of documentation.

For example, most (all?) of the SRFIs could be considered canon. I'd imagine
Spiffy would as well, along with many other eggs.

Something like ode, a "numerical solver framework for systems of first-order
differential equations", on the other hand, probably wouldn't.

This distinction would allow us to dictate, for example, that all documentation
for the eggs which are a part of Chicken has to be written in a certain style
and available in a certain place, without messing with libraries that are made
available as eggs but aren't really designed as a part of Chicken itself.



Oz

Post by Graham Fawcett
Ivan raised a good point on the Hackathon1 page (where he asks that
people don't move his egg documentation out of the egg and into the
wiki, because it's a pain to deal with eggs that don't have a copy of
their docs in the egg directory itself).
It's good to have the wiki docs, and especially so with Toby's
excellent callcc.org site as a search interface. But it doesn't
address "local" documentation very well. We've done some work on
wiki->texi conversion, which is good, but it's not integrated with
chicken-setup in any way, and that's a drawback.
One can imagine pushing local docs into the wiki upon releasing a new
egg version; or adding an "include" mechanism to the wiki to pull in
external docs (though that would make search-indexing harder if not
done properly). Since the wiki is stored in the svn repository, there
are opportunities for svn-commit hooks to do some of the work, as well
as opportunities for a decent inclusion mechanism.
Before we venture too far into 'wikifying' all of the egg
documentation, if that's a hackathon goal, we should probably ensure
that we have a consistent documentation plan that ensures a local copy
of the docs is preserved in some form.
Personally, I'd love to have texi documentation, and (optionally) have
chicken-setup do the necessary work to pull egg docs into the 'info'
system. I'd never have to leave Emacs to look something up, and that
would (for me) be more efficient than keeping a callcc.org browser
open.
Graham
_______________________________________________
Chicken-users mailing list
http://lists.nongnu.org/mailman/listinfo/chicken-users

[Peter Bex]

Post by Ozzi
This is perhaps a different concern, but I wonder if there would be value in
designating certain eggs as "part of" Chicken, and holding these eggs to a
stricter standard of documentation.

Why do you want to make a distinction?

The whole point of the note on the wiki was that we need _one_ documentation
system. The current system sucks, because you keep switching interfaces.
Say you're looking for some documentation, so you search using the wiki
system. However, the docs you're looking for happen to be written in eggdoc
or the legacy HTML documentation. Besides not being able to search these
docs, when you visit them, you go to another site and you lose the
navigational tools you get in the wiki.

Visually it's also confusing, because the three docs look different. This
last point might sound trivial, but I'm sure when a potential new user is
browsing for a new scheme implementation, he's might get scared away just
because he has no idea why some docs are on this site, some on that and why
they look and act differently. I know Chicken is a "hacker's scheme", but
there's no point in alienating people.

So, to conclude, I don't mind _what_ we're going to do, as long as it's
consistent and pleasant to use (both as doc author and reader).

Cheers,
Peter

[Ozzi]

Post by Peter Bex
The whole point of the note on the wiki was that we need _one_ documentation
system. The current system sucks, because you keep switching interfaces.
Say you're looking for some documentation, so you search using the wiki
system. However, the docs you're looking for happen to be written in eggdoc
or the legacy HTML documentation. Besides not being able to search these
docs, when you visit them, you go to another site and you lose the
navigational tools you get in the wiki.

Fair enough. I agree that one method would be best.

Post by Peter Bex
Visually it's also confusing, because the three docs look different. This
last point might sound trivial, but I'm sure when a potential new user is
browsing for a new scheme implementation, he's might get scared away just
because he has no idea why some docs are on this site, some on that and why
they look and act differently. I know Chicken is a "hacker's scheme", but
there's no point in alienating people.

This I agree with 100%. I still haven't figured out why Chicken seems to be
spread across three different sites.

http://galinha.ucpel.tche.br
http://chicken.wiki.br
http://www.call-with-current-continuation.org/

Post by Peter Bex
Why do you want to make a distinction?

The idea I was trying to get at was something like a "standard library" for
Chicken. When I go to the "Eggs Unlimited" page right now, there are lots and
lots of eggs, which is great, except there's no easy way to tell what's
standard-issue Scheming and what's more exotic stuff.

It would be great if there were a set of eggs that were considered to be a
standard part of Chicken, to help people who haven't been writing Scheme code
for years get oriented. Python and Ruby have lots of standard functionality
built in, but with Chicken you have to hunt down each egg you need. I think a
standard library of sorts would help.

I also believe it would help to focus development. If a consensus could be
reached as to what kind of functionality should be included in a reasonably
complete standard library for a useful language, then we could easily go about
implementing that functionality. A standard library would provide a smaller
target than the current wide-open universe of eggs.

So these are my ideas, and I'll admit they probably don't have much to do with
documentation per se, but that's just what happened to convince me to write them
down.

[Ivan Raikov]

There is no such thing as a "standard library" for Scheme, other
than what is defined in the R5RS standard. And there is no such thing
as "standard-issue" Scheming other than perhaps the idioms of
functional programming. R5RS Scheme was deliberately designed to be
minimalistic, in contrast with Perl, Python, and company. Which is why
there are tons of Scheme implementations to choose from, and only one
"canonical" implementation of Python. If you want a language with a
bloated "standard library", then you use Python. If you want a
language that doesn't suck, then you use Scheme. It took me only three
weeks to go from hacking in Standard ML to writing my first Chicken
Scheme egg, and I found the egg library to be rather
well-organized. And I chose Chicken Scheme precisely because of the
vast number of eggs available. So I don't understand why on earth you
want to limit everyone's choices, because you can't be bothered to
spend a couple of weeks reading some books and doing some code
exercises in Scheme.

-Ivan

Post by Ozzi
The idea I was trying to get at was something like a "standard
library" for Chicken. When I go to the "Eggs Unlimited" page right
now, there are lots and lots of eggs, which is great, except there's
no easy way to tell what's standard-issue Scheming and what's more
exotic stuff.
It would be great if there were a set of eggs that were considered to
be a standard part of Chicken, to help people who haven't been writing
Scheme code for years get oriented. Python and Ruby have lots of
standard functionality built in, but with Chicken you have to hunt
down each egg you need. I think a standard library of sorts would
help.
I also believe it would help to focus development. If a consensus
could be reached as to what kind of functionality should be included
in a reasonably complete standard library for a useful language, then
we could easily go about implementing that functionality. A standard
library would provide a smaller target than the current wide-open
universe of eggs.

[John Cowan]

Post by Ivan Raikov
There is no such thing as a "standard library" for Scheme, other
than what is defined in the R5RS standard.

True for R5RS Scheme. But for Chicken in particular, the "units" are
de facto a standard library, since the compiler relies on much of them.
Right now all the eggs are effectively second-class as a consequence of
the way they are packaged, but some of them, like syntax-case and numbers,
are actually necessary to get R5RS support, so it's kind of arbitrary.

I'd rather see units and eggs treated as on a par, and the distinction
drawn between community-supported, author-supported, and unsupported
packages.

[Ivan Raikov]

That's a good idea. I like the distinction of community-supported
vs. single-author-supported eggs. Something along those lines that
could probably be done easily is to extend chicken-setup to support
egg popularity counts. Each time chicken-setup is invoked to install
an egg from the main Chicken page, the popularity count for that egg
is increased, so that people can see which are the most commonly used
eggs. This could also help with testing new releases of Chicken,
because we would know which are the most important eggs to test.

-Ivan

Post by John Cowan
I'd rather see units and eggs treated as on a par, and the
distinction drawn between community-supported, author-supported, and
unsupported packages.

[felix winkelmann]

Post by John Cowan

Post by Ivan Raikov
There is no such thing as a "standard library" for Scheme, other
than what is defined in the R5RS standard.

True for R5RS Scheme. But for Chicken in particular, the "units" are
de facto a standard library, since the compiler relies on much of them.
Right now all the eggs are effectively second-class as a consequence of
the way they are packaged, but some of them, like syntax-case and numbers,
are actually necessary to get R5RS support, so it's kind of arbitrary.
I'd rather see units and eggs treated as on a par, and the distinction
drawn between community-supported, author-supported, and unsupported
packages.

Chicken is oriented towards being minimal and to externalize all
extra functionality. What's included in the base system is only the
stuff that is needed to run the compiler. Everything else should not
be part of the base.


cheers,
felix

[john]

and for using Chicken on small devices this is a great selling point!

cheers,

John.

Post by felix winkelmann
Chicken is oriented towards being minimal and to externalize all
extra functionality. What's included in the base system is only the
stuff that is needed to run the compiler. Everything else should not
be part of the base.
cheers,
felix
_______________________________________________
Chicken-users mailing list
http://lists.nongnu.org/mailman/listinfo/chicken-users

[Daishi Kato]

At Tue, 12 Feb 2008 22:46:54 -0500,

Post by John Cowan
I'd rather see units and eggs treated as on a par, and the distinction
drawn between community-supported, author-supported, and unsupported
packages.

This might work, but isn't it hard to say something is community-supported?
How about "Development Status" in sourceforge.net?

--daishi

[Mario Domenech Goulart]

I still haven't figured out why Chicken seems to be spread across
three different sites.
http://galinha.ucpel.tche.br
http://chicken.wiki.br
http://www.call-with-current-continuation.org/

galinha.ucpel.tche.br and chicken.wiki.br are the same machine.
galinha.ucpel.tche.br came first (since the ucpel.tche.br already
existed). chicken.wiki.br was bought later.

call/cc.org is the official chicken site and it is very limited
regarding to resources. That's why it's not used for, say, the wiki
system.

Best wishes,
Mario

[John Cowan]

Post by Mario Domenech Goulart
call/cc.org is the official chicken site and it is very limited
regarding to resources. That's why it's not used for, say, the wiki
system.

That is, call-with-current-continuation.org. There is also callcc.org,
a fourth domain name.

[Mario Domenech Goulart]

Post by John Cowan

Post by Mario Domenech Goulart
call/cc.org is the official chicken site and it is very limited
regarding to resources. That's why it's not used for, say, the wiki
system.

That is, call-with-current-continuation.org. There is also callcc.org,
a fourth domain name.

Ah, yes. Thanks for noticing it, John (and sorry for not mentioning
it before, Toby).

callcc.org (different from call/cc.org, an informal abbreviation for
www.call-with-current-continuation.org) is kindly mantained by Toby
Butzon.

This domain is also used for the chicken bugtracking system
(http://trac.callcc.org), maintained by Arto Bendiken.

Best wishes,
Mario

[Elf]

Post by John Cowan
--
You are a child of the universe no less John Cowan
than the trees and all other acyclic http://www.ccil.org/~cowan
--DeXiderata by Sean McGrath

go placidly amidst the noise and mailing lists, and remember what peace there
may be in writing code that needs no other documentation.

-elf

[Alejandro Forero Cuervo]

Post by Ozzi
This I agree with 100%. I still haven't figured out why Chicken seems to be
spread across three different sites.
http://galinha.ucpel.tche.br
http://chicken.wiki.br
http://www.call-with-current-continuation.org/

It should be noted that two of these are exactly the same, there's
really no difference at all (chicken.wiki.br was added later as an
alias and we haven't got rid of referenced to the old name).

Alejo.
http://azul.freaks-unidos.net/

[felix winkelmann]

Post by Peter Bex

Post by Ozzi
This is perhaps a different concern, but I wonder if there would be value in
designating certain eggs as "part of" Chicken, and holding these eggs to a
stricter standard of documentation.

Why do you want to make a distinction?
The whole point of the note on the wiki was that we need _one_ documentation
system. The current system sucks, because you keep switching interfaces.
Say you're looking for some documentation, so you search using the wiki
system. However, the docs you're looking for happen to be written in eggdoc
or the legacy HTML documentation. Besides not being able to search these
docs, when you visit them, you go to another site and you lose the
navigational tools you get in the wiki.

Note that all documentation for installed eggs can be found in HTML
format in $PREFIX/lib/chicken/3/index.html. That's about as easy as
it can get.


cheers,
felix

[Elf]

putting in my two cents (sorry for the delay, i didnt read the list today yet)
...
i am working on a documentation system to replace eggdocs, straight-wiki, and
chicken-man simultaneously. this is not to say or imply in any way that there
wont be web files on callcc! the goal of the system is to be able to generate
the documentation for chicken in any form, searchable via net or within the
interpreter or as a pdf or texi or WHATEVER, while enforcing some consistency
in presentation. this will (hopefully) make it easier to a) document both
eggs and core, b) keep the documentation up to date, c) reduce duplication of
effort, and d) reduce the learning curve. this is NOT a replacement for the
wiki, however; certain things can and SHOULD be wikiised.

a full (semi)formal specification will follow, hopefully later tonight. the
specification is intended as an rfc, not as an elf-says-so-its-set-in-stone,
obviously.

-elf

Post by Graham Fawcett
Ivan raised a good point on the Hackathon1 page (where he asks that
people don't move his egg documentation out of the egg and into the
wiki, because it's a pain to deal with eggs that don't have a copy of
their docs in the egg directory itself).
It's good to have the wiki docs, and especially so with Toby's
excellent callcc.org site as a search interface. But it doesn't
address "local" documentation very well. We've done some work on
wiki->texi conversion, which is good, but it's not integrated with
chicken-setup in any way, and that's a drawback.
One can imagine pushing local docs into the wiki upon releasing a new
egg version; or adding an "include" mechanism to the wiki to pull in
external docs (though that would make search-indexing harder if not
done properly). Since the wiki is stored in the svn repository, there
are opportunities for svn-commit hooks to do some of the work, as well
as opportunities for a decent inclusion mechanism.
Before we venture too far into 'wikifying' all of the egg
documentation, if that's a hackathon goal, we should probably ensure
that we have a consistent documentation plan that ensures a local copy
of the docs is preserved in some form.
Personally, I'd love to have texi documentation, and (optionally) have
chicken-setup do the necessary work to pull egg docs into the 'info'
system. I'd never have to leave Emacs to look something up, and that
would (for me) be more efficient than keeping a callcc.org browser
open.
Graham
_______________________________________________
Chicken-users mailing list
http://lists.nongnu.org/mailman/listinfo/chicken-users

[Ivan Raikov]

I don't understand why is everyone trying to come up with the Mother
of all Documentation Systems all the time. For the time being, can't
we just agree on having two documentation standards for Chicken: wiki
(for simple documentation) and eggdoc (for complex documentation with
examples, tutorials, etc.). Then we could gradually add eggdoc-like
markup to stream-wiki to the point where it would be easy to write a
script that automatically converts eggdoc to wiki. Of course, this
still doesn't solve the problem with not having the documentation
available in the SVN repository. So any automatic operation on the
repository, such as building Debian packages for the eggs cannot work
without manual intervention. Unless someone has a very clear and
detailed idea about to deal with this, I will ask you to defer
grandiose ideas about converting all documentation in the world to the
ultimate and bestest format.

-Ivan

Post by Elf
putting in my two cents (sorry for the delay, i didnt read the list today yet)
...
i am working on a documentation system to replace eggdocs, straight-wiki, and
chicken-man simultaneously. this is not to say or imply in any way that there
wont be web files on callcc! the goal of the system is to be able to generate
the documentation for chicken in any form, searchable via net or within the
interpreter or as a pdf or texi or WHATEVER, while enforcing some consistency
in presentation. this will (hopefully) make it easier to a) document
both eggs and core, b) keep the documentation up to date, c) reduce
duplication of effort, and d) reduce the learning curve. this is NOT
a replacement for the
wiki, however; certain things can and SHOULD be wikiised.
a full (semi)formal specification will follow, hopefully later tonight. the
specification is intended as an rfc, not as an elf-says-so-its-set-in-stone,
obviously.
-elf

[Elf]

i wasnt going for the Mother of All Documentation systems. this has just been
one of the primary things ive been thinking about for around a month, mostly
due to chicken-man being entirely worthless. the ability to convert between
formats is trivial. the hard bit has been to figure out what primitives
would be useful and what sorts of constraints to impose.

-elf

Post by Ivan Raikov
I don't understand why is everyone trying to come up with the Mother
of all Documentation Systems all the time. For the time being, can't
we just agree on having two documentation standards for Chicken: wiki
(for simple documentation) and eggdoc (for complex documentation with
examples, tutorials, etc.). Then we could gradually add eggdoc-like
markup to stream-wiki to the point where it would be easy to write a
script that automatically converts eggdoc to wiki. Of course, this
still doesn't solve the problem with not having the documentation
available in the SVN repository. So any automatic operation on the
repository, such as building Debian packages for the eggs cannot work
without manual intervention. Unless someone has a very clear and
detailed idea about to deal with this, I will ask you to defer
grandiose ideas about converting all documentation in the world to the
ultimate and bestest format.
-Ivan

Post by Elf
putting in my two cents (sorry for the delay, i didnt read the list today yet)
...
i am working on a documentation system to replace eggdocs, straight-wiki, and
chicken-man simultaneously. this is not to say or imply in any way that there
wont be web files on callcc! the goal of the system is to be able to generate
the documentation for chicken in any form, searchable via net or within the
interpreter or as a pdf or texi or WHATEVER, while enforcing some consistency
in presentation. this will (hopefully) make it easier to a) document
both eggs and core, b) keep the documentation up to date, c) reduce
duplication of effort, and d) reduce the learning curve. this is NOT
a replacement for the
wiki, however; certain things can and SHOULD be wikiised.
a full (semi)formal specification will follow, hopefully later tonight. the
specification is intended as an rfc, not as an elf-says-so-its-set-in-stone,
obviously.
-elf

[Kon Lovett]

Post by Ivan Raikov
I don't understand why is everyone trying to come up with the Mother
of all Documentation Systems all the time. For the time being, can't
we just agree on having two documentation standards for Chicken: wiki
(for simple documentation) and eggdoc (for complex documentation with
examples, tutorials, etc.).

Don't forget a 3rd, raw html. A few eggs have this for hysterical
reasons; ex: coerce, uri, testbase.

<snip>

Post by Ivan Raikov
_______________________________________________
Chicken-users mailing list
http://lists.nongnu.org/mailman/listinfo/chicken-users

Best Wishes,
Kon

[Raymond Medeiros]

what about something similar to rdoc, inline comments in your code
that get parsed out to generate documentation:

chicken-doc -to-wiki openssl.egg-dir
chicken-doc -to-pdf openssl.egg-dir

etc...?

Post by Kon Lovett

Post by Ivan Raikov
I don't understand why is everyone trying to come up with the Mother
of all Documentation Systems all the time. For the time being, can't
we just agree on having two documentation standards for Chicken: wiki
(for simple documentation) and eggdoc (for complex documentation with
examples, tutorials, etc.).

Don't forget a 3rd, raw html. A few eggs have this for hysterical
reasons; ex: coerce, uri, testbase.
<snip>

Post by Ivan Raikov
_______________________________________________
Chicken-users mailing list
http://lists.nongnu.org/mailman/listinfo/chicken-users

Best Wishes,
Kon
_______________________________________________
Chicken-users mailing list
http://lists.nongnu.org/mailman/listinfo/chicken-users

[Ivan Raikov]

Well, there is already mole, but nobody seems to use that. Actually,
I tried using it for my very first attempt at creating an egg, but the
markup mole supports was quite limited. In general, as much as I
admire Donald Knuth and everything he has done for computer science,
most attempts at literate programming seem to result in almost
unreadable code and documentation that is difficult to maintain.

-Ivan

Post by Raymond Medeiros
what about something similar to rdoc, inline comments in your code
chicken-doc -to-wiki openssl.egg-dir
chicken-doc -to-pdf openssl.egg-dir
etc...?

[raymond medeiros]

basically i was thinking about exactly what rdoc does ( i haven't used
mole )
look at rdoc. but then adding the ability to generate wiki code and
import it
into the svn wiki, and also the ability to generate various formats
like pdf's,
html etc...

another idea was, in your egg:

myegg.wiki

which would contain the wiki page, and get imported into svn wiki.
that way the maintainer has local control over the document,
but it gets automatically imported into the wiki. so you can
edit it with VIM or EMACS check it in, and when the egg gets
built it updates the appropriate wiki page, entering a new
revision using the committers credentials.

just my $0.02 in Au

Post by Ivan Raikov
Well, there is already mole, but nobody seems to use that. Actually,
I tried using it for my very first attempt at creating an egg, but the
markup mole supports was quite limited. In general, as much as I
admire Donald Knuth and everything he has done for computer science,
most attempts at literate programming seem to result in almost
unreadable code and documentation that is difficult to maintain.
-Ivan

Post by Raymond Medeiros
what about something similar to rdoc, inline comments in your code
chicken-doc -to-wiki openssl.egg-dir
chicken-doc -to-pdf openssl.egg-dir
etc...?

[Ivan Raikov]

I will look at rdoc, but you should look at mole :-) I think mole
follows a similar pattern, but the output formats are perhaps more
limited. As for the second idea, it is okay with me, but a long time
ago I wrote a proposal about incorporating eggdoc-like markup in
svnwiki, and nothing happened, so I am not holding my breath.

-Ivan

Post by raymond medeiros
basically i was thinking about exactly what rdoc does ( i haven't
used mole ) look at rdoc. but then adding the ability to generate
wiki code and import it into the svn wiki, and also the ability to
generate various formats like pdf's, html etc...
myegg.wiki
which would contain the wiki page, and get imported into svn wiki.
that way the maintainer has local control over the document,
but it gets automatically imported into the wiki. so you can
edit it with VIM or EMACS check it in, and when the egg gets
built it updates the appropriate wiki page, entering a new
revision using the committers credentials.

[raymond medeiros]

I was thinking that myegg.wiki would be the literal markup that svn
wiki uses.
but instead of having to navigate to a page and cut and paste your
updates
into a tiny text box, you could edit them in vim and the egg builder
would
automatically commit a revision to the wiki.

Post by Ivan Raikov
I will look at rdoc, but you should look at mole :-) I think mole
follows a similar pattern, but the output formats are perhaps more
limited. As for the second idea, it is okay with me, but a long time
ago I wrote a proposal about incorporating eggdoc-like markup in
svnwiki, and nothing happened, so I am not holding my breath.
-Ivan

Post by raymond medeiros
basically i was thinking about exactly what rdoc does ( i haven't
used mole ) look at rdoc. but then adding the ability to generate
wiki code and import it into the svn wiki, and also the ability to
generate various formats like pdf's, html etc...
myegg.wiki
which would contain the wiki page, and get imported into svn wiki.
that way the maintainer has local control over the document,
but it gets automatically imported into the wiki. so you can
edit it with VIM or EMACS check it in, and when the egg gets
built it updates the appropriate wiki page, entering a new
revision using the committers credentials.

[Ivan Raikov]

Well, unfortunately the wiki markup is much more limited compared to
the eggdoc markup -- and I want to automate the process of converting
from eggdoc to wiki as much as possible. So ideally, I would have some
extensions to stream-wiki to annotate procedures, type declarations,
etc. As of right now, I find the basic wiki syntax to be too spartan
for egg documentation.

-Ivan

Post by raymond medeiros
I was thinking that myegg.wiki would be the literal markup that svn
wiki uses. but instead of having to navigate to a page and cut and
paste your updates into a tiny text box, you could edit them in vim
and the egg builder would automatically commit a revision to the
wiki.

[Alejandro Forero Cuervo]

Then we could gradually add eggdoc-like markup to stream-wiki to the
point where it would be easy to write a script that automatically
converts eggdoc to wiki. Of course, this still doesn't solve the
problem with not having the documentation available in the SVN
repository. So any automatic operation on the repository, such as
building Debian packages for the eggs cannot work without manual
intervention.

I'm not sure I understand what the problem here is. Could you
explain?

Alejo.
http://azul.freaks-unidos.net/

[Ivan Raikov]

Well, I've been thinking about it, and perhaps it will be sufficient
to have a tool that translates from eggdoc to wiki syntax along the
lines of the following example. I would like to have fixed section
names and some code in the wiki that checks that all of the required
sections are present in the page. Also, it is not clear to me how to
convert eggdoc procedure, macro, and symbol-table formatting elements
to wiki format.


== Name
digraph

== Description
Directed graph in adjacency list format

== Author
...

== History

* Version 1.1 ...
* Version 1.0 Initial release

== Requires

[dyn-vector.html|dyn-vector]

== Usage
<code>(require-extension digraph)</code>

== Download
[digraph.egg|digraph.egg]

== Documentation

The digraph library is an implementation of a directed graph, where
the edges are stored as adjacency lists.

=== Directed graph procedures

The digraph object is created by procedure <code>make-digraph</code>,
which is the only user-visible procedure defined in this egg:

; Procedure: <code>make-digraph:: NAME INFO [NODE-LIST [SUCC-LIST [PRED-LIST]]] -> SELECTOR</code>

The returned selector procedure can take one of the following arguments:

; Describe name: returns the graph name (string or symbol)
; describe info: returns the graph metadata (arbitrary type)


== Examples
<pre>
;; example adapted from graph example in the Boost library documentation
(require-extension srfi-1)
(require-extension digraph)
(define g (make-digraph 'depgraph "dependency graph"))
</pre>

== License

...

Post by Alejandro Forero Cuervo
I'm not sure I understand what the problem here is. Could you
explain?
Alejo.
http://azul.freaks-unidos.net/

[Jim Ursetto]

Also, it is not clear to me how to convert ... symbol-table formatting
elements to wiki format.

Ivan,

The symbol-table is essentially a nod to aesthetics--it just alters the
appearance of the table (mainly, the 'symbol' column is monospaced).

The eggdoc-svnwiki egg translates symbol-table elements to
<table class="symbol-table">...</table>. Although svnwiki currently
ignores class elements, it might not in the future. In the meantime,
you just get a proportional font in the left column.

You can see the result by checking any wiki document that was translated
with eggdoc->svnwiki, e.g. http://chicken.wiki.br/objc .

[Ivan Raikov]

Oh, okay, this looks pretty good. Not as pretty as the original
eggdoc, but it will do. I will try converting some of my docs with
eggdoc-svnwiki this weekend, thanks.

-Ivan

Post by Jim Ursetto
Ivan,
The symbol-table is essentially a nod to aesthetics--it just alters the
appearance of the table (mainly, the 'symbol' column is monospaced).
The eggdoc-svnwiki egg translates symbol-table elements to
<table class="symbol-table">...</table>. Although svnwiki currently
ignores class elements, it might not in the future. In the meantime,
you just get a proportional font in the left column.
You can see the result by checking any wiki document that was translated
with eggdoc->svnwiki, e.g. http://chicken.wiki.br/objc .

[Jim Ursetto]

I'll also update eggdoc-svnwiki with the new <proc> syntax (or whatever final
form it takes) once that gets put in the wiki.

And in that vein:

The four types of definitions in eggdoc are "procedure",
"macro", "record" and "parameter", with an extra "signature" type which
is used when you want to name a new (uncommon) definition type.

In creating texinfo output, it became necessary to introduce a "read-syntax"
tag as well, to avoid confusing the Scheme expression parser (read) -- the
contents of this are used verbatim rather than running (read) to pick it apart.
(Although it's in eggdoc-texinfo, apparently 'read-syntax' was never added to
eggdoc. Oops.)

The parser also checks anything using a "signature" type for a name beginning
with "read" -- e.g. read-syntax, read syntax, reader macro -- and avoids
calling (read) on that too. This allows backwards compatibility with old
eggdocs and allows the author a little naming flexibility.

So ultimately, I think something like the following tags would be useful:

<proc>(string-set! a b)</proc>
<macro>(args:make-option (OPTION-NAME ...) ARG-DATA [BODY])</macro>
<record>hostinfo</record>
<param>eggdoc:doctype</param>
<read>@[object message: value ...]</read>
<signature type="string">doctype:xhtml-1.0-strict</signature>

Names subject to change. Thoughts?

Post by Ivan Raikov
Oh, okay, this looks pretty good. Not as pretty as the original
eggdoc, but it will do. I will try converting some of my docs with
eggdoc-svnwiki this weekend, thanks.

[Alejandro Forero Cuervo]

Thanks for the list! :-)

Post by Jim Ursetto
<proc>(string-set! a b)</proc>

Alright, I will simply expand this to:

[procedure] {{('''string-set!''' a b)}}

Post by Jim Ursetto
<macro>(args:make-option (OPTION-NAME ...) ARG-DATA [BODY])</macro>

I'll expand this to the same as the above, but with “macro” instead of
“procedure”.

Post by Jim Ursetto
<param>eggdoc:doctype</param>

Is this meant to be used as in “The procedure sets the contents of the
string <param>a</param> to a copy of the contents of
<param>b</param>”? In this case I don't think we should support it.
I think it makes things way too verbose for what it gets us. The
crucial thing to remember is that we want a compromise between having
some semantics and still making it easy for anyone to edit this code.

Post by Jim Ursetto
<record>hostinfo</record>
<signature type="string">doctype:xhtml-1.0-strict</signature>

Care to give me an example as to how these are used and what you think
they should expand to? I'm not completely sure I understand their
semantics.

Alejo.
http://azul.freaks-unidos.net/

[Jim Ursetto]

<proc> and <macro> look good. The wiki pages use either
'''procedure:''' (proc a b) or
[procedure] (proc a b)

depending on the author, so the rendering is up to you.

Post by Jim Ursetto
<param>eggdoc:doctype</param>

Is this meant to be used as in "The procedure sets the contents of the
string <param>a</param> to a copy of the contents of
<param>b</param>"?

No. To define a SRFI-39 parameter. It would expand to
[parameter] '''eggdoc:doctype'''

according to your expansion of proc/macro. For parameters
a procedure syntax should be accepted as well, e.g.
<param>(eggdoc:doctype TYPE)</param>.

Post by Jim Ursetto
<record>hostinfo</record>
<signature type="string">doctype:xhtml-1.0-strict</signature>

Care to give me an example as to how these are used and what you think
they should expand to? I'm not completely sure I understand their
semantics.

Same thing. Semantics are they introduce a definition, not that they
are used whenever this type is encountered in the text.
Check out any of the existing eggs, such as objc:

<read>@[RECEIVER KEYWORD ARGUMENT ...]</read>
'''read-syntax:''' @[RECEIVER KEYWORD ARGUMENT ...]

<record>objc:instance</record>
'''record:''' objc:instance

<signature type="string">doctype:xhtml-1.0-strict</signature>
'''string:''' doctype:xhtml-1.0-strict

This is so that symbols/variables other than procedures and macros
can be automatically indexed. Compare @deffn / @defmac / @defspec
/ @defvr / @defvar in Texinfo, which serve a similar purpose.
In other words, these tags are 'definition commands'.

[Alejandro Forero Cuervo]

Post by Jim Ursetto
<proc> and <macro> look good. The wiki pages use either
'''procedure:''' (proc a b) or
[procedure] (proc a b)
depending on the author, so the rendering is up to you.

Alright. I suppose I'll highlight the procedure name and make sure it
gets typeset in monospaced font, as:

[procedure] {{('''proc''' a b)}}

Based on your description, param, read, record and signature sound
worth supporting as well.

(My secret plan is to eventually sneak in support for some
<implementation>...</implementation> tags along with the <examples>
and perhaps <test> tags and then reorganize some of my eggs as wiki
pages from which the scm files are generated, but please don't tell
anyone!)

Alejo, Literate Programming Fan
http://azul.freaks-unidos.net/

[Tobia Conforto]

Post by Alejandro Forero Cuervo
My secret plan is to eventually sneak in support for some
<implementation>...</implementation> tags along with the <examples>
and perhaps <test> tags and then reorganize some of my eggs as wiki
pages from which the scm files are generated

The horror! :-)


Tobia

[Jim Ursetto]

Alright. I suppose I'll highlight the procedure name and make sure it
[procedure] {{('''proc''' a b)}}

I would like it if that line were wrapped in a <div> e.g.
<div class="definition">...</div> so that it can be styled via CSS
with borders, a background, or something. (Like the current ones,
which have a background/border that comes from <pre>.)

Span tags, e.g. <span class="type">[procedure]</span> and
<span class="signature">(proc a b)</signature> would probably
be nice but not as important as the <div>.

[Alejandro Forero Cuervo]

Post by Jim Ursetto

Alright. I suppose I'll highlight the procedure name and make sure it
[procedure] {{('''proc''' a b)}}

I would like it if that line were wrapped in a <div> e.g.
<div class="definition">...</div> so that it can be styled via CSS
with borders, a background, or something. (Like the current ones,
which have a background/border that comes from <pre>.)
Span tags, e.g. <span class="type">[procedure]</span> and
<span class="signature">(proc a b)</signature> would probably
be nice but not as important as the <div>.

Good thinking.

Alejo.
http://azul.freaks-unidos.net/

[Jim Ursetto]

Post by Jim Ursetto
<signature type="string">doctype:xhtml-1.0-strict</signature>

Thinking about this a little more, it strikes me that
"definition" or "def" is probably a better tag than "signature".
So:

<def type="string">doctype:xhtml-1.0-strict</def>

for unusual definitions we don't provide a built-in tag for.

You could really replace every definition tag like this, e.g.
<def type="macro">(receive args expr body)</def>

however, I think providing a few specific tags like we
discussed looks nicer. I'll leave the verdict on that
to the group.

[Alejandro Forero Cuervo]

Post by Jim Ursetto

Post by Jim Ursetto
<signature type="string">doctype:xhtml-1.0-strict</signature>

Thinking about this a little more, it strikes me that
"definition" or "def" is probably a better tag than "signature".
<def type="string">doctype:xhtml-1.0-strict</def>
for unusual definitions we don't provide a built-in tag for.
You could really replace every definition tag like this, e.g.
<def type="macro">(receive args expr body)</def>
however, I think providing a few specific tags like we
discussed looks nicer. I'll leave the verdict on that
to the group.

Heh, this discussion is kinda similar to the Common Lisp versus Scheme
discussion of whether different namespaces should be used for
different types of things or there should be only one namespace. :-P

I think we should stick to <proc>, <macro> and so on. They are easier
to type than <def type="proc">, <def type="macro"> and so on. The
fact that their associated rendering logic is very similar is not
relevant.

What if instead of <signature type="string"> and <def type="string">
we simply use <string>? Would that work?

Alejo.
http://azul.freaks-unidos.net/

[Alejandro Forero Cuervo]

Post by Graham Fawcett
Ivan raised a good point on the Hackathon1 page (where he asks that
people don't move his egg documentation out of the egg and into the
wiki, because it's a pain to deal with eggs that don't have a copy of
their docs in the egg directory itself).

I'm not sure I understand the problem here, so I'll share *my* vision
of how documentation for eggs should be handled in the ideal world.

Documentation for egg foobar should live in the chicken-eggs
repository, in wiki/foobar, in wiki format with some extensions for
including semantics. By this I mean wiki syntax using tags such as
<procedure> ... </procedure>, from where some semantics can be
extracted by other tools. I oppose using XML or some similar format
(eg. s-expr based format) on the basis that this would make it harder
for our users to modify. Raising the bar required for editing, even
if only slightly, can greatly reduce the number of contributions.

Documentation for eggs should not leave in the eggs' directories.
Instead, eggs should use the doc-from-wiki tag in their meta, so when
the egg gets created the latest version of the documentation gets
pulled from the wiki.

Documentation in the wiki should be generated from previous eggdoc
files only once. When that has happened and the documentation has
been imported to the wiki, that should be considered the live version.
Regenerating the stuff in the wiki from eggdocs in the future clashes
against the spirit of encouraging users to help developers improve the
documentation.

Documentation should only live in one place: the wiki (with some
additional semantics). HTML pages will be included with eggs if this
happens, eggs authors can modify their documentation with their
favorite editors and users can contribute and help improve it.

The only piece I see missing right now is that documentation can't be
posted to the wiki in a semanticly rich way from which other tools can
easily extract meaning. I will probably work on that.

Can you explain to me why it is a pain for some to deal with eggs that
don't have a copy of their docs in the egg directory itself?

Alejo.
http://azul.freaks-unidos.net/

[Alejandro Forero Cuervo]

Post by Alejandro Forero Cuervo
The only piece I see missing right now is that documentation can't be
posted to the wiki in a semanticly rich way from which other tools can
easily extract meaning. I will probably work on that.

Seeing that this has been just around the corner for months, I decided
to cross said corner today and start doing something about it. I have

Post by Alejandro Forero Cuervo
=== stream-xcons
<procedure name="stream-xcons" args="a b" returns="stream">
Of utility only as a value to be conveniently passed to higher-order
procedures.
<examples>
<expr>(stream-xcons (stream 'b 'c) 'a)</expr>
<result>#<stream (a b c)></result>
<expr>(stream-xcons (stream 2 3 4) 1)</expr>
<result>#<stream 1 2 3 4></result>
</examples>
The name stands for "eXchanged CONS."
</procedure>

The output can be seen, obviously, in:

http://galinha.ucpel.tche.br:8080/stream-ext#stream-xcons

You can see the code that supports this in
stream-wiki/trunk/extensions/chicken.scm. I would invite others to
define new syntactic constructions by extending that file and sending
patches (please do not commit directly to it) as a reply sent to the
list to this mail so that we can all comment on the new proposals.

Thanks.

Alejo.
http://azul.freaks-unidos.net/

[Jim Ursetto]

Just a comment: in eggdoc the name of the procedure / syntax etc. is taken as a
plain string -- e.g. "(stream-xcons a b)". For HTML output, it is used
verbatim. For texinfo output, which has special directives to mark functions,
this input is deconstructed into procedure name and arguments using (read), if
possible. (See eggdoc-texinfo for more.)

For example, <procedure sig="(stream-xcons a b)"> ... </procedure>.

This could be considered a design flaw in eggdoc, as the semantics have to
be reconstructed. But it was easier to type and didn't matter for HTML.

I think your proposal is fine, as any XML-based solution is going to
be verbose no matter what.

Post by Alejandro Forero Cuervo
<procedure name="stream-xcons" args="a b" returns="stream">
Of utility only as a value to be conveniently passed to higher-order
procedures.
The name stands for "eXchanged CONS."
</procedure>