Ah yes, I misread, thanks for clarifying. One advantage to the semi-freeform approach of the Wiki is that the writer can take liberties with the arrangement of prose and examples -- like in a book. Right now most of the examples are "Description: [code] [result]" but not all. An example could consist of multiple parts -- prose-code-result-prose-code-result -- but still hold together as a single example.
That said, I'm not married to the Wiki idea. If a consensus builds around a metadata approach, I'd be happy to convert any examples gathered so far into the new form. Justin On Jul 8, 2:40 pm, Moritz Ulrich <ulrich.mor...@googlemail.com> wrote: > I think Chas Emerick is suggesting something like the following: > > http://gist.github.com/468401 > > It is hard to implement on the server-side, as you store the raw > markdown-text in the datastore. However, in this form, it's not really > useful for ide developers, as they have to parse the html their self > to extract the examples or they have to display the unchanged html in > the ide. > > Maybe it's worth thinking about storing the examples one-by-one or in > an array on the server side. It would make many things easier. > > > > > > On Thu, Jul 8, 2010 at 7:48 PM, Justin Kramer <jkkra...@gmail.com> wrote: > > Oh: it probably would have helped if I had said the API returns JSON, > > not straight text/HTML. > > > Justin > > > On Jul 8, 1:44 pm, Justin Kramer <jkkra...@gmail.com> wrote: > >> They are separated: in the HTML version ("html-content" JSON > >> property), code is wrapped in <pre class="code">, results in <pre > >> class="output">, and verbiage in <p>. For the Markdown version ("raw- > >> content"), there are plain-text delineations. > > >> I will change the mime-type, though... > > >> Justin > > >> On Jul 8, 1:31 pm, Chas Emerick <cemer...@snowtide.com> wrote: > > >> > That's nifty. Suggestion though: if you really want to have tools > >> > pull those examples so that they could be used systematically, the > >> > json should really be structured to clearly separate code, expected > >> > results, and verbiage -- linebreaks aren't enough, as I could imagine > >> > many functions having a *lot* of examples, and just popping up a chunk > >> > of scrolling text may or may not be what a typical IDE user would find > >> > useful. > > >> > - Chas > > >> > On Jul 8, 2010, at 1:05 PM, Justin Kramer wrote: > > >> > > One use case I was thinking of for the Wiki is that IDEs could make > >> > > API requests for individual functions on-the-fly, or do a mass export > >> > > periodically. A basic version of the former exists now: > > >> > >http://clojure-examples.appspot.com/clojure.core/conj?format=json > > >> > > The result could be displayed plain text or as HTML in a popup/ > >> > > overlay/ > >> > > etc. > > >> > > One could even pull the examples from the Wiki and attach them to > >> > > metadata via John's set-examples!. This could be done by a function > >> > > that's only called when in REPL mode (similar to 'source' etc.). > > >> > > Or it could follow the approach of the 'javadoc' function: open your > >> > > browser to a page with detailed examples. > > >> > > Just some ideas, > > >> > > Justin > > >> > > On Jul 8, 11:38 am, Chas Emerick <cemer...@snowtide.com> wrote: > >> > >> I think there's a lot of value to having good documentation and > >> > >> examples available directly in your development environment. I'm not > >> > >> sure what a reasonable alternative would be for that context other > >> > >> than having the examples and docs included (or at least, adjacent, as > >> > >> set-examples! allows for). It certainly seems reasonable to ensure > >> > >> that such information is not included in whatever distribution of > >> > >> clojure you would "ship" (whatever that means in your context). > > >> > >> The details are sticky though, and would involve touching processes > >> > >> that aren't the most forgiving AFAICT (i.e. the core clojure build > >> > >> and > >> > >> surrounds). > > >> > >> - Chas > > >> > >> On Jul 7, 2010, at 4:35 PM, Moritz Ulrich wrote: > > >> > >>> I don't think examples should be integrated in the > >> > >>> function-definition. It's *way* to much bloat. > > >> > >>> I like the wayhttp://clojure-examples.appspot.com/clojure.coregoes. > >> > >>> A wiki-like documentation for examples, linked to every > >> > >>> clojure-namespace. These examples could be serialized into some data > >> > >>> structure and integrated in clojure.jar. This would result in no > >> > >>> bloat > >> > >>> for core.clj etc. and nice, accessible examples for our > >> > >>> development-tools. > > >> > >>> On Wed, Jul 7, 2010 at 9:05 PM, John Cromartie > >> > >>> <jcromar...@gmail.com> wrote: > >> > >>>> I've whipped up a proof-of-concept of how to implement built-in > >> > >>>> examples for functions and macros. The general idea is to add an > >> > >>>> attribute to the var that contains a list of docstrings and arg > >> > >>>> lists > >> > >>>> or code that illustrate common usage. > > >> > >>>> Let me know what you think:http://gist.github.com/466743 > > >> > >>>> It could also be useful for generating documentation. > > >> > >>>> -- > >> > >>>> You received this message because you are subscribed to the Google > >> > >>>> Groups "Clojure" group. > >> > >>>> To post to this group, send email to clojure@googlegroups.com > >> > >>>> Note that posts from new members are moderated - please be patient > >> > >>>> with your first post. > >> > >>>> To unsubscribe from this group, send email to > >> > >>>> clojure+unsubscr...@googlegroups.com > >> > >>>> For more options, visit this group at > >> > >>>>http://groups.google.com/group/clojure?hl=en > > >> > >>> -- > >> > >>> Moritz Ulrich > >> > >>> Programmer, Student, Almost normal Guy > > >> > >>>http://www.google.com/profiles/ulrich.moritz > > >> > >>> -- > >> > >>> You received this message because you are subscribed to the Google > >> > >>> Groups "Clojure" group. > >> > >>> To post to this group, send email to clojure@googlegroups.com > >> > >>> Note that posts from new members are moderated - please be patient > >> > >>> with your first post. > >> > >>> To unsubscribe from this group, send email to > >> > >>> clojure+unsubscr...@googlegroups.com > >> > >>> For more options, visit this group at > >> > >>>http://groups.google.com/group/clojure?hl=en > > >> > > -- > >> > > You received this message because you are subscribed to the Google > >> > > Groups "Clojure" group. > >> > > To post to this group, send email to clojure@googlegroups.com > >> > > Note that posts from new members are moderated - please be patient > >> > > with your first post. > >> > > To unsubscribe from this group, send email to > >> > > clojure+unsubscr...@googlegroups.com > >> > > For more options, visit this group at > >> > >http://groups.google.com/group/clojure?hl=en > > > -- > > You received this message because you are subscribed to the Google > > Groups "Clojure" group. > > To post to this group, send email to clojure@googlegroups.com > > Note that posts from new members are moderated - please be patient with > > your first post. > > To unsubscribe from this group, send email to > > clojure+unsubscr...@googlegroups.com > > For more options, visit this group at > >http://groups.google.com/group/clojure?hl=en > > -- > Moritz Ulrich > Programmer, Student, Almost normal Guy > > http://www.google.com/profiles/ulrich.moritz -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en
