Shop OBEX P1 Docs P2 Docs Learn Events
Gold Standard Library — Parallax Forums

Gold Standard Library

LeonLeon Posts: 7,620
edited 2012-08-02 20:55 in Propeller 1
I have just downloaded the much-vaunted Gold Standard Library file (http://www.parallaxsemiconductor.com/support/goldstandard), and was surprised to find only one entry - FullDuplexSerial.spin and a couple of examples showing how to use it. Is there a problem with the concept or the way it has been implemented?

BTW, there is the same typo in both the examples - "in leiu of".
«13

Comments

  • g3cwig3cwi Posts: 262
    edited 2012-07-12 08:09
    Leon

    The link page suggests

    "Questions pertaining to our Gold Standard may be directed to [EMAIL="goldobjects@parallaxsemiconductor.com?subject=Gold%20Object%20Comment%20or%20Question"]goldobjects@parallaxsemiconductor.com[/EMAIL]. Please report bugs here."

    I hope that helps.

    Cheers

    Richard
  • LeonLeon Posts: 7,620
    edited 2012-07-12 08:14
    I'm not asking about the Gold Standard per se, but the Library!

    Is a typo a bug? It isn't in the Gold Standard Object, anyway, but in the examples.
  • jazzedjazzed Posts: 11,803
    edited 2012-07-12 08:23
    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.
  • LeonLeon Posts: 7,620
    edited 2012-07-12 08:31
    Given their importance, perhaps Parallax should devote some in-house resources to making them available.
  • RaymanRayman Posts: 14,826
    edited 2012-07-12 08:35
    To me, the ones from Chip Gracey are the "gold standard" and all others (even mine) are suspect...

    (although I might expand that to include ones from Beau and other Parallax employees...)
  • photomankcphotomankc Posts: 943
    edited 2012-07-12 08:40
    I was wondering if that was ever going anywhere either. The OBEX is fine when you want to peruse or get something slapped in an working quick but the fact that everyone writes things thier own way definately makes it a bit more difficult if you start adding objects from different folks.


    One thing I was wondering though: Is SPIN the direction they are still heading?
  • LeonLeon Posts: 7,620
    edited 2012-07-12 08:49
    The Gold Standard Spec. assumes Spin/PASM. Perhaps there will be a C spec. in due course, although C might not offer enough performance.
  • mindrobotsmindrobots Posts: 6,506
    edited 2012-07-12 09:03
    Resources, resources, resources......would be my guess.

    An offer was put out for volunteers and apparently not many took up the call. I would have tried but I'm not up to Gold Standard in any of my coding.

    A call was made for SimpleIDE translators and that worked well. Volunteers rise to the occasions they want to rise to.

    There are volunteers working on PropGCC and SimpleIDE (me, for one, and I can tell you how unreliable and fickle volunteers can be!)

    If Parallax has a revenue generating task that needs to get done (new product launch, major production run, etc.), then the full-time resources need to go there. Customer service issues need to be addressed daily, running the business needs to be addressed daily. If consultants, interested third parties, volunteers or passionate forum members can fill the gaps, then the gaps get filled. If not, then the gaps wait.

    For every volunteer initiative, you also need to have someone inside Parallax involved to be the official voice and to provide official oversight of the activity. This again goes back to resources - there are only so many people inside Parallax that have the time, skills and pay grade to champion projects and provide oversight.

    A lot of times, I think people forget that Parallax isn't a BIG company. Think about it, if you took them all out to lunch, you'd fill up 10 or 11 booths at a restaurant. With other micro manufacturers, you have customer service, documentation or tool departments that are as big as all of Parallax.

    Was it ambitious to spin off Parallax Semiconductor? Heck, yes! Is it accomplishing what it was meant to? Only Ken and Chip can answer that. Is it moving forward as fast as expected? Probably not.

    I'm sure it has a few links on the priority chain and the things that really need to get done are getting done.
  • jazzedjazzed Posts: 11,803
    edited 2012-07-12 09:18
    Leon wrote: »
    The Gold Standard Spec. assumes Spin/PASM. Perhaps there will be a C spec. in due course ....

    C has enough standard zealots already. Asking Parallax to impose a C standard on anyone is setting a trap. Don't go there.
  • pedwardpedward Posts: 1,642
    edited 2012-07-12 10:40
    According to Daniel, I was the only one to participate in the bounty. I used the proceeds from the bounty to get parts for the PropKEY prototypes.
  • Duane DegnDuane Degn Posts: 10,588
    edited 2012-07-12 10:47
    jazzed wrote: »
    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.

    What kept me from taking up the offer was the "first submitted wins" aspect. I didn't want to work on an object when someone else might also be working on the same object.

    I don't mind being paid in Parallax products, I just don't like gambling with my time.
  • jazzedjazzed Posts: 11,803
    edited 2012-07-12 10:55
    Duane Degn wrote: »
    What kept me from taking up the offer was the "first submitted wins" aspect.
    Oh my. Did you mention that in Daniel's thread?
  • Phil Pilgrim (PhiPi)Phil Pilgrim (PhiPi) Posts: 23,514
    edited 2012-07-12 12:38
    I'm not sure there's even universal agreement on the Gold Standard spec, even though it's published on the web. For example, I would prefer to see my own AutoDoc tags become part of the standard, as it makes documentation part of the Spin source, and the HTML conversion makes long objects easier to navigate for information.

    -Phil
  • PublisonPublison Posts: 12,366
    edited 2012-07-12 13:18
    Phil Pilgrim (PhiPi) wrote: »
    I'm not sure there's even universal agreement on the Gold Standard spec, even though it's published on the web. For example, I would prefer to see my own AutoDoc tags become part of the standard, as it makes documentation part of the Spin source, and the HTML conversion makes long objects easier to navigate for information.

    -Phil

    +1 on the AutoDoc. I think it's the next step in documenting code.

    Whether or not if Parallax implements it, I thing it should be used in all OBEX code. I will use this for any code that I upload to OBEX.

    Jim


    Jim
  • jmgjmg Posts: 15,183
    edited 2012-07-12 14:49
    Phil Pilgrim (PhiPi) wrote: »
    I'm not sure there's even universal agreement on the Gold Standard spec, even though it's published on the web. For example, I would prefer to see my own AutoDoc tags become part of the standard, as it makes documentation part of the Spin source, and the HTML conversion makes long objects easier to navigate for information.

    Looks impressive, but one item I could not find, is any link to the complete original ?
    If this is being used for web libraries, it makes sense to do it all on one page - comments and complete source.

    ie either a Source Code expand that is Full Source Code (with a select-button, copy clipboard, or a save-link ? )

    This would also be great for small size tutorials, and there an option to expand all of the 'Source Code' blocks, would make sense.
    Then the page comes up scan ready, and expand all is ok on small examples.
  • Phil Pilgrim (PhiPi)Phil Pilgrim (PhiPi) Posts: 23,514
    edited 2012-07-12 15:02
    jmg wrote:
    ...one item I could not find, is any link to the complete original ?

    The user already has the complete original. That's what they use to generate the HTML. Perl POD works the same way. In fact, I've got an even newer app that attaches a DOC button to the Prop Tool. By clicking the button, the Spin source in the tab showing is converted and launched into the user's browser. If there's no markup, the user is given a chance to have the program add the markup framework so they can fill in the details.

    -Phil
  • jazzedjazzed Posts: 11,803
    edited 2012-07-12 15:03
    Phil, Got a link to your source and binaries? I assume it's all perl.
  • Phil Pilgrim (PhiPi)Phil Pilgrim (PhiPi) Posts: 23,514
    edited 2012-07-12 15:07
    Not yet. (Yes, it's all Perl.)

    -Phil
  • Ken GraceyKen Gracey Posts: 7,400
    edited 2012-07-12 15:46
    Hey Leon,

    It's a resource issue. We have a number of objects we can include in the Gold Standard Library (those from AppNotes, products, etc.) but it's been a resource allocation issue for us. When customers call our FAEs that takes priority, as was the case this week. We'll get the Gold Standard Library up to par as quickly as possible given the staff and priorities.

    Ken Gracey
  • pedwardpedward Posts: 1,642
    edited 2012-07-12 15:51
    I was kind of envisioning the PHPDOC tags that Eclipse uses, but it looks like you are using PerlDoc prototypes.

    I think PHPDOC is a little bit richer: http://en.wikipedia.org/wiki/PHPDoc
  • Phil Pilgrim (PhiPi)Phil Pilgrim (PhiPi) Posts: 23,514
    edited 2012-07-12 16:03
    It's actually neither. Both PHPDOC and PerlPOD are much too obtrusive. The idea was for the tags to blend into the source as much as possible, so that the commentary could be read smoothly without the HTML conversion. This is done by adapting and standardizing the normal commenting practices that many people already use, in order to produce cues for the HTML conversion. The only real exception is the use of the backtick (`) to indicate boldface. But even that is such a small tittle in the source code that it does not distract from reading the comments.

    -Phil
  • Duane DegnDuane Degn Posts: 10,588
    edited 2012-07-12 16:38
    jazzed wrote: »
    Oh my. Did you mention that in Daniel's thread?

    No I didn't.

    I incorrectly assumed there would be plenty of takers and I didn't want to suggest the rules should be changed on my account.

    Once I finish my current Parallax project, I might take a stab at converting some of the requested objects to Gold Standard objects.

    I'm trying to follow those same standards in the code I'm writing. I was pleased to see I already used most of those conventions in my current code. The only change I need to make to my coding style is to capitalize all the letters of constants. I presently start constants with an underscore followed by a capitalizating the first leter.

    FYI, We humans generally read lowercase letters with more ease than uppercase letters. By making all the letters of a constant capital, we're forcing most of us to read a little slower. Now that I've voiced my objection to all capitals in a constant, I'll be quiet about it and follow the convention.

    One thing I didn't see mentioned was the capitaliziation of object nicknames. I generally capitalize the first leter of an object nickname (example "Pst."). Is there a standard for this?

    I also think (almost) all constants should be declared.

    I personally would like to see this:
    waitcnt(((clkfreq / 1_000 * Duration - 3932) #> 381) + cnt)

    written this way:
    waitcnt(((clkfreq / 1_000 * Duration - WAIT_OVERHEAD) #> MIN_WAIT) + cnt)

    Not that it bothers me much.

    There are plenty of other examples of "magic numbers" is see in other code that bug me much more.
  • Phil Pilgrim (PhiPi)Phil Pilgrim (PhiPi) Posts: 23,514
    edited 2012-07-12 16:44
    Among those "magic numbers" are the counter configuration values. It would be nice if there were standard names for them, but it's probably too late to make them reserved words as well.

    -Phil
  • jmgjmg Posts: 15,183
    edited 2012-07-12 16:58
    Phil Pilgrim (PhiPi) wrote: »
    The user already has the complete original. That's what they use to generate the HTML.

    Of course, but I thought the idea was to morph this to use for an equivalent to Gold Standard Libraries on the Web.
    There, you really want a one-pass / one step publish to a web page ?
    Since the formatter has the source as it creates the HTML, the logical next step to me is to have it create a whole source block ?
  • Phil Pilgrim (PhiPi)Phil Pilgrim (PhiPi) Posts: 23,514
    edited 2012-07-12 17:20
    No, that's not the way it's designed to work. You start with the entire source: that's what's in the library. If you want to render it in HTML as a documentation aid, you use the renderer, which could either be standalone, part of an IDE, or an online app. That's not to say that the library could not also include HTML'd versions. If you visit CPAN, you will see HTML'd PerlPOD. But the HTML files, which are generated from the markup in the Perl source, are not the source of the modules being documented. Those are downloaded separately.

    -Phil
  • Cluso99Cluso99 Posts: 18,069
    edited 2012-07-12 18:39
    IMHO the FullDuplexSerial posted doesn't make the cut. It does not add the enhancements by others - in particular I added buffer size to be declared in the con section (FullDuplexSerial_rr004 in obex). IIRC there are later additions that do better timing.

    I do understand its a resource issue.
  • jmgjmg Posts: 15,183
    edited 2012-07-12 19:51
    Phil Pilgrim (PhiPi) wrote: »
    No, that's not the way it's designed to work. You start with the entire source: that's what's in the library. If you want to render it in HTML as a documentation aid, you use the renderer, which could either be standalone, part of an IDE, or an online app. That's not to say that the library could not also include HTML'd versions. If you visit CPAN, you will see HTML'd PerlPOD. But the HTML files, which are generated from the markup in the Perl source, are not the source of the modules being documented. Those are downloaded separately.

    The problem with twin forks like that, is Google can land you on the HTML - and as it is now, you have no idea where the real source file is, that is why a self-contained web page makes more sense for code publishing.
    Users will arrive 'straight from google'
  • Phil Pilgrim (PhiPi)Phil Pilgrim (PhiPi) Posts: 23,514
    edited 2012-07-12 21:02
    It's just not a problem, jmg. Take a look at CPAN, where both the source and HTML docs are provided as separate links.

    A properly-designed repository will have the source plainly visible to download and, perhaps, the HTML in close juxtaposition. It would even be possible to produce the HTML on the fly when the source is uploaded. That would be the ideal case, at least.

    So enough pontificating already, okay? It just ain't gonna happen the way you propose.

    -Phil
  • msrobotsmsrobots Posts: 3,709
    edited 2012-07-12 22:34
    @Phil,

    I think @jmg want your documentation to replace the achiv-function. thus including the complete source of each obj as last tag in the documentation.

    If you do, then you can publish the documentation as is somewhere but all source files needed are included. The generated html is just some KB heavier...

    Great work you do there, thank you - I will DEFINITELY use it

    It is quite simple - It not just looks professional, that logo and that Toc. IT IS.

    Thank you for all that work Phil, I will use it.

    Enjoy!

    Mike
  • jmgjmg Posts: 15,183
    edited 2012-07-12 23:19
    Phil Pilgrim (PhiPi) wrote: »
    Take a look at CPAN, where both the source and HTML docs are provided as separate links.

    Err ?? the one I looked at, does exactly what I am suggesting.

    http://search.cpan.org/~thaljef/Perl-Critic-1.118/lib/Perl/Critic.pm

    This has the HTML, and at the very top, is a name called [Source], all on one page. I can open or save as.
    So anyone landing on the HTML, can instantly find the source.
    Phil Pilgrim (PhiPi) wrote:
    So enough pontificating already, okay? It just ain't gonna happen the way you propose.

    We must be looking in different places, because the CPAN I looked at, already does what I propose.
    It already has happened :)
Sign In or Register to comment.