Editing wiki - providing some form of manual

[AlanSP1]

I see I can edit wiki and make changes, create new files. I'm willing to step by step add most useful info about how to use koreader, but I will need help.

For this, we can use this thread.

For starters, I created this page: https://github.com/koreader/koreader/wiki/Screen-saver-options and also linked it in this page: https://github.com/koreader/koreader/wiki/Features-list (at the end of list, screensaver).

At the moment I'm not satisfied how it looks, so I need suggestions. Also, I'd like to have settings.reader.lua examples within wiki, to make things easier for people to use.

First, to make this screensaver page full, can I have all options within settings.reader.lua file (i.e. how it should look within this file with syntax) here and what editing to use to make it look nicer than it looks now.

In the future you can use this thread to notify me about new features to be added to wiki (and old that are still missing).

Also, we need to have some form of uniformity within wiki, my general idea is to have one page with all features and within it linked all pages with further explanations and examples. And, of course, if some of you are willing to help make wiki with me, great.

[Frenzie]

Note that I put in quite a bit of effort to create the side nav.

[robert00s]

@Frenzie
I want to add screenshots from KO and refresh another. Where can I put png files. Another repository? Add folder to existing https://github.com/koreader/koreader.github.io? I can also create new issue with screenshots https://help.github.com/articles/adding-images-to-wikis/

[poire-z]

Thanks for your promising work on this ! :)

(I discovered too the wiki syntax is different than this github issues/PR syntax which is ridiculous... didn't really want to learn a new one so...)

A few links to some PR (that I remember, so most are mine :) that added not-yet-advertised-on-the-wiki features, and/or possibly undocumented (except in the PR) gestures/small features:

• Hold on buttons/titles/menu items to get more info (not many for now, but good to advertize) Show current and default values in config dialog (epub) #3952 Long press on Open last document shows filename to open #3967 TouchMenu: added hook to show help text on long-press #3980
• Hold on a single word > dict (because that's the most common use) - Hold more than 3s > highlight menu with more options Hold on a word for more than 3 seconds to access highlight menu and avoid the dict lookup #3199
• EPUB: follow link/Back with Swipe (useful with small fonts) + markers + location stack Added Swipe to follow nearest link/to jump to latest bookmark #3207 Show vertical marker at target position when following a link #3202 Show vertical marker at original position when back from link #3669
• EPUB: hold on image to view image in ImageViewer (which allow zooming, panning...): ImageViewer widget, better handling of external links, fix some blitbuffer memory leaks #2493 ImageViewer: added zoom & pan via gestures #2519 ImageViewer: allow zoom with vertical swipe on sides #2522.
• EPUB: limited SVG support Bump base/crengine for SVG images support #2832
• EPUB: alternative TOC from document headings (Hold on "Table of content") bump crengine: alternative TOC, no page break on borders #4011
• EPUB: Style tweaks Style tweaks: use css snippets to tweak book style #3944
• Dict & wikipedia histories Add LuaData and Dictionary Lookup History #3161 Adds Wikipedia history #3549
• Dict/Wiki: cancel lookups that take time with Tap Dict lookup: allow cancelling with tap #3228
• HTML dictionary support HTML dictionary support #3573 (and tweaking the final HTML is possible with tricks from HTML dict: enable color rendering and per-dict user fix html func #3585)
• Wikipedia lookup results with images (tap on image to see image caption, hold on image to view full screen) Show images in wikipedia lookup results #3609 (the animated image may find its place in the wiki "Wikipedia" page)
• Wikipedia articles can be saved as EPUB Wikipedia: save full page as epub (html, with optional images) #2507
• Some widgets can be moved/made transparent (to see text under them if needed) New MovableContainer: allow moving some widgets #3636 (animated image available too)
• Bookmarks can be edited/renamed by taping on them or, in the bookmark list widget, by holding on them Rename bookmarks name #3275
• File browser: hold on filename for popup menu
• Book information (and other KeyValuePage stuff): hold on trucated item to view full text Book information: refactored and additional features #2993

There are many others that are available thru menus (like Style tweaks) that are obvious/self-documenting, so less need for a long article, but they should probably be mentionned in the Feature list page (or some decicated pages for EPUB/HTML vs DJVU/PDF as these have quite different features).

[Frenzie]

@robert00s You should probably be able to just put 'em in the wiki repo if you clone it locally. That's also how I organized it in folders, which is something only of use when checking out the repo.

Note that you could consider preprocessing PNGs with pngquant. It's lossy, but especially for b&w images like ours there should be no visible quality loss.

I wrote down some tips here: https://fransdejonge.com/2017/03/image-optimization-guide/#optimizing-png

[KenMaltby]

Perhaps, in time, a summery with link to the full item in the manual could be included in a long press of the menu titles. This could be the in-line manual, that the user could come to expect, so they can understand menu options and how they can be properly used. Having them addressed first in the wiki should make adding the inline tip/info much easier.

[robert00s]

@Frenzie Thanks for info. It works.
I'll use pngquant after adding more PNGs.

[AlanSP1]

@Frenzie

Note that I put in quite a bit of effort to create the side nav.

You mean in wiki? How to add certain links to it? I see there's some links on the side (that's why I used already existing Feature list page, it is there), so it is possible...

[AlanSP1]

@poire-z

A few links to some PR (that I remember, so most are mine :) that added not-yet-advertised-on-the-wiki features, and/or possibly undocumented (except in the PR) gestures/small features:

Thanks, I'll go through your list and add info one by one, as well as explanation if it is needed.

[AlanSP1]

@robert00s
I'm not sure with this images, can I just hot link them within wiki (I guess I can).

And yes, setting for targeting single image, is it single? Or it is just understood if you target single image?

Also, can you put here examples of settings.reader.lua commands for poweroff, sleeping, etc. commands, to include them within wiki (as syntax is very important, I already managed to delete my settings.reader.lua without having backup before).

[AlanSP1]

I'll work slowly (to not loose interest soon), but hoping to work steady. So, I added page about pressing and holding: https://github.com/koreader/koreader/wiki/Press-and-hold-function

[Frenzie]

I see there's some links on the side

Not "some" but all. One of the ways to edit it is through the edit button (next to "Installation").

[AlanSP1]

Thanks, I saw a bit later edit button.

[AlanSP1]

I mentioned HTML dictionaries, but I'm not exactly sure how to install and tweak them. It would be good if someone who knows exactly what to do to add some more info on the subject: https://github.com/koreader/koreader/wiki/Dictionary-support

[poire-z]

HTML dicts are just stardict dictionaries, that happen to have the text in HTML.
You can't really know when you download such a dict if it is HTML or plain text. Details in #3606.
But KOReader should detect that and use the HTML widget or the text widget accordingly. And even do the right thing if the HTML is bad and MuPDF (the HTML rendered) doesn't like it (#3606 (comment)).
So, nothing special about installation or usage (dunno if it even deserves its own section on your page).

As for tweaking them, that will be for advanced users, and they'll have some (lots of) work to do. I don' think there will be many that interested in speding the time, so the issues/PRs you linked may help them, so links should be enough. (You can add #3606 then).

[AlanSP1]

Thanks, I changed accordingly part about HTML dictionaries, with added link to sample files.

[AlanSP1]

I just started file manager page (https://github.com/koreader/koreader/wiki/File-manager), but it needs much more info than what I know about it.

Can you please give me most important and relevant PRs and info about File manager?

Also, you can mention other important PRs and features to be mentioned. It is easier to me if you give me information as @poire-z give with his first post here, and I incorporate it afterwards, item by item into wiki.

[Frenzie]

Btw, I also try to write about some of this stuff in release notes, see for example https://github.com/koreader/koreader/releases/tag/v2018.04.10-beta ;-)

[AlanSP1]

Thanks, excellent suggestion, I'll look in release notes and take them as starting point for adding info in wiki.

BTW, I see some already done formatting that I'd like to use, e.g. gamepad controls. Is there a way how I can access it and just copy already formatted text into wiki. If I do "just" copy and paste, I loose formatting.

[Frenzie]

@AlanSP1 Sorry, I must've missed or forgotten to respond to your question in August. Could you please e-mail me (see here) or send me a PM on Gitter?

[Frenzie]

We now have a proper manual at http://koreader.rocks/user_guide/ thanks to @offset-torque.

See #11147 if you think anything's missing or unclear.