FR: automate advanced settings doc #2589
Comments
|
Yes, this would be very useful and also necessary. At the moment there's many options, but if we don't know how to use them, or that they even exist, we can't use them. Having them at least listed in wiki (or in some pdf or epub file that comes with koreader) would be great. |
|
There's also some with These are the ones i added or that have been discussed in topics i followed:
I haven't really checked each of the other ones, but from their names, there's no surprise and they all look like they are related to some menu entry i've seen :) |
|
There are some options in settings.reader.lua for screensavers: use of book cover, a specific image or directory or even a text message, differently for sleep and power-off. Here: #2349 (comment) |
|
My original plan was introducing setting annotation via comments similar to what we are doing with API docs. So we can write a little snippet comment to document every setting in the code right next to where the setting is used. Then we just need a custom script to parse out all those annotations and generate a manual with it. It should be very easy to do with LPEG, I just haven't had enough time to work on it. If anyone wants to give it a try, I can help point you to the right direction and clean up blockers for you :) |
The Wikipedia thing is hard to defend as a setting imo, assuming that without it all you get is some plain text. At worst one might complain that square and diamond are less clear than, say, Justification is slightly different because justification is very hard to get right. Frankly anything other than LaTeX is pretty awful at it and even then only if you monitor the results and define custom linebreaks. I missed one in my thesis (the result of some last minute edits) and it still annoys me. Not that I'd care enough to change such a setting, let alone look for it… but I can see why someone would defend its existence. Sounds simple enough (although I don't know if I have the time), but what format would we take for the comments? Would there be conflicts with the *Doc format of --- Summary ends with a period.
-- Some description, can be over several lines.
-- @param p1 first parameter
-- @param p2 second parameter
-- @return a string value
-- @see second_funor is that non-functional unless it's followed by a function definition? |
|
I am thinking something like the following: -- === ko-setting ===
-- @name: open_last
-- @value: boolean
-- @default: false
-- @category: filemanager
-- @description:
-- When set to true, filemanager will automatically open last opened file on start
local open_last = G_reader_settings:readSetting("open_last")Since we get to write our own parser, it doesn't need to be followed by function definition. The parser will just look for any comment block starts with |
|
I'm so fond of the new checkmarks for togglable menu items, that I wish we had more :) FILE BROWSER RELATED
READER RELATED
DICTIONARY AND WIKIPEDIA RELATED
SUSPEND, SLEEP, POWER, SCREENSAVER related
The next ones are Kobo only: MISCELLANEOUSplugins_disabled: allow for disabling some plugins (#4054) OTHERS that can probably be ignoredfontmap (reader.lua) : allow for overriding fonts defined in frontend/ui/font.lua ? ENGINE OPTIONScopt_embedded_css There may also be a few other interesting options in https://github.com/koreader/koreader/blob/master/defaults.lua |
|
The few that I still do, in the scripts : For me, with my Kobo AuraHD, it is in .adds\koreader\frontend\ui\widget\menu.lua To adjust number of lines per page, change: \koreader\frontend\apps\reader\modules\readerfooter.lua Line 57 return os.date ("%I:%M") To show the footer time as a 12 hour clock. |
|
offtopic: @poire-z thanks for your comment #2589 (comment) . Could you move it e.g. here https://github.com/koreader/koreader/wiki/Change-defaults as "Advanced" section? |
|
The wiki seems so outdated, including the page you linked to. And this page doesn't really feel right to host that list of manual settings. Updating the wiki (dictionary, wikipedia, for the features I modified quite a lot) would be a lot of work. It may feel easier to just link to the PRs/Issues where some features are introduced or discussed. |
|
offtopic: @poire-z even commercial developments have problems with keeping documentation up-to-date, so if free software also does it's not a surprise for me, and I won't complain. Keeping it here I see 3 major disadvantages:
I've paste it there https://github.com/koreader/koreader/wiki/Change-defaults. |
Other maintainers can edit it too. |
|
Is it possible to add options for:
|
|
Just set the DPI a little lower? :-) |
|
Higher you mean? I'll try that. |
|
Seems the DPI settings are Small, Medium and Large which actually correlated to high, medium and low DPI respectively. I have been unable to get the Custom DPI setting to work. Please could you advise how to access this feature? Thanks :) |
|
Huh, it seems to be broken. That's weird. I don't use it on my actual device, just in the emulator with the Anyway, you should be able to stick that environment variable in the startup script on Kobo too. But at some point you could just set a DPI through the menu. I thought it hadn't even been touched in years. >_> |
|
Oh! It's not broken. You just have to long-press it. I'll just quickly add that to the text between parentheses. |
|
Thanks for the quick response. A way to preview any change would be exceedingly useful but I suspect probably not widely requested. EDIT: just tested at 600 dpi and everything is massive which goes against my intuition. Some of the screens (like stats, don't seem to scale well at (in this case) low dpi either). |
* It was unclear that you needed to hold to set DPI, see koreader#2589 (comment) * Up the DPI limit to 900 as several Android devices have already breached 800. This will increase the possibility of crashes due to a higher setting even on relatively high-DPI devices, but that was always already an issue. * Also brings the custom DPI dialog box in line with the UX guidelines as per <http://koreader.rocks/doc/modules/ui.widget.confirmbox.html>.
|
I'm also getting some odd reflow behaviour in PDFs and DJVU at non auto DPI on my device (have tried 90, 100, "small" so far). Typeface resizing doesn't always work and you sometimes get sentences in much bigger typefaces in the middle of a paragraph. Side margins also disappear regardless of settings (still no top/bottom margins). |
|
Higher DPI means using more pixels to display things, so a lower DPI setting makes things smaller (= fewer pixels are used to draw stuff) and a higher DPI setting makes things bigger.
Note that you probably have to clear out the cache manually. There's a developer options menu on page 2 of the tools in file browser that enables you to do so. (Yeah, it's hard to find.) |
|
Thanks for the info about the cache. I think that's fixed it. Another thing that might be helpful is to show the user what small, medium and large correspond to quantitatively in order to aid in picking a good custom DPI without multiple restarts to test.
Really? I always understood that items/objects are a set number of pixels and higher DPI means greater pixel density hence the same thing takes up less physical space (appears smaller). |
* It was unclear that you needed to hold to set DPI, see #2589 (comment) * Up the DPI limit to 900 as several Android devices have already breached 800. This will increase the possibility of crashes due to a higher setting even on relatively high-DPI devices, but that was always already an issue. * Also brings the custom DPI dialog box in line with the UX guidelines as per <http://koreader.rocks/doc/modules/ui.widget.confirmbox.html>.
|
If you draw things at the same size then a higher DPI screen will display things smaller, yes. The point of the DPI setting is to draw items with more pixels so they're (roughly) the same size but sharper, based on a presumed "correct" size. In our case that's how the program looks on some ancient model Kindle with — you guessed it — a DPI of 160, while for Windows it's probably something like 800 x 600 on an 11 inch display, or 1024 x 768 on 14 inch. Some desktop environments, including Windows, have switched from calling it DPI to calling it a scaling factor. However, a scaling factor of 2 or 200% means nothing more or less than rendering at 200% of 96 DPI. In other words, the result is as if you're rendering at the "correct" size for a 192 DPI display. But the actual DPI of your display doesn't matter. I'd simply call it |
Implement the suggestion by @turkeyphant from <koreader#2589 (comment)>.
Follow-up of koreader#4388. Implements the suggestion by @turkeyphant from <koreader#2589 (comment)>. Also adds a little explanatory message when holding on the Auto DPI option.
Follow-up of koreader#4388. Implements the suggestion by @turkeyphant from <koreader#2589 (comment)>. Also adds a little explanatory message when holding on the Auto DPI option.
Follow-up of #4388. Implements the suggestion by @turkeyphant from <#2589 (comment)>. Also adds a little explanatory message when holding on the Auto DPI option.
|
It's nice that some configuration settings can be set permanently in the setting.reader.lua files, as it is useful that some other settings can be set interactively in koreader. What I'm missing is a way to permanently save the interactive settings, ideally for the file type they've been applied for. Take for example pdf files: especially on smaller screens, enabling reflow and turning on page mode is desired. But those settings don't stick - when opering another pdf file, they're back to the less useful defaults. As far I haven't found a way to make my settings permanent. |
|
Given that reflowable and fixed-layout documents don't actually share most of their settings, setting a global default in a PDF for most of the bottom-menu should only actually stick to PDFs? (As in, long-press on a setting to set is as default. Oh, Quickstart Guide, how people pass you by ;p). |
|
Thanks! Will check that at next opportunity. Missing that method is what one gets from consulting the "Configuration" section of https://github.com/koreader/koreader/wiki - thinking that diving into "real" docs may be preferable over a "quick" start - gestures, multi-swipes, dictionary setup, lots more there. Maybe I (or somebody else) should add a pointer to the quick start docs there too :) |
|
You're quite right that regardless of me whining about it, the Quick Start could use a bit of polishing, and getting it up to date on the recent (and not so recent ^^) features ;). |
|
Still valid as documentation, but given we moved a lot to the menu with some help_text, feels uneeded to document them more: just move them to the menu if they are that interesting. |
Issue
@poire-z made an interesting observation:
This should print an alphabetic list of all the available options.
Ideally we'd automatically add some explanation as well somehow, but for starters just getting the (slightly further processed) output of that command or something equivalent in auto-generated docs somehow would be nice.
The text was updated successfully, but these errors were encountered: