Re: [Chicken-users] RFC: documentation lookup utility
On 8/13/06, Toby Butzon [EMAIL PROTECTED] wrote: ... I think this is an *excellent* idea. I really like that URL-approach, very slick. Creating a cross reference is of course a major piece of work, but might be doable by combining ideas from eggdoc, the man egg, svnwiki and the stuff the compiler itself can provide (like .export files). cheers, felix -- http://galinha.ucpel.tche.br:8081/blog/blog.ssp ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] RFC: documentation lookup utility
Is there any existing document with sufficient metadata as to give me a way to machine-generate the index of all of Chicken's functions? If not, I expect I will spend a little time manually generating this sort of data; it may be beneficial to embed it in the existing manual (sexprs in HTML comments?) or otherwise (a) make it generally available and (b) keep it up-to-date. I think currently we can't build the index from the info in the wiki as it is. However, we could certainly make it possible to enrich the wiki pages, extending their format to make it reflects the semantics of the documents more closely, to make it possible to build the index directly from them. I think the way we would do this would be with a svnwiki extension. They way it would work would be that in the wiki pages we would use some tags such as /definition/ in: == foobar definition name=foobar/ enscript highlight=scheme(foobar baz)/enscript The svnwiki extension would probably map the definition tag to some lower level wiki construct (such as a name='foobar'/). And your parser could just look for definition tags as the one above (directly in the wiki sources) and record the pages they occur in, perhaps warning us if a given definition occurs in multiple locations. When your code is given a word to look it up, it could look it up in your index/db and redirect the browser to the page from the wiki it occured in (with the #word anchor). And if the word does not correspond to any definition, your code could just redirect the browser to the wiki search URL such as: http://galinha.ucpel.tche.br:8080/cgi-bin/svnwiki/default/?action=searchq=print Of course, that means it would be good to import SRFIs and R5RS into the wiki and mark all definitions ... Does this make sense 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] RFC: documentation lookup utility
Hello Toby, On Sat, 12 Aug 2006 20:52:05 -0400 Toby Butzon [EMAIL PROTECTED] wrote: On Sat, Aug 12, 2006 at 08:59:19PM -0700, Brandon J. Van Every wrote: Typing a word into a URL is not really the kind of documentation I want. I want to click on a word in the editor I'm using and be taken to relevant documentation. I don't want to use my brain, I want the computer to do that. I agree with you that editor-integrated documentation is nice. I haven't seen anything like that for Chicken yet A very modest start is at http://www.call-with-current-continuation.org/eggs/man.html. There's a dirty trick to bind a key to an Emacs function to show the documentation for a word under the cursor (e.g., a chicken procedure name). Best wishes, Mario ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] RFC: documentation lookup utility
Toby Butzon wrote: Did you have plans for where the data for each function would come from for your application? And are you planning to provide just the argument list or also a description of the function? I would be happy to combine efforts on this indexing/retrieval problem if our needs really do overlap. I don't really have a plan for such things. My bag is OpenGL, AI, game development, and CMake. As it is, I don't have any development time. Just found out today that I'm completely broke, so I've got fires to put out. I don't document functions in any consistent way. I'm a lone wolf developer, I don't need to ensure that every single one of my functions has a description. I do believe in clarity of design, and I do comment things that are unclear. But some stuff, people just have to study the code and scratch their head to figure out how it works. I don't like doing that; I'm not sure anyone does; in any event it is time consuming. I just don't think abundant comments are going to save anyone the burden of understanding someone else's code. So I comment briefly where I feel it's needed. If I were maintaining a public API I'd be more into comments and documentation. Maintaining public APIs is a huge chore. The CMake people aren't interested in doing it, for instance, even when offered the labor. An app is much easier to maintain than a public API. Another consideration is that some people prefer locally installed documentation to internet documentation. For one thing, some crazies like myself are still on dialup. Although someone else is footing my cell phone bill, it does tie up my cell phone and the battery only lasts so long. Laptop users have similar problems. Also, sometimes people's online access goes down and they don't want to be shafted waiting for the network to come back up. Internet documentation has the advantage of being up-to-date, but I think a packaging system that pulled docs from remote repositories as they are updated, would be preferable to being required to be online. There's an ecology of various Scheme development tools. I know that Quack http://www.neilvandyke.org/quack/ has some Chicken support in it, but it hasn't kept up with Chicken's website and documentation changes. I'll hazard a guess that the author isn't particularly into Chicken. Quack looks like a one man project, and as such, I doubt it's going to have any traction or use in Chicken circles. Quack seems heavily PLT oriented, and also GNU Emacs rather than XEmacs. It seems pretty important to have an author or group that actually uses Chicken, in order for Chicken to get first class support. Really this open source stuff doesn't work when it's just 1 guy doing his own thing with his own toolchain, and not really caring about other people's toolchains. I mean, it just took me 9 months to get the CMake build together, and eggs are still broken on MSVC and MinGW, quite apart from CMake. And Chicken has multiple contributors and some semblance of critical mass. I don't know what the answer is, because good editor support is not a fun problem for most people. I tried to use the Schemeway plugin on Eclipse and eventually gave up, because it was a one man project and my problems on Windows weren't getting fixed. It's been a long time and maybe it works now, but the strategic realities haven't changed. Eclipse means getting one's hands dirty with Java, and it's Kawa Scheme rather than Chicken Scheme, so that's another pull away from people's attention. Also I'm now into CMake and Eclipse is an Ant build culture. I seem to be stuck with a mishmash of tools and XEmacs is what passes for an editor lately. My knowledge of XEmacs from a programming standpoint is still decidedly primitive. I've used it as a glorified text editor, which is all that CMake requires. Ive got a CMake mode, it colorizes stuff, but it doesn't add any value to my work. I think I'll take a poke at the XEmacs website and see if there are any capabilities or 3rd party elisps I haven't noticed. Cheers, Brandon Van Every ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
[Chicken-users] RFC: documentation lookup utility
Hi all, My own tendancy when working with Chicken is to have a web browser open with the R5RS index, the Chicken manual, relevant eggs, et cetera, in separate tabs (in firefox), so lookups in the various documents are (somewhat) convenient. I've got some plans for a simplification of the above -- along the lines of what I would personally find useful -- that I would make generally available online. (It would be, after all, just a way of finding pointers to the information that's already online.) I'll outline the idea below; what I'm really interested in is (a) would you personally find the service useful and (b) if this idea doesn't fit the way you work and and wouldn't make things easier for you, I'm interested in hearing how you work -- I personally can't code very long before I have to go lookup what arguments a certain function takes, or to find a function that already exists to accomplish some task. So if you have a few minutes, I'd appreciate whatever feedback you could send me. Feel free to reply off list (or on, but I'd rather not hijack chicken-users :)). The details of what I'm thinking now follow... I've registered callcc.org, and it currently provides very rudimentary shortcuts to the documents I mentioned before. For example, http://callcc.org/ redirects to Chicken's home page; http://callcc.org/r5rs/ redirects to the HTML R5RS on schemers.org; http://callcc.org/wiki/ redirects to galinha; http://callcc.org/wiki/users redirects to galinha/users; and so on. Some of these (/wiki/ for example) serve as wildcards: /wiki/ takes you to / on galinha, while /wiki/users takes you to /users on galinha. Now, my goal is this: Any callcc.org URL should try to take me to something relevant. So I could use http://callcc.org/apply and be taken directly to the R5RS blurb on apply (and likewise everything indexed in the R5RS index would work). Similarly, functions specific to Chicken should be made available: http://callcc.org/print would take me to the Chicken manual on print http://galinha.ucpel.tche.br:8080/Unit%20library#print. URLs that don't exactly match (or don't return exactly 1 result) might instead return a page of search results. (This is all inspired by php.net's similarly functionality. Try http://php.net/echo to see an exact match and http://php.net/hex for an example of search results related to hex.) The Chicken manual part will probably require some indexing, which I haven't quite decided how to do yet. (AFAICT, unlike R5RS, there isn't an existing index of all of Chicken's functions that link into the appropriate portions of the manual. A machine-generated index might be sufficient, but I haven't decided exactly how yet. For instance, print should always take me straight to the print function, but the print function is no doubt mentioned in many places in the manual, and the word print (not necessarily referring to the function) even more, so the machine indexer would be lead to believe multiple results ought to be displayed in a case where one result is clearly correct.) I would like to have eggs and any other relevant documentation included, too. It all comes down to generating and maintaining the index, though; and that's where I was hoping to gather some feedback. I'm considering approaching this sequentially, as follows: * index functions first (R5RS, Chicken, eggs, ...) * maybe other somewhat structured things, like read syntax (#! etc) * and finally a full-text index of R5RS, Chicken manual, egg documentation, and so on, to be consulted when a query doesn't exactly match the before-mentioned indexen. The main difficulties I foresee are: * Is there any existing document with sufficient metadata as to give me a way to machine-generate the index of all of Chicken's functions? If not, I expect I will spend a little time manually generating this sort of data; it may be beneficial to embed it in the existing manual (sexprs in HTML comments?) or otherwise (a) make it generally available and (b) keep it up-to-date. * For eggs, the eggdoc source files might be enough (or come close; I haven't done enough research yet). It may be easy enough to pull out, e.g., foo from (procedure (foo BAR BAZ)), but HTML anchors will need to be added to the autogenerated output to make this be useful. Further, at least some of the eggs don't mention all of the functions they provide in the eggodc; but perhaps this shortcoming should rightly be fixed on their end. Anyway, there's the gist of it. Comments? -- Toby Butzon ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] RFC: documentation lookup utility
Hi Brandon, Thanks for the feedback. On Sat, Aug 12, 2006 at 08:59:19PM -0700, Brandon J. Van Every wrote: Typing a word into a URL is not really the kind of documentation I want. I want to click on a word in the editor I'm using and be taken to relevant documentation. I don't want to use my brain, I want the computer to do that. I agree with you that editor-integrated documentation is nice. I haven't seen anything like that for Chicken yet, and even when it exists, I'll still find the browser-based approach useful. It'd certainly bring Chicken bragging rights to have both. :) The common problem seems to be that both ideas would need an accurrate, well-maintained index of function names and [a pointer to or actual content of] the associated documentation. Knocking it out in one swing for both of us would be really nice. Although... Being able to fetch a blurb (instead of a link) might actually take a little more work. The R5RS functions are grouped with many on a single page, so it might be difficult to determine the appropriate boundaries for the blurb. In my application, the browser would handle this by starting the user off in the right place and they can read what they want. In an IDE, it might be unmanagable to get back more than a paragraph or so -- or you might just want the (func foo bar baz) synopsis to remind you of the arguments. We could possibly solve this by adding more metadata during the indexing process -- mark up not only the procedure and its arguments, but also give a description of it that would allow programs to know where the end of the text about each function is. Did you have plans for where the data for each function would come from for your application? And are you planning to provide just the argument list or also a description of the function? I would be happy to combine efforts on this indexing/retrieval problem if our needs really do overlap. -- Toby Butzon ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
Re: [Chicken-users] RFC: documentation lookup utility
That's what eggdoc-texinfo does; when it encounters a signature it pulls out the first element of the list, or returns the whole value if not a list. It also returns the whole value if evaluation of the signature fails; for example, it's pretty common to accidentally leave off a paren at the end of the signature. It works well so it may be viable if you go that route. On 8/12/06, Toby Butzon [EMAIL PROTECTED] wrote: * For eggs, the eggdoc source files might be enough (or come close; I haven't done enough research yet). It may be easy enough to pull out, e.g., foo from (procedure (foo BAR BAZ)) ___ Chicken-users mailing list Chicken-users@nongnu.org http://lists.nongnu.org/mailman/listinfo/chicken-users
