Incorporate usage guide into WP calculator

Lineflyer commented 7 years ago

I am wondering if we could add a comprehensive usage guide by just adding a heading description to each "section" of the calculator view.

E.g. the coordinate view could be preceeded by something like: "You can click on any of the coordinate digits below to replace it by a variable for further calculation"

The variable section could be preceeded with: "For each upper case variable assigned above you can either provide a numeric value or an equation also containing new lower case variables"

etc.

SammysHP commented 7 years ago

Once a user is an "expert", such messages are annoying. I'd suggest a ? button next to ✔ and ✘.

Lineflyer commented 7 years ago

I'd suggest a ? button next to ✔ and ✘.

Good idea. This would allow us to put a quick guide and external links (e.g. to demonstration video) on a separate page. Question would be if @S-Bartfast would be able and willing to implement such a help page as well or we need to find someone else to contribute this?

SammysHP commented 7 years ago

There is a very simple solution: Just some HTML in a (almost) fullscreen webview. This could lead to a full integrated manual (assuming we find enough people writing it).

Lineflyer commented 7 years ago

Are you refering to an online version (getting the page e.g. from our webpage repo) or something offline?

SammysHP commented 7 years ago

Both is possible, but I was talking about an offline version (html file in the APK which is displayed via a webview).

S-Bartfast commented 7 years ago

I'll be happy take a look at implementing a help screen.

I'd also be more than happy for the videos to be used as demonstration material but I'm thinking I'll redo them if there going to be used officially, just to make them a little more succinct and polished.

Lineflyer commented 7 years ago

@S-Bartfast

I'd also be more than happy for the videos to be used as demonstration material but I'm thinking I'll redo them if there going to be used officially, just to make them a little more succinct and polished.

I also posted this in the closed issue, but maybe its better to post it here: I think redoing the videos would be great for later official use. However are you ok if I link this video to a german user group on Facebook (there are quite some nightly users there and I would like to get their feedback and test): https://youtu.be/eN2y5mvJul4

S-Bartfast commented 7 years ago

As mentioned in #6689 I've been working on this issue.

At present I've added a question mark to the top left corner of the calculator:

Which, when pressed, opens a simple HTML page. I'm not really sure on what to say on this page but as a start this is what I have so far:

The HTML to create this page is as follows:

<html>
<head>
<style>
body {
    background-color: #444444;
    color: #FFFFFF;
}
mono {
    font-family: monospace;
    font-weight: bold;
    background-color: #666666;
}
</style>
</head>
<body>
<h1>Calculator Help</h1>
Tap coordinate buttons to toggle between digits and letters<br />
<br />
Long-press on coordinate buttons to set custom a digit or letter (or space to hide)<br />
<br />
The available operators for use in expressions are:<br />
<mono>'+'</mono>: <mono>&nbsp+42&nbsp</mono> and <mono>&nbsp40 + 2&nbsp</mono><br />
<mono>'-'</mono>: <mono>&nbsp-42&nbsp</mono> and <mono>&nbsp40 - 2&nbsp</mono><br />
<mono>'*'</mono>: multiplication, <mono>&nbsp6*9&nbsp</mono><br />
<mono>'/'</mono>: division, <mono>&nbspa/b&nbsp</mono><br />
<mono>'^'</mono>: power notation, <mono>&nbsp2^4&nbsp</mono><br />
<mono>'%'</mono>: remainder after division, <mono>&nbsp54 % 13&nbsp</mono><br />
<mono>'('</mono> and <mono>')'</mono>: priority, <mono>&nbsp(1+2)/(a+b)&nbsp</mono><br />
<br />
A short video demonstrating the calculator can be found here: <a href="https://youtu.be/eN2y5mvJul">4https://youtu.be/eN2y5mvJul4</a>
</body>

Note, the example above was only made to show the idea and is in no way intended to be representative of the actual help page itself. Please do make any suggestions you think appropriate as to what the format and text on the page should be and feel free to completely disregard the example shown.

Cheers, Slarti.

SammysHP commented 7 years ago

Except of the doubled "Calculator help" heading this looks great! IIRC we have/had a question mark button in a dialog somewhere already.

S-Bartfast commented 7 years ago

IIRC we have/had a question mark button in a dialog somewhere already.

I had a look in the code for a question mark and couldn't find any. The 'tick' and the 'cross' images are called "ic_menu_done_holo_dark.png" and "ic_menu_cancel_holo_dark.png" respectively, but I couldn't find any question mark images.

After a bit of Googeling I was able to find an image called "ic_menu_help_holo_dark.png" which looks like this: But it didn't look that great on the calculator so I just created my own in a style that I thought looked appropriate. If anyone else is capable of making a more appropriate image by all means send it this way and I'll gladly use it instead.

Lineflyer commented 7 years ago

If technically possible this HTML page should be multi language supporting.

SammysHP commented 7 years ago

Maybe there's even a simple markdown library for Android.

S-Bartfast commented 7 years ago

If technically possible this HTML page should be multi language supporting.

We can most certainly make it so. There will have to be separate HTML pages for each supported language but we can select the appropriate page based on the devices 'locale':

Lineflyer commented 7 years ago

Just a small remark: I would rather place the "?" icon (or whatever icon is chosen) on the right side left of the "x" with some space seperating it from the "x". The main reason for this proposal is, that users will now potentially not identify it as a clickable icon but as a header icon for the menu.

Lineflyer commented 7 years ago

@rsudev and others: Does anyone know if we can load these HTML pages on Crowdin or do we need to handle the localization on Github in this case?

kumy commented 7 years ago

html is supported.

See https://crowdin.com/page/tour/supported-formats for other formats.

S-Bartfast commented 7 years ago

I would rather place the "?" icon (or whatever icon is chosen) on the right side left of the "x" with some space seperating it from the "x".

It can be done:

But personally I think it looks better on the left:

Lineflyer commented 7 years ago

Thanks...IMHO it would be better on the right side, as there are all the other user actions: Help, Abort, OK What do others think?

pstorch commented 7 years ago

In the Settings dialog we have this Infoicon which opens the help text: rps20170821_212534

Lineflyer commented 7 years ago

That is a good idea. Why create just another icon, while the user already knows one from other places within the app.

@S-Bartfast If you think the code for this help window is good, feel free to submit a PR.

S-Bartfast commented 7 years ago

Why create just another icon, while the user already knows one from other places within the app.

I'll look into it on the weekend

@S-Bartfast If you think the code for this help window is good, feel free to submit a PR.

The code is fine, but I didn't think the text of the actual help page itself is much chop.

I was hoping a better wordsmith (or at least someone with a better sense of aesthetic) would be able to formulate a page that would serve the needs of users better. As it is the page's fine for people who already know how to use the calculator but it's not really very instructional for new users. You know, it reads more like a Unix 'man page' than a help file ;)

While my intention has been to make the calculator itself as intuitive as possible if we're going to provide a help page we might as well use it to explain how the calculator works. So, what I have there is fine as a mock up but I wouldn't really consider it "production ready" or anything.

Lineflyer commented 7 years ago

The code is fine, but I didn't think the text of the actual help page itself is much chop.

Not a big problem I think. Once you made the structure available there will be people around from the community with ideas for filling it.

You know, it reads more like a Unix 'man page' than a help file ;)

Well IMHO thats not to bad. We should not make it a whole story to read but give a compact overview. We could still link to other sources from there.

S-Bartfast commented 7 years ago

Just had a look at using the "Settings Info" icon for the calculator help, and it actually looks pretty good:

SammysHP commented 7 years ago

Still looks like an icon of the dialog and not like something you could press.

Lineflyer commented 7 years ago

Still looks like an icon of the dialog and not like something you could press.

That was the reason for my proposal to have it on the right side left of "X" as this implies, that the user can interact with it.

Lineflyer commented 7 years ago

BTW: Why does the heading read "Coordinates" it should better be "Calculator" or not?

S-Bartfast commented 7 years ago

Still looks like an icon of the dialog and not like something you could press.

That's true, but I still think it's fine. If you're scratching your head trying to figure out how to use this feature I'm sure most users would try tapping that icon in relatively short order regardless of it's location. Sure, if it's over the left hand-side they'll probably try clicking the "Done" and "Cancel" buttons before tapping the "Settings Info" button but I'm sure they'll 'find it' after not too much searching.

BTW: Why does the heading read "Coordinates" it should better be "Calculator" or not?

No reason, I'll fix that.

And here is what it looks like with the "Settings Info" icon in the three locations:

Personally I just think it looks best with the 'help' button on the left and don't really think it needs to be made to look that much more 'pressable'. I mean, it is right in the location that the 'hamburger menu' is typically placed and anyone lost will surely try it eventually, and it just looks good there ;)

pstorch commented 7 years ago

I vote for the Info icon on the right side (last picture)

Lineflyer commented 7 years ago

I vote for the second picture (right side, but left of cancel/ok).

S-Bartfast commented 7 years ago

Huh, so we have three people with three different opinions.

kumy commented 7 years ago

I vote for 2.

On 1 we can think of an icon illustrate an "info popup"

S-Bartfast commented 7 years ago

On 1 we can think of an icon illustrate an "info popup"

Sorry, what do you mean by that? Something lost in translation??

kumy commented 7 years ago

@S-Bartfast I mean, my first impression was that it wasn't a button where user can interact with, but more some sort of visual information telling that the popup is of type informational (this image ~represent what I have in mind https://blog-static.hieule.info/wp-content/uploads/2015/04/example-of-laravel-output-message.png)

S-Bartfast commented 7 years ago

RIC.

kumy commented 7 years ago

@S-Bartfast Sorry, what does "RIC" mean? :)

S-Bartfast commented 7 years ago

Hehe: "Arr, I see" (just say it out loud) :)

pstorch commented 7 years ago

If it helps, I'm also fine with the second option (info icon as the first of the right buttons) 😉

Lineflyer commented 7 years ago

I asked some nightly users yesterday and showed them the options. They had another argument for not choosing option 3: In the normal WP editor "OK" is always the right most option, so the usage flow is interrupted here by having to click something in the middle.

Lineflyer commented 7 years ago

How shall we continue with this one. I would love to see the help page merged into the code, to take a look and - if needed - propose corrections and improvements in a next step.

@S-Bartfast Is this ready to create a PR?

Regarding the location of the info button we have no huge majority, but at least some people being OK with option 2 (info icon as first button of the right buttons).

S-Bartfast commented 7 years ago

I would love to see the help page merged into the code, to take a look and - if needed - propose corrections and improvements in a next step.

It can be seen and corrections proposed here in this thread, yeah? That's what the thread is for is it not?

Is this ready to create a PR?

Well, not really. The code is fine but the actual text and format of the page is far from done. I've proposed a bit of an outline here but don't really have the goods to actually prepare the page itself. As mentioned, this feature simply displays a HTML page and basically it's just waiting for a decent page to show, so anyone who cares to produce a simple HTML page is most welcome to do so ;).

Also pleas do feel free to discuss any thoughts or ideas of what should be included here. I mean, this is what the thread's for :) :)

Lineflyer commented 6 years ago

@S-Bartfast Meanwhile I started creating a web based user guide for c:geo and its quite complete. There is also a section about the waypoint calculator, where I tried to explain the working mode as easy as possible but hopefully still catching the main principle and possibilities: http://cgeo.droescher.eu/en/coordinatedialog#waypoint_calculator

You are welcome to provide your feedback (or I can create you an account on that Wiki, so you can edit directly).

S-Bartfast commented 6 years ago

Oh, great work Lars. I am most impressed. 👍

Matze2 commented 6 years ago

For completeness a section about coordinate input in "Plain" mode would be nice.

Some keywords here:

digits are limited by parenthesis
often waypoint formulas can be copied from the listing with no or little modification
fields for variables appear if formula is correctly parsed
some typical traps when copying formulas from the listing
- spaces at unexpected places in formulas
- "em" dash or "en" dash instead of dash for minus sign
- ":" as division sign

Unfortunately I have no time to write a complete documentation at the moment.

Matze2 commented 6 years ago

Ok. I wrote a first draft of what I had in mind. Feel free to take it as a start.

EDIT: added some (too big) screenshots

Coordinate input in "Plain" format

Entering coordinates or coordinate formulas in "Plain" mode works completely different compared to the fixed formats. First change the "Coordinate format" to "Plain". The N/S and W/E coordinate part can be now entered in a free text field in "DDD°MM.MMM" or similar format. With "Plain" it is possible to use formulas directly within the coordinate pattern: single or multiple digits of a coordinate can be replaced with formulas surrounded with parenthesis. Often cache listings provide waypoint coordinates already in the expected format, These can be copied from the listing directly into the waypoint calculator.

Example (from GC4QT5M):

screenshot_2018-07-30-15-36-46

Copy&Paste the North part into the North input field. Do the same for East. If the coordinate contains formulas with variables the corresponding variable input fields appear below.

screenshot_2018-07-30-15-41-10 The formula produces input fields for I, J, K, L, M and N. You can fill the variable fields with values in the same way as with the fixed formats described above.

As soon as the input for all variable fields is complete the result prediction usually turns into white and shows the calculated coordinate.

screenshot_2018-07-30-17-01-14

In some cases the result field still stays gray because the coordinate parser could not interpret the initial coordinate input correctly.

screenshot_2018-07-30-17-01-26

Typical reasons are:

lower case variable names; variables must consist of capital letters
space between digits within a group (N45° 5.(K) (I/N)(K+L+M+N))
space before the degree sign (N45 ° 5.(K)(I/N)(K+L+M+N))
space before the decimal point (N45° 5 .(K)(I/N)(K+L+M+N))
space after the decimal point (N45° 5. (K)(I/N)(K+L+M+N))
wrong minus sign: there are many different dash signs - only the standard hyphen/minus sign ("-") is accepted
wrong multiplication sign: sometimes an "x" or an interpunct ("·") is taken as multiplier sign instead of an asterisk ("*")
wrong division sign: sometimes a colon (":") is taken as division sign instead of a slash ("/")

Lineflyer commented 6 years ago

@Matze2 I would like to invite you to add it into the Wiki yourself. If you provide your mail address to me (is there a PM possibility via Github?!) I create an account for you.

Edit: Just contact me via support@cgeo.org

Matze2 commented 6 years ago

Done. :+1:

Matze2 commented 6 years ago

By the way. While creating the screenshots above I had a crash in the calculator when turning it from portrait to landscape. Still trying to reproduce it...

Matze2 commented 6 years ago

I extended the existing calculator documentation with the Plain mode as described above. Feel free to review, comment and correct.

Lineflyer commented 6 years ago

Thanks @Matze2 I think it is a really good extension of the guide. I only modified some styling and changed one sentence in order not to always refer to North and East (there are also c:geo users in the S and W area ;) ).

Lineflyer commented 6 years ago

I think we can close this for now. The guide is in the user guide and can be advanced anytime on that Wiki

cgeo / cgeo

Incorporate usage guide into WP calculator #6664

Coordinate input in "Plain" format

Example (from GC4QT5M):