Gregg Reynolds <d...@mobileink.com> writes: >> I think that the counter argument to that is that many other programming >> languages have a richer documentation system than Clojure, and many >> programmers use them. >> >> To be clear, Clojure's documentation system is an unstructured string, >> the arglists metadata and (arguably) the private metadata. >> > > I would add comment syntax. Technically maybe not part of a doc "system", > but I have yet to meet a comment that doesn't count as documentation in > some sense.
True, and, to some extent, it inherits the ";" vs ";;" comment distinction. But, again, there is not structure. This is an unstructured string also. Compare Emacs Lisp, for example, which uses semi-structure in the comments to drive many of its features. >> Trivial things that I would like to be able to do that I cannot do (in a >> way which will be reliably interpreted). >> >> - Add hyperlinks >> - Distinguish between symbols (or names of vars) and normal words. >> - Distinguish between code (examples) and normal words >> - Have access to basic "markdown" style typography. >> > > I'm undecided on these. They would obviously be useful, but on the other > hand minimalism has its virtues. In the base case of reading code with a > plaintext editor, I usually find embedded doco with lots of markup annoying > and an impediment to code reading. I think I'm inclined to favor keeping > markup out of code but I'm keeping an open mind about it. I've used this example before; consider this unstructured string from `cons`. Returns a new seq where x is the first element and seq is the rest. So, cons returns a seq where x is the first element, and seq is the rest? Which means that cons returns the same (constantly x) for which (rest (constantly x)) could be said to equal (constantly x), as a infinite string of x's is the same as an infinite string of x's one shorter. Although Clojure will take an infinite amount of time to test this for you. > > At the moment I'm leaning toward DITA for heavy-duty documentation, in part > because it would allow generation of manpages. You can see an example at > leiningen-doc <https://github.com/mobileink/leiningen-doc> - pdf output > examples are in doc/pdf. It's mostly an outline at the moment, but if you > look at the driver file > ugbook.ditamap<https://github.com/mobileink/leiningen-doc/blob/master/ugbook.ditamap>and > the files in the ug directory you can get a quick idea of how it > works. Once you get the hang of it you can quickly write doco in a > language specifically designed for tech documentation (and extend it if you > wish). > > That puts me in a small (infinitesimal?) minority, I reckon, but DITA is > evolving and growing, at least among professional tech writers. An obvious > research topic is how Clojure and DITA might be made to play nice together. I was never a great fan of writing XML by hand, to be honest (which is what this appears to be). The first example that I looked at: https://github.com/mobileink/leiningen-doc/blob/master/ug/classpath.dita incidentally, appears to be ill-formed, having two "</concept>" tags. XML is hard to write. >> > If it were genuinely failing us in some important way, it would be >> > changed. >> >> This is, I think, a variant of the no true Scotsman fallacy. You can >> say, about any complaint about documentation system are wrong, because >> if they were right, it would be changed. By definition I can produce no >> counter examples. >> > > Does that mean I win? ;) Yes, but only if you can prove that you are a true Scotsman. > Actually I was thinking in terms of evolution rather than definition. > Since version 1 of clojure lots of unmet needs have been identified and > then met; the language has evolved in response to genuine needs (meaning: > new stuff is actually used to do useful things). Since that hasn't > happened much (to my knowledge) with respect to doc features, I conclude > that those features are at least minimally sufficient ("optimal" was a bad > choice of words) to contribute to "survival". I'm pretty sure Rich Hickey > would reject any proposed changes to the language that did not meet a > genuine unmet need, and the Clojure community is sufficiently active and > competent and imaginative, that I'm strongly inclined to believe that, were > the doc features genuinely deficient or inadequate in some way, the > language would have evolved in some way to remedy the problem. Many features added to Clojure come from other languages -- consider the requirement (or otherwise) for keyword arguments. People feel the lack of these features early on, when they try and port other code (or just their mind) to a new language. Documentation is about scalability; it only hits when you have a reasonable amount of code (especially external libraries). It also hits newcomers most. So, perhaps, the time is now. Phil -- 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 unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
