On Tue, Oct 26, 2010 at 9:27 AM, Chris <christopher.ma...@gmail.com> wrote: > Come to think of it, it might be cool to write doc strings in a kind > of "Clojure-flavored Markdown"... that'd give us images, links, lists, > formatting, etc. It's also got the benefit of being a familiar > format, and easy to read in unprocessed form.
I like that idea, especially if it could be extended to reference other code: (defn foo "Creates an echo server using [create-server][ref:clojure.contrib.server-socket/create-server]. Returns the result of the create-server call which can be shutdown by using [close-server][ref:clojure.contrib.server-socket/close-server]." [bar] ...) I think it'd be easy enough, the markdown compiler would just know that certain prefixes to references are treated differently. > On Oct 26, 6:05 am, Chris <christopher.ma...@gmail.com> wrote: >> On Oct 26, 3:50 am, Tom Faulhaber <tomfaulha...@gmail.com> wrote: >> >> > I do know that I want the images to be able to be embedded in the doc >> > string so that programs like incanter can use the image as part of the >> > narrative, but I want the "markup" that does it to feel natural to >> > readers who aren't seeing the image. >> >> Maybe something like Markdown link references? E.g., >> >> (defn foo [x y] >> "Blah blah blah, blah blah blah. Blah blah, >> as seen here: >> >> [Figure 1][] >> >> Also remember blah blah blah, and blah blah >> as well. Blah blah blah blah blah blah blah >> blah blah blah blah blah blah blah. >> >> [Figure 1]: /doc-files/figure-1.png" >> >> (+ x y)) >> >> Basically, have all the image file addresses as footnotes. If you're >> reading the docs in the REPL, for instance, you don't have big URL-ish >> strings distracting you from the documentation, but all the info is >> still there to be parsed out by autodoc. >> >> Chris > > -- > 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 -- http://www.apgwoz.com -- 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
