# Trying to bridge the gap to mobile-friendly reading of typeset equations, using EPUB3?

One of the sad facts about this blog is, that it’s not very mobile-friendly. The actual WordPress Theme that I use is very mobile-friendly, but I have the habit of inserting links into postings, that open typeset Math, in the form of PDF Files. And the real problem with those PDF Files is, the fact that when people try to view them on, say, smart-phones, the Letter-Sized page format forces them to pinch-zoom the document, and then to drag it around on their phone, not getting a good view of the overall document.

And so eventually I’m going to have to look for a better solution. One solution that works, is just to output a garbled PDF-File. But something better is in order.

A solution that works in principle, is to export my LaTeX -typeset Math to EPUB3-format, with MathML. But, the other EPUB and/or MOBI formats just don’t work. But the main downside after all that work for me is, the fact that although there are many ebook-readers for Android, there are only very few that can do everything which EPUB3 is supposed to be able to do, including MathML. Instead, the format is better-suited for distributing prose.

One ebook-reader that does support EPUB3 fully, is called “Infinity Reader“. But if I did publish my Math using EPUB3 format, then I’d be doing the uncomfortable deed, of practically requiring that my readers install this ebook-reader on their smart-phones, for which they’d next need to pay a small in-app purchase, just to get rid of the ads. I’d be betraying all those people who, like me, prefer open-source software. For many years, some version of ‘FBReader’ has remained sufficient for most users.

Thus, if readers get to read This Typeset Math, just because they installed that one ebook-reader, then the experience could end up becoming very disappointing for them. And, I don’t get any kick-back from ImeonSoft, for having encouraged this.

I suppose that this cloud has a silver lining. There does exist a Desktop-based / Laptop-based ebook-reader, which is capable of displaying all these EPUB3 ebooks, and which is as free as one could wish for: The Calibre Ebook Manager. When users install this either under Linux or under Windows, they will also be able to view the sample document I created and linked to above.

(Updated 1/6/2019, 6h00 … )

(As of 1/4/2019 : )

Hence, I could use the following logic:

• If people were able to read my PDF documents fully, they were already using either a Desktop or a laptop,
• If this is so, then they can also just install Calibre, at no financial cost,
• The added benefit of my using EPUB3 format now remains, that some people who were using smart-phones to read my blog, have the option of installing and paying for a proprietary solution.

But in practice, I don’t really see this as much of a win-win situation for my readers because, instead of telling them ‘Install this one piece of software,’ I’m telling them, ‘Install either this piece of software, or that piece of software, to take in my blog fully!’

I can appreciate how annoyed users get, when a Web-site requires actions from them. The ability to view PDF Files is always present, on a Desktop or a Laptop. The request to my readers, even to install Free Software, would be overbearing from me. And, so I’m balancing this scenario in my head, of generally offering these sorts of documents, in two formats.

It’s just a shame that the effort that would be required, for me to go back and offer an EPUB3 -version of all the PDFs, which I already did author, would be too great an undertaking, for me to embark on.

(Update 1/5/2019, 15h25 : )

I suppose that one question which some of my readers might want an answer to would be, ‘How can users generate EPUB3 ebooks, on a Linux platform?’ And yesterday I tried several solutions, the first of which had as goal, that I would generate EPUB2 ebooks, which my readers could view either with the apps ‘FBReader’ , or with ‘Aldiko’ . Those solutions gave inconsistent results. I was making use of the Linux command-line:

‘tex4ebook’

Only to find out that this command-line was ill-suited for typesetting Math. This command would generate small PNG (Image) Files, which contained the actual Math glyphs, and would first insert those into flowed HTML, before creating an EPUB document with the same HTML, and, if the option was given, to derive a MOBI-File document, from the generated EPUB-File, for which the proprietary command-line tool needs to be installed from Amazon, which is called ‘kindlegen‘ .

Regardless of how I modified my efforts yesterday, the best result that I could get was, that the Math would display in ‘FBReader’ , but with the line of text aligned to the PNG Image’s bottom. In some cases, the flowed text would display in such a way, that the line of text was actually aligned with the top of the image! By itself this is a deal-breaker because one cannot afford the confusion, of the reader perhaps interpreting an appended variable as having the semantic meaning of either being a subscript, or even an exponent, if the correct meaning is for the right-hand variable just to be multiplied, by whatever is to its left. Even if the item to the left of the variable is an expanded matrix, the author cannot leave it to the imagination of the reader to figure out, that what was meant should only be a matrix multiplication.

When opening the same files with ‘Aldiko’ , I found that this ebook-reader would insist on always displaying the pixels of the PNG-File, at a 1:1 ratio with the device’s / phone’s physical display, and no manipulation I could think of, of the generated Styles or of the HTML itself, would convince Aldiko to do otherwise. Also, the ‘-r’ command-line argument for ‘tex4ebook’ seemed to have no effect on this behaviour – Perhaps, a bug in the script? This tends to result in ‘a very small dot’ where the Math figure should appear, too small for people to recognize, and certainly not an acceptable result. And this unacceptable result would take place, not because of an error which the author might have made, but entirely due to which ebook-reader the reader had chosen.

So after attempting to achieve the unachievable for several hours, I finally conceded, and selected the ‘EPUB3′ format, which the ‘tex4ebook’ command-line does not generate in any special way, such as maybe, ‘With MathML instead of with those PNG Images?’ The following shell-script was instrumental in creating the desired result:

#!/bin/bash

#   /opt/dirk/Make_XHMTL.sh
#   Permissions:  chmod a+rx

#   Input: 1 Parameter with no spaces,
#       LaTeX File, with name ending in .tex
#   Output: XHTML File, with name ending in .html
#       Containing MathML

#   Warning: Many temporary files generated in pwd,
#       With same base-name !

#   Symlink to this script to be placed in /usr/local/bin

if [ -z "$1" ] || [ "${1: -4}" != ".tex" ] ; then
echo "Usage: Make_XHTML.sh <myfile.tex>"
echo "Output: <myfile.html>"
echo "Also generates many auxiliary files <myfile*>"
echo "Places all output in PWD."
exit 0
fi

PATTERN=$'[ \'"\t]' if [[$1 =~ $PATTERN ]] ; then echo "Error: Parameter must not contain spaces." exit 1 fi if ! [ -a "$1" ] || [ -d "$1" ] ; then echo "Error: Could not locate File$1"
exit 1
fi

htlatex \$1 'xhtml,charset=utf-8,mathml' ' -cunihtf -utf8 -cvalidate'



There are a few things which the reader should know about this script. One is the fact that we need to have a sufficiently-complete installation of LaTeX in order for the script to work. Another is the fact that what is output, is not an EPUB-File, but rather, a file with a name ending in .HTML, that is in fact an XHTML-File, as well as numerous auxiliary files.

But then, using the GUI of the installed application ‘Calibre’ , it’s possible to import the XHTML-File that results, into our library of ebooks. This will cause an entry to appear, that Calibre displays as only existing in ZIP-File format. And Calibre offers no options to view this format, other than as a bundle of files. But what this enables us to do next, is to Convert the ebook in question, to “EPUB Format”, again using the GUI. After that, EPUB will be one of the displayed formats for the book, which can be viewed as well as copied to another folder, and which is a self-contained file.

If the XHTML contained MathML, then an EPUB3 document will result, which the reader can either display correctly, or not at all. And with Math, that should be the desired result.

I suppose that I should add another comment on how the LaTeX document can be generated. In principle, many ways exist to output a TEX-File, along with all the supporting files. The method chosen results in small differences in the generated LaTeX. I like to use ‘LyX’ , a GUI-based, ‘WYSIWYM’ editor, mainly suited for exporting to LaTeX. There are some facts about how to use LyX, which users familiar with regular word-processors may not be familiar with.

The most important, relevant guideline is: All LyX or LaTeX documents have a “Document Class”. LyX defaults to the class ‘Article’ . Many of the PDF-Files I’ve generated for this blog were generated with that document class. It’s suitable for creating brief pieces of text, as well as figures, that simply seem to float in space. ‘Article’ is not a suitable document-class for EPUB documents! The most-suitable document class which I’ve found for the moment is “Book (Standard Class)”. What this document class will provide, is a context for generating a Title, which the GUI of LyX allows us to do, and from which LyX will enter a ‘\maketitle’ Tag into the generated LaTeX document.

Such meta-data will eventually become important, if the resulting document is to be imported into Calibre. And the reason is the fact that Calibre does not base its naming of the document, on file-names. Instead, Calibre will generate folders and file-names derived from this meta-data. What I actually found was, I needed to specify the ‘Author’ meta-data again, from within the GUI of Calibre.

(Update 1/6/2019, 6h00 : )

One of the feats which I was able to accomplish was, to edit the LaTeX-File, so that when using ‘tex4ebook’ to output an EPUB2 ebook, all the Math looked typeset almost correctly when viewed using the Calibre ebook-reader, even though some of its figures had first been converted into PNG Images. But, the resulting EPUB2 ebook did not look typeset correctly on any smart-phone app:

So here the issue remained, ‘A collection of 3 items stacked vertically cannot be encoded, so that a first item must instead be encoded as having both a subscript and a super-script. This would still be correct mathematically, if the resulting super-script was not additionally displaced horizontally, with respect to where the subscript is.’

The question could be regarded as meaningless, whether such an ebook format is still ‘valid’ . Calibre could have the ability to render it ‘correctly’ , simply because that reader has the entire resources of the PC it’s running on to do so. The display of EPUB documents (without MathML) is ultimately based on how well the platform-libraries render HTML, which means that on a PC, very convoluted EPUB documents will display, that do not on some smart-phones.

For that reason I’m not going to waste my readers’ time, explaining what LaTeX formatting led to this result.

Dirk