The [Source] on the page you referenced is just a link to a completely separate page. It's not part of the HTML doc file itself. What my program does is to take a source file that the user already has and produce a single HTML doc file that can be viewed in a web browser. To link back to the selfsame source file from the HTML would be redundant.
jmg,
The [Source] on the page you referenced is just a link to a completely separate page. It's not part of the HTML doc file itself.
It is certainly part of the HTML web page, which is what the user lands on, and what they and google see.
Whether it expands on the same page, or opens another, is more of a detail thing.
I would consider an expand on the same page more self contained, and less context dependent, and there is nothing stopping both.
I did take a start at the bounty but was a time issue and the time/money thing didn't work out although a big portion of it was wanting to help the community at large. I may try again if I get some more free time (assuming the bounty is still offered)
As for documentation, I think mbed offers an excellent example of what's possible using auto documentation (doxygen in their case). It is nice to pull up an object and not only see the API but the source code as well.
To me Gold Standard Objects means it works and has been tested and blessed by Parallax.
It has nothing to do with what the source code's text looks like. Does not mean some code
writing standard of naming convention or even what methods are in the object.
To me we already have many Gold Standard Objects already tested by being used by
everyone for several years, ie Full Duplex Serial. Does not even need to be rewritten to
some source code standard .
Over the years I have seen to many programming API's with elegent written source code text
that did not work or even do what the doc said.
It is not how elegant the source code that made the code looks like but how bug free and stable
the code it generates that is the most important thing.
I agree that for an object to work without error is a necessary prerequisite for Gold Standard inclusion. But Parallax has accepted the additional role of educator to that of mere provider. So they want programs that are also well-written and annotated to make it easier for users to understand not only how to use them but how they work.
I'd rather have some nice cabinetry, joinery, nice finish. And a good essay on how it was done too. And good specs about how heavy a vase can be put on top before it cracks, how the finish holds up to sunlight and water. How it folds for storage.
Gold? It is unfortunate that the library is out there with only one book on the long dusty shelves. To the uninitiated visitor it looks soooo bleak. It needs books even with dog-eared pages that by that very fact show that they have withstood the scrutiny of many readers.
Sorry for the mixed metaphors.
Full Duplex Serial is long in tooth. It was the starting point for many other efforts that improve on it: buffer size and flexibility, handling of framing errors, support for other modes and handshaking, jitter performance. All of those are issues that have been addressed subsequently. For example, Phil's PB&J addressed the jitter issue like finely crafted dove tail joints. It is a fact in the end though that one single serial program is not going to fit all needs.
A library is a system of cataloging, not censoring, and at the front is a shelf with a sign that says, "we recommend..."
Well - I took some time to upgrade FullDuplexSerial from Gold Standard to AUTODOC Gold Standard.
The result is quite neat. But I can't upload .htm. So I added a zip containing ALL existing Gold Standard Objects with added AUTODOC comments and the resulting FullDuplexSerial_Doc.htm.
I agree about the participation: I didn't work on the Gold Standardization Project because I was afraid that I'd take my time crafting a well written documentation, and then somebody else would submit the same object before me.
I agree about the participation: I didn't work on the Gold Standardization Project because I was afraid that I'd take my time crafting a well written documentation, and then somebody else would submit the same object before me.
But why start anything then? Someone else has probably done it already, or done it better...... but you know the answer to that anyway
I haven't really been in on this thread or discussion but I kind of like to think that there should be a Gold Standard Committee (not GFC or GST!) that will help to get objects up to the Gold Standard. Or maybe we could adopt a bronze, silver and gold standard to allow objects to be improved and promoted in stages, that way some may not be so reticent in submitting . Initially an object is in prototype stage and improved and then it is released into the OBEX. At this point it is automatically "bronze" but may be promoted by the GSC to a higher level or at a later stage when it has been improved and resubmitted. Perhaps the object is not even OBEX worthy and is rejected altogether! Who can make this call? Well just as moderators are appointed and work to ensure the forum maintains standards, the GSC (or even just the OBEX committee) can be appointed by Parallax with nominations submitted via the forum.
GSC members may even judge objects and provide recommendations and or assistance for improvements to the submitter to foster higher and higher standards.
BTW, I'm getting to like coding and documenting in Google Docs, even though I have been using them ever since they've been around for all kinds of things, this is the first time I have used it for this purpose.
But why start anything then? Someone else has probably done it already, or done it better
There was a relatively short list of objects Parallax wanted converted to gold standard objects. It was implied the easier objects would be taken up quickly.
If we completed converting one of these objects a little later than someone else, our object wouldn't be used and we would not be compensated. (At least this is how I understood it.)
This is much different than when two forum member build similar robots or have some other project that appears to have already been done since these projects have an intrinsic reward beyond any monetary compensation. Converting a previously written object to gold standard format doesn't have the same intrinsic value as many other Propeller projects and the main two reasons for undertaking it (which include helping the community and $50 of Parallax products) would not be enjoyed if someone else completed converting the object first.
Ya, I was surprised too. It seems to be a resource issue.
What's more surprising is that there is a reward for people to make more gold standard objects, and there have been very few if any participants. It could be that people who know enough to actually write good drivers are not interested in meeting that particular standard.
Where is it stated that there is a reward or bounty for writing Gold Standard objects?
I share your frustration about the Gold Standard Library. We are ready to start approving and appropriately distributing a Parallax-approved library.
The reason that this isn't already done is because we set an ideal goal too high for our resources (some sort of committee thing if I recall correctly), and our engineers have had higher priorities relating to customer support.
It might be good for us to enlist a few customers for this purpose. First I need to refine our plan and I think we can get our act together.
As long as people aren't expecting miracle objects we can create the Gold Standard Library. Could be accomplished by October.
Ken, I think the one thing that frustrates and hinders the march towards your goal is transparency.
To put it simply, you need to create a Google Code project that you can host these objects on and allow the community to improve them.
A very good example is the FullDuplexSerial object. There are at least 3 different renditions of this object floating around OBEX. The first is yours, the second is an improved version that fixes some niggling issues, the third is a 4 port version that has the same resource requirements.
Having 4 serial ports possible with 1 COG and object seems like a no-brainer to me.
Parallax should take the steward role in this endeavour, not the benevolent dictator. The PropGCC project was run very nearly how I propose, and I think it has been a successful prototype of the process.
You need 1 or more Parallax stewards who can be "owners" and convey permissions to select community members.
Phil is a no-brainer for having commit access, but I'm certain he wouldn't step on anyone's toes by making unorthodox changes; having the ultimate power of "commit" will most likely make him and others more conservative and likely to discuss changes thoroughly before committing them.
Obviously, you need a community member or three that can really run the project so the Parallax staff can get back to the business of business.
This committee of 3 would be the community council who would have authority and the responsibility of maintaining the project. They would have control to veto changes or make sweeping changes, with Parallax's ultimate approval.
The project would then have a list of "lieutenants" that have access to commit changes. Community-at-large members would have read-only access and would need to forward patches to lieutenants to get them included, unless Google has a more granular approval solution that can allow trust-but-verify contributions.
Transparency is important to keep people interested and projects alive. OBEX has suffered from the walled garden approach, each object is maintained (if at all) by one person and community members cannot contribute fixes, even if they have a recognized standing. Further complicating things and diluting OBEX are the myriad of variants that exist specifically because the community cannot contribute to exiting code!
I'm not proposing to solve the OBEX Dilemma(tm) right now, just propose a way to make the GSL happen and give it longevity.
Thanks Perry - I concur with your suggestions. We're also happy with the way the GCC project and SIDE progressed in the open. Keep in mind that OBEX's roots were from 2005 and it was a different time in many ways.
Are you proposing that final, approved objects live on Google Code? I'm not sure this is the right tool for cataloging, searching, and accessing objects as easily as OBEX, even though it's very open. What are your thoughts about a tool that can host the objects?
The only way the GSL will be accomplished is with the community. Even if we wanted to put ourselves in control (and lose transparency) we simply can't do it do to limited resources. If we can really engage the community like some of our other projects I'm ready to lend support. I think I need a little more help identifying the starting point and structure. Google Code can be used to mature individual objects, but we need a place to allow them to be searched so the list could grow. Would like to know your thoughts here, too.
msrobots: It's in OBEX - very simple changes to make the buffer size a constant - see FullDuplexSerial_rr004
Did you get the timing fixes too?
I really think the spin code should have IN & OUT (translate straight to RX & TX) too to try and be inline with TV & VGA & Keyboards.
I think we don't need google code. All we need is a copy of OBEX, called "Gold Standard Obex" or something.
We need some people - supervisors - from Parallax staff to:
- select a good objects from OBEX as candidates to Gold status
- start and take care of the process of making them gold: bug fixes, commenting, beta testing, etc. This can be done here, on this forum, under supervision.
- debugged, commented and tested object should be then placed in Gold OBEX by supervisor.
I think we don't need google code. All we need is a copy of OBEX, called "Gold Standard Obex" or something.
We need some people - supervisors - from Parallax staff to:
- select a good objects from OBEX as candidates to Gold status
- start and take care of the process of making them gold: bug fixes, commenting, beta testing, etc. This can be done here, on this forum, under supervision.
- debugged, commented and tested object should be then placed in Gold OBEX by supervisor.
I think this is a good idea. I would much rather Parallax maintain control of the hosting of the OBEX and Gold OBEX.
BTW It does not stop a separate hosting of objects wherever if someone wants to give it a shot. If it works well, then the objects could be migrated. But personally, I still would rather it be simple and on Parallax. I am not much into git, etc.
Google Code is a good solution for maintenance and distribution. A serious effort needs source control and issue tracking.
For example, the bigger buffer FullDuplex thing is very valuable and is not currently implemented as cluso99 reminds us.
With Google Code anyone can log an issue on that or anything else. The gold standard maintainer can test and push a proposed version. If for some reason that version is not acceptable, the change can be easily reversed. Also a "branch" can be produced for people to test before the changes are approved and merged into the default repository. There are many advantages to this methodology.
The thing I care about is making sure the latest/greatest code can be packaged. We have some library code and examples in a repository now for the upcoming SimpleIDE integrated SPIN/C++ release. IMO, the code must be functional and up to date. There is no way the OBEX today would qualify as a library in a production package, and the library we have is long in the tooth.
There are too many advantages to using Google Code to pass up. If nothing else it needs to be used for efficiency.
Thanks Perry - I concur with your suggestions. We're also happy with the way the GCC project and SIDE progressed in the open. Keep in mind that OBEX's roots were from 2005 and it was a different time in many ways.
Are you proposing that final, approved objects live on Google Code? I'm not sure this is the right tool for cataloging, searching, and accessing objects as easily as OBEX, even though it's very open. What are your thoughts about a tool that can host the objects?
The only way the GSL will be accomplished is with the community. Even if we wanted to put ourselves in control (and lose transparency) we simply can't do it do to limited resources. If we can really engage the community like some of our other projects I'm ready to lend support. I think I need a little more help identifying the starting point and structure. Google Code can be used to mature individual objects, but we need a place to allow them to be searched so the list could grow. Would like to know your thoughts here, too.
Ken Gracey
Ken, I think Google Code was a good model for PropGCC, which comprises a number of sub projects.
GSL was never envisioned to be the size of OBEX, so I think Google Code would be a good incubator for GSL while a more mature plan is hatched for OBEX.
I've had a bit of experience with release management and source control, and I've given thought to how I'd like to see OBEX sorted out. That is a discussion to have further.
For now, I think GSL v1.0 should be comprised of no more than 10 core objects, with proper examples and documentation.
This is manageable within the context of Google Code and can be ported to a Parallax hosted framework in the future.
Since I have raised my hand, I would be willing to be one of the project leaders to see this forward. I would want to see at least 2 other community members be part of the leader group. Off the top of my head, I could nominate a few others for project leaders and a handful more as lieutenants.
The criteria for leaders is based on a long term understanding of Parallax goals, lieutenants would be based on contributions made via forum observations. I can think of several people that don't really align one way or another, but are great contributors.
And to sort of let you know where my politics lean, I'm a proponent of SVN.
Comments
The [Source] on the page you referenced is just a link to a completely separate page. It's not part of the HTML doc file itself. What my program does is to take a source file that the user already has and produce a single HTML doc file that can be viewed in a web browser. To link back to the selfsame source file from the HTML would be redundant.
-Phil
And - YES - this should be part of the Gold-Standard.
Those documentation-pages generated look and are professional.
EDIT
How about replacing(or adding to) readme.txt thru read_Doc.html in th archiv-function? we would have both! Source and docs!
/EDIT
Enjoy!
Mike
It is certainly part of the HTML web page, which is what the user lands on, and what they and google see.
Whether it expands on the same page, or opens another, is more of a detail thing.
I would consider an expand on the same page more self contained, and less context dependent, and there is nothing stopping both.
... except the guy who's actually writing the software, and that would be me.
-Phil
Enjoy!
Mike
You miss the point: The ability to link to the source IS an integral part of the doc's HTML page.
The CPAN page design understands why this matters.
As for documentation, I think mbed offers an excellent example of what's possible using auto documentation (doxygen in their case). It is nice to pull up an object and not only see the API but the source code as well.
It has nothing to do with what the source code's text looks like. Does not mean some code
writing standard of naming convention or even what methods are in the object.
To me we already have many Gold Standard Objects already tested by being used by
everyone for several years, ie Full Duplex Serial. Does not even need to be rewritten to
some source code standard .
Over the years I have seen to many programming API's with elegent written source code text
that did not work or even do what the doc said.
It is not how elegant the source code that made the code looks like but how bug free and stable
the code it generates that is the most important thing.
Tom
I agree that for an object to work without error is a necessary prerequisite for Gold Standard inclusion. But Parallax has accepted the additional role of educator to that of mere provider. So they want programs that are also well-written and annotated to make it easier for users to understand not only how to use them but how they work.
-Phil
Gold? It is unfortunate that the library is out there with only one book on the long dusty shelves. To the uninitiated visitor it looks soooo bleak. It needs books even with dog-eared pages that by that very fact show that they have withstood the scrutiny of many readers.
Sorry for the mixed metaphors.
Full Duplex Serial is long in tooth. It was the starting point for many other efforts that improve on it: buffer size and flexibility, handling of framing errors, support for other modes and handshaking, jitter performance. All of those are issues that have been addressed subsequently. For example, Phil's PB&J addressed the jitter issue like finely crafted dove tail joints. It is a fact in the end though that one single serial program is not going to fit all needs.
A library is a system of cataloging, not censoring, and at the front is a shelf with a sign that says, "we recommend..."
The result is quite neat. But I can't upload .htm. So I added a zip containing ALL existing Gold Standard Objects with added AUTODOC comments and the resulting FullDuplexSerial_Doc.htm.
Enjoy!
Mike
EDIT: added updated version.
"Multiple copies of object allowed: Yes|No"
For example you can run multiple copies of Full Duplex Serial, but only one copy of Full Duplex Serial Plus.
John Abshier
I haven't really been in on this thread or discussion but I kind of like to think that there should be a Gold Standard Committee (not GFC or GST!) that will help to get objects up to the Gold Standard. Or maybe we could adopt a bronze, silver and gold standard to allow objects to be improved and promoted in stages, that way some may not be so reticent in submitting . Initially an object is in prototype stage and improved and then it is released into the OBEX. At this point it is automatically "bronze" but may be promoted by the GSC to a higher level or at a later stage when it has been improved and resubmitted. Perhaps the object is not even OBEX worthy and is rejected altogether! Who can make this call? Well just as moderators are appointed and work to ensure the forum maintains standards, the GSC (or even just the OBEX committee) can be appointed by Parallax with nominations submitted via the forum.
GSC members may even judge objects and provide recommendations and or assistance for improvements to the submitter to foster higher and higher standards.
BTW, I'm getting to like coding and documenting in Google Docs, even though I have been using them ever since they've been around for all kinds of things, this is the first time I have used it for this purpose.
There was a relatively short list of objects Parallax wanted converted to gold standard objects. It was implied the easier objects would be taken up quickly.
If we completed converting one of these objects a little later than someone else, our object wouldn't be used and we would not be compensated. (At least this is how I understood it.)
This is much different than when two forum member build similar robots or have some other project that appears to have already been done since these projects have an intrinsic reward beyond any monetary compensation. Converting a previously written object to gold standard format doesn't have the same intrinsic value as many other Propeller projects and the main two reasons for undertaking it (which include helping the community and $50 of Parallax products) would not be enjoyed if someone else completed converting the object first.
There you find some more Archives of useful objects I 'AUTODOCed'.
@Leon: I removed that line completly out of the examples of FullDuplexSerial. Made no sense to me anyways...
Enjoy!
Mike
http://forums.parallax.com/showthread.php?137491-Gold-Standard-Objects-Up-for-Commission
Only certain objects qualify for a reward. If you are going to work on one let us know so we don't duplicate your efforts (please).
If they cannot make the cut, one wonders why noone bothers.
Enjoy!
Mike
I share your frustration about the Gold Standard Library. We are ready to start approving and appropriately distributing a Parallax-approved library.
The reason that this isn't already done is because we set an ideal goal too high for our resources (some sort of committee thing if I recall correctly), and our engineers have had higher priorities relating to customer support.
It might be good for us to enlist a few customers for this purpose. First I need to refine our plan and I think we can get our act together.
As long as people aren't expecting miracle objects we can create the Gold Standard Library. Could be accomplished by October.
Ken Gracey
To put it simply, you need to create a Google Code project that you can host these objects on and allow the community to improve them.
A very good example is the FullDuplexSerial object. There are at least 3 different renditions of this object floating around OBEX. The first is yours, the second is an improved version that fixes some niggling issues, the third is a 4 port version that has the same resource requirements.
Having 4 serial ports possible with 1 COG and object seems like a no-brainer to me.
Parallax should take the steward role in this endeavour, not the benevolent dictator. The PropGCC project was run very nearly how I propose, and I think it has been a successful prototype of the process.
You need 1 or more Parallax stewards who can be "owners" and convey permissions to select community members.
Phil is a no-brainer for having commit access, but I'm certain he wouldn't step on anyone's toes by making unorthodox changes; having the ultimate power of "commit" will most likely make him and others more conservative and likely to discuss changes thoroughly before committing them.
Obviously, you need a community member or three that can really run the project so the Parallax staff can get back to the business of business.
This committee of 3 would be the community council who would have authority and the responsibility of maintaining the project. They would have control to veto changes or make sweeping changes, with Parallax's ultimate approval.
The project would then have a list of "lieutenants" that have access to commit changes. Community-at-large members would have read-only access and would need to forward patches to lieutenants to get them included, unless Google has a more granular approval solution that can allow trust-but-verify contributions.
Transparency is important to keep people interested and projects alive. OBEX has suffered from the walled garden approach, each object is maintained (if at all) by one person and community members cannot contribute fixes, even if they have a recognized standing. Further complicating things and diluting OBEX are the myriad of variants that exist specifically because the community cannot contribute to exiting code!
I'm not proposing to solve the OBEX Dilemma(tm) right now, just propose a way to make the GSL happen and give it longevity.
Are you proposing that final, approved objects live on Google Code? I'm not sure this is the right tool for cataloging, searching, and accessing objects as easily as OBEX, even though it's very open. What are your thoughts about a tool that can host the objects?
The only way the GSL will be accomplished is with the community. Even if we wanted to put ourselves in control (and lose transparency) we simply can't do it do to limited resources. If we can really engage the community like some of our other projects I'm ready to lend support. I think I need a little more help identifying the starting point and structure. Google Code can be used to mature individual objects, but we need a place to allow them to be searched so the list could grow. Would like to know your thoughts here, too.
Ken Gracey
Did you get the timing fixes too?
I really think the spin code should have IN & OUT (translate straight to RX & TX) too to try and be inline with TV & VGA & Keyboards.
We need some people - supervisors - from Parallax staff to:
- select a good objects from OBEX as candidates to Gold status
- start and take care of the process of making them gold: bug fixes, commenting, beta testing, etc. This can be done here, on this forum, under supervision.
- debugged, commented and tested object should be then placed in Gold OBEX by supervisor.
I think this is a good idea. I would much rather Parallax maintain control of the hosting of the OBEX and Gold OBEX.
BTW It does not stop a separate hosting of objects wherever if someone wants to give it a shot. If it works well, then the objects could be migrated. But personally, I still would rather it be simple and on Parallax. I am not much into git, etc.
For example, the bigger buffer FullDuplex thing is very valuable and is not currently implemented as cluso99 reminds us.
With Google Code anyone can log an issue on that or anything else. The gold standard maintainer can test and push a proposed version. If for some reason that version is not acceptable, the change can be easily reversed. Also a "branch" can be produced for people to test before the changes are approved and merged into the default repository. There are many advantages to this methodology.
The thing I care about is making sure the latest/greatest code can be packaged. We have some library code and examples in a repository now for the upcoming SimpleIDE integrated SPIN/C++ release. IMO, the code must be functional and up to date. There is no way the OBEX today would qualify as a library in a production package, and the library we have is long in the tooth.
There are too many advantages to using Google Code to pass up. If nothing else it needs to be used for efficiency.
Thanks,
--Steve
Ken, I think Google Code was a good model for PropGCC, which comprises a number of sub projects.
GSL was never envisioned to be the size of OBEX, so I think Google Code would be a good incubator for GSL while a more mature plan is hatched for OBEX.
I've had a bit of experience with release management and source control, and I've given thought to how I'd like to see OBEX sorted out. That is a discussion to have further.
For now, I think GSL v1.0 should be comprised of no more than 10 core objects, with proper examples and documentation.
This is manageable within the context of Google Code and can be ported to a Parallax hosted framework in the future.
Since I have raised my hand, I would be willing to be one of the project leaders to see this forward. I would want to see at least 2 other community members be part of the leader group. Off the top of my head, I could nominate a few others for project leaders and a handful more as lieutenants.
The criteria for leaders is based on a long term understanding of Parallax goals, lieutenants would be based on contributions made via forum observations. I can think of several people that don't really align one way or another, but are great contributors.
And to sort of let you know where my politics lean, I'm a proponent of SVN.