Enhancements to the Command Manual - References

inglewoodpete

Senior Member
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:

hippy

Technical Support
Staff member
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 ?
 

inglewoodpete

Senior Member
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.

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.

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.
 

Armp

Senior Member
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/showthread.php?20796-PWMOUT-on-20M2-Off-Frequency
 
Last edited:

mrburnette

Senior Member
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
 

inglewoodpete

Senior Member
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.
 

inglewoodpete

Senior Member
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?
 

srnet

Senior Member
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'
 

hippy

Technical Support
Staff member
I don't believe there are any plans to lose the PDF manual for precisely the reasons srnet notes and there's often a preference for something which has everything together in a single linear book format.
 

inglewoodpete

Senior Member
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'
Until today, I was unaware of the on-line version of the command "manual". This relates to the main reason why I started this thread. I can see the current revision and style of the on-line version is more to my liking: more advanced features. And I can see the need for a "book" or "text" for both the classroom and the "bedtime reading" that we often joke about.

I am also aware that all PCs running the Programming Editor are not always or not necessarily connected to the www and so a PDF version is still necessary. This has taken me in almost a full circle and now raises 2 points instead of my original 1!

1. The "related commands" for the PDF version of the manual that I original advocated. I'd still love to see it. (And it might cause further conjecture over what is and what is not a related command. ;)

2. An option in the new Programming Editor: on-line or PDF command help.
 

Hemi345

Senior Member
I think the most beneficial feature in the pdf manual, would be a link for every command that would take the reader to the online version so they could view the latest updates to that command and see comments posted. Some of the command references in the pdf version are meaningless for a beginner like myself and it wasn't until last week that someone lead me to the online version which was much more helpful for the advanced commands.

I still find myself reading through the pdf a lot, but this way, the pdf version wouldn't have to be updated and redownloaded as often.
 
Top