koreader icon indicating copy to clipboard operation
koreader copied to clipboard

Quick start guide for kindle legacy and K4

Open Commodore64user opened this issue 1 year ago • 28 comments

Pinging @poire-z and @Frenzie and @offset-torque (anyone else?)

Since there appears to be only a single touch-based quick start guide available to all KOReader users, I took the liberty of making some adjustments to the guide to make it useful for NT Kindle users (not my best work though ;))

Since I am not entirely sure how to handle documentation, I am uploading it here for your consideration.

Quickstart guide k4

local quickstart_guide_kindle4 = T(_([[
<div class="logo">![KOReader](resources/koreader.svg)</div>

# Quickstart guide

* [User interface](#ui)
* [User interface tips](#uitips)
* [Accessing files](#afiles)
* [Transferring files](#tfiles)
* [Shortcuts](#short)
* [While reading](#reading)
* [Installing dictionaries](#dicts)
* [More info](#more)

---
You can access the complete user manual from [our GitHub page](https://github.com/koreader/koreader).
]])
..
_([[## User interface <a id="ui"></a>

<div class="img-block">![Touch zones](resources/quickstart/K4.png)</div>

- To show the **TOP MENU** or **BOTTOM MENU** press the **Menu** or **Press** keys respectively.
- The **STATUS BAR** can be set to show a multitude of information regarding your reading progress or device state.
]])
..
_([[## User interface tips <a id="uitips"></a>

- You can change the interface language using:

> **Menu ➔ ![Settings](resources/icons/mdlight/appbar.settings.svg) ➔ Language**

- If you press both **ScreenKB** + **Press** on an option or menu item (font weight, line spacing etc.), you can set its value as **DEFAULT**.  The new value will only be applied to documents opened from now on. Previously opened documents will keep their settings. You can identify default values as a STAR in menu or as a black border around indicators as seen below:

<div class="img-block break-before-avoid">![Default setting 1](resources/quickstart/defaultsetting1.png)</div>
<div class="img-block break-before-avoid">![Default setting 2](resources/quickstart/defaultsetting2.png)</div>

- You can see explanations for some items on the **TOP MENU** by pressing both **ScreenKB** + **Press** on the name of the option.
- You can **CLOSE** full screen dialogs (History, Table of Contents, Bookmarks, Reading Statistics etc.) by pressing the **Back** key.
- **SCREENSHOTS** can be taken by pressing the **ScreenKB** + **Menu** keys

<div class="img-block break-after-avoid">![Number picker](resources/quickstart/numberpicker.png)</div>

- In dialogs containing adjustment arrow buttons like the one above, you can use the directional keys to move around. If widgets have menus, pressing the **Menu** key should open them.
- You can toggle content selection mode by pressing either the **Up** or **Down** keys. The selection tool becomes available so you can select one or multiple words, for either dictionary, wikipedia or text look ups.
- You can highlight blocks of text by selecting multiple words with the content selection tool.
- You can move through your document with the **Left** or **Right** cursor keys which, should take you to the previous or next chapter respectively.
- The content selection tool's sensitivity can be adjusted in the **TOP MENU**.

> **Menu ➔ ![Typesettings](resources/icons/mdlight/appbar.typeset.svg) ➔ Selection on text**
]])
..
_([[## Accessing files <a id="afiles"></a>

The following methods are available for accessing your books and articles:

* File Browser
* Favorites
* History

You can also set KOReader to open with any of these dialogs on startup via:

> **Menu (in File Browser) ➔ ![Filebrowser](resources/icons/mdlight/appbar.filebrowser.svg) ➔ Start with**
]])
..
_([[## Transferring files <a id="tfiles"></a>

In addition to transferring files the same way you would with the built-in reader application, other options are available depending on your device:

1. USB Mass Storage mode within KOReader
2. Cloud storage (Dropbox/FTP/Webdav)
3. SSH/SFTP access
4. Calibre transfer
5. News downloader
6. Wallabag
]])
..
_([[## Shortcuts <a id="short"></a>

The following is a non-exhaustive list of shortcuts available. 

When inside the reading module:

- **ScreenKB** + **Up**: Table of contents
- **ScreenKB** + **Right**: Add a bookmark
- **ScreenKB** + **Down**: Book map
- **ScreenKB** + **Left**: Bookmarks, notes and highlights
- **ScreenKB** + **Press**: Save current page to location history
- **ScreenKB** + **Home**: Toggle wifi on/off
- **ScreenKB** + **Back**: Switch to previosly opened book

When using a virtual keyboard:

- **ScreenKB** + **Right**: Move cursor to right char
- **ScreenKB** + **Left**: Move cursor to left char
- **ScreenKB** + **Press**: Show special characters behind virtual keyboard keys
- **ScreenKB** + **Home**: Toggle virtual keyboard on/off
- **ScreenKB** + **Back**: Delete char
]])
..
_([[## While reading <a id="reading"></a>

<div class="table"><div>

You can change the font

**Menu ➔ ![Typesettings](resources/icons/mdlight/appbar.typeset.svg) ➔ Font**

</div><div>

Make font bigger

**Press ➔ ![Textsize](resources/icons/mdlight/appbar.textsize.svg)**

</div><div>

Make font bolder

**Press ➔ ![Contrast](resources/icons/mdlight/appbar.contrast.svg)**

</div><div>

Invert the colors (white text on black)

**Menu ➔ ![Settings](resources/icons/mdlight/appbar.settings.svg) ➔ Night mode**

</div><div>

Change many formatting options

**Menu ➔ ![Typesettings](resources/icons/mdlight/appbar.typeset.svg) ➔ Style tweaks**

</div></div>
]])
..
_([[## Installing dictionaries <a id="dicts"></a>

KOReader supports dictionary lookup in EPUB and even in scanned PDF/DJVU documents. To see the dictionary definition or translation, tap and hold a word.

To use the dictionary lookup function, first you need to install one or more dictionaries in the StarDict format. KOReader has an inbuilt dictionary installation system:

**Menu ➔ ![Search](resources/icons/mdlight/appbar.search.svg) ➔ Dictionary Settings > Download dictionaries**
]])
..
_([[## More info <a id="more"></a>

You can find more information on our GitHub page

[https://github.com/koreader/koreader](https://github.com/koreader/koreader)

You can find other KOReader users on MobileRead forums

[https://www.mobileread.com/forums/forumdisplay.php?f=276](https://www.mobileread.com/forums/forumdisplay.php?f=276)

---
<div class="generated">Generated by KOReader %1.</div>
]]),
  rev)

Quickstart guide legacy

local quickstart_guide_kindle_legacy = T(_([[
<div class="logo">![KOReader](resources/koreader.svg)</div>

# Quickstart guide

* [User interface](#ui)
* [User interface tips](#uitips)
* [Accessing files](#afiles)
* [Transferring files](#tfiles)
* [Shortcuts](#short)
* [While reading](#reading)
* [Installing dictionaries](#dicts)
* [More info](#more)

---
You can access the complete user manual from [our GitHub page](https://github.com/koreader/koreader).
]])
..
_([[## User interface <a id="ui"></a>

<div class="img-block">![Touch zones](resources/quickstart/K3.png)</div>

- To show the **TOP MENU** or **BOTTOM MENU** press the **Menu** or **AA** keys respectively.
- The **STATUS BAR** can be set to show a multitude of information regarding your reading progress or device state.
]])
..
_([[## User interface tips <a id="uitips"></a>

- You can change the interface language using:

> **Menu ➔ ![Settings](resources/icons/mdlight/appbar.settings.svg) ➔ Language**

- If you press both **ScreenKB** + **Press** on an option or menu item (font weight, line spacing etc.), you can set its value as **DEFAULT**.  The new value will only be applied to documents opened from now on. Previously opened documents will keep their settings. You can identify default values as a STAR in menu or as a black border around indicators as seen below:

<div class="img-block break-before-avoid">![Default setting 1](resources/quickstart/defaultsetting1.png)</div>
<div class="img-block break-before-avoid">![Default setting 2](resources/quickstart/defaultsetting2.png)</div>

- You can see explanations for some items on the **TOP MENU** by pressing both **Shift** + **Press** on the name of the option.
- You can **CLOSE** full screen dialogs (History, Table of Contents, Bookmarks, Reading Statistics etc.) by pressing the **Back** key.
- **SCREENSHOTS** can be taken by pressing the **Alt** + **Shift** + **G** keys

<div class="img-block break-after-avoid">![Number picker](resources/quickstart/numberpicker.png)</div>

- In dialogs containing adjustment arrow buttons like the one above, you can use the directional keys to move around. If widgets have menus, pressing the **Menu** key should open them.
- You can toggle content selection mode by pressing either the **Up** or **Down** keys. The selection tool becomes available so you can select one or multiple words, for either dictionary, wikipedia or text look ups.
- You can highlight blocks of text by selecting multiple words with the content selection tool.
- You can move through your document with the **Left** or **Right** cursor keys which, should take you to the previous or next chapter respectively.
- The content selection tool's sensitivity can be adjusted in the **TOP MENU**.

> **Menu ➔ ![Typesettings](resources/icons/mdlight/appbar.typeset.svg) ➔ Selection on text**
]])
..
_([[## Accessing files <a id="afiles"></a>

The following methods are available for accessing your books and articles:

* File Browser
* Favorites
* History

You can also set KOReader to open with any of these dialogs on startup via:

> **Menu (in File Browser) ➔ ![Filebrowser](resources/icons/mdlight/appbar.filebrowser.svg) ➔ Start with**
]])
..
_([[## Transferring files <a id="tfiles"></a>

In addition to transferring files the same way you would with the built-in reader application, other options are available depending on your device:

1. USB Mass Storage mode within KOReader
2. Cloud storage (Dropbox/FTP/Webdav)
3. SSH/SFTP access
4. Calibre transfer
5. News downloader
6. Wallabag
]])
..
_([[## Shortcuts <a id="short"></a>

The following is a non-exhaustive list of shortcuts available. 

When inside the reading module:

- **T**: Table of contents
- **Shift** + **Right**: Add a bookmark
- **Shift** + **Down**: Book map
- **B**: Bookmarks, notes and highlights
- **Shift** + **Press**: Save current page to location history
- **Shift** + **Home**: Toggle wifi on/off
- **Shift** + **Back**: Switch to previosly opened book

When using a virtual keyboard:

- **Shift** + **Right**: Move cursor to right char
- **Shift** + **Left**: Move cursor to left char
- **Shift** + **Press**: Show special characters behind virtual keyboard keys
- **Shift** + **Home**: Toggle virtual keyboard on/off
- **Shift** + **Del**: Delete word
- **Shift** + **Back**: Delete whole line
- **Sym** + **Alphabet keys**: symbols, numbers and special characters
]])
..
_([[## While reading <a id="reading"></a>

<div class="table"><div>

You can change the font

**Menu ➔ ![Typesettings](resources/icons/mdlight/appbar.typeset.svg) ➔ Font**

</div><div>

Make font bigger

**Press ➔ ![Textsize](resources/icons/mdlight/appbar.textsize.svg)**

</div><div>

Make font bolder

**Press ➔ ![Contrast](resources/icons/mdlight/appbar.contrast.svg)**

</div><div>

Invert the colors (white text on black)

**Menu ➔ ![Settings](resources/icons/mdlight/appbar.settings.svg) ➔ Night mode**

</div><div>

Change many formatting options

**Menu ➔ ![Typesettings](resources/icons/mdlight/appbar.typeset.svg) ➔ Style tweaks**

</div></div>
]])
..
_([[## Installing dictionaries <a id="dicts"></a>

KOReader supports dictionary lookup in EPUB and even in scanned PDF/DJVU documents. To see the dictionary definition or translation, tap and hold a word.

To use the dictionary lookup function, first you need to install one or more dictionaries in the StarDict format. KOReader has an inbuilt dictionary installation system:

**Menu ➔ ![Search](resources/icons/mdlight/appbar.search.svg) ➔ Dictionary Settings > Download dictionaries**
]])
..
_([[## More info <a id="more"></a>

You can find more information on our GitHub page

[https://github.com/koreader/koreader](https://github.com/koreader/koreader)

You can find other KOReader users on MobileRead forums

[https://www.mobileread.com/forums/forumdisplay.php?f=276](https://www.mobileread.com/forums/forumdisplay.php?f=276)

---
<div class="generated">Generated by KOReader %1.</div>
]]),
  rev)

Now, these graphics were taken from Amazon's own user guides so not sure if we can use them but here they are nonetheless.

Commodore64user avatar Aug 06 '24 01:08 Commodore64user

Just mentioning, I was also thinking of updating the Quick Start after dealing with the current user guide release. In the current version, poire-z adapted the QS from the file I prepared. So the workflow will probably be the same (I prepare the QS -> they convert it). I will wait for the others to join for now.

offset-torque avatar Aug 06 '24 01:08 offset-torque

poire-z adapted the QS from the file I prepared

We were young at the time: https://github.com/koreader/koreader/discussions/7898#discussioncomment-1016354

So the workflow will probably be the same (I prepare the QS -> they convert it)

And at the time, you didn't know about HTML/CSS, but now you do :)

Anyway, now that it's HTML and changes PR'able like any other file, anybody can make changes - and if you can't or don't feel like making these changes, it's better to provide plain text changes than a full PDF/ODT that one would have to re-extract/convert :/ If there's going to be sections dedicated to Touch/NT4/NTlegacy, I guess some sections will have to be under device checks, but the common sections should not be duplicated.

(I'm off for 2 weeks, with visits here every other other day.)

poire-z avatar Aug 06 '24 07:08 poire-z

I need some clarification. Since discussion started here, we can continue here for a while for continuity:

Questions:

  • Why can't quickstart be a regular EPUB file?
  • Will we ship the user guide with KOReader if I make it e-ink suitable?
  • If we ship the user guide it will be an EPUB, not this embedded in LUA thing. Is this correct?
  • If we ship the user guide, quick start will be obsolete since it can be included directly in the guide. Is this correct?

Assuming yes to all, I can make a user guide:

  • suitable for e-ink
  • which includes quick start
  • packed as EPUB

So we can ship it inside the app or make it download-on-demand to save bandwidth.

offset-torque avatar Aug 06 '24 07:08 offset-torque

Why can't quickstart be a regular EPUB file?

It could. But it didn't need to at the time: it's a single html file in our git tree (so easy editing), linking a few images that we ship, so it works standalone. Making it an EPUB would involve either doing that EPUB building/packing when building the packages, or having it done on the device. Both bring no benefit.

Will we ship the user guide with KOReader if I make it e-ink suitable?

We could, depends on its size and what it adds to the packages. Your main HTML file is 200Ko, but the images would probably make it bigger. And there are the translated versions.

If we ship the user guide it will be an EPUB, not this embedded in LUA thing. Is this correct?

There are 4 options:

  • you build the EPUB on your side, and the packages automatic build process includes it as-is
  • the package build process picks your HTML file(s) and the images, and it is this process (some scripting that @Frenzie will probably have fun doing :)) that creates the EPUB
  • we ship the HTML file and images (as regular files in the packages), and the EPUB is created on the fly on the device (like it happens with Wikipedia "Save as EPUB")
  • we ship the HTML file and images (as regular files in the packages), and we open it as is, like the current Quick Start (no real benefit to have it as an EPUB, see above).

If we ship the user guide, quick start will be obsolete since it can be included directly in the guide. Is this correct?

Probably. Dunno if we should have both a small quick start guide auto-opened for first users, and an impressive and intimidating User Guide :)

poire-z avatar Aug 06 '24 08:08 poire-z

Got it poire-z, clear answer. I will think about the best approach after finishing the current update.

Commodore64user as you can see, quick start is pretty stale and currently on hold. I can add your changes to the user guide in the current release if you give them to me in doc/odt format. And later I will add them to the QS alongside other changes.

offset-torque avatar Aug 06 '24 22:08 offset-torque

Commodore64user as you can see, quick start is pretty stale and currently on hold. I can add your changes to the user guide in the current release if you give them to me in doc/odt format. And later I will add them to the QS alongside other changes.

I know you must be having a busy time dealing with the user guide so no worries at all. What I would say is, focus on that 100% and the quick start guide next (in my opinion it should not go btw, as nobody wants to read a user guide when they have just installed new software, I mean, some people won't even read the 8 page quick start guide so...)

I was thinking that, in the worst case scenario, you could use these guides for the next release (they are not perfect bu better than no QSG at all), that way you get a bit more time to get everything just the way you want it.

Regarding the changes to NT, I'll put something together and will get back to you soon.

btw, are those images fine to use? or would we need new ones?

Commodore64user avatar Aug 06 '24 23:08 Commodore64user

An additional point is that the quickstart guide, besides being nicely small and self-contained, also loads instantaneously for the very same reason.

Frenzie avatar Aug 07 '24 06:08 Frenzie

If the quickstart guide is being updated for the K4, could a note be included with a close-up of the D-Pad and Centre button, and what the respective functions are? After the confusion with v2024.7, it would be nice to know what the intended defaults for the buttons are (and how to remap them to page navigation, if necessary).

Darthagnon avatar Aug 08 '24 21:08 Darthagnon

but what confusion? @Darthagnon, #11749 clearly states that left/right take you to previous/next chapter. I am not sure why anyone would find that confusing.

and what the respective functions are?

that is already [somewhat] described there (QSG). nevertheless we can't just describe everything, specially when it comes to something as easy as pressing one button to figure out what it does, I understand telling people about shortcuts, but what up and down do is somewhat easy for anyone to figure out on their own.

(and how to remap them to page navigation, if necessary).

that in my opinion is for a user guide, not a qsg.

Commodore64user avatar Aug 08 '24 22:08 Commodore64user

@Commodore64user

User guide and as an extension quick start is under my responsibility. Please don't respond to related user requests like you are the author. It might create confusion.

Any remapping of hardware buttons from the device defaults should be explained as the first thing. Function being "easy to guess" is not an excuse. If users still need to guess things after checking the related part of a guide, this is a failure of documentation.

Also documenting the buttons limits their scope of actions. Buttons can trigger different functions depending on the context (reader view, file browser) or time (press, long-press, longer-press). If we omit mentioning a button, users can't be sure that it has hidden functions like this.

So @Darthagnon 's request is reasonable and explaining two extra buttons don't even take space on an image. Pixels are free. Since I already added the linked D-pad changes to the guide to-do list, you don't need to do anything extra.

that in my opinion is for a user guide, not a qsg.

Correct. We can drop a note in quick start for discoverability like this: "You can remap these buttons to other functions. Check the full user guide for how-to."

offset-torque avatar Aug 08 '24 23:08 offset-torque

@offset-torque sorry I forgot about this, nonetheless here are some* (there are others still but this is already too much)

SHORTCUTS:

Menu: menu button should open all menus throughout the whole UI, not just the TOP MENU (but this is the main one). For example when using a widget like the dictionary one, it opens the hamburger menu.

While reading:

Up or Down: content selection (used for dict lookup, highlights and more) Left: previous chapter Right : next chapter

Left and right can now be also used for page turning should a user choose to. (MENU > cog > navigation > physical buttons > use left and right...)

ScreenKB (or Shift) + Up : table of contents ScreenKB (or Shift) + Left: bookmarks ScreenKB (or Shift) + Right : bookmark current page ScreenKB (or Shift) + Down: book map ScreenKB (or Shift) + Press : save current location to history ScreenKB (or Shift) + Back : open previous document (supported on filemanager too) ScreenKB (or Shift) + Home turn wifi on/off (supported on filemanager too) ScreenKB (or Shift) + LeftPgBack / LeftPgFwd Previous/next page link (useful for footnotes)

In content selection:

Note: content selection tool's sensitivity can be adjusted by going to (MENU > page > selection on text > 'last three options') [you might need to be 'not isTouch' in order to see them]

Up, down, right, left: Navigational to control selection tool Press: select ScreenKB (or Shift) + Up :: move up by 20% of screen height ScreenKB (or Shift) + Left: move left by 20% of screen width ScreenKB (or Shift) + Right : move right by 20% of screen width ScreenKB (or Shift) + Down: move down by 20% of screen height

Screenshots:

ScreenKB + Menu on kindle 4 or Alt + Shift + G: on all other hasKeyboard

While using a virtual keyboard:

Note: the virtual keyboard can now be hidden on hasKeyboard or K4 by going to (MENU > cog > Device > Keyboard > show virtual keyboard)

ScreenKB (or Shift) + Home: toggle virtual keyboard ScreenKB (or Shift) + Back: on k4 works as backspace. on other kindles deletes a whole line. ScreenKB (or Shift) + Up :: move up one line ScreenKB (or Shift) + Left: move left by one char ScreenKB (or Shift) + Right : move right by one char ScreenKB (or Shift) + Down: move down one line Sym + Alphabet keys: different characters and numbers (kindle only)

Search related: work from both FM and reader

Alt (or Ctrl) + S: full text search (this one only works in reader) Alt (or Ctrl) + D: dictionary lookup Alt (or Ctrl) + F: file search Alt (or Ctrl) + W: wikipedia search

Using dictionary widget:

ScreenKB (or Shift) + Left: previous result ScreenKB (or Shift) + Right : next result

NOTE: The font menu, no longer exists, so the 'F' shortcut is no more. So is "shift'+'PgFwd' to increase font size.

Commodore64user avatar Aug 26 '24 23:08 Commodore64user

Thank you. I was trying to write it from the PR thread but this is much tidier and complete. Integrating now.

offset-torque avatar Aug 27 '24 00:08 offset-torque

Forgot to add:

ScreenKB (or Shift) + Press: long press (hold) works throughout the whole UI as well.

Side question: will these "temporary" guides make the next release?

Commodore64user avatar Aug 28 '24 15:08 Commodore64user

I didn't understand "temporary", this section will be a permanent part of the main user guide. And then it will be transferred to the QS.

PROCESS: After writing this section (alongside others that will be included in this guide update) I will request proofreading and checking. After that round, section will be ready for publishing. This whole process will take a few days from now.

Depending on the next release date, there might be time to add this to QS. User guide update is not synchronized with the releases so I generally don't care about the release deadlines.

@Frenzie can you tell us the deadline for the next release?

offset-torque avatar Aug 29 '24 03:08 offset-torque

While preparing the images for the guide, I noticed something weird. It seems that you renamed some buttons and also replaced them in the official Kindle user guide image at the top of the thread (that's why I thought these are official names).

Because I was surprised at the name of these buttons, thinking "Who the hell names a button Press and why ScreenKB?" and apparently it is not Amazon. Real names for these buttons are Center select and Keyboard button according to the Kindle User Guide. What you did is like a car company referring to the steering wheel as CircDirection in their manuals. This is not ok. So I will correct them in our guide to their official names (which will also be the quickstart).

Also I will divide the touch/non-touch shortcuts into separate sections.

And I need the default KOReader function assignments of the hardware buttons (these will be written on the image):

  • What happens when users press a button (without any modifier). Menu, left and right is known from your text but there are 10 more buttons in the touch Kindle. What do they do?
  • Does their functions change according to the context like File Browser?

offset-torque avatar Aug 29 '24 06:08 offset-torque

@Frenzie can you tell us the deadline for the next release?

Fwiw no release illustration has been made yet. Presumably this weekend or the next, but we work on a combination of WID and WIHT (when I have time). ;-)

Because I was surprised at the name of these buttons, thinking "Who the hell names a button Press and why ScreenKB?" and apparently it is not Amazon. Real names for these buttons are Center select and Keyboard button according to the Kindle User Guide.

I don't know about the ScreenKB thing but for press that's not true. Amazon calls it press the 5-way in their documentation (or used to), see e.g. https://kindle.s3.amazonaws.com/Kindle%20User%27s%20Guide,%204A%20Ed.%20-%20English.pdf

Frenzie avatar Aug 29 '24 06:08 Frenzie

PS Also there's some blocker: https://github.com/koreader/crengine/pull/584#issuecomment-2316852795

Frenzie avatar Aug 29 '24 07:08 Frenzie

I don't know about the ScreenKB thing but for press that's not true.

kindle

offset-torque avatar Aug 29 '24 07:08 offset-torque

Not true [that this is some developer name], not not true [that they call it center select somewhere else].

Frenzie avatar Aug 29 '24 08:08 Frenzie

I didn't understand "temporary", this section will be a permanent part of the main user guide. And then it will be transferred to the QS.

I am talking about the quick start guides that currently don't exist on NT, and that I made some adjustments to in this ticket, so that at least there is something for the next release. By "temporary" I mean, they should at least be used for next release before you get to make a final version of them. I am not bothered about the user guide (you have that covered already), it is the quick start guide I am referring to here.

Regarding the button naming situation. No, I am not making up names, at least no how you seem to be imagining I am. I simply used the existing names in the code. None of the names for the keys have anything to do with me, they have existed for a very long time and, if you want to change their name for the user guide, that's up to you, but here on GH I'll continue to use their names as written in the code.

What happens when users press a button (without any modifier). Menu, left and right is known from your text but there are 10 more buttons in the touch Kindle. What do they do?

well they are sort of self-explanatory, menu opens the top menu, back takes you back, home takes you to the home folder. On FM the page-turn buttons move you across different content pages, so if you have a long list of books, that expands over three pages, that is how you reach them.

Also I will divide the touch/non-touch shortcuts into separate sections.

Do, whatever you see fit. You have a vision for the user guide. I am happy either way.

in any case, I ask again. Will my "temporary" (that you can find at the top of this ticket but should be replaced by another ones you'll make in future) quick start guides make it to the next release?

Commodore64user avatar Aug 29 '24 08:08 Commodore64user

Regarding the button naming situation. No, I am not making up names, at least no how you seem to be imagining I am. I simply used the existing names in the code. None of the names for the keys have anything to do with me, they have existed for a very long time and, if you want to change their name for the user guide, that's up to you, but here on GH I'll continue to use their names as written in the code.

But that's not an objection: that's an admission of guilt. :smile:

Frenzie avatar Aug 29 '24 08:08 Frenzie

No one is guilty of anything here. And if someone doesn't like "ScreenKB" then they shouldn't read this comment https://github.com/koreader/koreader/issues/12302#issuecomment-2311301134 ;)

pre edit: this is a joke, no offence intended.

Commodore64user avatar Aug 29 '24 08:08 Commodore64user

Frenzie - that they call it center select somewhere else

This is not "somewhere else" if you are implying that I just found a random document on internet. This is the official user guide of that device and they call it Center button which is very logical because it is a button at the center of the 4 arrow buttons:

https://kindle.s3.amazonaws.com/Kindle_Users_Guide_2nd_Ed.pdf

Regarding the button naming situation. No, I am not making up names, at least no how you seem to be imagining I am. I simply used the existing names in the code.

This is generally what happens when programmers try to write documentation. It comes out more similar to a developer documentation than a user guide.

if you want to change their name for the user guide

It is not about what I want. I have to change their names to the proper ones. This is how the concept of documentation works. We can't just pull internal variables to name the buttons that 50 million users already know under a different (and official) name. Otherwise whole user guide can just be a collection of links to github issues and PRs.

I will give a more appropriate example. There are routers that users can install OpenWrt firmware which is more similar to KOReader concept (open source software on generic hardwares). Now imagine, in their documentation they say "Press btn_res until you see the led_pwron blinks" instead of "Press the RESET button until POWER led blinks". Same situation here.

Will my "temporary" (that you can find at the top of this ticket but should be replaced by another ones you'll make in future) quick start guides make it to the next release?

You can just merge the section you wrote from the first message of this thread. I don't have any objections to this. (Since it will be temporary and will be corrected with the bigger quickstart update)

offset-torque avatar Aug 29 '24 09:08 offset-torque

This is not "somewhere else" if you are implying that I just found a random document on internet. This is the official user guide of that device and they call it Center button which is very logical because it is a button at the center of the 4 arrow buttons:

"They" is Amazon. I'm implying that Amazon consistently says "press the 5-way" in a different manual, i.e., somewhere else.

image

Edit: screenshot from the link in https://github.com/koreader/koreader/issues/12302#issuecomment-2316840419

Frenzie avatar Aug 29 '24 09:08 Frenzie

Nobody would have ever called that dumb thing Press if it weren't what Amazon calls it, is my point. It would have been called literally just about anything other than press. This is not a coding thing.

Frenzie avatar Aug 29 '24 09:08 Frenzie

I think I see what's going on here. The k2 has a stupid looking knob (more like a joystick) which I presume is what they called "5-way", with the k3 they ditched that and used cursor buttons and the infamous centre button ("Press") which Amazon may or may not refer to as "Press".

I think we should call it, from this point forward. "The button formerly known as Press"

Commodore64user avatar Aug 29 '24 09:08 Commodore64user

I think I see what's going on here. The k2 has a stupid looking knob (more like a joystick) which I presume is what they called "5-way", with the k3 they ditched that and used cursor buttons and the infamous centre button ("Press") which Amazon may or may not refer to as "Press".

Yeah, that sounds quite plausible. Early kindles had some... fun HID ^^ (c.f., the K1's roller).

NiLuJe avatar Aug 29 '24 10:08 NiLuJe

A roller doesn't necessarily pair well with early or perhaps even present eink, but I don't think it's such a crazy concept per se.

Frenzie avatar Aug 29 '24 10:08 Frenzie

@Frenzie I made a couple of illustrations which you can find at the top of this ticket (replacing the older Amazon ones), are you happy to upload those?

Commodore64user avatar Sep 29 '24 15:09 Commodore64user

Afaik traced photographs or drawings are still a copy, an unauthorized derivative work. :-/

Frenzie avatar Sep 29 '24 18:09 Frenzie