User guide specs

[pazos]

I don't want to spam koreader/koreader#11147, since it has nothing to do with the main purpose of the user guide.

In order to export the guide to a self-contained offline document we would need:

• fix html validation
• probably aim to a letter-sized pdf/djvu, instead of a fully reflowable document
• set a pipeline with pandoc and a utf-8 aware latex distro (xetex or luatex)

a few minors things are converting webp images (one currently) to png and make sure inner links point to the correct placement.

I'm all in for the pandoc/latex thing, but I'm not sure if @offset-torque is at all interested in the guide exported as a document.

In case you're interested we just need to make sure the guide in html can be validaded in order to be parsed properly by pandoc. Fixing the issues that validation services are returning https://validator.w3.org/nu/?doc=https%3A%2F%2Fkoreader.rocks%2Fuser_guide%2F

[poire-z]

In order to export the guide to a self-contained offline document we would need:
[...] probably aim to a letter-sized pdf/djvu, instead of a fully reflowable document

It would be a step back to go with PDF: it was originally PDF, and was changed to HTML for easier reading and translation - which should allow easy translation to EPUB.
With a PDF and fixed layout, we won't allow users to change font size - or they would have to use reflow with all the crappy loss of formatting and ugliness.

And why offline ? if not for reading on KOReader :)
If for reading on KOReader, EPUB is obviously the best choice.
If for printing, a user can just print from his web browser our single-page user guide.

[pazos]

I'm totally fine with epub too. I guess it involves a work I'm not very familiar with.

[offset-torque]

I did some tests 🔬

User guide as a single HTML file (using the SingleFile browser extension):

• Creates a perfect offline copy as a self-contained browser compatible HTML file
• Base64 encodes the fonts and images
• Packed file size is equal to the unpacked size
• Usable in KOReader but needs changes to CSS because of limited crengine support

Procedure:
I already started making an e-ink friendly CSS for the guide a while ago.
So, after each guide update I can replace the CSS section and export the guide as a single HTML file.

User guide as a PDF:

This is inferior to the option above. Only advantage of PDF is printing I think.
If a user wants to print some part of the guide (current page, gesture actions chapter...) it is easier with a PDF.
I tried Firefox's inbuilt "Save as PDF" printing.

• Nearly identical to the web version
• Print size of text looks ok when page is scaled to fit
• File size increased ~3x

Procedure:
I can export to PDF after a guide update as mentioned above
OR
We can instruct users to do it themselves using their browser's Print dialog

User guide as an EPUB:

I used Calibre for converting the single HTML mentioned above.
This is not the correct workflow I know but I was just curious.
Result was a very mangled document.

---

I am curious about the comparison (advantages/disadvantages) between the single HTML and EPUB.
Since I don't have a proper EPUB of the guide now, I can't compare it myself on KOReader.
HTML rendered pretty good with zoomable images. Font scaling is possible too.

[poire-z]

I am curious about the comparison (advantages/disadvantages) between the single HTML and EPUB.

Not much, if your HTML with base64 images all works fine in koreader, that's fine - just a bit surprising as if I see a standalone HTML file, I would expect it to miss images and be crappy.
With an EPUB, you would get metadate (title, authors, publisher) - and a proper ToC.
Dunno if crengine is able to build a ToC with your HTML file - it may, from headings. But on other HTML readers/renderers, users may miss a ToC.

[Frenzie]

I used Calibre for converting the single HTML mentioned above.
This is not the correct workflow I know but I was just curious.
Result was a very mangled document.

I see no reason that wouldn't be a correct workflow. There are merely a few minor compatibility issues that'll need to be resolved.

[pazos]

If epub then we need embedded fonts¿?. I mean "microns" is used in the web for emojis. Do we have unicode coverage for emojis already? Damn..

[offset-torque]

poire-z - just a bit surprising as if I see a standalone HTML file, I would expect it to miss images and be crappy.

I am surprised that it worked well too.

Frenzie - I see no reason that wouldn't be a correct workflow. There are merely a few minor compatibility issues that'll need to be resolved.

The resulting epub was so broken that I assumed that the converter is confused with the bundled html. Calibre e-book viewer couldn't open it properly (only two pages could be shown) and Okular rendered it without any CSS applied.

pazos - If epub then we need embedded fonts¿?. I mean "microns" is used in the web for emojis.

I removed all the fonts except one in the previous update but translators complained (rightfully) that their fonts don't cover the symbols so this font is added as a lightweight symbol source.

---

As a next step, now I will work on the e-ink CSS so we would be able to see how the guide looks like on an e-ink with KOReader. poire-z replied with this #52 (comment) previously so I will have a look at what is supported and do some experiments.

[Frenzie]

The resulting epub was so broken that I assumed that the converter is confused with the bundled html.

Sure, but by itself that doesn't mean much of anything. My prediction would be that if you toss it in HTML Tidy first it'll be just fine. But we'll see in a minute or two: #60

Edit: Tidy was a touch more trouble than I anticipated, but you'll find it works a lot better now.
KOReader Manual EPUB.zip

[offset-torque]

I have a question:

These characters which are coming from emoji are rendered correctly on KOReader.
I assume these are being pulled from the bundled NotoSans Nerd Font.

But for example warning emoji codepoint is U+26A0 (and U+FE0F) which doesn't exist (or I couldn't find) in Nerd Font.
There are 2 other warning icons in Nerd Font but when I try to use them they render as "?".

Sooo what is going on here? I am very confused.
In essence: Why can't I render the symbols in NotoSans Nerd Font but the warning symbol works (despite not existing in the Nerd Font)

---

Why am I asking this:
Since we have nice symbols already bundled with KOReader, if I can use them, we don't need to pack any symbols font. Guide can use the user's own selected font so in this case we don't need to pack any fonts.

There is a wrinkle. Nerd Fonts is already included with KOReader so there is no overhead for using it but for online usage it is a giant font (which will double the inital page loading time). Forcing users to download 3705 glyphs to use 5 of them is not very elegant, so I was thinking of creating a subset for online use.

[poire-z]

Nerdfont (standalone, it has nothing to do with "Noto") is special and hacky: it contains glyphs that are not part of Unicode. It's just there to get symbols for use in our UI. It's always a pain to find out the code to use for a glyph.
Moreover, we "moved" range of glyphs to other part to avoid some conflicts, ie. koreader/koreader-fonts#8.
Moreover, it's an old version - recent versions of online nerdfond have shuffled glyphs around, so we can't even user their website search feature to find out a glyph and its code.

(No obvious idea and no time to think more about a solution to your issue.)

[offset-torque]

it has nothing to do with "Noto"

Embedded font info disagrees: "Full font name: Noto Sans Regular Nerd Font Complete"

So are you telling me that I can't access the characters in the font that we are packing with our software because...apparently no one knows which character is which? But if I only know the "secret code" I should be able to show them because they exist, right? But this secret table is not available anywhere. This sounds like some Harry Potter plot :)))

Anyone else in this repository knows how can I use these symbols?

---

(And if this monstrosity is already out of control like this and already lost synchronization with the up-to-date version, logical thing is extracting the few glyphs that we use in KOReader to a custom font instead of shipping this one megabyte black box. But I guess everyone is too busy and it "works".)

[Biep]

I still have the same issue with the version you posted here: when I open it, and do twice aNext page, I am on the page explaining Auto straighten.

• In KOReader it takes one more Next page, as the intro doesn't fit on a single page, and the page counter acknowledges that I am on page 5.
• In the Calibre eBook reader I am at 100% and further Next page attempts have no effect.

I wanted to take a screenshot of the table of contents, showing how much it thinks is on page 1, but I forgot the gesture for it. Looking for "which gesture does X" is hard, and menu search for "screenshot" only shows the screenshot folder setting. I defined two new gestures for it, but it seems they don't work in the table of contents.
Anyway, everything up to the page with Auto straighten is on page 1, according to it.

[NiLuJe]

NerdFont is a patchset on top of many many many fonts, we happen to use the Noto one because that's our UI font.

You'll have to poke at it with fontforge to search for the code point of the glyph you want by name.

[offset-torque]

Got it NiLuJe. I looked around a bit and found that symbols are actually recognized by KOReader and codepoints looks correct in the unicode debug view. But for some reason only one of the symbols is rendered in reader view, others are "?" as in the image. Any ideas?