koreader
FR: improve metadata
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
- app summary
- app description
- app screenshot topics and relevant captions
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:
- Is it optimized for e-ink?
- What formats can it open?
- Is it easy to read PDFs?
- Can I highlight and export?
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:
-
Custom UI without animation which is optimized for e-ink devices. Night Mode and screen light/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 mangas.
-
Special multi-page highlight mode with many online/local export options. Powerful gesture system and ability to create your own menus.
-
Multi-lingual user interface with a highly customizable reader view with complete typesetting options. Multi-lingual hyphenation dictionaries are bundled in.
-
Integrated with Calibre (search metadata, receive ebooks wirelessly, browse library via OPDS), Wallabag, Wikipedia, Google Translate and other content providers.
-
Unique Book Map and other widgets to overview and navigate your book. Detailed reading statistics.
-
Look up words with StarDict dictionaries / Wikipedia, add your own online OPDS catalogs and RSS feeds, online over-the-air self update, an FTP client and SSH server to transfer your books wirelessly, cloud storage support.
- Is it optimized for e-ink?
- What formats can it open?
- Is it easy to read PDFs?
- Can I highlight and export?
As a kindle man, there is one more think I would like to know (assuming I was trying to find an alternative to it):
- Can I synchronise my progress across my devices?
I like these a lot, I would only change:
- Custom UI without animation which is optimized for e-ink devices. Night Mode, screen light/warmth support.
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 mangas.
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 with complete typesetting options. Multi-lingual hyphenation dictionaries are bundled in.
Multi-lingual user interface with a highly customizable reader view and advanced typesetting options. Multi-lingual hyphenation dictionaries are bundled in.
- Integrated with Calibre (search metadata, receive ebooks wirelessly, browse library via OPDS), Wallabag, Wikipedia, Google Translate and other content providers.
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)
- Synchronise your progress across all your devices running KOReader using our own sync server or host your own.
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 https://github.com/koreader/koreader/issues/11829#issuecomment-2116307222, just a few nitpicks:
screen light/warmth support.
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.
online over-the-air self update, an FTP client and SSH server to transfer your books wirelessly
These features are not very relevant here. OTA updates are provided by the stores themselves, so not our feature. In both android and linux there're better alternatives for an FTP client. The SSH server is not supported in there.
The rest looks good, specially with bullet points :)
@pazos Yeah sure, please change them as necessary. I forgot about the platforms while writing that (sleep deprivation :)
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):
- Reading page (with some nicely formatted book and an informative status/progress bar)
- Bottom "text formatting menu collage" to show all the advanced customization options
- A book page with different highlight and note indicator types
- Book map
- Page browser
- (Maybe) History or Favorites
- (Maybe) Reading progress
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 Your changes are good.
what is that about creating your own menus? can we do that?
Yep, with our Quick Menu
what is that about creating your own menus? can we do that?
Yep, with our Quick Menu
ahh, yes. I do have one of those.
I think app screenshots for the stores can be like this list (and I can prepare them)
That would be amazing :)
We currently ship 3 sizes.
- phone (1080x1920), used by fdroid
- generic (1404x1872), used by koreader.rocks
- desktop with window decoration (2000x1398), used by flathub
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.
some nicely formatted book
Public domain, CC or similar license, please :) Extra points if it is something you can get from within KO (wikipedia, opds, wallabag, news...):)
(Maybe)
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
some nicely formatted book
Public domain, CC or similar license, please :)
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.
| Screenshot | Texts | Comments |
|---|---|---|
| 1 | Dark theme support | - Front screenshot: white theme, - Back screenshot: Dark theme. Both taken from the same reader page, with no top or bottom page view. This is to show clean interface. |
| 2 | Highlights and Notes | Show one of the Note popup message while the reader page in background with some highlights, underlines, strikethrough etc. |
| 3 | Bottom Menu | Always show white theme screenshot on top for better visibility |
| 4 | Book map, Page Browser | I think Book map has many things to show so it should be shown as Top screenshot & the Page browser behind it |
| 5,6 | History, Favorites | Since we've Collection feature now I think better to show Favourite &or Collection on top screenshot and History screenshot behind it |
| 7,8 | Reading Statistics | Show Reading Progress on top as it has more details, Calendar view behind it |
| 9 | ~RSS News~ | ~One of the following...wikipedia, opds, wallabag, news~ |
As background image of all the screenshot we can use some public domain image.
There's room for 6-10, so feel free to pick the relevant ones from your list or add others.
Just a mock-up idea to fit as many useful features in these 10 screenshots.
BTW F-Droid docs suggests to use featureGraphic.png. I think we can use the graphics what we use in releases (cropped as landscape 1024x500)
One of the following...wikipedia, opds, wallabag, news
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.
(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 :))
Agree 100%.
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.
We target phones as good as eink readers :) Anything with HiDPI below 8" is our forte :). The problem arises with non-hiDPI displays on desktop computers, big tablets or even huge eink devices.
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.
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.
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 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.
I agree. F-Droid docs suggests sevenInchScreenshots, tenInchScreenshots in different directories. So it should be picked up shown to relevant devices only.
Automated screenshots for Android: https://docs.fastlane.tools/getting-started/android/screenshots/
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.
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 :)
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 ~~devices~~ resolutions.
@pazos I will use Alice's Adventures in Wonderland in screenshots, which is also the standard book of our guide screenshots. It is available on Gutenberg and OPDS, in public domain and it is a neutral book (with interesting text). Also I have seen some other reader projects using it in their screenshots so I guess everyone likes Alice.
Some questions:
- Why do we need this: "generic (1404x1872), used by koreader.rocks". I guess this is for emulating an e-ink reader, probably that is one of Kindle's screen resolutions. Right?
- Flathub resolution is "2000x1400 for HiDPI" on that page. You wrote 1398. Why is that tiny 2 pixel difference?
- Do we have a deadline for this?
@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.
- If you look at the linked Flathub quality guidelines you will see they agree with this. Actually your image can be used as a "Do not do these!" example in their guidelines. I am quoting: "Do not include the wallpaper behind the app. Do not edit the screenshot, crop it, add text, or include promotional graphics." Since we will be submitting there too, I will make all our screenshots consistent with this. They will just have different aspect ratios for the relevant platforms.
- Setting aside the usability concerns, it won't even look good. Our interface is monochrome and it is ugly. Because it has to be ugly to be usable on e-ink devices. Because of this, anything you put around the screenshots will visually dominate them and just create clutter, instead of making them look nicer. Black and white lines can't compete with any image.
- F-droid interface is extremely simple too. Just 4-5 images side-by-side. There is no hero image like Play Store, nor a fancy carousel. All this effort for nothing.
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 👍🏿
Why do we need this: "generic (1404x1872), used by koreader.rocks". I guess this is for emulating an e-ink reader, probably that is one of Kindle's screen resolutions. Right?
Yup, HiDPI e-ink reader 3:4 ratio.
Flathub resolution is "2000x1400 for HiDPI" on that page. You wrote 1398. Why is that tiny 2 pixel difference?
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.
Do we have a deadline for this?
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 Screenshots go on https://github.com/koreader/koreader-artwork, except for the fdroid screenshots that go in https://github.com/koreader/koreader/tree/master/metadata/en-US/images
My plan, for the long run, is to update the script so it fetches translations and pulls screenshots from the artwork repo. Then it is a matter of calling it once a year or so to keep both things updated.
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.
I can:
- Take my base text above
- Apply the proposed changes here
- Simplify and polish the sentences for publishing and translation
By the way here is a Flathub page of a nice reader called Foliate that I used before. Our features will look like this, just a bit longer:
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 <ul>'s. The problem is fdroid. I couldn't find a single app that's using bullet points on its description or anything else that shows some style beyond plain text. If you find one please share it here :)
I searched for list and it somehow just worked out. xD https://f-droid.org/en/packages/uk.sensoryunderload.infinilist/
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 Fdroid repo has the manifest: https://gitlab.com/fdroid/fdroiddata/-/blob/master/metadata/uk.sensoryunderload.infinilist.yml but seems to lack metadata in https://gitlab.com/fdroid/fdroiddata/-/tree/master/metadata?ref_type=heads
Thank you very much @shuvashish76 :)
So it is <ul>s there too.
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 Viewer
KOReader is an ebook reader built from the ground up for e-ink devices.
Features:
-
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.
-
Integrated with Calibre (search metadata, receive ebooks wirelessly, browse library via OPDS), Wallabag, Wikipedia, Google Translate and other content providers.
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 ~~built from the ground up for e-ink devices.~~ with a custom user interface and optimized for e-ink devices.
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.
Do you miss some other bullet point? Do you want to change some expression?
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.
I'm not sure between "Features:" or "Some features" or "Highlights" or "Some highlights".
Features is fine, i think.
I suggest keeping these items:
- Unique Book Map and Page Browser features to navigate your book. (These will be in the screenshots so users will know what it is for.)
- Special multi-page highlight mode with many online/local export options. (Highlight and export features make KOReader the best -even the only- reader application suitable for academic reading so I think this is a big deal especially for big screen Android devices)
And this is for Commodore64user which is a good idea to include because many people read on multiple devices:
- Can synchronize your reading progress across all your KOReader running devices.
So three more items in total.
And tiny modifications for this item for easier translation:
- Supports ~~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.
We should definitely emphasize the e-ink optimization. Most of the e-reader apps on Android is pretty unusable due to transitions and animations:
- Multi-lingual user interface optimized for e-ink screens. Highly customizable reader view and advanced typesetting options. Multi-lingual hyphenation dictionaries are bundled in.
So final copy-pastable version with everything applied from this message and Commodore64user's suggestions above:
- Supports 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 be reflowed. Special flow directions for reading double column PDFs and manga.
- Multi-lingual user interface optimized for e-ink screens. Highly customizable reader view with complete typesetting options. Multi-lingual hyphenation dictionaries are bundled in.
- Unique Book Map and Page Browser features to navigate your book.
- Special multi-page highlight mode with many local and online export options.
- Can synchronize your reading progress across all your KOReader running devices.
- Deep integration with Calibre (search metadata, receive ebooks wirelessly, browse library via OPDS). Wallabag, Wikipedia, Google Translate and other content providers are also supported.
Do you want to change some expression?
Note that F-Droid has no algorithm to show featured/most_downloaded/popular_apps etc. Not sure about Flathub. Often I search with specific keywords...some* of the F-Droid clients support searching from app descriptions. For example Droid-ify fully support it VS official client doesn't VS F-Droid site partially i.e. iff matched with the complete word.
e.g. Search: WRITE_SECURE_SETTINGS keyword. Results: Droid-ify shows results even before completing it VS no results from official client VS result only if you type the full word for F-Droid site.
Whatever the description maybe...my point is keyword specific search is the only option to discover if you never heard about the relevant app (in this case hidden gem KOReader)...we've to use most important keywords from the users prospective.
ebook, reader, PDF, EPUB, TXT, manga, Kindle, Kobo, PocketBook, Calibre, e-ink, highlight, dictionar, plugin, animation (users searching for no animation), Wallabag, Wikipedia, metadata, gesture? RSS? News?, Statistics?, Profiles?, Vocabulary?
Most of the keywords are already present in our description...just a reminder not to remove important ones during the process :) Maybe allow AI to jumble around the keywords to generate it...the only thing in which AI is good at. 😒
So final copy-pastable version with everything applied from this message and Commodore64user's suggestions ~above~below:
@offset-torque Gesture keyword missing....I find it one of the most important feature. So most e-ink users will probably search for this keyword.
Old description: Powerful gesture system and ability to create your own menus.