You are viewing a plain text version of this content. The canonical link for it is here.
Posted to doc@openoffice.apache.org by Alexandro Colorado <jz...@oooes.org> on 2013/01/13 15:45:35 UTC
Make the IDL Reference a live documentation
For the longest I have been having the desire to have a live documents on
the IDL Reference. For people that don't know what I am talking about is
the documentation of the API objects that are supported by AOO. [1]
I have been wishing for an annotation property so users and developers can
add annotations to the various API Elements and code that could be used by
newcomers. Something similar to what PHP documents have. [2]
With technologies such as AJAX and JQuery, I think this should be very
simple to do for anyone with enough experience on web development. For the
longest time the activities of what happens in the community has been
somewhat alienated from the website. For example, there are tons of
snippets on the Forums, yet none of them make it to the site (or the
application for that matter). Looking at the SDK this morning I notice
there is almost no mention of PyUNO while the forum is filled with snippets
of this bridge[3].
My thought process is that by allowing this documentation to be more social
it will also connect the dots for new development to happen.
[1]
http://www.openoffice.org/api/docs/common/ref/com/sun/star/module-ix.html
[2] http://php.net/manual/en/function.strftime.php
[3] http://forum.openoffice.org/en/forum/viewforum.php?f=21
--
Alexandro Colorado
Apache OpenOffice Contributor
http://es.openoffice.org
Re: Make the IDL Reference a live documentation
Posted by Peter Junge <pe...@gmx.org>.
On 1/14/2013 5:09 AM, Dave Barton wrote:
> -------- Original Message --------
> From: Alexandro Colorado <jz...@oooes.org>
> To: doc@openoffice.apache.org, andrew@pitonyak.org
> Date: Sun, 13 Jan 2013 14:37:05 -0600
>> On Sun, Jan 13, 2013 at 2:07 PM, Andrew Douglas Pitonyak <
>> andrew@pitonyak.org> wrote:
>>
>>> Alexandro, consider subscribing to the mailing list :-)
>>>
>> odd I have been on the list for a bit now, at least I have got doc mails in
>> the past
>
> Some thing strange is happing here. I just pulled a doc subscriber list
> and Alexandro's email address is definitely included, but his posts are
> coming through moderation.
Maybe because headers 'From:' and 'Sender:' were not identical with
Alexandro's email.
Peter
>
> Alexandro, are you posting in html? If so try posting in plain text. I
> have noticed that the list servers can be a bit fussy about this.
>
> Regards
> Dave
>
Re: Make the IDL Reference a live documentation
Posted by Dave Barton <db...@tasit.net>.
-------- Original Message --------
From: Alexandro Colorado <jz...@oooes.org>
To: doc@openoffice.apache.org, andrew@pitonyak.org
Date: Sun, 13 Jan 2013 14:37:05 -0600
> On Sun, Jan 13, 2013 at 2:07 PM, Andrew Douglas Pitonyak <
> andrew@pitonyak.org> wrote:
>
>> Alexandro, consider subscribing to the mailing list :-)
>>
> odd I have been on the list for a bit now, at least I have got doc mails in
> the past
Some thing strange is happing here. I just pulled a doc subscriber list
and Alexandro's email address is definitely included, but his posts are
coming through moderation.
Alexandro, are you posting in html? If so try posting in plain text. I
have noticed that the list servers can be a bit fussy about this.
Regards
Dave
Re: Make the IDL Reference a live documentation
Posted by Rob Weir <ro...@apache.org>.
On Sun, Jan 13, 2013 at 10:38 PM, Alexandro Colorado <jz...@oooes.org> wrote:
> On 1/13/13, Andrew Douglas Pitonyak <an...@pitonyak.org> wrote:
>>
>> On 01/13/2013 03:37 PM, Alexandro Colorado wrote:
>>> On Sun, Jan 13, 2013 at 2:07 PM, Andrew Douglas Pitonyak
>>> <andrew@pitonyak.org <ma...@pitonyak.org>> wrote:
>>>
>>>
>>> Are you advocating something like doxygen? I would love it if we
>>> did that! :-)
>>>
>>>
>>> Well I dont really know doxygen, but like I mentioned just having a
>>> commenting system under the reference could help users get further
>>> clarification on the use of each element, I think.
>>>
>>> I watched some videos of doxygen but they focus too much on the
>>> generation of documentation from code, which is a different thing all
>>> together.
>>
>> So you are not advocating inserting the documentation into the code to
>> tell people how to use the code. You just mean create something that
>> will generate the documentation.
>
> I am advocating inserting annotations in the documentation by regular
> users. Something that doesnt change the structure or the content but
> can add comments to it. For example something like this:
>
> http://imagebin.org/242811 and http://imagebin.org/242812
>
OK. We might be able to do this. Infra recently came out with a new
commenting system that integrates with the CMS.
https://comments.apache.org/
It allows public comments, but also moderation by committers.
We briefly discussed it a while ago, but were concerned that putting
it on prominent pages like home or download would lead to pure chaos,
spamming, vandalism, etc. It is probably not possible to manage this
for pages that get 100K visits/day. But if we used it in a limited
way, on API pages, then this might be work better.
In any case, take a look at the above link and see if it sounds like a good fit.
-Rob
>>
>>>
>>>
>>> On 01/13/2013 09:45 AM, Alexandro Colorado wrote:
>>>
>>> For the longest I have been having the desire to have a live
>>> documents on
>>> the IDL Reference. For people that don't know what I am
>>> talking about is
>>> the documentation of the API objects that are supported by
>>> AOO. [1]
>>>
>>> I have been wishing for an annotation property so users and
>>> developers can
>>> add annotations to the various API Elements and code that
>>> could be used by
>>> newcomers. Something similar to what PHP documents have. [2]
>>>
>>> With technologies such as AJAX and JQuery, I think this should
>>> be very
>>> simple to do for anyone with enough experience on web
>>> development. For the
>>> longest time the activities of what happens in the community
>>> has been
>>> somewhat alienated from the website. For example, there are
>>> tons of
>>> snippets on the Forums, yet none of them make it to the site
>>> (or the
>>> application for that matter). Looking at the SDK this morning
>>> I notice
>>> there is almost no mention of PyUNO while the forum is filled
>>> with snippets
>>> of this bridge[3].
>>>
>>> My thought process is that by allowing this documentation to
>>> be more social
>>> it will also connect the dots for new development to happen.
>>>
>>> [1]
>>>
>>> http://www.openoffice.org/api/docs/common/ref/com/sun/star/module-ix.html
>>> [2] http://php.net/manual/en/function.strftime.php
>>> [3] http://forum.openoffice.org/en/forum/viewforum.php?f=21
>>>
>>>
>>> --
>>> Andrew Pitonyak
>>> My Macro Document: http://www.pitonyak.org/AndrewMacro.odt
>>> Info: http://www.pitonyak.org/oo.php
>>>
>>>
>>>
>>>
>>> --
>>> Alexandro Colorado
>>> Apache OpenOffice Contributor
>>> http://es.openoffice.org
>>>
>>>
>>
>> --
>> Andrew Pitonyak
>> My Macro Document: http://www.pitonyak.org/AndrewMacro.odt
>> Info: http://www.pitonyak.org/oo.php
>>
>>
>
>
> --
> Alexandro Colorado
> Apache OpenOffice Contributor
> http://es.openoffice.org
Re: Make the IDL Reference a live documentation
Posted by Alexandro Colorado <jz...@oooes.org>.
On 1/13/13, Andrew Douglas Pitonyak <an...@pitonyak.org> wrote:
>
> On 01/13/2013 03:37 PM, Alexandro Colorado wrote:
>> On Sun, Jan 13, 2013 at 2:07 PM, Andrew Douglas Pitonyak
>> <andrew@pitonyak.org <ma...@pitonyak.org>> wrote:
>>
>>
>> Are you advocating something like doxygen? I would love it if we
>> did that! :-)
>>
>>
>> Well I dont really know doxygen, but like I mentioned just having a
>> commenting system under the reference could help users get further
>> clarification on the use of each element, I think.
>>
>> I watched some videos of doxygen but they focus too much on the
>> generation of documentation from code, which is a different thing all
>> together.
>
> So you are not advocating inserting the documentation into the code to
> tell people how to use the code. You just mean create something that
> will generate the documentation.
I am advocating inserting annotations in the documentation by regular
users. Something that doesnt change the structure or the content but
can add comments to it. For example something like this:
http://imagebin.org/242811 and http://imagebin.org/242812
>
>>
>>
>> On 01/13/2013 09:45 AM, Alexandro Colorado wrote:
>>
>> For the longest I have been having the desire to have a live
>> documents on
>> the IDL Reference. For people that don't know what I am
>> talking about is
>> the documentation of the API objects that are supported by
>> AOO. [1]
>>
>> I have been wishing for an annotation property so users and
>> developers can
>> add annotations to the various API Elements and code that
>> could be used by
>> newcomers. Something similar to what PHP documents have. [2]
>>
>> With technologies such as AJAX and JQuery, I think this should
>> be very
>> simple to do for anyone with enough experience on web
>> development. For the
>> longest time the activities of what happens in the community
>> has been
>> somewhat alienated from the website. For example, there are
>> tons of
>> snippets on the Forums, yet none of them make it to the site
>> (or the
>> application for that matter). Looking at the SDK this morning
>> I notice
>> there is almost no mention of PyUNO while the forum is filled
>> with snippets
>> of this bridge[3].
>>
>> My thought process is that by allowing this documentation to
>> be more social
>> it will also connect the dots for new development to happen.
>>
>> [1]
>>
>> http://www.openoffice.org/api/docs/common/ref/com/sun/star/module-ix.html
>> [2] http://php.net/manual/en/function.strftime.php
>> [3] http://forum.openoffice.org/en/forum/viewforum.php?f=21
>>
>>
>> --
>> Andrew Pitonyak
>> My Macro Document: http://www.pitonyak.org/AndrewMacro.odt
>> Info: http://www.pitonyak.org/oo.php
>>
>>
>>
>>
>> --
>> Alexandro Colorado
>> Apache OpenOffice Contributor
>> http://es.openoffice.org
>>
>>
>
> --
> Andrew Pitonyak
> My Macro Document: http://www.pitonyak.org/AndrewMacro.odt
> Info: http://www.pitonyak.org/oo.php
>
>
--
Alexandro Colorado
Apache OpenOffice Contributor
http://es.openoffice.org
Re: Make the IDL Reference a live documentation
Posted by Andrew Douglas Pitonyak <an...@pitonyak.org>.
On 01/13/2013 03:37 PM, Alexandro Colorado wrote:
> On Sun, Jan 13, 2013 at 2:07 PM, Andrew Douglas Pitonyak
> <andrew@pitonyak.org <ma...@pitonyak.org>> wrote:
>
>
> Are you advocating something like doxygen? I would love it if we
> did that! :-)
>
>
> Well I dont really know doxygen, but like I mentioned just having a
> commenting system under the reference could help users get further
> clarification on the use of each element, I think.
>
> I watched some videos of doxygen but they focus too much on the
> generation of documentation from code, which is a different thing all
> together.
So you are not advocating inserting the documentation into the code to
tell people how to use the code. You just mean create something that
will generate the documentation.
>
>
> On 01/13/2013 09:45 AM, Alexandro Colorado wrote:
>
> For the longest I have been having the desire to have a live
> documents on
> the IDL Reference. For people that don't know what I am
> talking about is
> the documentation of the API objects that are supported by
> AOO. [1]
>
> I have been wishing for an annotation property so users and
> developers can
> add annotations to the various API Elements and code that
> could be used by
> newcomers. Something similar to what PHP documents have. [2]
>
> With technologies such as AJAX and JQuery, I think this should
> be very
> simple to do for anyone with enough experience on web
> development. For the
> longest time the activities of what happens in the community
> has been
> somewhat alienated from the website. For example, there are
> tons of
> snippets on the Forums, yet none of them make it to the site
> (or the
> application for that matter). Looking at the SDK this morning
> I notice
> there is almost no mention of PyUNO while the forum is filled
> with snippets
> of this bridge[3].
>
> My thought process is that by allowing this documentation to
> be more social
> it will also connect the dots for new development to happen.
>
> [1]
> http://www.openoffice.org/api/docs/common/ref/com/sun/star/module-ix.html
> [2] http://php.net/manual/en/function.strftime.php
> [3] http://forum.openoffice.org/en/forum/viewforum.php?f=21
>
>
> --
> Andrew Pitonyak
> My Macro Document: http://www.pitonyak.org/AndrewMacro.odt
> Info: http://www.pitonyak.org/oo.php
>
>
>
>
> --
> Alexandro Colorado
> Apache OpenOffice Contributor
> http://es.openoffice.org
>
>
--
Andrew Pitonyak
My Macro Document: http://www.pitonyak.org/AndrewMacro.odt
Info: http://www.pitonyak.org/oo.php
Re: Make the IDL Reference a live documentation
Posted by Alexandro Colorado <jz...@oooes.org>.
On Sun, Jan 13, 2013 at 2:07 PM, Andrew Douglas Pitonyak <
andrew@pitonyak.org> wrote:
> Alexandro, consider subscribing to the mailing list :-)
>
odd I have been on the list for a bit now, at least I have got doc mails in
the past
>
> Are you advocating something like doxygen? I would love it if we did that!
> :-)
Well I dont really know doxygen, but like I mentioned just having a
commenting system under the reference could help users get further
clarification on the use of each element, I think.
I watched some videos of doxygen but they focus too much on the generation
of documentation from code, which is a different thing all together.
>
>
> On 01/13/2013 09:45 AM, Alexandro Colorado wrote:
>
>> For the longest I have been having the desire to have a live documents on
>> the IDL Reference. For people that don't know what I am talking about is
>> the documentation of the API objects that are supported by AOO. [1]
>>
>> I have been wishing for an annotation property so users and developers can
>> add annotations to the various API Elements and code that could be used by
>> newcomers. Something similar to what PHP documents have. [2]
>>
>> With technologies such as AJAX and JQuery, I think this should be very
>> simple to do for anyone with enough experience on web development. For the
>> longest time the activities of what happens in the community has been
>> somewhat alienated from the website. For example, there are tons of
>> snippets on the Forums, yet none of them make it to the site (or the
>> application for that matter). Looking at the SDK this morning I notice
>> there is almost no mention of PyUNO while the forum is filled with
>> snippets
>> of this bridge[3].
>>
>> My thought process is that by allowing this documentation to be more
>> social
>> it will also connect the dots for new development to happen.
>>
>> [1]
>> http://www.openoffice.org/api/**docs/common/ref/com/sun/star/**
>> module-ix.html<http://www.openoffice.org/api/docs/common/ref/com/sun/star/module-ix.html>
>> [2] http://php.net/manual/en/**function.strftime.php<http://php.net/manual/en/function.strftime.php>
>> [3] http://forum.openoffice.org/**en/forum/viewforum.php?f=21<http://forum.openoffice.org/en/forum/viewforum.php?f=21>
>>
>>
> --
> Andrew Pitonyak
> My Macro Document: http://www.pitonyak.org/**AndrewMacro.odt<http://www.pitonyak.org/AndrewMacro.odt>
> Info: http://www.pitonyak.org/oo.php
>
>
--
Alexandro Colorado
Apache OpenOffice Contributor
http://es.openoffice.org
Re: Make the IDL Reference a live documentation
Posted by Andrew Douglas Pitonyak <an...@pitonyak.org>.
Alexandro, consider subscribing to the mailing list :-)
Are you advocating something like doxygen? I would love it if we did
that! :-)
On 01/13/2013 09:45 AM, Alexandro Colorado wrote:
> For the longest I have been having the desire to have a live documents on
> the IDL Reference. For people that don't know what I am talking about is
> the documentation of the API objects that are supported by AOO. [1]
>
> I have been wishing for an annotation property so users and developers can
> add annotations to the various API Elements and code that could be used by
> newcomers. Something similar to what PHP documents have. [2]
>
> With technologies such as AJAX and JQuery, I think this should be very
> simple to do for anyone with enough experience on web development. For the
> longest time the activities of what happens in the community has been
> somewhat alienated from the website. For example, there are tons of
> snippets on the Forums, yet none of them make it to the site (or the
> application for that matter). Looking at the SDK this morning I notice
> there is almost no mention of PyUNO while the forum is filled with snippets
> of this bridge[3].
>
> My thought process is that by allowing this documentation to be more social
> it will also connect the dots for new development to happen.
>
> [1]
> http://www.openoffice.org/api/docs/common/ref/com/sun/star/module-ix.html
> [2] http://php.net/manual/en/function.strftime.php
> [3] http://forum.openoffice.org/en/forum/viewforum.php?f=21
>
--
Andrew Pitonyak
My Macro Document: http://www.pitonyak.org/AndrewMacro.odt
Info: http://www.pitonyak.org/oo.php