On Fri, Sep 10, 2010 at 9:48 AM, Rony G. Flatscher
<rony.flatsc...@wu-wien.ac.at> wrote:
> Alexandro,
>
> you may want to look into
> <http://www.ooocon.org/index.php/ooocon/2010/paper/view/196>, once the
> slides are made available online by Peter (he has been doing a lot of
> work and needs probably more time to process all of the slides of the
> numerous presentations at this year's OOoCon, all in all, an incredible
> time-consuming task).
>
> "UNO API Info" is a tool that allows to gain documentation on the fly
> from any OOo programming language by either supplying the name of an IDL
> type (the fully qualified name e.g. of a service, an interface, a
> constant group, etc.) or by supplying any UNO object which then gets
> documented using reflection (which programmatically can be very
> challenging as you write yourself).
>
> The result is a writer/pdf document that has all the information
So how can we make this documentation Read/Write instead of just Read
Only. By that I mean that users can share examples and not just the
documentation of the service. What many users have been asking for is
a way that we can edit and put example uses of the services. And to be
able to manage those commentaries and notifications within the same
documentaion. An example of that is the information on the PHP
documentation, althought many FLOSS projects have that property.
A simple idea is to report to a wikilang instead of an odt/pdf and be
automated the publication on the wiki. Also keep a version of the
documentation so that the commentaries don't become obsolete although
the problem with that is that many services still good might get lost.
(Something to solve moving forward).
> formatted in a nice manner (members sorted by name, members sorted by
> type and name, constants sorted by name, depicting their values,
> properties sorted by name giving their type and attributes like
> maybevoid and the like, etc.) and also linked directly to the OOo
> documentation on the web. This way one can get an overview of all the
> functionality that is available, and for further documentation you just
> follow the links of those types/members that you are interested in.
>
> Finally, one can also have not only a single IDL service, interface or
> single UNO object documented, but also the members they contain ("layer:
> 2").
>
> If you point your browser to
> <http://wi.wu.ac.at/rgf/rexx/misc/OOoCon/2010_Budapest/>, then you'll
> get to see example PDFs that got generated on the fly by supplying the
> UNO object representing a writer object (which interestingly implements
> more than one service). This is a somewhat extreme example, which also
> demonstrates how much functionality is at the hands of a programmer of
> the writer component. However, it also demonstrates how documentation
> can be devised that lets one see the forest (instead of the many trees
> making up the forest) too.
>
> At this OOoCon I also presented this live, demonstrating how to use this
> facility among other languages from JavaScript and Python.
>
> There is a readme/documentation of the tool at
> <http://wi.wu.ac.at/rgf/rexx/misc/OOoCon/2010_Budapest/read-me-UNO_API_info.html.pdf>,
> which documents this utility (including code to demonstrate how to use
> it from Basic, Java, ooRexx as well).
>
> The tool is not meant as a replacement for XRay and relatives, but as an
> additional means of on-the-fly-documentation generation with overview
> character to help the programmers mastering their challenging work.
>
> If you (or anyone else) have (has) any questions/comments regarding this
> tool, then please just post them via this list.
>
> HTH,
>
> ---rony
>
>
>
> On 10.09.2010 16:19, Alexandro Colorado wrote:
>> 2010/9/6 Jürgen Schmidt <juergen.schm...@oracle.com>
>>
>>
>>> Hi Alexandro,
>>>
>>> thanks for picking up this topic immediately.
>>>
>>> Whatever we think will be an appropriate solution to provide an easier way
>>> how users can give feedback. I would suggest that we create a tool that use
>>> the input from the IDLs (the generated type library) as input and produce
>>> based on this info whatever is necessary.
>>>
>>>
>> Do we have this tool already? How does the current documentation gets form?
>> AFAIK the UNO interface is atomic and this will provide far too many items.
>>
>>
>>
>>> Follow up please only on one list -> dev@api.openoffice.org
>>>
>>> Juergen
>>>
>>>
>>>
>>> On 9/5/10 10:37 AM, Alexandro Colorado wrote:
>>>
>>>
>>>> Hi during OOoCon a conversation started about the lack of examples on the
>>>> API documentation as far as contributions goes. Basically there are
>>>> several
>>>> places where to go to:
>>>> - API Documentation
>>>> - CodeSnippets
>>>> - Developer Guide
>>>> - OOo Wiki
>>>>
>>>> The main issue is that users and readers have low accessibility to
>>>> introduce
>>>> examples or comments on the documentation. There have been some possible
>>>> solutions discussed:
>>>> - Move the API Docs to the Wiki
>>>> - Version the API Docs depending on the OOo version
>>>> - Close codeSnippets or move it to a technology that allow users to just
>>>> paste snippets directly on the site
>>>>
>>>> As always the issue becomes lack of resources, time and information. My
>>>> feeling is that if we air this topic with possible solutions would help us
>>>> find better solutions. I do have a small script that allow me to clean off
>>>> the documentation from the collabnet HTML and just isolate the HTML
>>>> snippet.
>>>> My next step could be to find a converter from HTML to a wikilang that
>>>> allow
>>>> us to easy publish it on the wiki and publish it on the wiki as a service
>>>> (batch upload).
>>>>
>>>> Help is welcomed.
>>>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org
> For additional commands, e-mail: dev-h...@api.openoffice.org
>
>
--
Alexandro Colorado
OpenOffice.org Español
http://es.openoffice.org
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org
For additional commands, e-mail: dev-h...@api.openoffice.org
