Re: Can we please deprecate the :use directive ?
A couple thoughts, my own 2-cents-worth. First, I think I’m seeing an entirely legitimate concern being expressed by some developers that :use complicates life in their shops. Contrariwise, there’s clearly a set of developers who are in environments where :use feels very natural, and is of considerable convenience. As someone who is generally in the latter situation, I have a hard time with notion of getting rid of :use, but I can equally well picture myself doing Clojure environments where the restriction was pertinent. So, how about if there was a compiler option that caused :use to be flagged with a warning or error? I’d say that was entirely acceptable solution that kept everyone happy. In general: if you’re talking about expanding the existing functionality to help solve people’s problems, I’m all for it. If you’re talking about restricting existing functionality to require conformity with your particular vision, that’s a problem. BTW, if you insist on making the :use functionality substantially less convenient, well, I know how I respond to such things. I recall a saying from long ago in the Lisp community that “if you don’t like the syntax, write your own!”---and so I do. I’ve already dealt with several perceived nuisances in existing Clojure by writing and using my own macros. Coming up with a custom replacement for the ns macro feels a little challenging, but I dare say I’d rise to the occasion if need be. If that becomes common practice, I’d say you’ve won the conformity battle but lost the war. (Hey, maybe we should get rid of macros to prevent such heinous acts, eh? It worked for Java…) Next, there's an "I can't tell where identifiers come from" thought. Yeah, I've felt that pain, and as I've indicated, I'm situationally sympathetic. But here's a thought: how is this different from any programming language where one file/class/module/whatever can be included by another? Might there already be technology for dealing with it---even technology that doesn't involve manually qualifying every non-local identifier? Finally, with respect to the “it’s too hard for newcomers” line of argumentation, my reaction is: this is silly. Do you *really* want to optimize Clojure for use by newcomers? Assuming you managed such a thing, would the result still be useful to experienced programmers---who are, after all, are the main constituency for Clojure? Newcomers don’t tend to stay newcomers for very long, right? Similarly, with respect to the “ns is too complex” meme, my response is: gimme a break. It really isn’t all *that* complicated, and reducing its set of options by one isn’t going to change that very much. In the overall scheme of things involving functional programming in general and Clojure in particular, this tiny spec of complexity hardly signifies. Now, what *is *a problem is one of explanation---like, how to make newcomers aware of a good-enough set of recipes to get them going, or a lucid description of what the options actually are, and where they should be applied. So, here's a suggestion: improve the documentation!! Have you looked at the docstring associated with ns? Yeeesh! It’s all proper and correct, and about as profoundly uninformative as can be. (I’ve been doing Clojure intensively for about three years now, and just now I had a hard time even parsing it.) In fact, I think I’d generalize on this, as a lot of the docstrings in core Clojure are, um, terse… so I’d suggest that if Clojure 2.0 is afoot, improving the documentation would be an excellent goal. FWIW... Howard -- -- 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/groups/opt_out.
[ANN] CJD 0.1.0, a documentation technology for Clojure programs
I'd like to announce the availability of CJD 0.1.0. CJD is a technology for documenting Clojure programs which I devised to satisfy my idiosyncratic documentation-related propensities. It's mostly complete, so I thought I'd share it with the community just in case there are any fellow travelers with similar inclinations. CJD makes use of structured comments embedded in Clojure source code in a fashion inspired by Javadoc, to which it bears a superficial similarity. Like Javadoc, CJD comments support a simple form of markup that not only can add formatting detail but also provides a modicum of metadata that describes what's being documented. This allows CJD's processing facility to extract the documentation content from collections of Clojure namespaces and convert it into trees of consistently-formatted HTML documents. Thus, CJD comments represent a much more expressive alternative or supplement to docstrings. Ground zero for CJD is its home on GitHub <https://github.com/greenh/CJD>, which includes a FAQ <http://greenh.github.com/CJD/doc/FAQ.html> that provides a reasonably concise overview and rationale for CJD, and a user's guide <http://greenh.github.com/CJD/doc/User.html> that represents a first-pass attempt at describing the gory details. Needless to say, CJD uses CJD for its own program documentation. You can see the output of a representative namespace in your choice of light-background <http://greenh.github.com/CJD/doc/light/cjd.exome.html>and dark-background <http://greenh.github.com/CJD/doc/dark/cjd.exome.html> (my favorite!) renderings, and the source from which it was generated here<https://github.com/greenh/CJD/blob/master/src/clojure/cjd/exome.clj> . Here's a few additional points about CJD. You'll get all these and more from the links above, but just in case your interest hasn't already been piqued… - Documentation comments generally consist largely of ordinary text, so they're easily readable in source form. Required additions for markup and escape sequences tend to be fairly minimal. - Markup is structured in terms of syntactically valid Clojure forms, allowing Clojure-aware editors to be used to good advantage. - A recursively-defined documentation syntax allows Clojure's recursively-defined data structures and functions to be documented to whatever depth is needful. - Structure-aware support for documenting core Clojure artifacts (vars, functions, macros, protocols, records, etc.) is available right out of the box. CJD also provides facilities for extensions that allow user-defined artifacts to be compatibly documented. - Recognizing the value of richly-linked documentation, CJD tries to make it easy to link to other artifacts' documentation, both within and external to a project. - What does and doesn't get documented, and to what extent, is entirely at the developer's discretion. No pressure, no complaints—CJD happily accepts whatever scraps of documentation you throw its way. And, it's available from Clojars <https://clojars.org/cjd>, it includes a plugin that works with both the 1.x and 2.x versions Leiningen, it runs from the REPL, and there's even support for all you command-line enthusiasts out there. Enjoy! --- Howard -- 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
Re: [ANN] CJD 0.1.0, a documentation technology for Clojure programs
Yes, no argument, this is a problem, and I'm open to suggestions for solving it. As an aside, I personally don't find it to be a problem, as pretty much all of my documentation needs tend to be fulfilled by browser-based mechanisms, and my use of docstrings in a running system is negligible. That notwithstanding, I'm entirely sensitive to the fact that not everyone does it my way... so the notion of tying it into the existing state of affairs is entirely reasonable. Anyway, I'm thinking about it... -- Howard On Tuesday, December 18, 2012 2:47:59 PM UTC-8, FrankS wrote: > > It sure looks very nice! > > … but doesn't your use of #_ preclude us from getting that doc-info in the > running system? > > In other words, how would you enhance the doc facility in the repl to > pickup your doc-meta-data in real-time? > > -FrankS. > > > On Dec 18, 2012, at 11:10 PM, greenh > > wrote: > > > I'd like to announce the availability of CJD 0.1.0. > > > > CJD is a technology for documenting Clojure programs which I devised to > satisfy my idiosyncratic documentation-related propensities. It's mostly > complete, so I thought I'd share it with the community just in case there > are any fellow travelers with similar inclinations. > > > > CJD makes use of structured comments embedded in Clojure source code in > a fashion inspired by Javadoc, to which it bears a superficial similarity. > Like Javadoc, CJD comments support a simple form of markup that not only > can add formatting detail but also provides a modicum of metadata that > describes what's being documented. This allows CJD's processing facility to > extract the documentation content from collections of Clojure namespaces > and convert it into trees of consistently-formatted HTML documents. Thus, > CJD comments represent a much more expressive alternative or supplement to > docstrings. > > > > Ground zero for CJD is its home on GitHub, which includes a FAQ that > provides a reasonably concise overview and rationale for CJD, and a user's > guide that represents a first-pass attempt at describing the gory details. > > > > Needless to say, CJD uses CJD for its own program documentation. You can > see the output of a representative namespace in your choice of > light-background and dark-background (my favorite!) renderings, and the > source from which it was generated here. > > > > Here's a few additional points about CJD. You'll get all these and more > from the links above, but just in case your interest hasn't already been > piqued… > > > > • Documentation comments generally consist largely of ordinary > text, so they're easily readable in source form. Required additions for > markup and escape sequences tend to be fairly minimal. > > • Markup is structured in terms of syntactically valid Clojure > forms, allowing Clojure-aware editors to be used to good advantage. > > • A recursively-defined documentation syntax allows Clojure's > recursively-defined data structures and functions to be documented to > whatever depth is needful. > > • Structure-aware support for documenting core Clojure artifacts > (vars, functions, macros, protocols, records, etc.) is available right out > of the box. CJD also provides facilities for extensions that allow > user-defined artifacts to be compatibly documented. > > • Recognizing the value of richly-linked documentation, CJD > tries to make it easy to link to other artifacts' documentation, both > within and external to a project. > > • What does and doesn't get documented, and to what extent, is > entirely at the developer's discretion. No pressure, no complaints—CJD > happily accepts whatever scraps of documentation you throw its way. > > And, it's available from Clojars, it includes a plugin that works with > both the 1.x and 2.x versions Leiningen, it runs from the REPL, and there's > even support for all you command-line enthusiasts out there. > > > > Enjoy! > > > > --- Howard > > > > > > > > > > -- > > You received this message because you are subscribed to the Google > > Groups "Clojure" group. > > To post to this group, send email to clo...@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+u...@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
