[Exist-development] Function documentation app (fundocs, xqfdocs)

[Joe W. <jo...@gm...>]

Hi Jens,

(Moving this thread from exist-commits over to exist-development.)

> Oh, I see - now you mention it, I guess this was mentioned on a list …. So before libraries like this were kept in webapp or inside the app using it, now they are kept in eXide? This can't be the ideal solution.

Right, the ace javascript library (used for syntax highlighting) is a
dependency of eXide, Atomicwiki, the regular documentation app, and
the function documentation app, so the question is how to handle
dependencies.  We don't have a clear mechanism for declaring or
resolving dependencies with EXPath packages, so I guess for now we're
left with verbal instructions.  We could always just reference copies
of Ace hosted on CDNs, but if we want to retain the ability to run
these apps offline, we have to store the libraries somewhere.  An
unresolved issue, I'd say - but you're right, the current situation
isn't ideal.

> There are a few things that need to be fixed in the function docs app.
>
> 1) The dropdown has to note the location of the module. There are many version of modules with the same uri.
>
> 2) When you choose to browse one of these, you are always shown the same one.

Yes, I find this a little quirky too.  Right now modules are
identified only by namespace URI, leading to the phenomenon you
mentioned in #1.  I think the solution is to add an additional
identifier - full database URI - to the function documentation UI and
logic.  That would be a unique identifier that would let users see the
distinction between different modules with the same URI, and would let
the app display only the desired module.

As the list of modules grows (now that Wolfgang's module scanner finds
all modules so effectively), I imagine it will be easy for users to be
overwhelmed with the list of modules.  I think it would help to add a
distinction between "core" modules and "app" modules.  Core modules
would be fn, util, xmldb, etc. - perhaps simply those declared in
conf.xml.  These should appear at the top of the module dropdown list.
 The "app" modules would be all other modules found in the database.
Between the core and app modules we could have a horizontal rule - to
distinguish between the two groups.

> 3) The installed name "xqfdocs" and the repo name "fundocs" should be the same.

I agree - consistency is always good.  I personally would prefer a
more readily understandable app name like "functions" or "modules".

My other idea is to merge the former "RESTful" function documentation
browser into this one, so that we retain the ability to cite modules
with clean URLs, like:

  http://exist-db.org/apps/functions/xmldb/store

The module namespace URI collisions make such clean URLs tricky, but
still a desired end.

> I got some of 1) fixed, but I don't think I can finish it.

Cool.

Joe


> On Oct 10, 2012, at 4:28 PM, Joe Wicentowski <jo...@gm...> wrote:
>
>> Hi Jens,
>>
>> You're right that the function signature problem has to do with Ace.
>> The solution is to uninstall eXide and reinstall it from the public
>> repo.  It has an updated version of ace that works.
>>
>> Joe
>>
>> On Wed, Oct 10, 2012 at 9:20 AM, Jens Østergaard Petersen
>> <oe...@gm...> wrote:
>>> With me, with latest versions of just about everything, the function signatures do not show up in the function doc - there is a thickish black bar instead. The text is clipped away by some late-running js, probably ace, and the text appears to be black on dark gray early in its short life.
>>>
>>> .function .signature should probably have
>>>    height:1.25em;
>>>
>>> in style.css (which is not linked in page.html).
>>>
>>> I don't know how to deal with ace.
>>>
>>> Jens
>>>
>>> On Oct 6, 2012, at 12:45 AM, Joe Wicentowski <jo...@gm...> wrote:
>>>
>>>> Hi Wolfgang,
>>>>
>>>> I can confirm you have gotten it working!  Many thanks!
>>>>
>>>> Joe
>>>>
>>>> On Fri, Oct 5, 2012 at 5:19 PM,  <wol...@us...> wrote:
>>>>> Revision: 17239
>>>>>         http://sourceforge.net/p/exist/code/17239
>>>>> Author:   wolfgang_m
>>>>> Date:     2012-10-05 21:19:28 +0000 (Fri, 05 Oct 2012)
>>>>> Log Message:
>>>>> -----------
>>>>> [ignore] Fixed ace import path for code highlighting. Requires latest version of ace - and thus eXide - to be installed though.
>>>>
>>>> ------------------------------------------------------------------------------
>>>> Don't let slow site performance ruin your business. Deploy New Relic APM
>>>> Deploy New Relic app performance management and know exactly
>>>> what is happening inside your Ruby, Python, PHP, Java, and .NET app
>>>> Try New Relic at no cost today and get our sweet Data Nerd shirt too!
>>>> http://p.sf.net/sfu/newrelic-dev2dev
>>>> _______________________________________________
>>>> Exist-commits mailing list
>>>> Exi...@li...
>>>> https://lists.sourceforge.net/lists/listinfo/exist-commits
>>>
>