EPUB

[Rob Beezer]

I would like to prioritize some progress on EPUB. The goal would be to have it
as an output format on equal footing with HTML and LaTeX/PDF. Reliable,
regularly tested, regularly improved based on reports.

Why?

1. It demonstrates our commitment to multiple output formats. Many interactive
features will necessarily need to be static, but at the same time this is an
electronic format based on HTML output. So as a development activity it will
strengthen both HTML formats (web, Jupyter, Reveal slides) and static formats
(PDF, braille).

2. There is a new eBraille standard, which was released as version 1.0 back in
August. We know how to do this - Unicode braille (Speech Rule Engine in MathJax
for Nemeth, liblouis for literary text), tactile graphics from PreFigure,
packaged up as EPUB 3.0. It would be so nice to be relieved of the strict line
and character counts of embossed braille and the indentation rules. I've not
kept up, so cue ChatGPT:

"eBraille is a new digital publication format developed for braille content
(including tactile graphics) that works especially well with refreshable braille
displays of varying size and line lengths"

"eBraille uses a file-set that is compatible with EPUB 3 technologies, e.g.,
XHTML, CSS, navigation documents, manifest/spine via the EPUB packaging model."

3. There is regular interest in offline formats. And I (we?) are fond of
saying that PDF is a bad, bad format (for many reasons) and EPUB is superior.
We should put our money where our mouth is. OK, we don't have much money -
development effort.

4. There are some accessibility standards for EPUB. And we can convert an EPUB
document into speech using various tools, so "talking" books are possible. (We
already embed speech strings for math.)

What needs to be done? And who might do it?

A. Relax the "book-only" setup and accomodate #article so we can test on a
broader range of test documents (minimal, sample article, WW sample chapter).
Rob, Mitch, perhaps Oscar.

B. Figure out offline placement of CSS and isolate what PreText needs, and what
EPUB does not need. I'm hoping the recent CSS push will be invaluable for this,
but I'd also guess it might be a big job. Andrew, perhaps Oscar.

C. Offline math via MathJax, espcially for MathJax 4. David A.

D. Testing. Calibre works great on desktops. Good for development, but almost
like cheating. I've had great luck with iBooks on iPad. Android was a
continuing frustration. Anyone with tablet hardware (Apple and Android and
Fire, etc) could help here. The "epubcheck" tool can be run against your own
projects, to catch things we are not finding.

E. Kindle support. Really frustrating, I know. Can wait until this effort
settles down. Mitch.

F. Accessibility (other than braille). Improve our HTML as it goes into EPUB.
Make talking books. Alex.

Of course, anyone with interest can help. Names above are just the likely
suspects. All expressions of enthusiasm and interest in participating are
encouraged.

Rob

[Rob Beezer]

> All expressions of enthusiasm and interest in participating are encouraged.

OK, I'm in and enthusiastic and have a little bit of progress to report. ;-)

I turned off the "we fail if you are not a book" switch and added chunking
levels for "article". So almost no effort.

Minimal article - looks great, lacks a ToC. Two warnings and one error (that is
not related to CSS).

Sample article. Not bad. Still lots of rough edges. About 600 non-CSS errors,
half of those are based things in SVG built by other tools (Sage, Mermaid). We
might be able to easily edit those out once understood. The remainder come in
big categories of multiple instances of the same "problem". Looks to mostly be
images not in the manifest, or reactions to the structure of an #article (vs. a
#book).

Have a look via Calibre (which is cross-platform), or even better, try your
tablet/phone.

https://pretextbook.org/beta/epub/minimal-20251122.epub

https://pretextbook.org/beta/epub/sample-article-20251122.epub

Rob

[David Austin]

I'm in and enthusiastic as well.  I've even been reading through the eBraille standards as a fun reading project this fall and in anticipation of this.  I view eBraille as an important development and believe we need to "put our money where our mouth is."  And yes, I also think "we" know how to do this, at least in the big picture.  eBraille looks a lot easier than the embossed version.  Maybe we can get a Monarch on loan through one of our contacts?

David

--
You received this message because you are subscribed to the Google Groups "PreTeXt development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/MTAwMDAwNy5iZWV6ZXI.1763842686%40pnsh.

[Andrew Scholer]

I'm willing to contribute. Mostly by helping identifying causes and/or implementing solutions to CSS related issues.

I would be extra willing to help if we are organized about making issues so I can periodically dive in and work on multiple things at once. (Without having to search back through old -dev posts looking for issues.)

I just got the ball rolling on what hopefully is a wave of EPUB issues:
https://github.com/PreTeXtBook/pretext/issues/2726


Andrew

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/CANXmVMA_aQeZB7RQ5Oc7U__msv0ga2aeL6NfqKWS5UZBxcAOkQ%40mail.gmail.com.

[Rob Beezer]

On 11/23/25 08:51, Andrew Scholer wrote:
> I'm willing to contribute. Mostly by helping identifying causes and/or
> implementing solutions to CSS related issues.

Thanks very much, Andrew! Where the CSS comes from, and how it gets placed, is
not at all rational, iirc. Maybe we can talk at Drop-In about a better starting
place to iterate from.

> I would be extra willing to help if we are organized about making issues so I
> can periodically dive in and work on multiple things at once. (Without having to
> search back through old -dev posts looking for issues.)

Good idea.

> I just got the ball rolling on what hopefully is a wave of EPUB issues:

> https://github.com/PreTeXtBook/pretext/issues/2726 <https://github.com/
> PreTeXtBook/pretext/issues/2726>

And I just put an "epub" label on that one. And I think we have a "css" label
too. So I'll try to be diligent about getting those in-place.

Rob

[Bradley Miller]

Who is our target audience for epub?  After reading this I went down a gpt hole to see what kind of support for Javascript exists today.  The answer is depressing.  Mostly it depends on the reader you use and the readers range from hostile (Kindle) to pretty good (Apple iBooks) to mostly broken kind of everything else.

Alternatives to consider are Progressive Web Apps and/or A static page with offline support including a service worker.  This would give a user the functionality of a current html (non-runestone) build but fully functional when offline, and of course very fast.

Brad Miller
Professor Emeritus, Luther College
Founder, Runestone Academy LTD
Blog: http://reputablejournal.com

Set up a time to meet with me.

--
You received this message because you are subscribed to the Google Groups "PreTeXt development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/MTAwMDAxNi5iZWV6ZXI.1763925684%40pnsh.

[Rob Beezer]

On 11/22/25 13:37, David Austin wrote:
> I'm in and enthusiastic as well.

Thanks for the enthusiasm. ;-)

> I've even been reading through the eBraille
> standards as a fun reading project this fall and in anticipation of this.  I
> view eBraille as an important development and believe we need to "put our money
> where our mouth is."  And yes, I also think "we" know how to do this, at least
> in the big picture.  eBraille looks a lot easier than the embossed version.

I've been musing that perhaps we should rip out every text node (non-math), hit
it with liblouis (Python bindings), and make it avaiable to whatever conversion
needs it. Giving it an ID could be the hard part - just haven't thought it
through very far.

The mjsre script is really the big blocker at the monent (and the "mathjax
knowls" javascript). Ideas on making progress on that?

> Maybe we can get a Monarch on loan through one of our contacts?

That would be very nice to experiment with. Maybe Al and Alexei know how to
swing that. Looks a bit too rich for the PROTEUS grant.

[Rob Beezer]

Dear Brad,

We have no illusions about supporting the Javascript bits within EPUB. I won't
take issue with anything you found in your GPT hole. We've first-hand
experience with most of that.

There may be better solutions for an offline format for small (or weak) devices.
I would encourage anyone with an interest in this to commit to creating a
conversion. And commiting to maintaining it long-term.

Conversion to EPUB has seen a lot of development effort, and is working pretty
well now. It has some rough edges that need work. Already, we've hit a bug
with "local tags" in offline MathJax and I am now reminded of some overdue
improvements to the HTML conversion that are necessary for the EPUB conversion.

EPUB is a precursor for Kindle (thanks, Mitch!). Which provides a convenient
route for authors/publishers that want to distribute their text for a few
dollars. Or many dollars. EPUB packaging is the basis for eBraille. The only
reason we ever embarked on braille in the first place was because we had sorted
out "offline math" for EPUB and the strategy was nearly identical.

EPUB is a notch superior to PDF. But not by much. But I would cringe when I
would walk theough the library and see *all* the students hunched over their
laptops reading 2-up PDFs. Yuck. However, many authors want physical copies of
their books, and PDF is the way to go for that.

I have made the long-term commitment to the EPUB conversion. I'm ready to
improve it, that's what a long-term commitment looks like. It is an important
part of PreTeXt and the effort should pay-off PreTeXt-wide.

Rob

On 11/23/25 11:49, Bradley Miller wrote:
> Who is our target audience for epub?  After reading this I went down a gpt hole
> to see what kind of support for Javascript exists today.  The answer is
> depressing.  Mostly it depends on the reader you use and the readers range from
> hostile (Kindle) to pretty good (Apple iBooks) to mostly broken kind of
> everything else.
>
> Alternatives to consider are Progressive Web Apps and/or A static page with
> offline support including a service worker.  This would give a user the
> functionality of a current html (non-runestone) build but fully functional when
> offline, and of course very fast.
>
> Brad Miller
> Professor Emeritus, Luther College
> Founder, Runestone Academy LTD
> Blog: http://reputablejournal.com
>

> Set up a time to meet <https://fantastical.app/bonelake-Gj2i/meet-with-
> brad> with me.
>
>
>> On Nov 23, 2025, at 11:21 AM, 'Rob Beezer' via PreTeXt development <pretext-

> to pretext-dev...@googlegroups.com <mailto:pretext-
> dev+uns...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/pretext-

> dev/431B11DC-AB6B-4930-A786-A0D009A56A93%40runestone.academy <https://
> groups.google.com/d/msgid/pretext-dev/431B11DC-AB6B-4930-A786-
> A0D009A56A93%40runestone.academy?utm_medium=email&utm_source=footer>.

[Rob Beezer]

Making good progress on getting the EPUB conversion to function properly on
everything in the sample article. Concentrating first on errors reported by the
XSL, then will do nore about errors from the EPUB validator. Just pushed some
changes.

* Lots of work to get "generated" images properly slotted into the EPUB
manifest. Think QR codes, MOM images, and more. Took care of
https://github.com/PreTeXtBook/pretext/issues/2345
https://github.com/PreTeXtBook/pretext/pull/2326

* @Oscar - I've got an idea for "printouts" I'd like to run by you at Drop-In
tomorrow.

* @Andrew - EPUB validator doesn't like a @role attribute value on some Mermaid
SVGs. I haven't scratched the surface yet on this one, but we can probably edit
it out. There are going to be other things to edit out, lots of unlovable stuff
in various SVGs we make/use.

* @David A - EPUB validator seems to want a namespaced @id in PreFigure SVG. I
thought we had fixed that? I update PF, and rebuilt the image files. Could be
a mistake on mny end.

* @Brian W - I'm seeing the following from applying xsl/pretext-epub.xsl (six times)

PTX:INFO : * error
PTX:INFO : * xsl-number : negative value
PTX:ERROR : * PTX:ERROR: No matching #evaluate for #fillin in "".

The stuff in quotes is a value of @visible-id (maybe it should be @unique-id?).
I've got no real idea what is going on, but the error message leads back to
FITB. We are using the "static" version of the output from the pre-processor.

Rob

[Rob Beezer]

On 11/24/25 19:38, 'Rob Beezer' via PreTeXt development wrote:
> Just pushed some changes.

And a word of warning if you dive into this. Side-by-sides aren't. Maybe they
never have?

https://github.com/PreTeXtBook/pretext/issues/2727

Rob

[Rob Beezer]

The Python routines now have an option to dump the build directory for an EPUB
build, as-is, without "zipping" it into an archive to become a proper single
EPUB file.

For the pretext/pretext script, if you would have used "-f epub-svg" now try
"-f epub-svg-nozip", and similar for the three other ways of embedding the
math bits.

This is really meant for debugging, so the directory of stuff you will get has
some extra cruft that could be useful in tracking effects, changes, and bugs.
I've been doing this for a long time using the (preserved) temporary
directories, but this will be much cleaner/easier for development.

@Oscar - new signature, with a "file_format" argument right after the "dest_dir"
argument (sorta like for HTML). Values are "epub" (status quo) and "nozip"
(new). All the changes are in two commits. Does not necessarily *need* to be
in the CLI - your call, of course.

Rob

[David Austin]

*  @David A - EPUB validator seems to want a namespaced @id in PreFigure SVG.  I
thought we had fixed that?  I update PF, and rebuilt the image files.  Could be
a mistake on mny end.

I see that too, but only with two of the PreFigure diagrams included in the sample article and not with every instance of @id.  One of those two diagrams is annotated and the other not so that doesn't seem to be an issue.  The epub sampler passes the check.  I'll try to dig into it over the holiday.

David

 

* @Brian W - I'm seeing the following from applying xsl/pretext-epub.xsl (six times)

PTX:INFO    : * error
PTX:INFO    : * xsl-number : negative value
PTX:ERROR   : * PTX:ERROR: No matching #evaluate for #fillin in "".

The stuff in quotes is a value of @visible-id (maybe it should be @unique-id?).
I've got no real idea what is going on, but the error message leads back to
FITB.  We are using the "static" version of the output from the pre-processor.

Rob

--
You received this message because you are subscribed to the Google Groups "PreTeXt development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.

To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/MTAwMDAwOC5iZWV6ZXI.1764041939%40pnsh.

[David Austin]

The EPUB issue with the @id attributes in PreFigure SVGs is something new, but manageable.  EPUB (or at least epubcheck) enforces restrictions on the characters in the value of an @id attribute.  There are places where PreFigure generates @id attributes for SVG elements using the value of the @stroke attribute.  So if an author defines @stroke="#ffa", then the hashtag can slip into an @id attribute.  Something similar can happen with PreFigure #repeat elements.

I'll tighten up the way that PreFigure generates @id's, which should lead to a couple of improvements anyway, and include a check on author-created @id's.

David

[Rob Beezer]

Thanks, David! Now you can enjoy your holidasy, with the mystery solved. ;-)
No rush on a fix, now that we the source it identified.

I think I might have seen some fragment complaints, too, but had not chased
those down.

> which should lead to a couple of improvements anyway

Exactly. That is a small, but not insignificant, part of this EPUB push. The
HTML conversion has already seen some other (necessary) improvements.

Rob

> an email to pretext-dev...@googlegroups.com <mailto:pretext-
> dev%2Bunsu...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/pretext-

> dev/MTAwMDAwOC5iZWV6ZXI.1764041939%40pnsh <https://groups.google.com/d/
> msgid/pretext-dev/MTAwMDAwOC5iZWV6ZXI.1764041939%40pnsh>.

>
> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email

> to pretext-dev...@googlegroups.com <mailto:pretext-
> dev+uns...@googlegroups.com>.

> To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/

> CANXmVMBJoSt3nDbbFp%3D_UeLNLPpALEnJ26z22X9ceKs7J9qWnw%40mail.gmail.com <https://
> groups.google.com/d/msgid/pretext-dev/
> CANXmVMBJoSt3nDbbFp%3D_UeLNLPpALEnJ26z22X9ceKs7J9qWnw%40mail.gmail.com?
> utm_medium=email&utm_source=footer>.

[Rob Beezer]

> The EPUB issue with the @id attributes in PreFigure SVGs is something new,
but manageable.

Over on an issue, Andrew S alerted me to the latest version of the validator.
Running v5.3 got rid of *hundreds* of spurious errors, and seems to have
*increased* the errors for PF. Same files, same error mmessage, but more like
30 errors for "fibonnaci-b".

5.3 is easy if you have a command-line Java installed. I got it right first
time. ;-) Probably worth being sure you are using that (maybe you are!).

Rob

On 11/26/25 07:04, David Austin wrote:

> an email to pretext-dev...@googlegroups.com <mailto:pretext-
> dev%2Bunsu...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/pretext-
> dev/MTAwMDAwOC5iZWV6ZXI.1764041939%40pnsh <https://groups.google.com/d/
> msgid/pretext-dev/MTAwMDAwOC5iZWV6ZXI.1764041939%40pnsh>.
>

> --
> You received this message because you are subscribed to the Google Groups
> "PreTeXt development" group.
> To unsubscribe from this group and stop receiving emails from it, send an email

> to pretext-dev...@googlegroups.com <mailto:pretext-
> dev+uns...@googlegroups.com>.

[David Austin]

Right, there are 41 errors associated to that file (not trying to sound pedantic!).  I can fix them all with a one character change to the PreFigure source.  For some reason, epubcheck isn't working from the command line on my machine so I've been using the jar file so I think I'm seeing the same thing as Andrew.

David

To unsubscribe from this group and stop receiving emails from it, send an email to pretext-dev...@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/pretext-dev/MTAwMDAzNy5iZWV6ZXI.1764195910%40pnsh.