Cgeo: Incorporate usage guide into WP calculator

[Lineflyer]

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]

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

[Lineflyer]

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]

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]

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

[SammysHP]

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

[S-Bartfast]

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]

@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]

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:
```

Calculator Help

Tap coordinate buttons to toggle between digits and letters



Long-press on coordinate buttons to set custom a digit or letter (or space to hide)



The available operators for use in expressions are:

'+': &nbsp+42&nbsp and &nbsp40 + 2&nbsp

'-': &nbsp-42&nbsp and &nbsp40 - 2&nbsp

'': multiplication, &nbsp69&nbsp

'/': division, &nbspa/b&nbsp

'^': power notation, &nbsp2^4&nbsp

'%': remainder after division, &nbsp54 % 13&nbsp

'(' and ')': priority, &nbsp(1+2)/(a+b)&nbsp



A short video demonstrating the calculator can be found here: 4https://youtu.be/eN2y5mvJul4

```

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]

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]

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]

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

[SammysHP]

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

[S-Bartfast]

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]

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]

@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]

html is supported.

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

[S-Bartfast]

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]

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]

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

[Lineflyer]

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]

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]

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]

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

[SammysHP]

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

[Lineflyer]

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]

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

[S-Bartfast]

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]

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

[Lineflyer]

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

[S-Bartfast]

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

[kumy]

I vote for 2.

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

[S-Bartfast]

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

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

[kumy]

@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]

RIC.

[kumy]

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

[S-Bartfast]

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

[pstorch]

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

[Lineflyer]

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]

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]

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]

@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]

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

[Matze2]

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]

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):

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.

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.

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

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]

@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 [email protected]

[Matze2]

Done. :+1:

[Matze2]

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]

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

[Lineflyer]

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]

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