You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Phil Steitz <ph...@gmail.com> on 2013/01/13 20:28:41 UTC
[math] User Guide needs some love
I just fixed a couple of errors in the User Guide. There are likely
lots more and some whole sections that need to be rewritten.
Patches are most welcome.
One thing we might want to consider is creating separate test
packages for the User Guide examples. While this was not
consistently done, we used to lift user guide examples from the unit
tests, which made sure the examples actually worked. The problem
with that approach is that there is nothing to guarantee that when
the unit test gets updated to reflect updates / better practices,
the same thing happens in the corresponding User Guide example. It
would be more likely for this to happen if we either annotated the
test cases including guide examples somehow or separated them into a
"userguide" test package. We could do this incrementally, by
top-level package for example, as we validate and update the guide.
What do you think?
Phil
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] User Guide needs some love
Posted by Thomas Neidhart <th...@gmail.com>.
On 05/23/2013 09:48 PM, Thomas Neidhart wrote:
> On 05/23/2013 08:53 PM, Luc Maisonobe wrote:
>> Le 23/05/2013 17:41, Phil Steitz a écrit :
>>> On 5/23/13 1:18 AM, Thomas Neidhart wrote:
>>>> I would like to create more examples, but instead of creating my own
>>>> plotting functions (was ok for simple scatter plots) use something like
>>>> jfreechart.
>>>> Is it ok to include this dependency with scope test?
>>>
>>> No problem IMO, as long as scope is test.
>>
>> I think it is OK if we don't distribute it, due to this:
>> <http://www.apache.org/legal/resolved.html#prohibited>
>>
>> So it would be better if it is not a declared as a dependency (typically
>> not in the pom), but as an external tool.
>>
>> Look for example at
>> <http://www.apache.org/legal/resolved.html#category-b>, there is an
>> interesting sentence in the explanation:
>>
>> By attaching a prominent label to the distribution and requiring
>> an explicit action by the user to get the reciprocally-licensed
>> source, users are less likely to be unaware of restrictions
>> significantly different from those of the Apache License. Please
>> include the URL to the product's homepage in the prominent label.
>>
>> The "explicit action by the user" part is the reason I would suggest
>> not to declare a dependency in the pom.
>
> I have now found xchart (http://xeiam.com/xchart.jsp) which is available
> from maven central, is released under Apache license and seems to
> support all that I need, so I will give it a try.
Added a first example with screenshot in MATH-983.
Thomas
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] User Guide needs some love
Posted by Thomas Neidhart <th...@gmail.com>.
On 05/23/2013 08:53 PM, Luc Maisonobe wrote:
> Le 23/05/2013 17:41, Phil Steitz a écrit :
>> On 5/23/13 1:18 AM, Thomas Neidhart wrote:
>>> I would like to create more examples, but instead of creating my own
>>> plotting functions (was ok for simple scatter plots) use something like
>>> jfreechart.
>>> Is it ok to include this dependency with scope test?
>>
>> No problem IMO, as long as scope is test.
>
> I think it is OK if we don't distribute it, due to this:
> <http://www.apache.org/legal/resolved.html#prohibited>
>
> So it would be better if it is not a declared as a dependency (typically
> not in the pom), but as an external tool.
>
> Look for example at
> <http://www.apache.org/legal/resolved.html#category-b>, there is an
> interesting sentence in the explanation:
>
> By attaching a prominent label to the distribution and requiring
> an explicit action by the user to get the reciprocally-licensed
> source, users are less likely to be unaware of restrictions
> significantly different from those of the Apache License. Please
> include the URL to the product's homepage in the prominent label.
>
> The "explicit action by the user" part is the reason I would suggest
> not to declare a dependency in the pom.
I have now found xchart (http://xeiam.com/xchart.jsp) which is available
from maven central, is released under Apache license and seems to
support all that I need, so I will give it a try.
Thomas
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] User Guide needs some love
Posted by Luc Maisonobe <Lu...@free.fr>.
Le 23/05/2013 17:41, Phil Steitz a écrit :
> On 5/23/13 1:18 AM, Thomas Neidhart wrote:
>> I would like to create more examples, but instead of creating my own
>> plotting functions (was ok for simple scatter plots) use something like
>> jfreechart.
>> Is it ok to include this dependency with scope test?
>
> No problem IMO, as long as scope is test.
I think it is OK if we don't distribute it, due to this:
<http://www.apache.org/legal/resolved.html#prohibited>
So it would be better if it is not a declared as a dependency (typically
not in the pom), but as an external tool.
Look for example at
<http://www.apache.org/legal/resolved.html#category-b>, there is an
interesting sentence in the explanation:
By attaching a prominent label to the distribution and requiring
an explicit action by the user to get the reciprocally-licensed
source, users are less likely to be unaware of restrictions
significantly different from those of the Apache License. Please
include the URL to the product's homepage in the prominent label.
The "explicit action by the user" part is the reason I would suggest
not to declare a dependency in the pom.
Luc
>
> Phil
>>
>> btw. you can reference the test source in the user guide like this:
>>
>> xref-test/org/apache/commons/math3/geometry/partitioning/utilities/AVLTreeTest.html
>>
>> this displays the html formatted source code.
>>
>> Thomas
>>
>>
>>
>> On Tue, May 21, 2013 at 7:37 PM, Thomas Neidhart
>> <th...@gmail.com>wrote:
>>
>>> On 01/15/2013 02:00 PM, Gilles Sadowski wrote:
>>>> On Tue, Jan 15, 2013 at 10:01:17AM +0100, Thomas Neidhart wrote:
>>>>> On Sun, Jan 13, 2013 at 8:28 PM, Phil Steitz <ph...@gmail.com>
>>> wrote:
>>>>>> I just fixed a couple of errors in the User Guide. There are likely
>>>>>> lots more and some whole sections that need to be rewritten.
>>>>>> Patches are most welcome.
>>>>>>
>>>>>> One thing we might want to consider is creating separate test
>>>>>> packages for the User Guide examples. While this was not
>>>>>> consistently done, we used to lift user guide examples from the unit
>>>>>> tests, which made sure the examples actually worked. The problem
>>>>>> with that approach is that there is nothing to guarantee that when
>>>>>> the unit test gets updated to reflect updates / better practices,
>>>>>> the same thing happens in the corresponding User Guide example. It
>>>>>> would be more likely for this to happen if we either annotated the
>>>>>> test cases including guide examples somehow or separated them into a
>>>>>> "userguide" test package. We could do this incrementally, by
>>>>>> top-level package for example, as we validate and update the guide.
>>>>>> What do you think?
>>>>>>
>>>>> I think a math-samples project / directory / whatever would be quite
>>> nice.
>>>>> So users could directly try out the examples from the guide without the
>>>>> need to copy & paste things from there.
>>>> Actually, what would be great to enforce consistency is to have the
>>> examples
>>>> of the user guide directly link to the code in the "userguide" part of
>>> the
>>>> test source repository, where the corresponding code would be marked with
>>>> some kind of "anchor" (that would create the anchor to be linked to in
>>> the
>>>> generated HTML). I've no idea whether that's possible... :-}.
>>> added first sample code in
>>> src/test/java/org/apache/commons/math3/userguide: ClusteringExample
>>>
>>> The example prints results of different clustering algorithms for
>>> various datasets, and I plan to include the resulting image in the user
>>> guide.
>>>
>>> Thomas
>>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] User Guide needs some love
Posted by Thomas Neidhart <th...@gmail.com>.
On 05/23/2013 05:41 PM, Phil Steitz wrote:
> On 5/23/13 1:18 AM, Thomas Neidhart wrote:
>> I would like to create more examples, but instead of creating my own
>> plotting functions (was ok for simple scatter plots) use something like
>> jfreechart.
>> Is it ok to include this dependency with scope test?
>
> No problem IMO, as long as scope is test.
sure, any feedback on the ones I have created so far?
Thomas
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] User Guide needs some love
Posted by Phil Steitz <ph...@gmail.com>.
On 5/23/13 1:18 AM, Thomas Neidhart wrote:
> I would like to create more examples, but instead of creating my own
> plotting functions (was ok for simple scatter plots) use something like
> jfreechart.
> Is it ok to include this dependency with scope test?
No problem IMO, as long as scope is test.
Phil
>
> btw. you can reference the test source in the user guide like this:
>
> xref-test/org/apache/commons/math3/geometry/partitioning/utilities/AVLTreeTest.html
>
> this displays the html formatted source code.
>
> Thomas
>
>
>
> On Tue, May 21, 2013 at 7:37 PM, Thomas Neidhart
> <th...@gmail.com>wrote:
>
>> On 01/15/2013 02:00 PM, Gilles Sadowski wrote:
>>> On Tue, Jan 15, 2013 at 10:01:17AM +0100, Thomas Neidhart wrote:
>>>> On Sun, Jan 13, 2013 at 8:28 PM, Phil Steitz <ph...@gmail.com>
>> wrote:
>>>>> I just fixed a couple of errors in the User Guide. There are likely
>>>>> lots more and some whole sections that need to be rewritten.
>>>>> Patches are most welcome.
>>>>>
>>>>> One thing we might want to consider is creating separate test
>>>>> packages for the User Guide examples. While this was not
>>>>> consistently done, we used to lift user guide examples from the unit
>>>>> tests, which made sure the examples actually worked. The problem
>>>>> with that approach is that there is nothing to guarantee that when
>>>>> the unit test gets updated to reflect updates / better practices,
>>>>> the same thing happens in the corresponding User Guide example. It
>>>>> would be more likely for this to happen if we either annotated the
>>>>> test cases including guide examples somehow or separated them into a
>>>>> "userguide" test package. We could do this incrementally, by
>>>>> top-level package for example, as we validate and update the guide.
>>>>> What do you think?
>>>>>
>>>> I think a math-samples project / directory / whatever would be quite
>> nice.
>>>> So users could directly try out the examples from the guide without the
>>>> need to copy & paste things from there.
>>> Actually, what would be great to enforce consistency is to have the
>> examples
>>> of the user guide directly link to the code in the "userguide" part of
>> the
>>> test source repository, where the corresponding code would be marked with
>>> some kind of "anchor" (that would create the anchor to be linked to in
>> the
>>> generated HTML). I've no idea whether that's possible... :-}.
>> added first sample code in
>> src/test/java/org/apache/commons/math3/userguide: ClusteringExample
>>
>> The example prints results of different clustering algorithms for
>> various datasets, and I plan to include the resulting image in the user
>> guide.
>>
>> Thomas
>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] User Guide needs some love
Posted by Thomas Neidhart <th...@gmail.com>.
I would like to create more examples, but instead of creating my own
plotting functions (was ok for simple scatter plots) use something like
jfreechart.
Is it ok to include this dependency with scope test?
btw. you can reference the test source in the user guide like this:
xref-test/org/apache/commons/math3/geometry/partitioning/utilities/AVLTreeTest.html
this displays the html formatted source code.
Thomas
On Tue, May 21, 2013 at 7:37 PM, Thomas Neidhart
<th...@gmail.com>wrote:
> On 01/15/2013 02:00 PM, Gilles Sadowski wrote:
> > On Tue, Jan 15, 2013 at 10:01:17AM +0100, Thomas Neidhart wrote:
> >> On Sun, Jan 13, 2013 at 8:28 PM, Phil Steitz <ph...@gmail.com>
> wrote:
> >>
> >>> I just fixed a couple of errors in the User Guide. There are likely
> >>> lots more and some whole sections that need to be rewritten.
> >>> Patches are most welcome.
> >>>
> >>> One thing we might want to consider is creating separate test
> >>> packages for the User Guide examples. While this was not
> >>> consistently done, we used to lift user guide examples from the unit
> >>> tests, which made sure the examples actually worked. The problem
> >>> with that approach is that there is nothing to guarantee that when
> >>> the unit test gets updated to reflect updates / better practices,
> >>> the same thing happens in the corresponding User Guide example. It
> >>> would be more likely for this to happen if we either annotated the
> >>> test cases including guide examples somehow or separated them into a
> >>> "userguide" test package. We could do this incrementally, by
> >>> top-level package for example, as we validate and update the guide.
> >>> What do you think?
> >>>
> >>
> >> I think a math-samples project / directory / whatever would be quite
> nice.
> >> So users could directly try out the examples from the guide without the
> >> need to copy & paste things from there.
> >
> > Actually, what would be great to enforce consistency is to have the
> examples
> > of the user guide directly link to the code in the "userguide" part of
> the
> > test source repository, where the corresponding code would be marked with
> > some kind of "anchor" (that would create the anchor to be linked to in
> the
> > generated HTML). I've no idea whether that's possible... :-}.
>
> added first sample code in
> src/test/java/org/apache/commons/math3/userguide: ClusteringExample
>
> The example prints results of different clustering algorithms for
> various datasets, and I plan to include the resulting image in the user
> guide.
>
> Thomas
>
Re: [math] User Guide needs some love
Posted by Thomas Neidhart <th...@gmail.com>.
On 01/15/2013 02:00 PM, Gilles Sadowski wrote:
> On Tue, Jan 15, 2013 at 10:01:17AM +0100, Thomas Neidhart wrote:
>> On Sun, Jan 13, 2013 at 8:28 PM, Phil Steitz <ph...@gmail.com> wrote:
>>
>>> I just fixed a couple of errors in the User Guide. There are likely
>>> lots more and some whole sections that need to be rewritten.
>>> Patches are most welcome.
>>>
>>> One thing we might want to consider is creating separate test
>>> packages for the User Guide examples. While this was not
>>> consistently done, we used to lift user guide examples from the unit
>>> tests, which made sure the examples actually worked. The problem
>>> with that approach is that there is nothing to guarantee that when
>>> the unit test gets updated to reflect updates / better practices,
>>> the same thing happens in the corresponding User Guide example. It
>>> would be more likely for this to happen if we either annotated the
>>> test cases including guide examples somehow or separated them into a
>>> "userguide" test package. We could do this incrementally, by
>>> top-level package for example, as we validate and update the guide.
>>> What do you think?
>>>
>>
>> I think a math-samples project / directory / whatever would be quite nice.
>> So users could directly try out the examples from the guide without the
>> need to copy & paste things from there.
>
> Actually, what would be great to enforce consistency is to have the examples
> of the user guide directly link to the code in the "userguide" part of the
> test source repository, where the corresponding code would be marked with
> some kind of "anchor" (that would create the anchor to be linked to in the
> generated HTML). I've no idea whether that's possible... :-}.
added first sample code in
src/test/java/org/apache/commons/math3/userguide: ClusteringExample
The example prints results of different clustering algorithms for
various datasets, and I plan to include the resulting image in the user
guide.
Thomas
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] User Guide needs some love
Posted by Gilles Sadowski <gi...@harfang.homelinux.org>.
On Tue, Jan 15, 2013 at 10:01:17AM +0100, Thomas Neidhart wrote:
> On Sun, Jan 13, 2013 at 8:28 PM, Phil Steitz <ph...@gmail.com> wrote:
>
> > I just fixed a couple of errors in the User Guide. There are likely
> > lots more and some whole sections that need to be rewritten.
> > Patches are most welcome.
> >
> > One thing we might want to consider is creating separate test
> > packages for the User Guide examples. While this was not
> > consistently done, we used to lift user guide examples from the unit
> > tests, which made sure the examples actually worked. The problem
> > with that approach is that there is nothing to guarantee that when
> > the unit test gets updated to reflect updates / better practices,
> > the same thing happens in the corresponding User Guide example. It
> > would be more likely for this to happen if we either annotated the
> > test cases including guide examples somehow or separated them into a
> > "userguide" test package. We could do this incrementally, by
> > top-level package for example, as we validate and update the guide.
> > What do you think?
> >
>
> I think a math-samples project / directory / whatever would be quite nice.
> So users could directly try out the examples from the guide without the
> need to copy & paste things from there.
Actually, what would be great to enforce consistency is to have the examples
of the user guide directly link to the code in the "userguide" part of the
test source repository, where the corresponding code would be marked with
some kind of "anchor" (that would create the anchor to be linked to in the
generated HTML). I've no idea whether that's possible... :-}.
Regards,
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [math] User Guide needs some love
Posted by Thomas Neidhart <th...@gmail.com>.
On Sun, Jan 13, 2013 at 8:28 PM, Phil Steitz <ph...@gmail.com> wrote:
> I just fixed a couple of errors in the User Guide. There are likely
> lots more and some whole sections that need to be rewritten.
> Patches are most welcome.
>
> One thing we might want to consider is creating separate test
> packages for the User Guide examples. While this was not
> consistently done, we used to lift user guide examples from the unit
> tests, which made sure the examples actually worked. The problem
> with that approach is that there is nothing to guarantee that when
> the unit test gets updated to reflect updates / better practices,
> the same thing happens in the corresponding User Guide example. It
> would be more likely for this to happen if we either annotated the
> test cases including guide examples somehow or separated them into a
> "userguide" test package. We could do this incrementally, by
> top-level package for example, as we validate and update the guide.
> What do you think?
>
I think a math-samples project / directory / whatever would be quite nice.
So users could directly try out the examples from the guide without the
need to copy & paste things from there.
Thomas