User:Inductiveload/Sandbox/Formatting for export

Preparing works for export
Certain things must be checked before marking a work as "ready for export".


 * Consider what content is exported and in what order.
 * Check the formatting is suitable for exported formats.
 * Add Category:Ready for export when, and only when the work is ready.
 * Use Export formatting needed to mark a page as needing work for making it ready for export (adds to Category:Works needing export formatting).
 * Use Export to check to mark a page that you think is ready but would like to be checked (adds to Category:Works needing export check).

Headers are not exported
The header template is not exported. This includes the notes field. There should be no content in that field that is necessary for the navigation of the ebook. For example, do not put a Table of Contents in that field if there is no TOC also in the main text body.

Also, do not rely on a singe "next" link to provide navigation to begin the book. Use a TOC on the front page of the work.

Listing pages for export
The export tool looks for links to subpages on the top level page and uses them in the order that they appear. Usually, this works well, as most works are either on a single page, or have a TOC on the top page that lists all subpages in order.

If a work does not have such a TOC (e.g. it has multiple TOCs on subpages, you must add a TOC that WS-export can read, using the class . (TODO: this needs an example in use)

....

Formatting for export
Some formatting that works well on a device with a large screen and feature-rich browser, like a computer, does not work so well on less-capable devices like e-readers. There are some things you can do to make the EPUB and MOBI exports look and function better on e-readers. There are some main things you should consider when formatting a work with a view toward exports:


 * E-reader devices generally have much smaller screens
 * E-reader devices, apps or the ebook export tools may not support all formatting features that work in browsers
 * Some content visible on Wikisource is excluded from the exported formats

Formatting for small screens
Smartphones often have an effective pixel width of around 350px. For a "normal" font size, this is about 23em. Because e-readers can adjust the font size, you should be cautious when making assumptions about screen width in relative terms such as "em". If the user has set a large font (perhaps due to their vision), they may have a page only 10em wide.

Avoid fixed-width formatting


Any formatting that uses a "fixed width" is at risk of not fitting on a mobile device screen, especially if the width end up over about 350px.

In the following examples, the red box is a simulation of a small screen, and any content that spill out is either not visible at all, or must be scrolled to be seen. Blue boxes are examples of a larger screen.

Here, we have a fixed-width block center template that is wider than the screen. Everything outside the red box will spill off the screen on an e-reader of that size:

The solution here is to use the  CSS property. This means that the content will not grow larger than the stated size, but it can shrink to be smaller if needed, for example, if the screen is smaller than the stated 500px. If the screen is wider than 500px, the content will be limted to 500px.

Avoid wide fixed-width images
Images are also often elements that spill off pages, as they are specified in pixels and are frequently wider than 350px:





Some ebook readers (and the mobile Wikisource site) provide extra logic to ensure images fit the screen, so you may or may not run into this issue in testing.

An alternative is a template like img float or large image that provides CSS that prevents the image being larger than its container, but still allows the image to expand up to the given pixel size, if there is space to do so:

On a 350px screen, the image will not spill out:

On a 600px screen, the image goes up to the specified 500px:

The FI template is similar, but can also be a problem, because it loads the full-size image. This can inflate the size of the ebook by 10–50 times, resulting in a file over 100MB. Some e-readers have only 1–2GB of storage, so this is quite limiting. large image allows the same shrink-to-fit as FI, but will not request the full-sized image.

Avoid fixed indenting
Indenting by a large amount with the following construction (sometimes used to simulate right alignment) can spill off the page:


 * Indented content


 * Indented content

Depending on what you are trying to achieve, one of the following might be more suitable:

Right aligned Right aligned with offset Centered

Right aligned Right aligned with offset Centered text

Avoid fixed columns
Fixed column layout look fine on a computer, but they can become very squeezed on e-readers:

You can specify the minimum width of the columns, so that the number of columns reduces in narrow screens. The correct minimum width may well depend on the content, but generally, around 12em is a good lower bound, below which columns tend to start looking very squeezed.

Table-based columns templates like multicol cannot do this, and these are very likely to produce ebook content that is difficult to read due to extremely narrow columns, especially if there are more than 2 columns.

Sometimes, for things like side-by-side translations (as is common in bi-lingual treaties, for example), there might be not much you can do about this.

Obsolete tags
Obsolete HTML tags like  are not understood by the ebook formatters. Do not use them, and prefer templates like center instead. Such tags are also often lint errors too, so they should be removed anyway.

Table alignment
The following construct for centring a table on the page does not export, and the table will be aligned to the left of the page:

Instead, use the CSS  style to do this in a modern and portable manner:

Dot leaders
Table dot-leaders generally do not export well, as they are generated by a complex "hack" that some ebook readers do not understand.

Page breaks
The page break template should be used to force page breaks in ebooks. It contains special CSS that ebook readers can use to paginate content. This is often useful in the front matter of books where the content should not flow together:

Testing
You can text e-book formatting in 2 ways:


 * Viewing the online page in a browser's "mobile view".
 * Downloading an EPUB or MOBI format and viewing on an e-reader or e-reader app. Only this method allows to you to check for issues like missed sections.

Online viewing
You can test how a page looks in a mobile browser (which is generally broadly similar to most e-reader devices) by using the "Responsive Mode" in your browser. In Firefox, this is Ctrl-Shift-M and in Chrome it is also Ctrl-Shift-M, but the developer tools has to be opened first.

As a rule of thumb, if the work looks OK in both Layout 1 (full-screen width) and Layout 2 (constrained central column), it will generally be OK on mobile. However, Layout 2 is still about 50% wider than a phone screen, so you could miss some issues.

Using an e-reader or e-reader program
You can test e-reader compatibility by downloading the EPUB or MOBI file as normal and opening it on an e-reader device or with an e-reader program or simulator.

Native desktop programs that aren't dedicated simulators generally use fully-capable HTML renderers (like browsers do) so they may do better than real devices at rendering content.

Examples of e-reader programs


 * Most PDF viewers on Linux
 * Calibre eBook Reader
 * Firefox e-reader Extension: https://addons.mozilla.org/en-US/firefox/addon/epubreader/

Examples of simulators that attempt to render an ebook as on a device:


 * Kindle Previewer (Windows only): https://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000765261
 * Adobe Digital Editions: https://www.adobe.com/solutions/ebook/digital-editions/download.html

Wikisource issues
There are some site-wide issues that lead to issues in ebooks. Not all of these may be tractable to fix.


 * Dot-leader tables: as mentioned, these do not look good due to the hacks used to format them. There is probably not a lot that can be done about this, other than simply not using them.
 * block center with fixed width: perhaps these can be changed to max-width across the board. Is there any case where a block center must not shrink to fit its container?
 * Sidenotes rarely work in ebooks. Generally they are simply inlined with the surrounding text, usually with a fairly acceptable result. Again, there is probably not much that can be done here.
 * sfrac does not work well - the line ends up spanning the whole page. Some usages can be changed for Unicode fractions, but not all.
 * overfloat image is hardcoded to use pixels for sizes. This is pretty much guaranteed to break if the image is rescaled (e.g. on mobile)

E-reader issues
These might indicate issues in Wikisource HTML output (in which case they belong above), ebook conversion (open a WS-export bug) or the apps/devices themselves (open issue on those projects):


 * block center doesn't seem to render correctly in MoonReader+, it ends up left-aligned.
 * small caps doesn't work in MoonReader+