[Chicken-users] egg documentation with subpages
Hi, It is now possible to break up egg documentation into several pages. This was previously possible on the wiki, but is now supported by chicken-doc as well. Procedure: instead of creating a file, create a directory and populate it with subpage files. To document the main page, call the page index. Example: allegro/color allegro/display allegro/index chicken-doc-admin supports directories and will automatically recurse. It also works with the host-installed eggs option. Notes: - You should probably create at least a stub index file because otherwise the main page will 404. - It's a good idea to place links to the subpages on the main page. chickadee will automatically pick up subpages and place them in the contents bar, but the wiki will not. - All subpages are considered eggs, which means: - It may confuse users who expect each doc page to correspond to exactly one egg, unit or module -- there is no allegro color egg for example. - Subpages will show up in a chicken-doc identifier or egg search, which may be confusing or annoying. There may eventually need to be a way to tag a page as something other than an egg for chicken-doc, but that doesn't exist yet. Jim ___ Chicken-users mailing list Chicken-users@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation with subpages
Nice! I didn't realize chicken-doc-admin was even a thing, and this ability should make updating docs much easier to do. When next I get around to updating the allegro egg from 5.06 to 5.09 and fixing the library discovery bug I'll see about also switching over to using this to manage the documentation. Thanks! -Dan On 4/15/2013 3:41 PM, Jim Ursetto wrote: Hi, It is now possible to break up egg documentation into several pages. This was previously possible on the wiki, but is now supported by chicken-doc as well. Procedure: instead of creating a file, create a directory and populate it with subpage files. To document the main page, call the page index. Example: allegro/color allegro/display allegro/index chicken-doc-admin supports directories and will automatically recurse. It also works with the host-installed eggs option. Notes: - You should probably create at least a stub index file because otherwise the main page will 404. - It's a good idea to place links to the subpages on the main page. chickadee will automatically pick up subpages and place them in the contents bar, but the wiki will not. - All subpages are considered eggs, which means: - It may confuse users who expect each doc page to correspond to exactly one egg, unit or module -- there is no allegro color egg for example. - Subpages will show up in a chicken-doc identifier or egg search, which may be confusing or annoying. There may eventually need to be a way to tag a page as something other than an egg for chicken-doc, but that doesn't exist yet. Jim ___ Chicken-users mailing list Chicken-users@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-users ___ Chicken-users mailing list Chicken-users@nongnu.org https://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On 2008 Feb 21, at 23:57, Alejandro Forero Cuervo wrote: As such, I will need more convincing before implementing support for indexentry. I don't see what it adds that we can't already do. Ok, I see that it would allow arbitrary pages to declare sub-topics of a given topic, but I don't think that should be supported. I fully agree that much of the indexing can be done automatically, but a good index also includes entries that can't be generated automatically. Again, taking my append example, we might be documenting SRFI-1, in which case we might want concatenate to have an index entry for append. Truthfully, the indexing facility is going to be more useful for the Chicken manual itself, but I do think that a complicated egg might also benefit from it. As for bold-facing entries, sometimes that can be done from section headings, but sometimes that isn't practical. Consider documenting the tinyclos egg, where you might find that the main index entry for `method resolution order' may or may not be in a section with that name. These entries would just be written to a file, and external code would then process them to produce index pages or whatever. I think an index of the entire wiki would be way too big to be useful. If there's interest in this, I could generate it. Keep in mind that the wiki currently has 300+ files. Ulp. That requires more thought on my part. Again, I was mostly thinking in terms of an index database for the manual, or for a small locally- developed set of eggs. Perhaps Alejandro's database of `where symbols in the wiki are documented' could also be added to this external file? I like this idea. I'll probably do it. :-) Thanks for the suggestions, Vincent. My pleasure! -- v ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
What if instead of signature type=string and def type=string we simply use string? Would that work? Functionally yes, but I can only think of one person who has ever used 'string' in an egg: myself. In my opinion, the def tag should be there for really unusual cases such as that, since we can't think of every type of definition. Check out the sqlite3-tinyclos doc for another example; Thomas thought up 'class' and 'method', which were not in eggdoc. (The 'signature' type was put in eggdoc for just that case.) I still think def is useful for unusual or unimplemented definitions, unless you really want to restrict people to a few major definition types (or update svnwiki every time someone thinks of a new one). I think this wouldn't be very hard to do, since they would all behave pretty much in the same way. We can probably just keep a list with them (ie. '(string class method)) that we add to as needed. That is, I think you're assuming that adding new ones is hard, and I'm just letting you know that nah, once everything is in place, it would be rather easy. :-) So I'll add support for string, class and method. Does that sound good to you? Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On Thu, Feb 21, 2008 at 12:42:00AM -0800, Alejandro Forero Cuervo wrote: I think this wouldn't be very hard to do, since they would all behave pretty much in the same way. We can probably just keep a list with them (ie. '(string class method)) that we add to as needed. That is, I think you're assuming that adding new ones is hard, and I'm just letting you know that nah, once everything is in place, it would be rather easy. :-) So I'll add support for string, class and method. Does that sound good to you? I'm losing sight of the changes a bit. Could you please update the wiki-syntax doc so we have something to work with for the hackathon? Cheers, Peter -- http://sjamaan.ath.cx -- The process of preparing programs for a digital computer is especially attractive, not only because it can be economically and scientifically rewarding, but also because it can be an aesthetic experience much like composing poetry or music. -- Donald Knuth pgpph12y3m89V.pgp Description: PGP signature ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
So, will the stream-wiki egg be updated accordingly? The post-commit stuff does a wiki-html conversion, so we have to get access to the new markup. This will be done by adding code to the chicken.scm file (which is already used by the post-commit stuff for the chickenegg tag. Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
Alejandro Forero Cuervo wrote: I've created this document: http://chicken.wiki.br/wiki-syntax-chicken Note that I've expanded proc and param to procedure and parameter respectively. I've also added a bit more details about how to include examples. I expect to automatically build a page including all the examples and whether or not they pass. Suggestions would be appreciated. :-) Great! What about the topics= attribute we discussed a few days ago? It could be described as available on all those: procedure, macro... and also on a top-level tag for egg pages. Is that going to be chickenegg, or did I misundestand its purpose? I think that if there's interest for such a feature (automatic indexes by topic--and it would seem there is) we'd better define the syntax and a list of basic topics up front. Tobia ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On Thu, Feb 21, 2008 at 1:55 PM, Alejandro Forero Cuervo [EMAIL PROTECTED] wrote: Given the following SQL table: CREATE TABLE symbols ( symbol varchar, file varchar, line integer ); could someone create a function that receives (1) a base path containing a checkout of the chicken-eggs svn repository, (2) a path to some file inside the repository and (3) a sqlite3 database with said table and, if the file is a Scheme file outside of the wiki, adds one entry to the table for each symbol defined? Is that possible, given that reading the Scheme file may require custom syntax? As a subcase, if a record type is defined, do you list all the record getter and setter procs (e.g. post-macro-expansion) or just the define-record (pre-expansion)? At least define-record is standard syntax; if an egg uses custom syntax, it may be impossible to tell whether there are any definitions at all; or worse, it may contain numerous internal definitions that should not be exposed in an index. Just a thought, G ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
Sorry, forgot to answer some of your questions: (wiki-db-update-symbols! db-file base-path file-path) - boolean Would the absolute file pathname be (make-pathname base-path file- path)? Yes. The file column is what? An absolute pathname, a relative pathname, a filename w/ extension, a filename w/o extension? A pathname corresponding to the paths inside the chicken-eggs svn repository, with extension, such as /stream-ext/trunk/stream-cons.scm. Basically, it is just the file-path passed to your function. Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On Thu, Feb 21, 2008 at 3:09 PM, Kon Lovett [EMAIL PROTECTED] wrote: Some day, we might want to offer an alternate way of marking which procs should be indexed, or providing a formal exports list, like the (declare ) form but for interpreted files as well. That would cover the cases where automated indexing is intractable. But yes, 50% is a good target for a first attempt. It should get 100% of the global symbols. What I can't do reliably is get the define syntax forms. The expanded syntax that defines global symbols though is caught. Might it not turn up global symbols that weren't intended for public visibility, though? Perhaps well-designed eggs shouldn't do that, but it could happen in the wild. (/me jumps to the egg repo to see how well-designed his eggs are...) Perhaps this isn't a problem, if the use-case is to provide a search facility. But I think that preparing a good index might take more care (as good indexes always do). Graham 'Flattering to the author, insulting to the reader, she said. In a hyphenated word, she said with the shrewd amiability of an expert, self-indulgent. I'm always embarrassed when I see an index an author has made of his own work. It's a revealing thing... a shameless exhibition' -- Claire Minton, in Vonnegut's 'Cat's Cradle', on why one should never index one's own book. ;-) ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On 2008 Feb 21, at 03:38, Alejandro Forero Cuervo wrote:
Sure, good thinking. I've created this document:
http://chicken.wiki.br/wiki-syntax-chicken
...
Suggestions would be appreciated. :-)
The page is much appreciated, and I now have a much better vision of
how the markup is
going.
I hesitate to bring it up again, but can we please have some kind of
indexing markup?
I agree that much of the indexing can be done automatically from the
procedure and
similar tags, but, especially if we're going to use the new markup for
the CHICKEN
manual, custom index entries will be absolutely necessary.
Here's my suggested syntax, keeping it XML-compliant:
indexentry major=List procedures [minor={{append}}]
[bold=yes|no] [see=other topic]/
where the major and minor attributes refer to the major and minor
levels of the
index entry, bold indicates whether the current page number shall be
boldfaced
(representing a definition of the topic and see replaces the page
number with
its operand, for `see also' type entries).
These entries would just be written to a file, and external code would
then process
them to produce index pages or whatever.
Perhaps Alejandro's database of `where symbols in the wiki are
documented' could
also be added to this external file?
Thanks for considering this! -- v
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
Here's my suggested syntax, keeping it XML-compliant:
indexentry major=List procedures [minor={{append}}]
[bold=yes|no] [see=other topic]/
Hmm, I think this would be very redundant with the following syntax,
which not only is already support, I also find easier to type:
== List procedures
...
=== Append
...
As for the “bold” part, I think whether a title for a section is shown
as bold or not should probably depend on its level in the hierarchy
(eg. all ==, === and titles (corresponding to h2, h3 and
h4) should be bold, the rest shouldn't). I'm not sure I understand
the “see=other topic” functionality so I can't really comment on it,
but I believe it could be provided with other features already present
in the wiki.
Titles in a page can be automatically assembled from this, as
exemplified here:
http://chicken.wiki.br/stream-ext
As such, I will need more convincing before implementing support for
indexentry. I don't see what it adds that we can't already do. Ok,
I see that it would allow arbitrary pages to declare sub-topics of a
given topic, but I don't think that should be supported.
These entries would just be written to a file, and external code
would then process them to produce index pages or whatever.
I think an index of the entire wiki would be way too big to be useful.
If there's interest in this, I could generate it. Keep in mind that
the wiki currently has 300+ files.
Perhaps Alejandro's database of `where symbols in the wiki are
documented' could also be added to this external file?
I like this idea. I'll probably do it. :-)
Thanks for the suggestions, Vincent.
Alejo.
http://azul.freaks-unidos.net/
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On 2/19/08, Alejandro Forero Cuervo [EMAIL PROTECTED] wrote:
Alright. I suppose I'll highlight the procedure name and make sure it
gets typeset in monospaced font, as:
[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.
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On 2/19/08, Jim Ursetto [EMAIL PROTECTED] wrote: signature type=stringdoctype: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=stringdoctype: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. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On 2/19/08, Jim Ursetto [EMAIL PROTECTED] wrote: signature type=stringdoctype: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=stringdoctype: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/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On 2/19/08, Alejandro Forero Cuervo [EMAIL PROTECTED] wrote:
Alright. I suppose I'll highlight the procedure name and make sure it
gets typeset in monospaced font, as:
[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/
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
So ultimately, I think something like the following tags would be useful:
Thanks for the list! :-)
proc(string-set! a b)/proc
Alright, I will simply expand this to:
[procedure] {{('''string-set!''' a b)}}
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”.
parameggdoc:doctype/param
Is this meant to be used as in “The procedure sets the contents of the
string parama/param to a copy of the contents of
paramb/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.
recordhostinfo/record
read@[object message: value ...]/read
signature type=stringdoctype: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/
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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. On 2/19/08, Alejandro Forero Cuervo [EMAIL PROTECTED] wrote: parameggdoc:doctype/param Is this meant to be used as in The procedure sets the contents of the string parama/param to a copy of the contents of paramb/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. recordhostinfo/record signature type=stringdoctype: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 ...] recordobjc:instance/record '''record:''' objc:instance signature type=stringdoctype: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'. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
By the way, on the subject of wiki markup, I'd like to put in a plug for marking index entries. Hmm, what do you mean? Alejo, a bit slow today. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 Jim Ursetto [EMAIL PROTECTED] writes: 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 . ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 recordhostinfo/record parameggdoc:doctype/param read@[object message: value ...]/read signature type=stringdoctype:xhtml-1.0-strict/signature Names subject to change. Thoughts? On 2/18/08, Ivan Raikov [EMAIL PROTECTED] wrote: 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. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 codemake-digraph/code, which is the only user-visible procedure defined in this egg: ; Procedure: codemake-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 ... Alejandro Forero Cuervo [EMAIL PROTECTED] writes: I'm not sure I understand what the problem here is. Could you explain? Alejo. http://azul.freaks-unidos.net/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 the following in wiki/stream-ext: === 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/ ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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. On 2/17/08, Alejandro Forero Cuervo [EMAIL PROTECTED] wrote: 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 ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
I forgot to mention: if you accept a plain string you can also slim down the overall representation considerably. In the example below, some will remark that you've no longer wrapped the procedure description in a tag. However, any reasonable parser should be able to reconstruct this information heuristically--after all, we don't require the user to wrap entire wiki sections in tags; we simply reconstruct where they end. Off the top of my head, you could terminate reading the procedure description at the next procedure or section tag. In my opinion, moving the smarts to the parser reduces the burden on the user quite a bit, with little semantic loss. For example: proc(stream-xcons a b)/proc Of utility only as a value to be conveniently passed to higher-order procedures. proc(stream-cons* a b)/proc Like stream, but the last argument provides the tail of the constructed stream, returning: ... On 2/17/08, Jim Ursetto [EMAIL PROTECTED] wrote: For example, procedure sig=(stream-xcons a b) ... /procedure. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On 2/17/08, Ivan Raikov [EMAIL PROTECTED] wrote: 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 . ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
In the example below,
some will remark that you've no longer wrapped the procedure
description in a tag. However, any reasonable parser should be able
to reconstruct this information heuristically--after all, we don't
require the user to wrap entire wiki sections in tags; we simply
reconstruct where they end.
I think you've touched on a crucial aspect of this, specially by your
use of the word “heuristically”. Clearly, we are not looking for an
XML-based (or, equivalently, an s-expr based) format, but some
compromise between the goals of (1) being very easy to edit and (2)
containing semantics that can be extracted by other tools.
In practice, I expect to use drivers (in the stream-wiki definition of
“drivers”) to programatically extract meaning (such as a
wiki-procedures function, receiving a wiki page and returning a list
(stream) of all the procedures defined on it).
I like your example. I will add a bit to it:
proc(+ a b ...)/proc
Adds two or more values.
Examples:
example
labelAdd 3 numbers together/label
expr(+ 1 2 3)/expor
result6/result
/example
example
labelSimple example of adding two numbers/label
expr(+ 4 5)/expr
result9/result
/example
proc(string-append a b ...)/proc
...
Examples:
example
labelSimple example of appending two strings./label
expr(string-append foo bar)/expr
resultfoobar/result
/example
...
example
labelSimple example of the use of {{~A}} escape sequences./label
init(use format-modular)/init
expr
(format #t There are ~A objects. 10)
/expr
outputportThere are 10 objects./outputport
/example
Note that with just a bit of glue (a driver similar to the
wiki-procedures I described above) we would very easily be able to
extract the information from the examples and turn it into unit tests,
so users adding examples to the documentation would actually be
defining user tests and we could programatically get notified when we
break one of the examples in our documentation. We could also create
wiki pages to contain nothing but tests like these and encourage users
to submit new tests to them (of course, the person running the tests
would need to validate the logs/diffs or use sandboxes). This is
something I find very exciting.
Care to add more to my example above? I'll probably implement
something like this during the next weekend or so.
Alejo.
http://azul.freaks-unidos.net/
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
The problem is that the .html files generated from the wiki files are not present in the repository. So any scripts that traverse the egg directories and do stuff with the eggs would not have the _rendered_ documentation accessible. For example, I want to be able to run a script that builds Debian packages for each egg that has a debian subdirectory. So that script either needs to be able to run the wiki-html script that is used to create the egg, or the generated .html file needs to reside somewhere in the repository. -Ivan Alejandro Forero Cuervo [EMAIL PROTECTED] writes: 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. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On Feb 12, 2008 7:16 PM, Peter Bex [EMAIL PROTECTED] wrote: On Tue, Feb 12, 2008 at 11:10:28AM -0600, Ozzi wrote: 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 ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On Feb 13, 2008 4:46 AM, John Cowan [EMAIL PROTECTED] wrote: Ivan Raikov scripsit: 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 ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
and for using Chicken on small devices this is a great selling point! cheers, John. On 13/02/2008, felix winkelmann [EMAIL PROTECTED] wrote: 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 Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
At Tue, 12 Feb 2008 22:46:54 -0500, John Cowan wrote: 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 ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On Tue, Feb 12, 2008 at 11:10:28AM -0600, Ozzi wrote: 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 -- http://sjamaan.ath.cx -- The process of preparing programs for a digital computer is especially attractive, not only because it can be economically and scientifically rewarding, but also because it can be an aesthetic experience much like composing poetry or music. -- Donald Knuth pgpUM54Wc6beV.pgp Description: PGP signature ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On Tue, 12 Feb 2008 19:11:36 -0600 Ozzi [EMAIL PROTECTED] wrote: 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 ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 Ozzi [EMAIL PROTECTED] writes: 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. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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. 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/ 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. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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...? On Feb 12, 2008, at 10:24 PM, Kon Lovett wrote: On Feb 12, 2008, at 4:36 PM, Ivan Raikov wrote: 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 ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users Best Wishes, Kon ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On Feb 12, 2008, at 4:36 PM, Ivan Raikov wrote: 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 ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users Best Wishes, Kon ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 raymond medeiros [EMAIL PROTECTED] writes: 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. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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. On Feb 12, 2008, at 11:41 PM, Ivan Raikov wrote: 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 raymond medeiros [EMAIL PROTECTED] writes: 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. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 On Feb 12, 2008, at 11:10 PM, Ivan Raikov wrote: 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 Raymond Medeiros [EMAIL PROTECTED] writes: 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...? ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 Raymond Medeiros [EMAIL PROTECTED] writes: 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...? ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 John Cowan [EMAIL PROTECTED] writes: 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-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 raymond medeiros [EMAIL PROTECTED] writes: 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. ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
Ivan Raikov scripsit: 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. -- Is a chair finely made tragic or comic? Is the John Cowan portrait of Mona Lisa good if I desire to see [EMAIL PROTECTED] it? Is the bust of Sir Philip Crampton lyrical, http://ccil.org/~cowan epical or dramatic? If a man hacking in fury at a block of wood make there an image of a cow, is that image a work of art? If not, why not? --Stephen Dedalus ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
-- You are a child of the universe no less John Cowan than the trees and all other acyclichttp://www.ccil.org/~cowan graphs; you have a right to be here.[EMAIL PROTECTED] --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 ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On Tue, Feb 12, 2008 at 03:16:35PM -0200, Mario Domenech Goulart wrote:
Hi Mark,
On Tue, 12 Feb 2008 10:52:02 -0600 Mark Fredrickson [EMAIL PROTECTED]
wrote:
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.
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.
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.
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
--
http://sjamaan.ath.cx
--
The process of preparing programs for a digital computer
is especially attractive, not only because it can be economically
and scientifically rewarding, but also because it can be an aesthetic
experience much like composing poetry or music.
-- Donald Knuth
pgpS0oKNe9Agv.pgp
Description: PGP signature
___
Chicken-users mailing list
Chicken-users@nongnu.org
http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
Mario Domenech Goulart scripsit: 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. -- You are a child of the universe no less John Cowan than the trees and all other acyclichttp://www.ccil.org/~cowan graphs; you have a right to be here.[EMAIL PROTECTED] --DeXiderata by Sean McGrath ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 On Tue, 12 Feb 2008, Graham Fawcett wrote: 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 Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
Hi Mark, On Tue, 12 Feb 2008 10:52:02 -0600 Mark Fredrickson [EMAIL PROTECTED] wrote: 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 ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 Graham Fawcett wrote: 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 Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 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 descriptionThis is foo/description /procedure From a known format, we can convert the wiki documentation to whatever format we need and even have an interactive documentation system. The current problem with the wiki documentation is that we don't have semantic markup. Best wishes, Mario ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
Hi Graham and folks, On Tue, 12 Feb 2008 11:32:26 -0500 Graham Fawcett [EMAIL PROTECTED] wrote: 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 descriptionThis is foo/description /procedure From a known format, we can convert the wiki documentation to whatever format we need and even have an interactive documentation system. The current problem with the wiki documentation is that we don't have semantic markup. Best wishes, Mario ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 On Wed, 13 Feb 2008, Ivan Raikov wrote: 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 Elf [EMAIL PROTECTED] writes: 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 ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
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 Elf [EMAIL PROTECTED] writes: 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 ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
[Chicken-users] egg documentation
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 Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] egg documentation
On Tue, 12 Feb 2008 21:12:16 -0500 John Cowan [EMAIL PROTECTED] wrote: Mario Domenech Goulart scripsit: 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 ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
