Issue: bookdown::epub_book renders ePub that fails epubcheck v. 4.2.6 with ERROR(RSC-012) and ERROR(RSC-005)

Summary (details and minimal working example at end): I have rendered an .Rmd to a .epub via bookdown::epub_book. From the _output.yml used in my Make File I have

bookdown::epub_book:
cover_image: "./Images/epubSampleCover.png"
chapter_level: "1"
epub_version: "epub3"
stylesheet: styles.css
number_sections: no
fig_width: 3
fig_height: 4
fig_caption: true
toc: yes

I have also tried

number_sections: yes

In both cases, the resulting .epub fails to pass epubcheck (and therefore cannot be uploaded into Apple Books since passing epubcheck is a necessary condition).

I have isolated the first error ERROR(RSC-012) "Fragment identifier is not defined" to the use of \@ref as in

{r,Figure \@ref(fig:epubSample1)}

when referencing a figure caption. I can confirm that, while bookdown::ePub-book does not throw errors in RStudio when building, the resulting ePub and figure references in the text do not shift focus to the figure but instead to the first page when testing the file on a local version of Apple Books.

I have isolated the second error ERROR(RSC-005) "While parsing file: value of attribute "width" is invalid; must be an integer" to the use using the out.width option in include_graphics as in

{r epubSample2, out.width="900px", fig.cap="(ref:epubSample2)"}
if(knitr::is_html_output()) knitr::include_graphics(c("./Images/epubSample2.png")) else knitr::include_graphics(c("./Images/epubSample2.png"))

I have also tried for out.width 100%, 100vh, 100vmax, 100vw but all throw the same "non-integer" error.

As @cderv has kindly pointed out to me recently, as a new person to RMarkdown/Bookdown/RStudio, not all issues are bugs, some are user errors. I do not know which is true in this case.

Possible Issue/Resolution:

In the case of Error[RSC-005], I can simply take out the out.width but then I am not sure how to size the images if needed.

It is unclear to me from reading the epub_book options what and how the sizing works

fig_width: 3
fig_height: 4

particularly when changing these numbers does not seem to affect the figure sizes (in my experience).

The Error[RSC-012] seems like I have forgotten to do something or set some option to allow ePub to reference figures. Perhaps it's a bug?

I can offer that in looking at the .epub output at one of the files in the OPF container EPUB/text/ch001.xhtml as text file I can see that

{r,As seen in Figure <a href="#fig:epubSample1">1</a>}

which seemed to be the same kind of output as in the pdfbook and htmlbook outputs where figure referencing does function properly.

I do not have a resolution to this epubcheck Error[RSC-012].

Details and Minimal Working Example:

I have placed all the files necessary to reproduce this error in a public repo on Bitwarden

In the folder ./source-posts you will find the file epubSampleTwoErrors.Rmd which compile via Make Files to ./output/posts/epubSampleTwoErrors.epub. There is also a file ./output/posts/epubSampleNoErrors.epub which shows how naively resolving the issues will have no errors.

The epubcheck information I have is from

java -jar /opt/homebrew/Cellar/epubcheck/4.2.6/libexec/epubcheck.jar --help

which returns I believe the latest version of epubcheck

EPUBCheck v4.2.6

I hope this is enough information to help figure out how to make my ePub created in Bookdown pass the epubcheck required for uploading to Apple Books.

Thanks to anyone who can provide some clarity or a solution.

Best,

Jason M. Osborne

I believe these can all be issues. Possibly related to

Epub is not an easy format to handle, and we rely a lot on Pandoc converted mostly.
I don't know if your issue are related to the one there, but this is definitely seem like something to look into.

We need to see if we can fix that on bookdown level, or if this is something to fix upstream in Pandoc.

I don't have the bandwidth right now to fix that but happy to help dig through this and review possible fix.

Sorry for the inconvenience on this.

Please do open a new issue if you think it is not related to the one above. The more minimal example we manage to create, the more easy it will be to look into what should be the right way to do that;

A few additional information from a quick check:

  • RSC 012 seems related to this : Fragment identifier is not defined. · Issue #1073 · w3c/epubcheck · GitHub
    It seems the issue would be that #fig:epubSample1 does not exist in the epub ?
    Does the figure has caption with an id in the epub ?

  • For RSC-005, I am just curious which is in the epub really ? If they want no using maybe you shouldn't provide one in out.width ?
    If we can know what is the expected output, we can check that Pandoc does produce the correct one, and that knitr does too.

Thank you @cderv for the link to the GitHub issue below

as this helped resolve my issue as follows:

  1. The Problem Using the epubSampleTwoErrors.epub file in public repo on Bitwarden (./output/posts) I found the following information

a. From the content.opf file we can see that the Figure in question is given an id file0_gif

 <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml" />
    <item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav" />
    <item id="stylesheet1" href="styles/stylesheet1.css" media-type="text/css" />
    <item id="cover_xhtml" href="text/cover.xhtml" media-type="application/xhtml+xml" properties="svg" />
    <item id="title_page_xhtml" href="text/title_page.xhtml" media-type="application/xhtml+xml" />
    <item id="ch001_xhtml" href="text/ch001.xhtml" media-type="application/xhtml+xml" properties="mathml" />
    <item properties="cover-image" id="epubSampleCover_png" href="media/epubSampleCover.png" media-type="image/png" />
    <item id="file1_png" href="media/file1.png" media-type="image/png" />
    <item id="file0_gif" href="media/file0.gif" media-type="image/gif" />
  </manifest>

b. However, in the text of the .epub file itself ch001.xhtml we see that when using \@ref as in Figure 1

Figure <a href="#fig:epubSample1">1</a>

that from the bookdown original, error output that the div does not have an id but that the img does have a source src="../media/file0.gif"

<div class="figure" style="text-align: center" >
<img alt="**The area of a $1 \times 1$ square on a sphere approaches $A=1$ as the radius of the sphere $\rho$ increases.**" src="../media/file0.gif"/>
<p class="caption">
Figure 1: <strong>The area of a <math display="inline" xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mn>1</mn><mo>×</mo><mn>1</mn></mrow><annotation encoding="application/x-tex">1 \times 1</annotation></semantics></math> square on a sphere approaches <math display="inline" xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>A</mi><mo>=</mo><mn>1</mn></mrow><annotation encoding="application/x-tex">A=1</annotation></semantics></math> as the radius of the sphere <math display="inline" xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mi>ρ</mi><annotation encoding="application/x-tex">\rho</annotation></semantics></math> increases.</strong>
</p>
</div>
  1. The Solution, in my case, is to give the div the same id as the href name. The functioning code is
<div class="figure" style="text-align: center"  id="fig:epubSample1">
<img alt="**The area of a $1 \times 1$ square on a sphere approaches $A=1$ as the radius of the sphere $\rho$ increases.**" src="../media/file0.gif"/>
<p class="caption">
Figure 1: <strong>The area of a <math display="inline" xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mn>1</mn><mo>×</mo><mn>1</mn></mrow><annotation encoding="application/x-tex">1 \times 1</annotation></semantics></math> square on a sphere approaches <math display="inline" xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>A</mi><mo>=</mo><mn>1</mn></mrow><annotation encoding="application/x-tex">A=1</annotation></semantics></math> as the radius of the sphere <math display="inline" xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mi>ρ</mi><annotation encoding="application/x-tex">\rho</annotation></semantics></math> increases.</strong>
</p>
</div>
  1. To Check this solution works note that using the epubcheck command line tool on the original, error file gives

%java -jar /opt/homebrew/Cellar/epubcheck/4.2.6/libexec/epubcheck.jar epubSampleTwoErrors.epub

ERROR(RSC-005): epubSampleTwoErrors.epub/EPUB/text/ch001.xhtml(68,592): Error while parsing file: value of attribute "width" is invalid; must be an integer
ERROR(RSC-012): epubSampleTwoErrors.epub/EPUB/text/ch001.xhtml(42,43): Fragment identifier is not defined.

Check finished with errors
Messages: 0 fatals / 2 errors / 0 warnings / 0 infos

EPUBCheck completed

Checking on the updated, file

%java -jar /opt/homebrew/Cellar/epubcheck/4.2.6/libexec/epubcheck.jar epubSampleOneError.epub

should give only one error now (the RSC-005, which is fixable by removing out.width) which we confirm with

ERROR(RSC-005): epubSampleOneError.epub/EPUB/text/ch001.xhtml(68,592): Error while parsing file: value of attribute "width" is invalid; must be an integer

Check finished with errors
Messages: 0 fatals / 1 error / 0 warnings / 0 infos

EPUBCheck completed

I am still new to looking at GitHub, so it is a bit unclear to me if issue was resolved or not.

Since I understand the problem and fix then the solution will be a simple "find and replace" on the chapter .xhtml files.

However, It would be nice if bookdown added an id to the div for figures so that one does not have to post-process output epub file.

From my reading of bookdown's origins and purpose, one of the main features is \@ref. So it might be nice to make sure that this feature works for all of the render_book formats that are indicated (pdfbook, htmlbook, ebook, gitbook, etc.). I have exported to all of these types so far and only had a problem with the ebook output format with \@ref. So that is pretty awesome and cool.

Thanks @cderv for pointing me to the issue which lead to the fix.

Best,

Jason M. Osborne