Is it feasable to create a literate haskell like alternate format for Clojure?
2010/9/6 Tim Daly <d...@axiom-developer.org>: > See http://en.wikipedia.org/wiki/Axiom_computer_algebra_system > which is "in process" to become a fully literate computer > algebra system. 20 volumes so far and a lot of documentation > still to come. > > Once a system gets larger than one person's head (e.g. Rich's) > then the question of "why" becomes interesting. Once it becomes > large enough to have a full community the question of "why" > becomes vital. Unfortunately, the "why" answers rarely get > written down by the primary developers and the follow-on developers > have to guess. > > Literate programs are a place to write down what motivates a design > choice (the "why") so that others can share the same motivation. > Thus when they see really complex code (e.g. 32-tries) they can > judge whether this is still reasonable ("should we use 64-tries?") > or whether it should just go away ("the hardware doesn't have cache"). > Without the motivation the code will be mangled by well-meaning coders. > > The Clojure project needs an english major to become the "editor-in-chief". > This person should not let any code enter the core or the accepted contrib > without a strong story line. Good code, like good characters, should have > strong motivations for what gets done. We should just be able to download > the Clojure "book", read it, and execute it. > > Maybe Stu can get his book editor on board :-) > > Tim Daly > > Joop Kiefte wrote: >> >> To have a good idea of how this can work, see Literate Haskell >> >> 2010/9/6 Tim Daly <d...@axiom-developer.org>: >> >>> >>> The literate programming discussion centered around the question >>> "what should be the state of the art in clojure documentation", >>> not "what is the state of the art in clojure documentation". >>> >>> If you're looking for API documentation then literate programming >>> is the wrong tool. An API would document calling conventions and >>> something like javadoc would be most appropriate. For the API see >>> http://clojuredocs.org/quickref/Clojure%20Core >>> >>> A literate program is intended as a novel-like presentation where >>> the code is presented along with its motivation. So you would expect >>> to find a discussion of why 32-way trie-like structures are used in >>> data structures or why data structures are immutable. This information >>> is available in some videos but has not been associated with the code. >>> >>> Tim Daly >>> >>> Mark Engelberg wrote: >>> >>>> >>>> I spent some time recently documenting a large clojure project. The >>>> approach I used was a combination of doc-strings, comments throughout >>>> my code, and a project-wide emacs-org-mode file summarizing the point >>>> of each file, the important functions in each file categorized by >>>> purpose, and an overview of how to use those functions effectively. >>>> It worked, but I'm not entirely pleased with the result. There was a >>>> lot of duplication between the org-mode file and the comments within >>>> the files, and I have a feeling it will be hard to maintain the >>>> documentation as the project evolves. >>>> >>>> autodoc doesn't work on Windows, but even if it does, I'm not certain >>>> it would be sufficient for me. As far as I know, it's main purpose is >>>> to show an alphabetized API of all the public functions and >>>> docstrings, which is a good start, but doesn't allow for the kind of >>>> categorization and usage notes I think would be ideal. A couple years >>>> ago, when I was doing a lot of Actionscript coding, I fell in love >>>> with Natural Docs (http://www.naturaldocs.org/) and this is really the >>>> kind of thing I would most enjoy using if I'm going the route of >>>> automatically extracting comments and doc strings, because it gives >>>> good control over how the API is organized, and the extra annotations >>>> are quite readable in the code. >>>> >>>> The recent post of the website that displays the clojure API >>>> categorized by purpose is a good example of the kind of thing I'm >>>> looking for. Recently, there was a thread about Literate Programming, >>>> including org-babel and Mark Fredrickson's changeling lein plugin, >>>> which also raised interesting possibilities. So I'm guessing a lot of >>>> people are interested in versatile doc tools and are working on and >>>> exploring the options. >>>> >>>> So this seems like a good time to ask: what is the current >>>> state-of-the-art in Clojure documentation tools? >>>> >>>> >>>> >>> >>> -- >>> 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 -- Linux-user #496644 (http://counter.li.org) - first touch of linux in 2004 Demandoj en aŭ pri Esperanto? Questions about Esperanto? Vragen over Esperanto? Perguntas sobre o Esperanto? - http://demandoj.tk -- 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
