User Guide Maintenance

[offset-torque]

ATTENTION PLEASE: This thread carries on from the original user guide discussion thread.

Archived original thread covers the discussions for the PDF version and can be found here: #8058

[offset-torque]

CONTRIBUTING TO THE USER GUIDE

‼️ If you want to make changes to the user guide please read this message carefully.

✅ If you are not changing anything, you can skip this message and write in this thread directly.
Examples: You just have a request or want to report something is missing in the guide.

---

Our user guide is written by a single person (me) with the feedback of devs.
So it is not a collaboratively created document with many authors.
Core principles of this guide are functionality and usability.
Aesthetics comes after these requirements.

If you want to change something in the guide, you should first write in this thread:

• What you want to change
• Why is this an improvement over the current state

Changes that are welcome

• Missing topics: Features of KOReader that you couldn't find in the guide
• Language improvements: Explanation is not clear enough, spelling/grammar mistakes etc.
• Topics that are not directly a feature of KOReader but might help users like the "Optimizing manga for your mobile reader device" section in the guide
• CSS changes that fix some broken behavior with mobile devices or some browsers

Changes that you should be careful about
Any style changes including:

• Font type and properties
• Margins, indents and white spaces
• Colors

Any of the changes proposed in this second group should follow the Web Content Accessibility Guidelines, especially in contrast and readability areas. And you should be able to explain how your change improves the readability, based on design and usability principles. Also if you propose a change to the colors, you should provide a palette which has enough contrast and separation and that is also optimized for color blindness.

Please only suggest a change if you are sure that it will improve the experience of the users reading this guide.
(As an example, you might enjoy "low-contrast pastel colors with tiny fonts" in your text editor, but that is definitely not suitable for this guide.)

⚠️ Any PRs that bypasses this thread will be ignored

[sonix-github]

I would like to contribute to translation of the user guide. Where can I find some kind of template for translation, please?

[Frenzie]

Nothing of the sort exists as of yet, but it should be possible to add it to Weblate.
https://docs.weblate.org/en/latest/formats/html.html

[sonix-github]

Great. I'm looking forward to it :)

[offset-torque]

@sonix-github

I guess that you want to contribute Slovak translation since you added the Slovak keyboard before. I just checked the user guide page translated into Slovak with Google Translate. I looked at random parts and to my surprise they are pretty good (I try to keep sentences short and clear in the English version for our non-English users so that helped maybe). Please have a look yourself. Only possible problem might be menu items in green text.

So what I am saying is, instead of translating all of the guide yourself (which is a substantial effort), you can just proofread a Google translated version which would be much easier.

[Frenzie]

As a quick note on that front, I find that DeepL and perhaps also ChatGPT 3/4 provide a higher quality, more natural translation than Google. But I say that mainly on the basis of Dutch/English/German/French; it might be different for Slovak.

[sonix-github]

@offset-torque: yes, I meant translation to Slovak
No problem for me to translate or proofread machine translation. I regularly contribute to translation of Koreader strings via Weblate

[offset-torque]

Frenzie - I find that DeepL and perhaps also ChatGPT 3/4 provide a higher quality, more natural translation than Google.

It was missing but now I checked again and DeepL added Slovak it seems. Slovak language is generally missing from all translation services/models. Closest thing you can find is Czech language instead, which is very similar to Slovak so they don't bother with a smaller language I guess. GPT3 was prone to hallucinating in Slovak because of sparse training data I think. I haven't checked GPT4 yet.

Maybe we can add some kind of translate widget to the user guide page like some websites do, so users can translate it on the fly to their language.

What do you think Frenzie ? Better than nothing I guess, but I don't know the downsides (Also I don't know how good it is for CJK languages).

[Frenzie]

I'm inclined to think people can enter the link in Google Translate themselves if they want to, but if you want they made it simple to add.

[Frenzie]

@offset-torque It looks like I'll have to rename it to en.html for Weblate, but presumably other variations like index-en.html or index.en.html would also be possible if you prefer something like that.

[offset-torque]

Whichever one you see appropriate, Frenzie. You know this system better than me.

[Frenzie]

This side of Weblate is all new to me too. But I'll make it en.html then.

[Frenzie]

@sonix-github https://hosted.weblate.org/projects/koreader/user-guide/ now exists. Please let me know if you see anything strange.

[sonix-github]

@sonix-github https://hosted.weblate.org/projects/koreader/user-guide/ now exists. Please let me know if you see anything strange.

Thanks @Frenzie It seems OK. Im going to start the translation to Slovak language

[poire-z]

Will this translation survive if the change color: #009788 to some other value, or replace the long style= with class=?

It feels it may be too early to start tranlating this big html file: it feels it needs some bit of cleaning and normalisation with proper class names instead of inline CSS, and maybe more line breaks in the source file to expose translatable text from the HTML noise, which would make the strings available to translators also simpler.

[offset-torque]

I agree with what poire-z said. Although I tried to use classes to make changes easier later, some "style" exceptions exist like that example. Also I didn't think about translation compatibility so yes it can be optimized to make translator's job easier. I am sure things can be more elegant but my CSS knowledge is very basic so any help/suggestion is welcome.

[sonix-github]

I am familiar with basic HTML syntax, therefore I am aware of preserving the tags. I can also contribute to translation of PDF user guide to Slovak language.

[poire-z]

I guess you are, but other translators might not be :)
And if we later decide to clean the HTML file, by for example adding a \n after KOREADER USER GUIDE, what you have translated today may be lost/not found to associate as a translation to KOREADER USER GUIDE (but I have no idea how clever is Weblate), and you may have to redo many of the translations...
And if there are too many translation works already done, we may be lukewarm at touching/fixing the source HTML and break them all, and we'd be stuck with some imperfect source (and imperfect past translations, and futur translations) forever... (ie. if we want to have it fully classname based if we want to have CSS themes, ie. the current smart colors one, and a pure black & white for eInk, etc...)
Just mentionnig that, better go slow and think than rush and be stuck :)

[sonix-github]

You are right @poire-z so I am going to "stand-by" mode with translations :)

[poire-z]

QUESTION: THIS SWIPING FEATURE IS “ON” BY DEFAULT, RIGHT ?

Right.

Toc, Alt ToC : all good, no comment.
(May be a sentence that Alt ToC is only available on CRE document, while Custom ToC is available on all types.)
Wording, missing "be"in new menu items will added to the user interface

And you can disable this feature completely in the same way you enabled it, if you want to return to the original ToC.
I think you can say that it will not be lost (I think ? don't remember :/), so you can switch between these 2 ToC as needed.

👍 on the explanations and how to for hidden flows !

These hidden sections will not be shown in your Progress bar.
I think this is wrong: we still show all of the book in the progress bars of footer and skimto widgets. The hidden flow sections may be gray though.

poire-z, can you explain “Clear inactive marked pages” option in a few sentences. I understood that it is related to the orphaned/overlapping markings of the pages but I couldn’t write it as a coherent example scenario

The ConfirmBox text says: Inactive marked pages are pages that you tagged as start hidden flow or restart regular flow, but that other marked pages made them have no effect.
You could write:
As you work on making hidden flows, do corrections, try things, as you tag pages as "Start hidden flow" or "Restart regular flow", some of the previously made ones may have no effect (ie. when you make Start hidden flow a few pages before an existing Start hidden flow, that existing one is no longer involved). They are remembered for practical purpose (in the previous example, if you end that second hidden flow before the existing-no-longer-involved Start hidden flow, this one will be involved again).
Once you are done making hidden flows and happy with the results, or if you find that this reactivation of olders marked pages get in your way, you can clear all inactive markers.

QUESTION: WHY WOULD A USER NEED TO CHANGE TO THIS ALTERNATIVE THEME ?
I MEAN WHICH PROBLEM THIS ALTERNATIVE THEME IS SOLVING (GHOSTING, LEGIBILITY,...) ?

No real problem, just user taste :) Discussed/argued all along #10193.
@jonnyl2 wanted and like the alt theme, and gray chapter titles and hatching, so he can tell you why it's so wonderfully good - I can't :)
I personally don't want it on my Kobo GloHD because any solid gray (non pure white nor pure black) cause some distracting flashing when it is drawn, so the default is this old pure black and white theme.

[Frenzie]

I think it's clear. 👍 It may or may not read a little bit better changed like this, but feel free to keep it as is.

There is only one minute difference → There is only a one minute difference

[hius07]

QUESTION: THIS SWIPING FEATURE IS “ON” BY DEFAULT, RIGHT ?

Right.

No more comments, all is okay, thank you.

[jonnyl2]

jonnyl2 wanted and like the alt theme, and gray chapter titles and hatching, so he can tell you why it's so wonderfully good - I can't :)

Allow me to clarify that I neither wanted nor asked for an alt theme. My only gripe with the standard design was that the chapter boundaries were not clearly discernible. It is hard to tell where one chapter ends and where the next one begins (at least for me). And as the chapter names are repeated on each new line, it results in tedious rereading of the same chapter titles over and over again. @poire-z graciously offered to create an alternative theme with alternating background shading (one of several suggested design elements), which solves the aforementioned issue as the eye can effortlessly skip to the next chapter without re-reading like-named title bars, is beautiful to look at, and of course I appreciate very much 👍 💯

[offset-torque]

Thanks for the feedback folks. All suggestions applied/corrected/integrated.

Exception below:

"These hidden sections will not be shown in your Progress bar." poire-z > I think this is wrong: we still show all of the book in the progress bars of footer and skimto widgets. The hidden flow sections may be gray though.

Are you sure poire-z? Custom flows are removed from my Progress bar as seen in the image below.

And yes, they are visible in the Skim widget, I just added this to the guide. But now I noticed that Skim widget is problematic because custom flows before the current page become totally invisible, which makes it impossible to jump to a previous custom flow. That needs fixing I think. Maybe they can be white to indicate empty spaces.

Marked area is a Custom flow but indistinguishable here:

@jonnyl2
Now I see the difference and I think this Alternative theme is a good idea. I remember having the same problem related to the chapter boundaries. Even though I dislike gray flashing, added clarity here is helpful so I will use this mode. Thanks for suggesting this and also poire-z for implementing.

[poire-z]

Are you sure poire-z? Custom flows are removed from my Progress bar as seen in the image below.

Oh, indeed. And when you jump to a page in a hidden flow, the progress bar resets (restart at 0, and spans only this hidden flow). Once you reach the end of that hidden flow (so, progress bar filled), next tap, going back into the main flow, restores the original book-spanning progress bar.
A bit strange, but understandable. Been like that since the non-linear flows PR #6847.

But now I noticed that Skim widget is problematic because custom flows before the current page become totally invisible, which makes it impossible to jump to a previous custom flow. That needs fixing I think. Maybe they can be white to indicate empty spaces.

I notice that too. In that PR, it seems they were shown, in a darker nearly black dark gray. Dunno if it changed or if it's an effect of gray/alpha/dim/darken blitbuffer stuff. Maybe for @NiLuJe (who also cared about these Progress widget) to look at it.

[offset-torque]

@poire-z and @Frenzie
After seeing the last issue with the broken epub, I remembered that I have seen similar issues before. And with the increasing number of online services converting/producing epubs, I expect the number of problematic books to go up. As I have seen, generally users blame this on KOReader instead of the broken book. So I decided to write a section for the guide about "slow books" so any time this issue comes up, you can just link to this section instead of writing everything again and again. Please have a look.

24.02_Additions_2.pdf

[poire-z]

Looks fine to me.
You could also mention that KOReader doesn't support "fixed layout EPUBs" (they will open, but will render as reflowable EPUBs and probably won't look nice or readable).

ARE THERE ANY OTHER SOLUTIONS ? WE DON’T NEED TO HAND HOLD THE USER STEP BY STEP. JUST MENTIONING AND
LINKING TO THE TOOLS IS ENOUGH TO GIVE DIRECTION I THINK.
OR WE CAN ALSO TELL WHAT TO CHECK / HOW TO CHECK IN DETAIL FOR MORE ADVANCED USERS SO YOU DON’T NEED
TO SAY IT AGAIN AND AGAIN IN THE ISSUES.

Some ideas:

• With EPUBs, you can set Embedded Styles: off in the bottom menu to see if ignoring all the document stylesheets makes it faster (of course, you'll probably lose any nice formatting, but you'll know what is the culprit).
• You can select some text and use View HTML to inspect the HTML and the CSS files, and judge of their quality or uneeded complexity by yourself if you can.
• (Dunno if worth mentionning as quite technical) Another rare cases of slowness is when the content is wrapped in a HTML <table> (as crengine has to somehow render/draw each cell on each page turn, so if a cell (containing many paragraphs) spans 50 pages, this may take time. Solution: style tweak with table, tr, td { display:block; }
• I have no experience with Calibre, but may be it has options/plugins to "clean" a book (spans, styles) ?

by dragging and dropping it on your message in the GitHub IT NEEDS TO BE ZIPPED I THINK ?.

It's juste the extension .epub or .html that are not accepted. .txt and .zip are find. Some people rename their epub to .zip. But yes, safer to mention to zip it.

GIVING A LINK TO AN EXAMPLE ISSUE MIGHT BE USEFUL, WHAT DO YOU THINK ?

Sure. I think there are probably others (but no time to look for the most interesting ones).

[Frenzie]

KOReader is optimized to work reasonably fast even on the limited hardware of e-book readers. Generally thousand page books
can be opened in a few seconds and page turning is without a delay. Here we will talk about the reasons if your book feels very slow
when opening, page turning or adjusting its appearance.

Imo it's just fast period, not "reasonably" fast. :-)

Put another way, I effectively never have a document take more than 2-3 seconds to load on my decade-old H2O (with kerning: best!), much faster still on my Libra 2, and page turning is extremely fast.

PDF file itself might be too big for your device memory.

I don't know if it's worth going into details, but it's really just on a page by page basis for PDF.

• If you set your RENDER QUALITY to HIGH text will be more pleasing but it can be much slower (several seconds for page turn)
  than DEFAULT depending on your document. If your PDF/DJVU files are slow, this is the first setting you should check.

This is only for reflow, so maybe the header should say something like My PDF/DJVU files are slow with reflow enabled.

But some EPUB books abuse
these formatting rules (CSS declarations) so much that KOReader has to do many calculations just to show even a single
sentence.

It'd be a bit more diplomatic to say something more neutral like some EPUB books add a great number of formatting rules.

ARE THERE ANY OTHER SOLUTIONS ? WE DON’T NEED TO HAND HOLD THE USER STEP BY STEP. JUST MENTIONING AND
LINKING TO THE TOOLS IS ENOUGH TO GIVE DIRECTION I THINK.

Maybe it's too nitty gritty, but running epubcheck will give some indication as to the general quality of the file. Though it does give warnings for many things that hardly matter and it doesn't warn about some things that do, but of course it's just a tool.

GIVING A LINK TO AN EXAMPLE ISSUE MIGHT BE USEFUL, WHAT DO YOU THINK ?

Can't hurt.

[Frenzie]

Sample issue where epubcheck was helpful: #11268

[offset-torque]

I made all the additions/corrections to the slow book section.

It'd be a bit more diplomatic to say something more neutral like some EPUB books add a great number of formatting rules.

I corrected this as you wrote Frenzie, but that last book had a ~800 KB CSS. I read whole series smaller than that :)

You can have a look at this if you have time, Solutions part changed mainly.

slow_check.pdf

Also @hius07 and @mergen3107. If you have your own tips/tricks/solutions in addition to the ones in this PDF, please tell.

[Frenzie]

I corrected this as you wrote Frenzie, but that last book had a ~800 KB CSS. I read whole series smaller than that :)

Sure, but that's an exceptional situation. There's a wide range below that where it's excessive but not quite abusive. ;-)

I have no further comments at this time.

[poire-z]

slow_check.pdf

Looks fine to me, except:

Another rare cases of slowness is when the content is wrapped in a HTML <table>. KOReader has to render/draw each cell on each page turn, so if a cell (containing many paragraphs) spans 50 pages, this will slow down the rendering make page turning quite slow.

[offset-torque]

Quick question: Is it "Quick Menu" or "QuickMenu".
It is separated in the guide but I have seen it referred as joined.
What do we call this feature officially?

[Frenzie]

It seems to be called QuickMenu, though that might just come from code without much thought behind it otherwise (where it's necessarily QuickMenu, unless you do something awkward like Quick_Menu). But I think it's fine to keep it.

koreader/plugins/gestures.koplugin/main.lua

Line 249 in 3e7ab19

text = _("Anchor QuickMenu to gesture position"),

koreader/plugins/profiles.koplugin/main.lua

Line 131 in 3e7ab19

text = _("Show as QuickMenu"),

[offset-torque]

24.02 Guide Update Changelog

First update of the year. On one hand I am glad that the project is constantly improving, on the other hand I have to document all these improvements :) I am not sure (because we don't have pages anymore) but the guide is now around 75 pages which makes it probably one of the best documented open source applications.

NOTE: We now have a "If your book is slow" section, just under the Troubleshooting section. You can directly link to this, if someone opens an issue complaining about a slow book (so you don't have to explain everything repeatedly).

I also made lots of style changes, so the guide should look tidier, more professional and prettier. Have fun !

New sections:

• Custom ToC
• Alternative ToC
• Custom hidden flows
• If your book is slow

Added:

• Folder shortcuts
• New "Reset document" options
• "Open with..." file type associations
• Setting a screenshot as custom book cover
• Flomo and XMNote export formats
• QuickMenu: Keep menu open after interaction
• QuickMenu: Anchor menu to gesture position
• Quick Menu: Quick font changing tip
• Highlighting: Adjusting highlight dialog position
• Tip when reading serialized books like manga
• Usage of keyboard swipes and how to disable them
• Using "Custom Text" item for status bar alignment
• Alternative theme for Book map and Page browser
• Pocketbook SmartLight option warning
• Fast warmth change tip
• History search tip

Updated:

• New images and screenshots for the added features
• Added and moved lots of Gesture Manager items
• Night mode UI update
• User guide thread links

Guide style changes

• Changed the font to the newly released "SN Pro" font family
• Introduced info box and tip box classes in addition to the warning box
• Adjusted many elements including standard text, paragraph styles, lists, links
• Cleaned up the CSS classes and added more comments
• Optimized the font appearance, colors and margins
• Added rounded corners to images
• Added header image for the guide

[elandorr]

https://koreader.rocks/user_guide/#bookmarks under "Editing a highlight" you may want to specify adjusting only works with epub files. #11519

[hius07]

with epub files

"with reflowable documents"

[offset-torque]

@elandorr - Thanks, I will add that.

[cpuks]

Export Highlights plugin <- that section needs a further explanation either by pointing to Highlight-export or explaining how to set up each service in detail - ie memos service needs /api/v1/memo path at the end of URL.

[offset-torque]

@cpuks - I didn't even know this wiki page exists, no one told me :) I will add that info to the guide and also provide a link to that page just in case. Thanks.

[cpuks]

@offset-torque yeah same - I mean I’ve seen it couple times but yesterday after two hours I found out what URL means for memos export - worst part that it didn’t help anyway.

[offset-torque]

@Frenzie
Currently I am adding parts and making changes to the guide. Since there are not many changes in this release, it will take time till the next guide update.

My question: Is there a lockout procedure in github that signalizes that the file is being edited by someone so others shouldn't make changes until it is released by the current editor (to avoid conflicts and messy diffs). So for example you want to make a change, first I merge my changes then you can work on it. How is this coordination done? Although not many people are editing the guide, it is good to know the correct procedure.

[Frenzie]

As far as us here are concerned what you just did is the procedure. You could do it a bit more publicly in a draft PR if you're comfortable airing your dirty laundry, or split it up into slightly smaller edits (e.g., per section).

Maybe adding a notice to the README file is an option if you implicitly meant you're mostly worried about people who don't follow this thread.

[offset-torque]

Got it, thanks. Since I have to test every little change (sometimes in multiple browsers) to be sure that it renders as intended, draft PR option is impossible. I guess more frequent edits is the way.

[offset-torque]

24.03 Guide Update Changelog

Minor update with small additions.
Biggest change: We now have a nice, coffee flavored dark mode so users won't need sunglasses when searching for help at night :)

Content updates

• Adjusting mosaic grid and list items
• Added OCRmyPDF to "document preparation" apps
• Added some example font names and links
• Updated "verbose debug logging enabling" procedure
• Added ToC tools to "What can you do with KOReader" section
• Added internal links to "ToC tools"
• Indicate that highlight editing works only on reflowable documents
• Added "Export Highlights plugin online services wiki" link
• Alternative screenshot gesture added to relevant places
• How to disable highlight auto-scroll on corners
• Other small corrections

Style and code updates

• Implemented dark mode and adjusted optimized dark mode variants of colors
• Changed all colors to variables
• Added navigational markers for VS Code
• Fixed indentations and EOL whitespace