Page 1 of 2 1 2 LastLast
Results 1 to 10 of 13

Thread: Enhancements to the Command Manual - References

  1. #1
    Senior Member
    Join Date
    Jan 1970
    Location
    Perth, Western Australia
    Posts
    3,451

    Lightbulb Enhancements to the Command Manual - References

    Something that would help many users of Manual 2 (Commands) would be references to other commands.

    My suggestion is for (almost) every command, add one or two lines referring to Similar Commands and/or Related Commands.

    Eg1: For the "pause" command
    Similar commands: Sleep, Wait, Doze

    Eg2: For the "hserout" command:
    Similar commands: serout, sertxd
    Related commands: hsersetup
    Last edited by inglewoodpete; 17-03-2012 at 05:17. Reason: See? I just found "doze" in the manual and added it to the "pause" references

  2. #2
    Senior Member
    Join Date
    Feb 2011
    Location
    Cardiff,UK
    Posts
    3,431

    Default

    A PICAXE Thesarus ?

  3. #3
    Senior Member
    Join Date
    Aug 2011
    Location
    Hudson Valley, NY
    Posts
    400

    Default

    How about:

    Eg3: For the "PWMOUT" command:
    Related commands: STOP, END


  4. #4
    Technical Support
    Join Date
    Jan 1970
    Location
    UK
    Posts
    19,764

    Default

    Quote Originally Posted by Armp View Post
    Eg3: For the "PWMOUT" command:
    Related commands: STOP, END
    The online reference does contain functional command groupings and cross-references for individual commands -

    http://www.picaxe.com/BASIC-Commands

    I am sure there's going to be some debate on individual cross-referencing there and the suggestion above highlights one of the difficulties of that; particularly what does "related command" mean or what would readers be expecting - related by function, alternatives to use, or is affected by or has an affect upon ?

    The wider the relationship the more likely all commands relate to every other command which are already categorised under particular sections such as "Time Delays" so it could be said extensive cross-referencing adds no more and actually makes things less useful.

    Then there's the question of back-reference. If we accept STOP and END are related commands for PWMOUT, does it follow that PWMOUT is a related command for STOP and for END ? One can argue it both ways; yes for consistency, but not so much use for a user who simply wants to find the options for ending their program.

    It gets even more complicated when it comes to READTEMP, READTEMP12 and READINTERNALTEMP; all obviously related, but one can use a thermistor to measure temperature so are READADC and READADC10 related, and again for back-references ?

  5. #5
    Senior Member
    Join Date
    Jan 1970
    Location
    Perth, Western Australia
    Posts
    3,451

    Default

    Quote Originally Posted by hippy View Post
    The online reference does contain functional command groupings and cross-references for individual commands -
    http://www.picaxe.com/BASIC-Commands
    A useful webpage but it fragments the help away from the main command manual.

    Quote Originally Posted by hippy View Post
    It gets even more complicated when it comes to READTEMP, READTEMP12 and READINTERNALTEMP; all obviously related, but one can use a thermistor to measure temperature so are READADC and READADC10 related, and again for back-references ?
    I don't agree with ReadADC or ReadADC10 being related to reading temperatures. Usinging the same argument, spiin and readi2c etc could temperatures from suitable transducers too. Or serialin etc etc.

    Quote Originally Posted by Armp View Post
    Eg3: For the "PWMOUT" command:
    Related commands: STOP, END
    I'm not sure if Armp is just just having a stir of the pot or not. However, I don't think Stop has any relationship with PWMOut. Maybe there is room here for an additional category of related commands: Possible Conflicting Commands.

    My reason for making the suggestion is that during the development of my PICAXE programming skills, and I'm sure I still have a long way to go, there have been occasions where alternate and related commands would have helped me code more efficiently. This may have been by saving the development time of doing something twice or it could have helped me find related commands more quickly. I genuinely believe listing related commands would help both newcomers and more experienced programmers.

  6. #6
    Senior Member
    Join Date
    Aug 2011
    Location
    Hudson Valley, NY
    Posts
    400

    Default

    Quote Originally Posted by hippy View Post
    Then there's the question of back-reference. If we accept STOP and END are related commands for PWMOUT, does it follow that PWMOUT is a related command for STOP and for END ? One can argue it both ways; yes for consistency, but not so much use for a user who simply wants to find the options for ending their program.
    Actually STOP does mention PWMOUT:

    The stop command does not switch off internal timers, and so commands such as
    servo and pwmout that require these timers will continue to function.
    Example:
    Code:
    main:
    pwmout C.1,120,400
    stop
    However there is no reference under PWMOUT that points you to STOP to read this vital snippet, and deduce that if there's no STOP you're not going to get an output - see my recent thread. http://www.picaxeforum.co.uk/showthr...-Off-Frequency
    Last edited by Armp; 17-03-2012 at 15:43.

  7. #7
    Senior Member
    Join Date
    May 2011
    Location
    Atlanta, GA
    Posts
    775
    Blog Entries
    24

    Default

    Actually STOP does mention PWMOUT:
    I did not know that. . Live and learn...

    @IWP, One nightmare I remember was building an enterprises xref to an HP-UX audit a few years back. Built in Excel but xref to multiple teams, emails, patches, and HP tech responses on mutually exclusive issues was a wonderful tool but was nearly impossible to keep current.

    There is probably some double the volume and square the effort math involved. Outside of building a database of commands and indexing on command metadata, I would surely not wish the update effort on any RevEd employee. Even mechanized, it would be like keeping a wild animal as a pet... you would never know when the beast may turn on you and scramble its indexes!

    - Ray

  8. #8
    Senior Member
    Join Date
    Jan 1970
    Location
    Perth, Western Australia
    Posts
    3,451

    Default

    Quote Originally Posted by Armp View Post
    However there is no reference under PWMOUT that points you to STOP to read this vital snippet, and deduce that if there's no STOP you're not going to get an output - see my recent thread.
    Hi Armp, You may have misunderstood what was actually happening with PWMOut. Rather than risk having this thread go off topic, I have added some clarification to your other thread.

  9. #9
    Senior Member
    Join Date
    Jan 1970
    Location
    Perth, Western Australia
    Posts
    3,451

    Default

    I don't think it would be such a huge task to maintain the help with references. New commands are added every 1 to 2 years with the introduction of new models. The manuals have to be updated at that time anyway.

    I guess the question to ask here is: Are there plans to dispense with the PDF command manual? It appears that quite a lot of work has been put into the on-line manual that hippy referenced earlier: http://www.picaxe.com/BASIC-Commands. Perhaps the Programming Editor should be pointing it's help menu at the on-line version?

  10. #10
    Senior Member
    Join Date
    Feb 2011
    Location
    Cardiff,UK
    Posts
    3,431

    Default

    Quote Originally Posted by inglewoodpete View Post
    Perhaps the Programming Editor should be pointing it's help menu at the on-line version?
    May cause problems for schools, think about it, "Now class can everyone look at the 'high' command in the PICAXE manual"

    Then there are the pour souls, who believe it or not, are not always 'connected'

Tags for this Thread

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •