Documentation improvements and corrections

[JayPanoz]

I'm submitting an issue following some feedback from @mickael-menu

Short description of the issue/suggestion:

There are a few places in docs that could be improved or clarified.

Other information (e.g. related issues, suggestions how to fix, links for us to have context)

Here’s a list of things we could improve.

var root = document.documentElement || document.getElementById("iframe-wrapper").contentWindow.document.documentElement; 

We should remove || document.getElementById("iframe-wrapper").contentWindow.document.documentElement since it doesn’t add much to it, implementers dealing with iframes know they are using an iframe and the context is the contentDocument anyway.

For default.css we should make it clear inline style="" should be checked in the entire DOM and not only html or body.

“Theme” is confusing in the User prefs doc as it’s used for multiple things. In addition it’s not super clear what sepia and night modes are compared to custom themes.

For the typeface names, we could mention this link to highlight it’s mapped on type classifications people use in typography. We could maybe even advise to use these names in the pref panel instead of hardcoded Font family names we are not sure are available on the platform.

The typeScale concept could probably be defined/described in a few sentences and illustrated by something like this web app: https://type-scale.com

There’s a mistake in the API Doc: font stacks are listed for fontSize.

We should also add instructions for embedding fonts (and mentions of alternatives like google fonts, downloadable fonts on Android/iOS, etc.).

[mickael-menu]

We should remove || document.getElementById("iframe-wrapper").contentWindow.document.documentElement since it doesn’t add much to it, implementers dealing with iframes know they are using an iframe and the context is the contentDocument anyway.

I found this piece of code confusing, but it could still be useful to mention that properties need to be set on iframes' contentWindow, when used.

[JayPanoz]

Re i18n doc

Although the vast majority of the UX can be ltr, I’m noticing that vertical writing + the toc panel is an open question BTW.

In Requirements for Japanese Text Layout:

For example, the table of contents may contain small modifications. Furthermore, there are many examples of indexes with a different page format than the basic page format, and vertically set books often have indexes in horizontal writing mode and sometimes multiple columns.

They just mention indexes for ltr layout in vertical-rtl so I’m assuming Apple Books does the right thing by having the toc panel the same as the reading progression of the publication.

[JayPanoz]

Add this warning about Mongolian directly in docs.