I'm answering these out of order, sorry. :) On Tuesday, March 17, 2015 at 12:40:53 AM UTC-5, Reid McKenzie wrote: > > Hey Christopher, > > I'm Reid, the Grimoire maintainer. > I'm delighted to see that someone besides myself and Alex is interested in > this project and I wish you the best in your GSoC application. > > I'm somewhat concerned in reading your proposal that while you claim the > proposed data structure represents a "minimal superset of the other > documentation engines", it is by no means a superset of the lib-grimoire > infrastructure. > In fact the proposed "list of defs, list of namespaces" fails entirely to > address the issues with multiple versions of multiple artifacts on multiple > platforms that I've spent the last four releases of Grimoire and > lib-grimoire wrangling. >
Agreed, I think addressing versioning is a critical aspect. > The Thing structure and list/walk/read/write API I've provided via > lib-grimoire seem to solve these issues at least in my work of trying to > build a general documentation engine behind Grimoire so that I can just add > artifacts left and right. > I haven't looked at this yet, but I think that's a requirement for this. > If I wanted to build a system like Grimoire where the fundamental > navigation is entirely `group -> artifact -> version -> platform -> ns -> > def` hierarchical decent, why would I choose your representation over the > representation already present and usable in lib-grimoire? > I note with some entertainment that there exists a set of namespaces > duplicated between ClojureScript's Clojure and ClojureScript sources. > For these namespaces and the defs therein, CrossClj.info incorrectly > displays the Clojure namespaces when doing a qualified symbol lookup. > Grimoire used to have the same issue until I asked David Nolen and he said > that's a bug. > You absolutely need the platform to disambiguate what definition and > source you're looking at. > That's interesting. I suspect the new reader conditional and cljc portable file extension will further complicate this. > If I wanted to display the documentation for all the forks of > `org.clojure/clojure`, how could I get all of that into your system? > All the forks have defs in the namespace `clojure.core`. > How do you propose to tell them apart? > You have to have the Maven artifactid and groupid. > Yes. > Multiple versions of a single artifact? > Now you need the Maven version as well. > Yes. > Now we've encoded all the same information that lib-grimoire already does. > Why would I agree to use this pair of lists structure and then reconstruct > a hierarchy from node data when I could use a fundamentally hierarchical > structure for instance the one proposed [here]( > https://github.com/clojure-grimoire/lib-grimoire/issues/9)? > [by my metrics](http://conj.io/heatmap > <http://www.google.com/url?q=http%3A%2F%2Fconj.io%2Fheatmap&sa=D&sntz=1&usg=AFQjCNGFEQ4IhEHCVXR7Mu2kYvjxTb0_cg>), > > the most-visited URLs on Grimoire specify a single def or other content > precisely. > Why would I want to adopt a data format which does not inherently > represent this common case of documentation being a lookup when as above I > could build or use one that does? > That you discard these datums with no discussion is worrysome to say the > least since I found that they were needed and was forced to invent them > after I had done without them for some time. > Like I said in the other mail, Chris (or whoever does this project) is going to start with less context than you or I. The project hasn't started yet and I expect this kind of feedback to be incorporated. > I agree that there is a lot of duplicated code between the various > documentation systems. > Most of it has to do with finding namespaces on the classpath, loading > them and documenting them. > Thankfully we already have `clojure.tools.namespace` which is supposed to > solve this problem. > Currently `clojure.tools.namespace` can't find ClojureScript namespaces. > As I recall, codox ducks this limitation by implementing its own classpath > searching code. > (apologies to Stuart Sierra who I bugged about patching this a while back.) > If stuff like this needs to be built, I think that's a perfectly adequate sub-goal for the project. > Your goal of "Building a repl plugin that will search statically across > the code accessible by the project so you can query all artifacts without > actually loading them." could use some clarification. > It took me longer than I care to admit to realize you were talking about > browsing _documentation_ via some packaged documentation structure(s) > before the user actually loads code. > > Since the novel work you propose is really a documentation distribution > convention, you should say more about that. > Are you suggesting that every artifact package a "doc.edn" file? > Is this an open research question you don't have an answer to yet? > I do not know what the serialization format should be, but I envision this being a jar of stuff that can be automatically built on a project and deployed to maven repos with a known classifier (just like the -javadoc and -source jars built and distributed with most Java projects). Except instead of distributing source metadata as html, we can distribute it as *data*. Given a known classifier, this artifact can be consumed automatically by build or other dev tools. For example, imagine that you could download source metadata artifacts for all of your project dependencies and run a dynamic web service that gave you "clojure docs" specifically for your project. Or let you search across them, scoped specifically to your dependencies. Another aspect that I didn't list in the original proposal to keep things simpler is the idea of merging multiple metadata artifacts for the same project. For example, examples or other explanatory information (for Clojure itself for example) could be maintained in a secondary repository of just that, then merged into the automatically extracted source metadata to produce something like what you get with clojure docs or grimoire. In particular, people are often bothered by the conciseness of Clojure's docs. There are no plans to change that, but there is the option to combine those docstrings with (for example) a curated repo of examples or extended description. > > This is a set of problems I've sunk a lot of time into and would like to > see addressed. > It is certainly not my intent to dissuade you from this project. > Whatever documentation packaging and distribution system you come up with > I'm likely to wind up supporting in Grimoire so it's in my direct interests > to make sure that you skip as many of the pitfalls that I hit as possible. > I hope that you find this feedback constructive, and I look forwards to > seeing how this project evolves. > Feel free to bug me about Grimoire related stuff, especially if you find > bugs or documentation issues :P > We will regardless. :) Thanks for the feedback. > > All the best, > > Reid > -- 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.
