2009/4/14 Laurent PETIT <laurent.pe...@gmail.com>
> Great initiative !
>
> Some thoughts I had when reading your proposal:
>
> 2009/4/14 Tom Faulhaber <tomfaulha...@gmail.com>
>
>
>> [This is specifically for contrib authors, but also for anyone whose
>> interested.]
>>
>> There was some discussion (or maybe the wailing and gnashing of teeth)
>> about the fact that there's lots of cool functionally coming into
>> clojure.contrib but no easily accessible documentation. I had been
>> thinking about this already and figured maybe I'd set up the framework
>> for fixing it.
>>
>> My idea is to use the namespace and var metadata to auto-generate a
>> set of documentation that has:
>> - an overview page that lists the namespaces in contrib and presents a
>> summary of each derived from the namespace metadata.
>> - each entry on the namespace overview page will have a link to an API
>> page for that namespace. That page will be basically like the API page
>> on clojure.org.
>> - probably should have an index page as well, but I haven't thought
>> about it much.
>> - an ability to link from a namespace to a custom created piece of
>> documentation (like the nice DatalogOverview that Jeffery wrote).
>>
>> I've written the code that builds (a first cut of) this stuff from the
>> namespaces. It uses the following metadata:
>>
>> On the namespace:
>> - :author to supply a string with the author(s) name(s)
>> - :wiki-doc to supply a wiki specific doc string (that can include
>> wiki markup) or, if that doesn't exist, we fall back to
>> - :doc the default doc string
>
>
> Could this be made a little bit more generic ? (If you find it useful) :
>
> Have a global var *rich-doc-renderers* which holds a map of
> type-of-rich-documentation to a map of renderer functions indexed by type of
> output (mime/type such as plain/html , plain/text for the :doc ...). This
> var could be enriched by libraries willing to contribute new standards :
> they would provide in the same time a new type of doc, and also ways to
> transform these docs into output formats:
>
> Example of *rich-doc-renderers* "out-of-the-box" could be :
>
> *rich-doc-renderers* { :default { :plain/html some.namespace/some-fn
> :plain/text some.namespace/some-other-fn ... } } ; default is what would be
> used for clojure / clojure-contrib ;
>
> And we could have a :rich-doc instead of :wiki-doc , with a simple version
> (if the default type of rich doc is to be used) and an extended version:
>
> simple version :rich-doc "my rich doc" => the type of formatting content to
> be used is :default , one can use the provided renderers for :default
>
> extended version :rich-doc { :type :default :content "my rich doc" } =>
> this version explicits the type of doc in :content. Of course for the
> general case it's not needed, but if a lib implementor wants to enrich
> *rich-doc-renderers* with a new set of renderers, it could be interesting ?
>
Of course, some rules could be used to smoothly downgrade the documentation
if the renderers throw exceptions, or are impossible to load ... :
the doc function could use this simple algorithm :
find the :doc tag.
If found, use it
If not found, try to use :rich-doc with a :plain/text renderer
the function for getting :rich-doc in a particular format could use this
simple algorithm :
find the :rich-doc tag
if not found: find the :doc tag. if found, use it. if not found, return
nil or "".
if found :
if it's a string, find and load the renderer for the :default type and
the expected output format (if exception in the chain, try to return the
:doc tag content)
if it's a map, get the value for :type, try to resolve it in
*rich-doc-renderers*, and then search and load the renderer function for the
expected output format (again, if exception in the chain, try to return the
:doc tag content)
if neither a string or map, ? (throw an exception, or defaults to the
doc with a warning message on *err* ?)
Well,
something like that ...
>
>
> One problem I can see with my proposal is that it forces the rendering part
> to be an explicit dependency (*rich-doc-renderers* references functions).
> Maybe this could be loosened by requiring symbols and not fns in the map ?
>
>
> Do you thing it's interesting, or overkill ?
>
>
--~--~---------~--~----~------------~-------~--~----~
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
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
-~----------~----~----~----~------~----~------~--~---
