On Tue, May 6, 2014 at 4:53 AM, Phillip Lord <phillip.l...@newcastle.ac.uk>wrote:
> Gregg Reynolds <d...@mobileink.com> writes: > > That sounds about right to me; communication (writing) skills, mainly. > Of > > course, my degree is in the humanities, so I would say that. Now I think > > of computation as a new addition to the classic liberal arts. > > > > I'm beginning to think that the Clojure documentation system may be > > optimal. Not "best possible", just optimal: does what it does (meets > > programmer needs) just well enough to survive. > > 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. > > 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. > > Less trivial things that I would like to be able to do: > - transclude documentation from secondary files, so that the developer > of a piece of code sees a short piece of documentation, while users > of code can see something longer. > - expand the documentation system as I see fit; i.e. the documentation > system should be designed to an abstraction, not an implementation. > All good; but personally I would want a way to do this kind of thing without mixing a lot of "doc system" code in with the algorithm code. For what it's worth, I generally prefer manpages for API and language documentation. Very fast, with good search capabilities. My main complaint about the Clojure doc ecosystem is that I can't do something like $ man clj-doseq to see docs on doseq. 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. More generally: I'm inclined to think that the "native" doc support in Clojure ("doc features" of the language itself) should be kept to a minimum, and fancier stuff made available as add-ons. Related: I think we need a better language for talking about documentation. Just consider the many ways people discover and access documentation of various kinds, and their various reasons and purposes. What "documentation" ought to look like (norms of content, organization, functionality of the discovery/access system, etc.) may be different in each case, so we need a concise language that allows us to clearly relate needs to uses/purposes and so forth. But currently our language is relatively impoverished. "Documentation" as commonly used covers just about everything, so it is inevitable that major disagreements will arise from people using the term with different ideas in mind. Addressing this need for clear articulation is part of the idea behind codegenres<https://github.com/mobileink/codegenres>. > > 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? ;) 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. -Gregg -- 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.
