-
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
FR: improve metadata #11829
Comments
My preference would be "ebook reader" or "document viewer". For the description, I'd say we take from "multi-format documents" and "full-featured reading" in the readme, when we previously went over this in detail. |
Thanks for the feedback, @Frenzie. I mostly agree with that. I would like an opinion from our UX focused people @offset-torque and @Commodore64user: Could you take a look at https://github.com/koreader/koreader/blob/master/metadata/en-US/full_description.txt? I assume the part that says it is portable or it is optimized for eink devices is not that important in the description. The rest of highlights seem relevant. Is somebody able to summarize that into a couple of paragraphs? Strong opinions are encouraged here :) Also, if you are unaware, english is not my forte. I wouldn't mind to have something to copy/paste :D |
Automated screenshots for Android: https://docs.fastlane.tools/getting-started/android/screenshots/ |
I actually expanded the linked text from the guide's "What can you do with KOReader?" section. We have some newer very useful and unique features. So I am writing this as a base to modify. I am trying to think as a user searching an "ebook reader" (I agree with Frenzie, this is exactly what I would search) on F-droid. Most important things would be probably:
Here is the expanded text. First three items answers the questions above so I consider them important. You, Frenzie and Commodore64user can pick and join/add/subtract the parts as you like:
|
As a kindle man, there is one more think I would like to know (assuming I was trying to find an alternative to it):
I like these a lot, I would only change:
Custom UI without animations, optimized for e-ink devices. Night Mode, screen light and warmth support.
Support for both fixed page formats (PDF, DjVu, CBT, CBZ) and reflowable e-book formats (EPUB, FB2, Mobi, DOC, CHM, TXT, HTML). Scanned PDF/DjVu documents can also be reflowed. Special flow directions for reading double column PDFs and manga.
Multi-lingual user interface with a highly customizable reader view and advanced typesetting options. Multi-lingual hyphenation dictionaries are bundled in.
Deep integration with Calibre (search metadata, receive ebooks wirelessly, browse library via OPDS), Wallabag, Wikipedia, Google Translate and other content providers also supported. what is that about creating your own menus? can we do that? last but not least (I actually don't know how it works so correct me if wrong)
not quite happy with it but I'll think about it and edit it if I can think of a better way of phrasing it. |
Thank you! I'm totally ok with #11829 (comment), just a few nitpicks:
That's hardware, it might not be available on a particular device or platform. It might not be supported on a specific device even when it is supported on others of the same platform.
These features are not very relevant here. OTA updates are provided by the stores themselves, so not our feature. The rest looks good, specially with bullet points :) |
@pazos Coincidentally last week I started making some screenshots for the main page showing our new features. I think app screenshots for the stores can be like this list (and I can prepare them):
I think showing these features is important because there are many reader apps on F-Droid and some of them are just simple wrappers around a PDF library or a very basic EPUB reader. Our informative (and cool) screenshots would help differentiate KOReader from these simpler apps. @Commodore64user
Yep, with our Quick Menu |
ahh, yes. I do have one of those. |
That would be amazing :) We currently ship 3 sizes.
Slightly different sizes shouldn't be a problem as long as the ratio is preserved. It is totally ok to use the emulator to make all the snapshots. Try to follow https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines/quality-guidelines/#default-settings but feel free to change DPI settings for different form factors.
Public domain, CC or similar license, please :)
There's room for 6-10, so feel free to pick the relevant ones from your list or add others. It seems quite a job to recreate meaninful data on the emulator just to showcase advanced widgets as they deserve :) |
Suggestion ideas for Android Screenshots
Pick books from Gutenberg, which has all the books as public domain. Only download the books that has some nice cover images so that we can show them in KOReader "History" & Favorites" screenshots.
As background image of all the screenshot we can use some public domain image.
Just a mock-up idea to fit as many useful features in these 10 screenshots. BTW F-Droid docs suggests to use |
I probably wouldn't pick the newsreader. On anything but an ereader there are many choices. I suppose you don't really need Wikipedia integration there either but in any case that's properly nice, especially the saved EPUB articles. Nice comment btw, thanks. 👍 |
(I'm probably in the minority, but I quite hate these fancy presentations with parts of the screen covered, and some tilted - give me real horizontal full view screenshots and I'm happier. But it's your thing :)) If this targets Android, another question is: should the "model" be a phone (like in the presentation above), or an eReader looking device (with a more 4/3 aspect ratio). I think we target eInk devices better, than plain and tall Android phones, where our monochromatic glory may not be really appreciated, and a good amount of phone-only users will just hate it. |
Agree 100%.
We target phones as good as eink readers :) The autoDPI setting doesn't scale well, so desktop users might want to set DPI to 90/100 (it really depends on the DE) and big tablet users might want something like 110-130. But, yeah: the screenshots are handled by fastlane and cover phone and tablet images. In theory both will be picked if present and the one relevant to the device is displayed. Any e-ink (or not eink) tablet should use the tablet images if it was built correctly (hint: they're not) We currently only ship phone images, so including tablet images could be a nice addition. |
Actually I don't like them either, I like minimalist useful screenshots. From what I've seen majority of people like fancy designs...I might be wrong as we target F-Droid users not PlayStore.
I agree. F-Droid docs suggests |
Thanks for the hints. Unfortunately we can't use it as it relies in a view hierarchy we don't implement. Not sure if it worth the hussle to script screenshot creation, specially if we stay with a few untranslated screenshots. |
My idea was to add multiple screenshots to condensed under 10 but as there is no such limitations to show max10 screenshots we can use 10+ most useful features show as real separate horizontal full view screenshots :) Only limitation for F-Droid is "500 characters for changelogs" which is not relevant for KOReader. |
Please don't :) The restriction comes from https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines/quality-guidelines/#at-least-one-screenshot To prevent maintainer nightmares in the future it is useful to keep the same metadata everywhere, so lets use that 6-10 limit for screenshots. They should also cover the same stuff, with the same settings across diferent |
@pazos Some questions:
@shuvashish76 please look at the image below. This is your image and green area shows the pixels that belong to real screenshot areas. According to this, you want us to allocate more than 60% of our available screenshot area to a world map instead of the user interface of our application. Why? How this benefits users? How taking a full size screenshot and scaling down and rotating it to make them less readable help users. This is form over function, just a fancy marketing carousel. Problem is we are not selling anything. Users will want to see what the program looks like, and we don't have the luxury to throw away those pixels.
|
Thanks, nothing to disagree here. Besides all the points you mentioned, this is the perfect reason not use such designs 👍🏿 |
Yup, HiDPI e-ink reader 3:4 ratio.
Because that's what I've got trying to reach flathub specs :). As I said a few pixels more or less shouldn't hurt as long as the ratio is mostly the same.
Nope. Screenshots can wait as long as we want. The text needs to be updated ASAP to be included in our translation pipeline. The thing I will need to figure out is how to add these beautiful bullet points in each store while keeping the sentences straight for translation. For text we're currently using https://github.com/koreader/koreader/blob/master/tools/update-metadata.lua#L15-L31 My plan, for the long run, is to update the script so it fetches translations and pulls screenshots from the |
I can:
By the way here is a Flathub page of a nice reader called Foliate that I used before. https://flathub.org/apps/com.github.johnfactotum.Foliate For screenshots, I have to create a workflow because probably I will have to make around 40-50 images in different resolutions and text appearance/dpi settings (including feedbacks, revisions, updates etc.). |
Yep, flathub works with html |
I searched for list and it somehow just worked out. xD |
Great, that shows it is possible. Now if I could figure out where the metadata is stored... Not on github: https://github.com/fredx100/InfiniList |
Thank you very much @shuvashish76 :) So it is By looking at flathub in Deutsch https://flathub.org/de and Español https://flathub.org/es it looks like there's no translated metadata. Or at least not used in there. Appstream supports translations but it isn't clear how they're wrapped up into apps (a single appstream.xml?, one per language?), so I'm going to leave flathub untranslated for the moment. If somebody figures out how it is expected to work it should be trivial to translate them using the same F-Droid metadata. |
the mpv for app-store metadata would be: Document ViewerKOReader is an ebook reader built from the ground up for e-ink devices. Features:
Is that ok? @Frenzie @poire-z @shuvashish76 @offset-torque @Commodore64user? Do you miss some other bullet point? Do you want to change some expression? I'm not sure between "Features:" or "Some features" or "Highlights" or "Some highlights". |
I would change this: KOReader is an open source ebook reader I would also use the bullet points as I wrote them (i am biased), and please tell me that i can synchronise my progress with all my devices.
Yes, see above. I want to know that i can start reading on kobo (well not me) and continue on Android just where i left off. I also want to be told in small print that a wifi connection is required ;), and batteries not included in the box.
Features is fine, i think. |
Current short_description : Ebook reader with support for many formats like PDF, DjVu, EPUB, FB2, CBZ IMO we don't need to mention formats here as already mentioned on full_description, it's just to get the initial impression about the software. |
My vote is for "ebook reader". Document viewer gives the wrong impression IMO. (I'd use a "document viewer" to take a quick glance at a document, not to spend serious time on it. I'd also not expect a document viewer to leave metadata-traces on disk after opening a file.) |
Thank you all for all your feedback! Changes in text metadata for appimage/flathub can be reviewed in the link above. Changes in text metadata for f-droid will happen on different stages.
Screenshots and screenshot's captions are welcome at any time :) |
I have hebrew text (with diacritics) screenshots on my website https://kindleseforim.paritcher.com/ If you would like a different size, i should be able to generate them. |
@yparitcher we will have screenshots in different scripts (Latin, Hebrew, Arabic, Russian, Chinese, Japanese and Korean) so it will look more professional if all of them have the same UI and similar text appearance settings. I think it would be much less effort for me (and everyone included) to generate these screenshots myself instead of coordinating these 3 different device settings with 7 different users and having feedbacks and retakes if necessary. But you can help me with this, since I was going to ask in this thread:
|
Some background: For Hebrew there are 2 types of books that one can be reading. 1. Typeset in modern Hebrew or 2. Typeset in biblical Hebrew. modern Hebrew generally does not use Nikkud (diacritics) so
Biblical Hebrew can make heavy use of nikkud.
All Hebrew reader should be able to read both (they are not separate type systems), and even modern hebrew can use nikkud to disambiguate identically typed words. Now my (subjective :) opinion, as one who primarily reads Jewish texts in Hebrew.
If we can find a neutral book with nikkud great (i will take a quick look), however i do believe that most of them that will be found will be religous texts. |
Thanks for the informative reply yparitcher.
I totally agree with this. We are trying to showcase the capabilities of KOReader. Now we have a valid justification for it, we can use the religious texts. I installed the SBL font, I agree that it looks more elegant than modern sans fonts. And I can see the nikkud move to their correct places with the kerning in KOReader set to BEST. I downloaded the Seforim archive file from your website. Which file/page do you suggest for the screenshots? |
I would say the first page of בראשית.epub in the chumah rashi folder. (That is the beginning of Genesis in the bible, so the most basic book.) If you want a second one i would say try the mishna. Ty |
I don't know what "nikkud" means, but don't take the religious route (no offence to anyone). There is just no valid reason to go that way. You would just be alienating users. |
Not taking a religious route is a religious stance ;) I wouldn't mind people reading all kind of books with this software, including religious ones. But none of the languages So I would say: stay with english only ebooks that are available under a non restrictive license an let people using non-latin scripts to trust us a bit, install the application and read whatever they want. |
If there are only enough screenshots for english, so be it. |
I really don't know what's the best option :/ Maybe we can add a new test epub that showcases RTL and CJK in a single document and use that in a single screenshot? |
These marked dots and lines. Correct positions in green: I mean if we can do something correctly that even Kindles fail, this is a big deal.
Best solution is to find a neutral text with these special cases I agree, but do they exist I don't know.
Yes, I was thinking of combining the screenshots so it wouldn't be very crowded. One split for RTL (Hebrew+Arabic) and one for CJK scripts maybe. So 2 extra screenshots to show that we are adept at rendering many other scripts sounds reasonable to me.
I agree. I don't have strong opinions about this topic so I will go with the consensus here. For now I will start with the English ones, we will come to a decision in the meantime. |
Simply sticking 2 or 3 RTL languages in one screenshot is also what I was going to suggest. You could also do something really dumb, like:
|
Just got some spare time and dig a bit o the topic. Flathub metadata isn't translated on the webpage but both Translations go on the same xml file, with a <summary>Ebook reader</summary>
<summary xml:lang="es">Lector de libros electrónicos</summary> So, everything is translatable :) Which leads me to the next question, @Frenzie @poire-z: Do we have some xml tools to do these kind of tasks (ie: editing xml files in place or keep a representation as a lua table and dump it to an xml file on demand)? Or do I need to read the whole file, line by line, and append each translated line for each translated category for each translated language? |
(No idea nor experience about these topics :/ sorry.) |
Err, there's an XML parser hidden away in NewsDownloader I think if that helps whatever you're thinking of. |
Thank you. I ended up writing xml manually as part of #11869. |
You might want to preemptively escape |
I don't aim at xml validation, only appstream validation: appstreamcli validate koreader.metainfo.xml
I: rocks.koreader.KOReader:4: cid-maybe-not-rdns rocks.koreader.KOReader
I: rocks.koreader.KOReader:7: developer-name-tag-deprecated
I: rocks.koreader.KOReader:25: relation-memory-in-requires
W: rocks.koreader.KOReader:117: invalid-iso8601-date %%DATE%%
I: rocks.koreader.KOReader:~: developer-info-missing
✘ Falló la validación: alertas: 1, información: 4, redundante: 4 The warning is expected as goes away on flatpak/appimage builds. |
My assumption is that malformed XML will make appstream go 💀 |
There's no problem, AFAICT. We keep the metadata in a lua table and generate the xml from there. Most of it is untranslated in a big If you see I missing something lets move conversation to #11869 :) |
That's particulary true on flatpak/flathub, which follows FreeDesktop specs and lacks a category for "reading". So, currently we're in two additional categories ("viewer" and "literature") but not a main one. That means a category search won't place KO in any of the categories supported by stores that deal with flatpak. But flatpak let us specify keywords, which can be translated. So a subset of the keywords you highlighted above would be great. Not many to avoid being a spammy mess. For instance I do believe our support for wikipedia is good enough to add wikipedia as a keyword. I don't think the same about translate. Probably particular apps, such as calibre, wallabag, readwise or google translate, don't deserve a keyword as we're just confusing users that look for a different piece of software. Here are some I think they're ok as keywords.
Any other suggestions? tl;dr: In order for KO to appear in a linux app store the user needs to search by its name. With keywords the app can be listed on queries like "epub reader", "multilingual dictionary" or "wikipedia downloader" |
The Wallabag plugin is also quite good fwiw.
Definitely PDF and DjVu, those are main formats, probably also FB2.
browser? |
as in File browser. Nvm, deleted it :)
good
Ok, added. More keywords can be added on the future but we shouldn't include words that are going to be removed soon. BTW, I think file formats shouldn't be translated. For now I have: <keywords>
<keyword>reader</keyword>
<keyword>viewer</keyword>
<keyword>dictionary</keyword>
<keyword>wikipedia</keyword>
<keyword>wallabag</keyword>
<keyword>annotations</keyword>
<keyword>epub</keyword>
<keyword>fb2</keyword>
<keyword>pdf</keyword>
<keyword>djvu</keyword>
</keywords> |
As for the main categories it doesn't seem flathub imposes them: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines/#categories-and-keywords But having one shouldn't hurt. Sadly, without "Reading", the best fit is either "Education" or "Office" and none of them stay close to reading :/ |
In KDE software center all document viewers, EPUB reading/editing utilities etc. are under the Office category. Flathub category can be Office too to keep them in sync. |
Okular is in graphics and office So while it sounds a bit weird I imagine we should simply follow that example. |
We're currently in two different app stores.
The metadata needs some love.
It differs between both stores. Summary and description need to be improved.
The summary should be something short like "Document viewer", "Ebook reading app" or "Ebook reading platform" or any other suggestion.
The description can be longer but it isn't possible to cover what the app does, so we need to highlight some features.
The snapshots need a caption related to the action you're seeing in the picture.
So, I'm asking for
The text was updated successfully, but these errors were encountered: