discussion:manual:chapter1:intro [newRPL User Manual]

discussion:manual:chapter1:intro

I rediscovered what Claudio said to me via PM on the hpmuseum.org forum, that every page has a possible talk page, like on mediawiki (old dokuwikis did not have this, see openwrt's dokuwiki or wiki4hp's dokuwiki). So there is a way to discuss contents without creating additional pages (and having the additional work to order those pages without littering the wiki). — pier4r 2017/04/23 09:02

At some point we should agree on conventions for formatting key combinations, and what we call certain keys (LS = left shift, I think we can all agree on that; but what about the keypad arrows?). For example, I've adopted bolding a key to denote key hold. — S. Martin (2017/5/5)

Yes I do agree on this, and we need a guideline even for internal wiki formatting. Trying to decode the formatting from the previous writing is not so trivial sometimes. — pier4r 2017/05/07 23:39

So I do need pointers in my searches since I'm searching with google on the hpmuseum.org for newRPL discussions and if I save here where I am, then I don't get crazy. Furthermore another person can start where I left.

So far I use the search string site:hpmuseum.org new RPL plus a time limit a month after another, so far I'm at April 2015 - May 2015 (excluding the big newRPL topic so far). I know that there is a thread in the general forum that has useful information about speed and batteries but I do not remember the title. For the big newRPL topic, I'm through up to post 20. — pier4r 2017/04/23 08:58

Information is scattered, I suggest you use the info you find to do your own testing with newRPL, and only write about what's actually in newRPL right now, because much of the things you will find are going to be obsolete.
The source code has a ton of information. For example there's a table of keys in hal_keyboard.c, with every single key assignment. C.L.

Thanks for the info, then I will reconsider my searching efforts. I will check the source and if it is not difficult for me I can try to explain what is going on. (The problem is that with one 50g, juggling betwen newRPL/2.15 is not so feasible. This until the newRPL does not have the usb connection) — pier4r 2017/04/24 08:00

If possible, get a second 50g. It makes comparisons between newRPL and the stock ROM so much easier! S. Martin

Yes that is my idea. I do think too it would help a lot, also being motivated just to 'use' it. — pier4r 2017/05/02 13:31

Should we put in place holders for things coming, like graphics (I thought I saw a post in the HP forum about this being in development)? Or just have the manual reflect what is in the current ROM? S. Martin

Yes, please. Let's have empty placeholders for graphics, the GUI, plotting, etc. We can leave the docs empty until the actual feature is implemented. C.L.

Ok. S. Martin

I think Port memory section should be removed. There's no such thing as port memory in newRPL.

Sure, if C.L. says so. I threw on port memory not knowing for sure how newRPL manages memory. S.Martin

Not sure how we should handle this chapter. It seems like the programming model will closely follow the 50g stock ROM, so would we just be duplicating a lot of docs already out there? Here's a thought: just discuss how programming is different in newRPL? S. Martin

I think this can follow closely the “Programming in newRPL” articles that are on the website. Even though it's quite similar to the stock rom, there's a lot of differences when it comes to local variable handling, sandboxing, secondaries that evaluate immediately, etc. that justifies writing the whole thing again. C.L.

Fair enough, sounds good. S. Martin

I also think that a manual should be as helpful as possible in itself. Would be a bit frustrating to say “well, now that you can play around with the basics you want to program, right? Sorry, check this manual and this chapter, you don't find the information embedded here, wrong site”. Instead existing information may be addressed as “also this and that document may give ideas how to approach RPL programming”. — pier4r 2017/05/02 13:33

I hope I get some focus to finish reordering the second part of the chapter5 ASAP, sorry for the delay.

About that, if one wants to show the reader an example how to use certain constructs in a program - it is just an excuse to pack together: newRPL experience, writing the wiki, exposing basic concepts - would it be accepted in the wiki? If yes, where? (To me it would be always yes, even if the wiki ends up being a sort of library of short programs)

I was thinking something like: namespace::chapter::examples::date_or_title where the example is named after the date (or a title) and linked from the main chapter page. Actually the same could be done for further notes, advanced sections, etc.

Or do we pack, at first, everything in one page and then we will refactor when the article grows too much? Like wikipedia does?

Pier 2017/05/27

Any answer on this? Also Claudio I'm going to PM you my workflow on the 50g once I got through this period (I have to search for a relocation, so I won't be so active until August I think), I sent it already to smartin and he suggested me to show it to you. If it is not a problem I can post it here too.

Pier 2017 06 24

If I understand your concern, you are worried that the programming page may become too long because of code examples? I would think a long page is ok since there is always the table of contents at the top for jumping to sections. On the other hand, if you are going to include sample programs (more than just snippets) maybe having a separate page ('RPL Programs') under chapter 5 as well, which could be linked to from the 'basics of RPL' page would make sense.

S.M. (2017-06-24)

(Sorry I'm not so active in those days. I hope to be back in August)
The Idea is from wikipedia and other wikis on which I contributed. In general one may fill a page and when this gets big (around 50 thousand chars), can be split in other pages. But here I wanted to avoid making the manual part boring.

Like: this and this command, the syntax is this at glance. Then for examples look there.

I guess your idea of making another page with examples with link, makes sense.

Pier (2017-07-23)

For this chapter I was thinking it would be for newRPL commands only (not duplicating all commands in the 50g stock ROM). Then, have the chapter organized by sections (categories), and newRPL commands listed alphabetically within the sections. I'll throw up a change to the sidebar showing what I had in mind. S. Martin

The bulk of commands will match the 50g. Some have minor differences (for example in DOLIST the number of lists is not an optional argument). What we need to do is to generate a basic template. Once the template is ready, I'll write some code to extract every command from the command database and create the entry in the wiki, with the name of the command prepopulated, and perhaps the on-calc help extracted from the project source code. This way we have a base that we can modify to include more information where more is needed. Other commands we can have a typical line saying “100% compatible with userRPL” and that's it. C.L.

Ahh, if it's that automated, great! S. Martin

A list of commands (although without description at the start) could greatly help. Because one may assume that the commands have similarities with those in the userRPL standard lib. Otherwise a user is left, for what I know, with google searches or the autocomplete that may be tiresome. Hence, could we have a list of commands, updated every now and then? Many thanks and - in the case - merry Christmas! — pier4r 2017/12/16 06:01

I think we need to add more things to this section. Some differences in formatting are starting to show between authors. We need to standarize everything and this section is the perfect place. For example, key presses. Let's come up with one and only one way to write them, put it in this section, then all of us will have to go over each and every section we already wrote and make sure every key press follows the formatting guidelines. C.L. 2017/05/11

Some suggestions for consideration (S.M. 2017/5/11):

LS = left shift

RS = right shift

LA = left keypad arrow

RA = right keypad arrow

UA = up keypad arrow

DA = down keypad arrow

BS = back space key

For hold operations, how about going back to the older 49 manuals that use & to denote key hold.

For example,

ON & UA = ON(hold) up keypad arrow = increase system precision

Also, all key presses should be referred to by the most appropriate keyboard label. So to access the main menu, refer to pressing SYMB key.

I like the suggestion of C.L of calc object/commands/etc.. being highlighted in red, like this: EVAL. And, how about having keys to press in bold, so the above example should be:

ON&UA

another example, where two keys are hold:

ON&A&C

but a non hold version could have a dash delimiter:

LS-EVAL = to activate PRG menu

I'm adding another section to chapter 1 that will outline the formatting conventions, whatever we decide on.

###

I normally try to follow, if a general guideline is missing (or not known), the local formatting of the article (this is suggested both by wikipedia and the google code guidelines) . For example in chapter 5 - the first iteration of reorganizing the content of the flow control section is still WIP - I will try to follow the same formatting shown in the part before the flow control, just it takes a bit due to several factors. Of course if someone is faster, well, this is a wiki!

Moreover I find the suggestion about keys ok, just, as whatever symbolism, if there is a guide for a user then and it is followed in non-ambiguous way, then there should be no problem. Just the difference between '-' and '&' may be subtle if one is glancing at the text. Maybe a comma like in: first this, then that? Anyway those are minor stuff, the important part is to be consistentPier4r 2017/05/17

I'd like to fix up the sections I worked on with the new key conventions I suggested. Perhaps C.L you could let me know if your happy with it? Comma separator versus dash:

LS,EVAL = to activate PRG menu

LS-EVAL = to activate PRG menu

Maybe I still prefer the dash, I feel like the comma may be getting a bit lost (at least on my screen)?

(S.M. 2017/5/17)

I'm more inclined towards the dash myself. To put it in perspective, I'm copying one paragraph from the menus section that uses lots of keys:

«quote»

Activating any tab in the main menu will change the active menu into the corresponding submenu. In the main menu, activating a tab using any Shift or Shift^hold combination will display the submenu in the secondary menu (by default Menu 2).

For example, after pressing P to bring the main menu, pressing:

A will show the Math submenu in Menu 1, the main menu is no longer visible in Menu 1.
RS-A will show the Math submenu in Menu 2, while Menu 1 still has the main menu available.

To go back to a previous menu in Menu 1, use RS-M. To go back to a previous menu in Menu 2, use RS&M (RS^hold-M ??). The last 8 submenus are remembered by the system, so it is possible to use this key to go back multiple times.

«End of quote»

Now it looks to me key presses need to be accented somehow, so I agree they should all be bold. The hold combination should/could be & and non-hold combinations should have a dash. For the casual reader, it won't be easy to remember that & means hold, how about one of these? (I edited the quote above with the first one, just for testing):
RS^hold-A
RS^h-A
RS_hold-A
RS_h-A

And how do we explain the alpha combinations? AL-C or Alpha-C?

Also, I would prefer to describe keys by the letters rather than by function (P instead of SYMB) unless there is no other choice, like ., SPC or ENTER. The reason is because the keys original meaning may not be related to what it does, like SYMB doesn't have anything to do with symbolics anymore, it brings the main menu, HIST has nothing to do with history, etc. And also because the symbol on the key may not be easy to type like the √X key, and this will become worse on future platforms like the “toolbox” key on the Prime, and the next 3 keys to the right of that one. Now if you are describing an example with trig functions, I think pressing COS makes sense, so in that case it's fine.

C.L. 2017/05/19

###
I agree with pointing out the easier unambiguous symbol to point out a key. So Q instead of Y^x . Moreover if we stick with the pattern, so letters, then it is even better.

For the hold part, I find better for a casual reader (me) to write it down. Maybe superscript/subscripts while very neat typographically are tiresome to write? I don't see any button for quick insertion of the tags.

Therefore my current view is:
sequence- LS-P (then why not '+' like all the keyboard shortcuts around that say like Ctrl+V ? Anyway, minor stuff, consistency is what matters) . As far as I understood it means I can press LS and then P without holding LS .
sequence- ALPHA-L , like before ALPHA then L .
hold sequence- hold(RS)-A , I hold RS while I press A . I would prefer such “function-like” notation that adapts well also when one has to hold two, or more, buttons, like hold(ON-C) . This is of course less pretty but to me has a good tradeoff between “it is easy to memorize” (instead of “what was it for hold? & or - ?” ), “it is flexible” (we can put inside many simbols), “it is not tiresome to type or edit”. Any variation of it is welcomed of course. Of course I would also stick with the guideline chosen or imposed, at the end a discussion cannot last forever.

Pier 2017 05 21

I think we are converging on a scheme, the only remaining question as I see it is how to denote a button hold. I really do like the superscript “hold” notation best, it seems the most intuitive to me and also gets out of the way of the main keys referred to. Perhaps a little more cumbersome to type in the wiki, but I think worth it. I'm going to update the first chapter section on notations to summarize the conventions.

Ok, now after writing it up, I realized we need some special notation for the arithmetic keys to avoid confusion with other tokens:

The basic arithmetic keys are referred to as: DV = divide (also Z), MX = multiply, SB = subtraction, PL = addition.

S.M. 2017/5/21.

OK, I think we'll do the ^hold, but I agree that is cumbersome to type, so I added a button (the last to the right), which inserts the ^hold text. As far as key names, I think we need to use the same string names that the custom keys have in newRPL, so the manual is consistent when the user goes to redefine his keys:

    'ON',KB_ON,
    'AL',KB_ALPHA,
    'LS',KB_LSHIFT,
    'RS',KB_RSHIFT,
    'BK',KB_BKS,
    'EN',KB_ENT,
    'UP',KB_UP,
    'DN',KB_DN,
    'LF',KB_LF,
    'RT',KB_RT,
    'SP',KB_SPC,
    'DOT',KB_DOT,
    '0',0,KB_0,
    '1',0,KB_1,
    '2',0,KB_2,
    '3',0,KB_3,
    '4',0,KB_4,
    '5',0,KB_5,
    '6',0,KB_6,
    '7',0,KB_7,
    '8',0,KB_8,
    '9',0,KB_9,
    'A',0,KB_A,
    'B',0,KB_B,
    'C',0,KB_C,
    'D',0,KB_D,
    'E',0,KB_E,
    'F',0,KB_F,
    'G',0,KB_G,
    'H',0,KB_H,
    'I',0,KB_I,
    'J',0,KB_J,
    'K',0,KB_K,
    'L',0,KB_L,
    'M',0,KB_M,
    'N',0,KB_N,
    'O',0,KB_O,
    'P',0,KB_P,
    'Q',0,KB_Q,
    'R',0,KB_R,
    'S',0,KB_S,
    'T',0,KB_T,
    'U',0,KB_U,
    'V',0,KB_V,
    'W',0,KB_W,
    'X',0,KB_X,
    'Y',0,KB_Y,
    'Z',0,KB_Z,
    'DIV',0,KB_DIV,
    'MUL',0,KB_MUL,
    'ADD',0,KB_ADD,
    'SUB',0,KB_SUB,

The custom key definition uses a 2-letter code, which is in the list above, except I changed the following ones because it will look better in the wiki:

DOT instead of DT
DIV instead of /
MUL instead of *
ADD instead of +
sub instead of -

Key combinations with these will look better spelled out: LS– is not clear, it's best to use LS-SUB. Similarly, LS-+ vs LS-ADD. The dot would be almost invisible, and DOT is much clearer than DT. Other than these changes, the list is exactly as accepted by the ASNKEY command. If we all agree, I'll put the entire list in the “Contributing” article. C.L. 2017/05/21

If you look at my Notation and conventions section in Chapter 1 I did use some different nomenclature than you use in your key definitions. I was concerned about using 'ADD', 'SUB', 'DIV' and 'DOT' since they are also built-in 50g commands (at least in the stock ROM), and I thought that might be a source of confusion? S.M. 2017/5/21 (or 5/21/2017, which is the USA way, but I was trying to be respectful of you all on the other side of the pond :)

You're right, I fixed all my dates to YYYY/MM/DD, that's the way it should be to keep it free from localization. I wouldn't worry too much about the command names, they are not in the keyboard so it should be clear from the context, or how else can we do it? perhaps fully spelled out? LS-MINUS LS-PLUS LS-MULTIPLY LS-DIVIDE C.L. 2017/05/23

Ok, agreed. I've updated the chapter 1 section on notations, and have fixed all my edits to reflect the key definitions. I was curious though, whether defining two key assignments to the same key ('Z' and 'DIV') has any impact on the newRPL OS? S.M. 2017/05/24

Ok great for the guideline, I hope to make as little confusion as possible. So let me see , LS^hold-P, awesome. The sup tags with a button are pretty neat.

Also for the timeline, In EU should be like 27/05/2017 but I learned using various OS that a proper way to name files after dates is the following format .

Pier 2017/05/27

—

I just realized that there seems two possible places where notation is defined and may produce confusion. Notations and conventions and Contributing to the wiki. I would suggest that one of those takes the lead (notation) and the other gets cleaned from references about the formatting conventions. Because it is quite likely that one will be older than the other sooner or later and confusion arise.

Oh another point, I just did the first pass conversion in the page The Command Line (woah how much did you write! I feel ashamed, but slowly I'll do my part too) and the arrow shorten names are, well, not so memory friend for me except for UP. Can we just leave “left, right, up, down” ? I mean those are at maximum 5 puny chars to write and unlikely we write them in series like “alpha-hold-right-shift-add” (I'm making up). Of course for the moment I used LF, rn, up, dn but I feel strange using them. I mean sometimes for me it is easier to write 4 chars without much mental effort, than to remember “wait wast it LFT or LF? ” Same for alpha rather than al. Backspace cannot be just DEL ? Just asking, otherwise I will try to comply as much as I can.

Pier 2017/06/04

Ok, I updated the page on contributing to the wiki, so that key press conventions link back to the Notations and conventions section of chapter 1.

S.M. 2017/06/05

I would assume that the desktop version of newRPL is a standalone version (that is, not emulating the arm processor), should the manual also cover it (because it may seem a 1:1 with the 50g, but it is not. For example the sd card image). I'm not sure whether is it intended to offer the newRPL desktop version as usable version (I would say yes, it is a great work).

Pier 2017/06/04

I raised this same issue with C.L. about a month ago (thought I did that in our discussions here, but it seems it was through a HP Museum PM), since I suggested renaming the wiki to include '50g', since it won't really reflect other hardware, at least initially. Here was C.L.'s response:

I'd say until I release newRPL on a different platform, there's no need to separate. Since the core works the same on any hardware, I think perhaps just reorganizing the chapter on keyboard would work, for example to have a section on the 50g keyboard and (hypothetically) a section on the Prime. But we can add that later without much trouble, for now let's assume newRPL on 50g is the only newRPL there is.

S.M. 2017/06/05

Ok good to know. Indeed I can see the desktop version as 50g simulator (although I think it has no emulation layer). Just because typing there is not so immediate, it is really like the calculator, like pressing Ctrl-+ to insert the program brackets and so on. Plus one (like me) could decide to first develop a stable version of an algorithm on the simulator and then pass to the calculator to minimize sd card transfers. Although as I asked on the MoHPC forum it is a bit unclear how can I pass just one object (a program) from the simulator to the sd. It seems I can save the entire state of the simulator, but nothing else.

Pier 2017/06/05

To Do:

Add some examples to the brief intro to show what RPL looks like (S. Martin)

discussion/manual/chapter1/intro.txt
Last modified: 2017/04/25 19:50
by smartin