[Boost Library Incubator] Unable to submit library

classic Classic list List threaded Threaded
29 messages Options
12
Reply | Threaded
Open this post in threaded view
|

[Boost Library Incubator] Unable to submit library

Edward Diener-3
I tried to submot a library to the Boost Library Incubator only to get a
parsing error message followed by absolutely nothing happening no matter
how many times I attempted to click the Submit button. It is no fun
re-entering all that data again.


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Edward Diener-3
On 7/19/2014 4:34 PM, Edward Diener wrote:
> I tried to submot a library to the Boost Library Incubator only to get a
> parsing error message followed by absolutely nothing happening no matter
> how many times I attempted to click the Submit button. It is no fun
> re-entering all that data again.

It worked the second time I submitted it with the same data.


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Mostafa-6
On Sat, 19 Jul 2014 13:41:18 -0700, Edward Diener  
<[hidden email]> wrote:

> On 7/19/2014 4:34 PM, Edward Diener wrote:
>> I tried to submot a library to the Boost Library Incubator only to get a
>> parsing error message followed by absolutely nothing happening no matter
>> how many times I attempted to click the Submit button. It is no fun
>> re-entering all that data again.
>
> It worked the second time I submitted it with the same data.

Only the first page of the html documentation is rendering properly. The  
"Variadics Macro" link and other ones render raw html. I don't think it's  
a browser issue as I tried using two different browsers.


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Robert Ramey
Coincidentally I was tweaking this area of the web site - should be OK now.

I also fixed up the links in the form -

For those who prefer instant gratification (as I do), I fixed the documentation link to point to the master branch html documentation.  Browsable html documentation is a requirement of the web site.

I fixed up the issues to point to the issues page for this library in Git hub.

I fixed up the download link to point to the github created *.zip file.

So you should be in business - good luck with this.

Though not strictly a requirement, consider implementing the test dashboard.  Different authors have addressed this in various ways.  Look at my advice how to do it and and look at other authors usage of continuous integration websites.

Robert Ramey
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Edward Diener-3
On 7/19/2014 5:22 PM, Robert Ramey wrote:
> Coincidentally I was tweaking this area of the web site - should be OK now.
>
> I also fixed up the links in the form -

How did you figure out to setup all those links ? Was all that available
to me on GitHub but I did not realize it ?

>
> For those who prefer instant gratification (as I do), I fixed the
> documentation link to point to the master branch html documentation.
> Browsable html documentation is a requirement of the web site.

Where did that string come from ? It works beautifully but I have no
idea from where that gets generated.

>
> I fixed up the issues to point to the issues page for this library in Git
> hub.

That I can see on the GitHub sight. Am I supposed to fill that out myself ?


>
> I fixed up the download link to point to the github created *.zip file.

How did you generate that zip file on GitHub ?

>
> So you should be in business - good luck with this.

Thanks very much ! Evidently I have no idea all those facilities were
available on GitHub, evidently somewhere.

>
> Though not strictly a requirement, consider implementing the test dashboard.
> Different authors have addressed this in various ways.  Look at my advice
> how to do it and and look at other authors usage of continuous integration
> websites.

I have tests for the library that run under modular boost in the test
subdirectory using bjam/Boost Build. Is the test dashboard connected to
those tests somehow ?


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Robert Ramey
Edward Diener-3 wrote
On 7/19/2014 5:22 PM, Robert Ramey wrote:
> Coincidentally I was tweaking this area of the web site - should be OK now.
>
> I also fixed up the links in the form -

How did you figure out to setup all those links ? Was all that available
to me on GitHub but I did not realize it ?
yep
>
> For those who prefer instant gratification (as I do), I fixed the
> documentation link to point to the master branch html documentation.
> Browsable html documentation is a requirement of the web site.

Where did that string come from ? It works beautifully but I have no
idea from where that gets generated.
I forgot where I found that.  I copied the link from Safe Numerics then
altered it to point to your documentation.  BTW, if you want your docs
to look like boost ones, all you have to do is add the appropriate *.css
and image files to the html directory.  Again, check safe numerics to
see how this works.
>
> I fixed up the issues to point to the issues page for this library in Git
> hub.

That I can see on the GitHub sight. Am I supposed to fill that out myself ?
What I do is invoke the issues from the git hub website and copy the URL.
Then I paste this URL into the submission form
>
> I fixed up the download link to point to the github created *.zip file.

How did you generate that zip file on GitHub ?
same as above
>
> So you should be in business - good luck with this.

Thanks very much ! Evidently I have no idea all those facilities were
available on GitHub, evidently somewhere.
The whole idea of the incubator is to provide a uniform facade to all the
facilities that a boost library needs with the minimal disruption possible.
So if one already has his own trac equivalent, he can just point to that.
I started this before we made a big commitment to git.  It was a happy
coincidence that it is a good match.
> Though not strictly a requirement, consider implementing the test dashboard.
> Different authors have addressed this in various ways.  Look at my advice
> how to do it and and look at other authors usage of continuous integration
> websites.

I have tests for the library that run under modular boost in the test
subdirectory using bjam/Boost Build. Is the test dashboard connected to
those tests somehow ?
I struggled with this.  The website requires tests for a library to be included
but there was no obvious way to get something like the boost test matrix
without turning this thing into a really big job.  Also any system I might
run wouldn't scale.

After a lot of time learning to understand CMake, I got it working to my
taste for safe numerics and wrote the instructions in my Simple Tools
advice.  I prefer this to boost build for a number of reasons - not the least
of which it creates a project in my IDE.  It also permits.  CMake can
create a project which posts the results to a test dashboard which they
run on their own website.  I've described how to do it in the documentation.
I like this because it lets those who use a library to test it in their own environment
and post the results to this common area. It means that the platforms being
used is the same set as platforms being tested.  And it's totally scalable! And
it zero work for me or anyone else.

Other libraries such as AFIO have used some "continuous integration" websites
with what looks like good success.  Pretty soon I'll lean on the authors to write
a page with instructions (for dummies) on how to set it up.  You can see this
in action by clicking on the test dashboard link for AFIO, DI and others.

The fact that I was able to put all this together with relatively little effort
suggests to me that we're at the dawn of a new era for boost.  One where
it's much easier to get a library ready for review without sacrificing our
standards.  Lets hope so anyway.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Robert Ramey
In reply to this post by Mostafa-6
Mostafa-6 wrote
On Sat, 19 Jul 2014 13:41:18 -0700, Edward Diener  
<[hidden email]> wrote:

Only the first page of the html documentation is rendering properly. The  
"Variadics Macro" link and other ones render raw html. I don't think it's  
a browser issue as I tried using two different browsers.
Damn! - This is the first time I've noticed this - it's not just here - it's on all the links which use this method.  Looks like I've got something else to chase down
_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Edward Diener-3
In reply to this post by Robert Ramey
On 7/20/2014 2:03 AM, Robert Ramey wrote:

> Edward Diener-3 wrote
>> On 7/19/2014 5:22 PM, Robert Ramey wrote:
>>> Coincidentally I was tweaking this area of the web site - should be OK
>>> now.
>>>
>>> I also fixed up the links in the form -
>>
>> How did you figure out to setup all those links ? Was all that available
>> to me on GitHub but I did not realize it ?
>
> yep
>
>>>
>>> For those who prefer instant gratification (as I do), I fixed the
>>> documentation link to point to the master branch html documentation.
>>> Browsable html documentation is a requirement of the web site.
>>
>> Where did that string come from ? It works beautifully but I have no
>> idea from where that gets generated.
>
> I forgot where I found that.  I copied the link from Safe Numerics then
> altered it to point to your documentation.

Actually when someone clones my library, the top-level index.html
redirects to the index.html in the html sub-directory.

> BTW, if you want your docs
> to look like boost ones, all you have to do is add the appropriate *.css
> and image files to the html directory.  Again, check safe numerics to
> see how this works.

All those *.css and images become redundant when someone clones my
library from GitHub under their own local modular-boost. That is why I
do not include them in the html sub-directory.

>
>>>
>>> I fixed up the issues to point to the issues page for this library in Git
>>> hub.
>>
>> That I can see on the GitHub sight. Am I supposed to fill that out myself
>> ?
>
> What I do is invoke the issues from the git hub website and copy the URL.
> Then I paste this URL into the submission form

I see the issues page on GitHub now.

>
>>>
>>> I fixed up the download link to point to the github created *.zip file.
>>
>> How did you generate that zip file on GitHub ?
>
> same as above

I see that now on my library's GitHub page.

>
>>>
>>> So you should be in business - good luck with this.
>>
>> Thanks very much ! Evidently I have no idea all those facilities were
>> available on GitHub, evidently somewhere.
>
> The whole idea of the incubator is to provide a uniform facade to all the
> facilities that a boost library needs with the minimal disruption possible.
> So if one already has his own trac equivalent, he can just point to that.
> I started this before we made a big commitment to git.  It was a happy
> coincidence that it is a good match.
>
>>> Though not strictly a requirement, consider implementing the test
>>> dashboard.
>>> Different authors have addressed this in various ways.  Look at my advice
>>> how to do it and and look at other authors usage of continuous
>>> integration
>>> websites.

I will look at it.

>>
>> I have tests for the library that run under modular boost in the test
>> subdirectory using bjam/Boost Build. Is the test dashboard connected to
>> those tests somehow ?
>
> I struggled with this.  The website requires tests for a library to be
> included
> but there was no obvious way to get something like the boost test matrix
> without turning this thing into a really big job.  Also any system I might
> run wouldn't scale.
>
> After a lot of time learning to understand CMake, I got it working to my
> taste for safe numerics and wrote the instructions in my Simple Tools
> advice.  I prefer this to boost build for a number of reasons - not the
> least
> of which it creates a project in my IDE.  It also permits.  CMake can
> create a project which posts the results to a test dashboard which they
> run on their own website.  I've described how to do it in the documentation.
> I like this because it lets those who use a library to test it in their own
> environment
> and post the results to this common area. It means that the platforms being
> used is the same set as platforms being tested.  And it's totally scalable!
> And
> it zero work for me or anyone else.

I think you can appreciate that having to duplicate tests which already
exist through bjam/Boost Build when the user clones the project is not
something I really want to do. I really don't see the big deal of
someone interested in my library cloning it locally under modular-boost
and then having all the documentation and tests locally. I explain very
carefully in my top-level *.txt files how to do all this.

>
> Other libraries such as AFIO have used some "continuous integration"
> websites
> with what looks like good success.  Pretty soon I'll lean on the authors to
> write
> a page with instructions (for dummies) on how to set it up.  You can see
> this
> in action by clicking on the test dashboard link for AFIO, DI and others.
>
> The fact that I was able to put all this together with relatively little
> effort
> suggests to me that we're at the dawn of a new era for boost.  One where
> it's much easier to get a library ready for review without sacrificing our
> standards.  Lets hope so anyway.

I do appreciate the work you put into it. But I think that anyone
interested in a library in the Boost Library Incubator sight should be
trying it out locally just like everyone does with Git projects.



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Robert Ramey
Edward Diener-3 wrote
On 7/20/2014 2:03 AM, Robert Ramey wrote:
> Edward Diener-3 wrote

I think you can appreciate that having to duplicate tests which already
exist through bjam/Boost Build when the user clones the project is not
something I really want to do. I really don't see the big deal of
someone interested in my library cloning it locally under modular-boost
and then having all the documentation and tests locally. I explain very
carefully in my top-level *.txt files how to do all this.
There's no disagreement here.  That's exactly how I envision that
this site be used.
I do appreciate the work you put into it. But I think that anyone
interested in a library in the Boost Library Incubator sight should be
trying it out locally just like everyone does with Git projects.
There's no disagreement here either.

But there are a couple issues you've left unaddressed.

a) One looking for a library can only find documentation for libraries
already in boost.  For the sandbox one had to download the package and
(maybe) build the documentation in order to see the decimation.  For me
this was a big problem which I addressed by requiring browsable html
documentation.  The github method - (has a minor/temporary problem - I know)
is perfect for this.  It means one can browse the documentation immediately.
So this issue is resolved for me.

b) If I have an interest in a library, I like to see reviews by others regarding
their experience - again immediately.  This is addressed by using the facilities
in the of wordpress web development to permit comments and boost style
reviews - and # stars rating info - on libraries not part of boost.
So this issue is resolved for me.

c) When evaluating a library, I like to be able to test it.  Currently only
libraries already in boost are tested by our system.  And our system
requires dealing with boost build and all it's problems.  In spite of the
heroic efforts by boost build developers, it's just to big a hill to climb,
too soon for one who want's to make a library which might not be
accepted.  the Incubator requires tests - but it does not require any
specific testing/building setup - e.g. boost build.  Certainly, boost
build fulfills the requirement - but other systems to also.  After much
time investigating alternatives - I'm recommending that library
submitters use CMake in the manner that I have described in the
Advice/Simple Tools section.  Not perfect - but along with the
information I provided - provides the simplest and most expedient
way to get the job done and fulfill the incubator requirements.

d) When evaluating a library, I would like to immediately see test
results on a variety of platforms, compilers, etc.  Boost testing dashboard
only displays results of libraries already in boost - so it's no help.
Turns out that CMake has this facility.  It is hard to figure out from
the CMake documentation  (another problem) but I've included
detailed instructions on setting this up along with an example
using safe numerics.  So that's what I'm recommending personally.
Other library submitters have used other means to fulfill the requirement
for a testing/deployment method.  And I have no problem with that.

So that's the rationale behind how we got to where we are today
on this.  It might be helpful to remember that the incubator is
different than boost in that it has a much looser structure.  It doesn't
prescribe methods - only requirements.  The web site is really
a facade to make the various ways of fulfilling the requirements
look more uniform and impose some (but not too much) structure
on the process of library development.

It's a work in progress.  I much appreciate the feedback from all
parties working with this system - it's a great help.  Thats why
I love boost - it makes me a better person.

Robert Ramey


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Robert Ramey
In reply to this post by Robert Ramey
fixed this - pilot error.  All html docs display correctly at any depth.

Robert Ramey
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Edward Diener-3
In reply to this post by Robert Ramey
On 7/20/2014 12:59 PM, Robert Ramey wrote:

> Edward Diener-3 wrote
>> On 7/20/2014 2:03 AM, Robert Ramey wrote:
>>> Edward Diener-3 wrote
>>
>> I think you can appreciate that having to duplicate tests which already
>> exist through bjam/Boost Build when the user clones the project is not
>> something I really want to do. I really don't see the big deal of
>> someone interested in my library cloning it locally under modular-boost
>> and then having all the documentation and tests locally. I explain very
>> carefully in my top-level *.txt files how to do all this.
>
> There's no disagreement here.  That's exactly how I envision that
> this site be used.
>
>> I do appreciate the work you put into it. But I think that anyone
>> interested in a library in the Boost Library Incubator sight should be
>> trying it out locally just like everyone does with Git projects.
>
> There's no disagreement here either.
>
> But there are a couple issues you've left unaddressed.
>
> a) One looking for a library can only find documentation for libraries
> already in boost.  For the sandbox one had to download the package and
> (maybe) build the documentation in order to see the decimation.  For me
> this was a big problem which I addressed by requiring browsable html
> documentation.  The github method - (has a minor/temporary problem - I know)
> is perfect for this.  It means one can browse the documentation immediately.
> So this issue is resolved for me.

That's fine since you figured out how to show the documentation that is
in the library at GitHub.

>
> b) If I have an interest in a library, I like to see reviews by others
> regarding
> their experience - again immediately.  This is addressed by using the
> facilities
> in the of wordpress web development to permit comments and boost style
> reviews - and # stars rating info - on libraries not part of boost.
> So this issue is resolved for me.

Reviews and responses are great.

>
> c) When evaluating a library, I like to be able to test it.  Currently only
> libraries already in boost are tested by our system.  And our system
> requires dealing with boost build and all it's problems.  In spite of the
> heroic efforts by boost build developers, it's just to big a hill to climb,
> too soon for one who want's to make a library which might not be
> accepted.  the Incubator requires tests - but it does not require any
> specific testing/building setup - e.g. boost build.  Certainly, boost
> build fulfills the requirement - but other systems to also.  After much
> time investigating alternatives - I'm recommending that library
> submitters use CMake in the manner that I have described in the
> Advice/Simple Tools section.  Not perfect - but along with the
> information I provided - provides the simplest and most expedient
> way to get the job done and fulfill the incubator requirements.

I give specific instructions how to test the library with Boost Build.

>
> d) When evaluating a library, I would like to immediately see test
> results on a variety of platforms, compilers, etc.  Boost testing dashboard
> only displays results of libraries already in boost - so it's no help.
> Turns out that CMake has this facility.  It is hard to figure out from
> the CMake documentation  (another problem) but I've included
> detailed instructions on setting this up along with an example
> using safe numerics.  So that's what I'm recommending personally.
> Other library submitters have used other means to fulfill the requirement
> for a testing/deployment method.  And I have no problem with that.

I do not think it is very important to see test results online. It means
next to nothing unless you can look at the tests themselves and
understand what they are doing. In my library running the Boost Build
tests locally gives the results and you can use any compiler supported
by Boost Build. I am not going to invent another way of testing just to
show some results online. Anybody who is really interested in a library
should not be so lazy that they are not willing to clone it locally and
try it out.

I am not saying I may not look at your CMake/CTest/CDash combo at some
time, but if it is an absolute prerequisite for having a link to online
test results in the Boost Library Incubator I would rather remove my
library. Dealing with Boost Build is hard enough. Spending much time on
yet another set of underdocumented build tools, and trying to figure out
how they work together just to be able to specify some URL of test
results, is too depressing for me to think about. It is not your fault
that nearly all of the people who create build and/or tests systems are
so poor in explaining how they work, but it seems that is always the case.

>
> So that's the rationale behind how we got to where we are today
> on this.  It might be helpful to remember that the incubator is
> different than boost in that it has a much looser structure.  It doesn't
> prescribe methods - only requirements.  The web site is really
> a facade to make the various ways of fulfilling the requirements
> look more uniform and impose some (but not too much) structure
> on the process of library development.
>
> It's a work in progress.  I much appreciate the feedback from all
> parties working with this system - it's a great help.  Thats why
> I love boost - it makes me a better person.

I think your site is a great idea but aside from someone putting their
library there and hopefully responding/discussing other people's
comments, suggestions, queries etc. I think the less you require of a
library submitter the better. If others are too lazy to follow
instructions for using the library locally then that is their problem,
not that of the library creator. In fact I think you should have another
field in your Library Submissions page: something like "how to use the
library and any other comments the library submitter would like to make
about his library for the benefit of end-users".


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Robert Ramey
Edward Diener-3 wrote
On 7/20/2014 12:59 PM, Robert Ramey wrote:
> Edward Diener-3 wrote
>> On 7/20/2014 2:03 AM, Robert Ramey wrote:

I give specific instructions how to test the library with Boost Build.
very good
I do not think it is very important to see test results online. It means
next to nothing unless you can look at the tests themselves and
understand what they are doing. In my library running the Boost Build
tests locally gives the results and you can use any compiler supported
by Boost Build.
I disagree - I love seeing other peoples test results and check the
Boost Test matrix on a daily basis.  I always lamented the lack
of this facility for libraries not in boost.

I am not going to invent another way of testing just to
show some results online.
No one is asking you to.  The existence of a test suite is a requirement
for submissions to the incubator - the existence of a test dashboard
is not.  Note that on the submission form, the link to the test dashboard
is NOT marked with a * - that means that you can leave the field blank.
Anybody who is really interested in a library
should not be so lazy that they are not willing to clone it locally and
try it out.
lol - you're preaching to the choir.  That is to say I agree.  But what
I like about the test dashboard (like boost test matrix) is that it gives
me feed back on test failures on platforms that I don't have at my
disposal.  This is very useful to me as a library developer.  I would love
to see the tests of people having problems.  Even better, when some
person complains "This #$%^&* thing doesn't work - I can as the
developer tell him: "Run the test suite and post the results to your
test dashboard."  This would help me eliminate a huge amount of
wasted time with people who are not really helpful.  This is another
great motivator for me.

I am not saying I may not look at your CMake/CTest/CDash combo at some
time, but if it is an absolute prerequisite for having a link to online
test results in the Boost Library Incubator I would rather remove my
library.
It's not in the requirements - and they are explicitly stated in the introduction
page.  Your library met the stated requirements so it's in the incubator.
Had it not done so - I would have let you know.  Truth is - this hasn't
been a problem so far.  Every library submitted has met the requirements.
I credit this to the fact that
a) the requirements aren't to unreasonable.
b) they specify "what" rather than "how" so they are quite flexible.
c) there are a number of libraries already in the incubator and the
demonstrate "how it's done" which is helpful.
d) people who look over the requirements and the submission form
don't even bother.  

So, so far it's working perfectly (aside from some technical glitches).

Dealing with Boost Build is hard enough.
again, you're preaching to the choir.  It's a lot of time and work
(for the rest of us).  That's why I don't recommend it in this context.
That doesn't mean that it's prohibited though.

Spending much time on
yet another set of underdocumented build tools, and trying to figure out
how they work together just to be able to specify some URL of test
results, is too depressing for me to think about. It is not your fault
that nearly all of the people who create build and/or tests systems are
so poor in explaining how they work, but it seems that is always the case.
lol, again we're on the same page.  You don't have to do this.

The real response is that boost build should have an easy method to
post test results to some test dashboard.  This is a way non-trivial
task and is never going to happen.  The incubator requirements
recognize this and don't require the test dashboard.  

> It's a work in progress.  I much appreciate the feedback from all
> parties working with this system - it's a great help.  Thats why
> I love boost - it makes me a better person.

I think your site is a great idea but aside from someone putting their
library there and hopefully responding/discussing other people's
comments, suggestions, queries etc. I think the less you require of a
library submitter the better.
Hopefully, it should be clear that this has been my intention from moment
one reads the introductory page and list of requirements.  For me some
requirements were non-negociable:
a) browsable documentation
b) test suite
c) some sort of deployment method
and these don't specify any specific tools, formats (other than html docs),
issues database, source control, etc. I explicitly tried to keep requirements
the the minimum necessary - and mother more.

If others are too lazy to follow
instructions for using the library locally then that is their problem,
not that of the library creator.
lol - maybe - but if one want's his library to be successful it has to be
accessible to the widest possible group of programmers.  Hopefully,
a submitter who goes through the Boost  Incubator website will be
able to do this with the minimum amount of wasted effort.  

In fact I think you should have another
field in your Library Submissions page: something like "how to use the
library and any other comments the library submitter would like to make
about his library for the benefit of end-users".
The library description is pretty free form so such information could be
included.  But I think that the a better place would be in the library
documentation itself.  Now that it's browsable on line, it's easy to find.
So I wouldn't be too concerned about this issue.

One think that's great about the github browsing of the documentation.
It's zero effort to maintain.  When every you make a change in your
qbk docs - just regenerate and check into git hub - users are now
all up to date.  This is really great in my opinion.  Keeps the browsable
docs in sync with the current code with almost no effort.

Another very fun thing about this - try the button "display statistics"
on your library page.  This will show you graphs, and records of
people who have surfed your library.  I do it for mine every day.  It's
a great way to get through those teleconference meetings which
drone, on and on and on.  You can get some feed back on your
library just from looking at this.  If I had time I would improve
the statistics some and make the page readable by users who
are not registered - but it was free and already quite good - and fun.

Robert Ramey


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

pabristow
In reply to this post by Robert Ramey


> -----Original Message-----
> From: Boost [mailto:[hidden email]] On Behalf Of Robert Ramey
> Sent: 20 July 2014 17:59
> To: [hidden email]
> Subject: Re: [boost] [Boost Library Incubator] Unable to submit library
>
> Edward Diener-3 wrote
> > On 7/20/2014 2:03 AM, Robert Ramey wrote:
> >> Edward Diener-3 wrote
> >
> > I think you can appreciate that having to duplicate tests which
> > already exist through bjam/Boost Build when the user clones the
> > project is not something I really want to do. I really don't see the
> > big deal of someone interested in my library cloning it locally under
> > modular-boost and then having all the documentation and tests locally.
> > I explain very carefully in my top-level *.txt files how to do all this.
>
> There's no disagreement here.  That's exactly how I envision that this site be
used.

>
> > I do appreciate the work you put into it. But I think that anyone
> > interested in a library in the Boost Library Incubator sight should be
> > trying it out locally just like everyone does with Git projects.
>
> There's no disagreement here either.
>
> But there are a couple issues you've left unaddressed.
>
> a) One looking for a library can only find documentation for libraries already
in
> boost.  For the sandbox one had to download the package and
> (maybe) build the documentation in order to see the decimation.  For me this
was a
> big problem which I addressed by requiring browsable html documentation.  The
> github method - (has a minor/temporary problem - I know) is perfect for this.
It
> means one can browse the documentation immediately.
> So this issue is resolved for me.

The issue of generated (mainly html) files in GIT is still a nuisance.

If you are a sole developer, then it is quite easy - you simply include all the
/doc folder with /html etc in GIT.

But if you are developing *with* someone else, these generated files are a PITA.

You have keep reverting the /html files every time you want to GIT pull.

And you have push the updated docs every time too - and these may be quite big.

I don't see a better way round this yet.  Ideas?

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
+44 01539 561830







_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Nat Goodspeed-2
On Mon, Jul 21, 2014 at 7:02 AM, Paul A. Bristow
<[hidden email]> wrote:

> The issue of generated (mainly html) files in GIT is still a nuisance.
>
> If you are a sole developer, then it is quite easy - you simply include all the
> /doc folder with /html etc in GIT.
>
> But if you are developing *with* someone else, these generated files are a PITA.
>
> You have keep reverting the /html files every time you want to GIT pull.
>
> And you have push the updated docs every time too - and these may be quite big.
>
> I don't see a better way round this yet.  Ideas?

In fact I seem to recall some objections on this list a week or two
ago about checking generated files into source control. Please excuse
my laziness in not citing the thread.

Since the Incubator site is explicitly agnostic about how .html is
generated from source files, it's not realistic to think one could
code a "generate documentation on demand" feature into the Incubator
site -- even if resources/performance were not an issue.

Speaking from the viewpoint of "a little knowledge" (in other words,
beware!) I read through parts of the Boost.Build documentation a few
weeks ago and was a bit ashamed of the unkind remarks I myself have
made about it from time to time. It seems to me that it wouldn't be
too unreasonable to post a few cookbook Jamfile.v2 files for a
hypothetical simple Boost.Foo library, then for a somewhat less simple
Boost.Bar library: code and tests and documentation. (Let's just
stipulate that as your library's build requirements grow in
complexity, you must eventually bite the bullet and learn Boost.Build
yourself.) But a new library author, whose requirements are presumably
still pretty straightforward, could copy, tweak, iterate and ask
questions until s/he gets results.

Now we enter the realm of fantasy. Suppose someone were willing to
host a CI site on which you could register a URL to a particular
candidate library structured according to Boost library module
conventions: build/Jamfile.v2, test/Jamfile.v2, doc/Jamfile.v2. The CI
site should work with github, but any URL compatible with git clone
should also work. This site would run tests on each registered library
using Boost.Build and produce a dashboard; similarly it would run
documentation builds using Boost.Build and support a library-specific
URL by which one could retrieve its documentation (or a page saying
"Documentation not yet built" or "Documentation build errors: ...").

I blithely imagine that the test-dashboard scripting wouldn't be too
dissimilar from what people already use to run regression tests on
official Boost libraries.

I said "a CI site," but perhaps it would be better to imagine a family
of sites, each on a different hardware/OS combination. I imagine an
initial period during which you'd have to follow separate links to get
test results on Windows 7, Windows 8, OS X 8, ... At some point clever
people would provide a way to obtain a consolidated dashboard. Perhaps
the documentation generation would be yet another site, equipped with
any special software required for documentation generation.

The above speculation is intended to address the question: how could
we provide online test results and documentation for a candidate
library that uses Boost.Build, without having to commit generated
files to the repository? Consider it an existence proof: there does
seem to be at least one way.

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Edward Diener-3
In reply to this post by pabristow
On 7/21/2014 7:02 AM, Paul A. Bristow wrote:

>
>
>> -----Original Message-----
>> From: Boost [mailto:[hidden email]] On Behalf Of Robert Ramey
>> Sent: 20 July 2014 17:59
>> To: [hidden email]
>> Subject: Re: [boost] [Boost Library Incubator] Unable to submit library
>>
>> Edward Diener-3 wrote
>>> On 7/20/2014 2:03 AM, Robert Ramey wrote:
>>>> Edward Diener-3 wrote
>>>
>>> I think you can appreciate that having to duplicate tests which
>>> already exist through bjam/Boost Build when the user clones the
>>> project is not something I really want to do. I really don't see the
>>> big deal of someone interested in my library cloning it locally under
>>> modular-boost and then having all the documentation and tests locally.
>>> I explain very carefully in my top-level *.txt files how to do all this.
>>
>> There's no disagreement here.  That's exactly how I envision that this site be
> used.
>>
>>> I do appreciate the work you put into it. But I think that anyone
>>> interested in a library in the Boost Library Incubator sight should be
>>> trying it out locally just like everyone does with Git projects.
>>
>> There's no disagreement here either.
>>
>> But there are a couple issues you've left unaddressed.
>>
>> a) One looking for a library can only find documentation for libraries already
> in
>> boost.  For the sandbox one had to download the package and
>> (maybe) build the documentation in order to see the decimation.  For me this
> was a
>> big problem which I addressed by requiring browsable html documentation.  The
>> github method - (has a minor/temporary problem - I know) is perfect for this.
> It
>> means one can browse the documentation immediately.
>> So this issue is resolved for me.
>
> The issue of generated (mainly html) files in GIT is still a nuisance.
>
> If you are a sole developer, then it is quite easy - you simply include all the
> /doc folder with /html etc in GIT.
>
> But if you are developing *with* someone else, these generated files are a PITA.
>
> You have keep reverting the /html files every time you want to GIT pull.
>
> And you have push the updated docs every time too - and these may be quite big.
>
> I don't see a better way round this yet.  Ideas?

I do not think that generated HTML documentation should be in Git. The
only reason I put it in for my VMD library is because it is on the Boost
review queue, so I am trying to make it easy for someone who might be
interested in the library to look at the documentation without having to
create it themselves. But really, with the proper jamfile in the docs
directory, anybody should be able to recreate the docs.

While I think it is an advantage of the Boost Library Incubator that
someone should be able to see the docs directly from the website, anyone
interested enough in a library should be willing to clone it locally and
regenerate the docs.


_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

pabristow


> -----Original Message-----
> From: Boost [mailto:[hidden email]] On Behalf Of Edward Diener
> Sent: 21 July 2014 14:13
> To: [hidden email]
> Subject: Re: [boost] [Boost Library Incubator] Unable to submit library
>
> On 7/21/2014 7:02 AM, Paul A. Bristow wrote:
> >
> >
> >> -----Original Message-----
> >> From: Boost [mailto:[hidden email]] On Behalf Of
> >> Robert Ramey
> >> Sent: 20 July 2014 17:59
> >> To: [hidden email]
> >> Subject: Re: [boost] [Boost Library Incubator] Unable to submit
> >> library
> >>
> >> Edward Diener-3 wrote
> >>> On 7/20/2014 2:03 AM, Robert Ramey wrote:
> >>>> Edward Diener-3 wrote
> >>>
> >>> I think you can appreciate that having to duplicate tests which
> >>> already exist through bjam/Boost Build when the user clones the
> >>> project is not something I really want to do. I really don't see the
> >>> big deal of someone interested in my library cloning it locally
> >>> under modular-boost and then having all the documentation and tests
locally.

> >>> I explain very carefully in my top-level *.txt files how to do all this.
> >>
> >> There's no disagreement here.  That's exactly how I envision that
> >> this site be
> > used.
> >>
> >>> I do appreciate the work you put into it. But I think that anyone
> >>> interested in a library in the Boost Library Incubator sight should
> >>> be trying it out locally just like everyone does with Git projects.
> >>
> >> There's no disagreement here either.
> >>
> >> But there are a couple issues you've left unaddressed.
> >>
> >> a) One looking for a library can only find documentation for
> >> libraries already
> > in
> >> boost.  For the sandbox one had to download the package and
> >> (maybe) build the documentation in order to see the decimation.  For
> >> me this
> > was a
> >> big problem which I addressed by requiring browsable html
> >> documentation.  The github method - (has a minor/temporary problem - I
know)

> is perfect for this.
> > It
> >> means one can browse the documentation immediately.
> >> So this issue is resolved for me.
> >
> > The issue of generated (mainly html) files in GIT is still a nuisance.
> >
> > If you are a sole developer, then it is quite easy - you simply
> > include all the /doc folder with /html etc in GIT.
> >
> > But if you are developing *with* someone else, these generated files are a
PITA.
> >
> > You have keep reverting the /html files every time you want to GIT pull.
> >
> > And you have push the updated docs every time too - and these may be quite
big.
> >
> > I don't see a better way round this yet.  Ideas?
>
> I do not think that generated HTML documentation should be in Git. The only
reason
> I put it in for my VMD library is because it is on the Boost review queue, so
I am
> trying to make it easy for someone who might be interested in the library to
look at
> the documentation without having to create it themselves. But really, with the
> proper jamfile in the docs directory, anybody should be able to recreate the
docs.
>
> While I think it is an advantage of the Boost Library Incubator that someone
should
> be able to see the docs directly from the website, anyone interested enough in
a
> library should be willing to clone it locally and regenerate the docs.

Historically, building the docs has been a step too far for most people.

Unless the build process can be fully automated, it's just not going to happen -
not just to peruse a library that may never make it.

I think that until we have fully digested modular-GIT, that's not going to
happen either.

Paul

---
Paul A. Bristow
Prizet Farmhouse
Kendal UK LA8 8AB
+44 01539 561830










_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Edward Diener-3
On 7/21/2014 9:21 AM, Paul A. Bristow wrote:

>
>
>> -----Original Message-----
>> From: Boost [mailto:[hidden email]] On Behalf Of Edward Diener
>> Sent: 21 July 2014 14:13
>> To: [hidden email]
>> Subject: Re: [boost] [Boost Library Incubator] Unable to submit library
>>
>> On 7/21/2014 7:02 AM, Paul A. Bristow wrote:
>>>
>>>
>>>> -----Original Message-----
>>>> From: Boost [mailto:[hidden email]] On Behalf Of
>>>> Robert Ramey
>>>> Sent: 20 July 2014 17:59
>>>> To: [hidden email]
>>>> Subject: Re: [boost] [Boost Library Incubator] Unable to submit
>>>> library
>>>>
>>>> Edward Diener-3 wrote
>>>>> On 7/20/2014 2:03 AM, Robert Ramey wrote:
>>>>>> Edward Diener-3 wrote
>>>>>
>>>>> I think you can appreciate that having to duplicate tests which
>>>>> already exist through bjam/Boost Build when the user clones the
>>>>> project is not something I really want to do. I really don't see the
>>>>> big deal of someone interested in my library cloning it locally
>>>>> under modular-boost and then having all the documentation and tests
> locally.
>>>>> I explain very carefully in my top-level *.txt files how to do all this.
>>>>
>>>> There's no disagreement here.  That's exactly how I envision that
>>>> this site be
>>> used.
>>>>
>>>>> I do appreciate the work you put into it. But I think that anyone
>>>>> interested in a library in the Boost Library Incubator sight should
>>>>> be trying it out locally just like everyone does with Git projects.
>>>>
>>>> There's no disagreement here either.
>>>>
>>>> But there are a couple issues you've left unaddressed.
>>>>
>>>> a) One looking for a library can only find documentation for
>>>> libraries already
>>> in
>>>> boost.  For the sandbox one had to download the package and
>>>> (maybe) build the documentation in order to see the decimation.  For
>>>> me this
>>> was a
>>>> big problem which I addressed by requiring browsable html
>>>> documentation.  The github method - (has a minor/temporary problem - I
> know)
>> is perfect for this.
>>> It
>>>> means one can browse the documentation immediately.
>>>> So this issue is resolved for me.
>>>
>>> The issue of generated (mainly html) files in GIT is still a nuisance.
>>>
>>> If you are a sole developer, then it is quite easy - you simply
>>> include all the /doc folder with /html etc in GIT.
>>>
>>> But if you are developing *with* someone else, these generated files are a
> PITA.
>>>
>>> You have keep reverting the /html files every time you want to GIT pull.
>>>
>>> And you have push the updated docs every time too - and these may be quite
> big.
>>>
>>> I don't see a better way round this yet.  Ideas?
>>
>> I do not think that generated HTML documentation should be in Git. The only
> reason
>> I put it in for my VMD library is because it is on the Boost review queue, so
> I am
>> trying to make it easy for someone who might be interested in the library to
> look at
>> the documentation without having to create it themselves. But really, with the
>> proper jamfile in the docs directory, anybody should be able to recreate the
> docs.
>>
>> While I think it is an advantage of the Boost Library Incubator that someone
> should
>> be able to see the docs directly from the website, anyone interested enough in
> a
>> library should be willing to clone it locally and regenerate the docs.
>
> Historically, building the docs has been a step too far for most people.
>
> Unless the build process can be fully automated, it's just not going to happen -
> not just to peruse a library that may never make it.

You have made a good point, but the principle remains the same:
generated information which can easily change when some "source" changes
is a PITA for any source control system.

>
> I think that until we have fully digested modular-GIT, that's not going to
> happen either.

For Boost libraries does anybody put their generated documentation on
Git ? I know that I don't for TTI.



_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Jürgen Hunold-2
Hi,

Am Montag, 21. Juli 2014, 09:40:22 schrieb Edward Diener:
> On 7/21/2014 9:21 AM, Paul A. Bristow wrote:

> You have made a good point, but the principle remains the same:
> generated information which can easily change when some "source" changes
> is a PITA for any source control system.
>
> > I think that until we have fully digested modular-GIT, that's not going to
> > happen either.
>
> For Boost libraries does anybody put their generated documentation on
> Git ? I know that I don't for TTI.

Most of them were added long ago in svn times.
"find libs -name "html" -type d | wc -l" finds 37 libraries with html docs
checked in.

Yours,

Jürgen
--
* Dipl.-Math. Jürgen Hunold  !
* voice: ++49 4257 300       ! Fährstraße 1
* fax  : ++49 4257 300       ! 31609 Balge/Sebbenhausen
* [hidden email]             ! Germany

_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Robert Ramey
In reply to this post by Nat Goodspeed-2
Nat Goodspeed-2 wrote
On Mon, Jul 21, 2014 at 7:02 AM, Paul A. Bristow
<[hidden email]> wrote:

Speaking from the viewpoint of "a little knowledge" (in other words,
beware!) I read through parts of the Boost.Build documentation a few
weeks ago and was a bit ashamed of the unkind remarks I myself have
made about it from time to time. It seems to me that it wouldn't be
too unreasonable to post a few cookbook Jamfile.v2 files for a
hypothetical simple Boost.Foo library, then for a somewhat less simple
Boost.Bar library: code and tests and documentation. (Let's just
stipulate that as your library's build requirements grow in
complexity, you must eventually bite the bullet and learn Boost.Build
yourself.)
I've been using Safe Numerics as a canonical example to illustrate
how I've envisioned that authors use this site.  For this purpose
I've used CMake as described in the Simple Tools section of the
website.  After years of dealing with Boost Build, I believe the
CMake solution is far superior on this context.

However, there is absolutely no reason that one can't include
JAM files in the site as well.  This would permit those interested
in using Boost Build to test Safe Numerics to do so.  But more
important it would provide a simple canonical example for
library authors who want to use Boost Build.  If you or anyone
else want's to provide some such files (with lots of comments!)
I'll gladly include them along with updated text in the website
to refer to them.
But a new library author, whose requirements are presumably
still pretty straightforward, could copy, tweak, iterate and ask
questions until s/he gets results.
Again, I wouldn't recommend this to new submitters - but if that
works for them - I'm all for it.


Now we enter the realm of fantasy.  ... <snip>

The above speculation is intended to address the question: how could
we provide online test results and documentation for a candidate
library that uses Boost.Build, without having to commit generated
files to the repository? Consider it an existence proof: there does
seem to be at least one way.

My view is that boost testing doesn't scale.

When it was conceived there were far fewer libraries than there
are now.  Testing takes longer than it used to.  But we have faster
machines so things have managed to keep up.  But, still, I feel reluctant
to add more tests (for example portable binary archives)  for fear of
slowing down the system even more.  How could we get to 500
libraries with the current system?

So my vision is entirely different.  In my world, each user tests the
libraries he's going to use on his own machine and posts the results
to a common dashboard - one per library.  The advantages are

a) it scales without limit
b) it doesn't require any boost infrastructure.
c) it automatically tests the platforms/os that users actually use
rather than having special boost testers select the platforms they
want to test with.
d) It doesn't waste time testing platforms/os combinations that no
one is actually using.
c) there is already free infrastructure available - CDash and several
CI websites.
d) It's ready to start using now and in fact. the incubator is already using it!

Were boost to evolve to use this approach, the only thing we would
need would be a website listing all the links to the dashboards.
(Hmmm - that's what the incubator is).

Robert Ramey
Reply | Threaded
Open this post in threaded view
|

Re: [Boost Library Incubator] Unable to submit library

Robert Ramey
In reply to this post by pabristow
Paul A. Bristow-2 wrote
The issue of generated (mainly html) files in GIT is still a nuisance.
I totally disagree with this.
If you are a sole developer, then it is quite easy - you simply include all the
/doc folder with /html etc in GIT.

But if you are developing *with* someone else, these generated files are a PITA.

You have keep reverting the /html files every time you want to GIT pull.

And you have push the updated docs every time too - and these may be quite big.

I don't see a better way round this yet.  Ideas?
I don't see any problem here at all.  From time to time the html files will
get of sync with the *.qbk files.  To sync them up, one of the developers
generates the new html and pushes it to the master branch - game over
and easy as pie.  Best of all - nothing more to distribute.  Anyone using
the incubator link will automatically be using the most recent version
on the master branch.  

Robert Ramey







_______________________________________________
Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
12