asciidoctor-mathematical
asciidoctor-mathematical copied to clipboard
asciidoctor
Image size in epb3
When trying asciidoctor-mathematical with the epub3 backend, it correctly generates the SVG files, but the fonts are very large which means the equations look very odd. This will be even more problematic for in-line expressions, e.g., "You can see that x \times 3 = 9".
Have you tried the png backend? Does switching from svg to png solve the problem?
Here's the source:
Here is some maths in a block
[latexmath]
++++
k_{n+1} = n^2 + k_n^2 - k_{n-1}
++++
And another block.
[latexmath]
++++
sqrt(4) = 2
++++
Here is some inline maths latexmath:[a=4^2].
Here's a screenshot of the output using:
asciidoctor -r asciidoctor-epub3 -r asciidoctor-mathematical -a mathematical-format=png -b epub3 sample.adoc
And here's how it looks using:
asciidoctor -r asciidoctor-epub3 -r asciidoctor-mathematical -a mathematical-format=svg -b epub3 sample.adoc
I note that it's also not rendering the inline latexmath.
The disappeared inline math origins from the handling of default image dir, which is related to #8. The incorrect size may be bugs in asciidoctor-epub3, which seems to ignore image size settings in an image block as well as width and height settings in svgs. By settings ppi to 72.0 (in the source code currently, a later version will allow setting math ppi in documents) and use png, correct sized images are obtained.
To manage the equation size, I think we simply need to pass the width attribute from the stem node to the generated image node. It's absolutely correct that the SVG fills the available space if no width is specified (because we wouldn't want to assume a default width).
[latexmath,width=50%]
++++
k_{n+1} = n^2 + k_n^2 - k_{n-1}
++++
This is consistent with Asciidoctor Diagram, which allows the width of the generated diagram to be set via the width attribute.
We could also support a document attribute that would assign a default width if no width is given.
:stem-width: 50%
Another approach is to set a default width using CSS (via a docinfo file).
The incorrect size may be bugs in asciidoctor-epub3, which seems to ignore image size settings in an image block as well as width and height settings in svgs.
This is actually due to the fact that embedding SVGs in EPUB3 is very complicated (due to the fact that different readers handle them differently). That's why we ignore the width and height in the SVG and require that the width be set using CSS.
Actually, the width attribute will be ignored by the EPUB3 converter. Therefore, we should also supported scaledwidth, which is used by the EPUB3 converter, and pdfwidth, which is used by the PDF converter.
By default, the scaledwidth value is 100% in the EPUB3 converter, which is why the SVG stretches the width of the page.
I am new to epub. Does it mean that we can not set width as absolute pixels, but as relative width using scaledwidth? If so, this problem is much harder.
Your understanding is correct. It's also the correct approach since epub3 is a fluid canvas, so any assignment in pixels is actually undesirable. It might look good on a tablet, but then the image will be incorrect on a phone. Images in epub3 need to be relative to the size of the page width.
Due to the difficulties of embeding svgs in epub3, I would recommend use the png format for epubs. Then the problem is how we fit into the 'fluid canvas'. Is is possible for asciidoctor-epub3 to automatically calculate the scaledwidth using the width attribute in the image macro? For a converter-agnostic extension like asciidoctor-mathematical, it does not seem the right way to adjust scaledwidth based on hueristics. @mojavelinux
For the moment, I would recommend use mathematical-format=png and mathematical-ppi=72.0 for a not-good-looking but working approach to embed formulee into epubs. Would you try this on your document, @paulvickers?
It seems that generated inline stem images are not copied to the resultant epub. I can verify that all stems are generated and the files are located in 'images'. But the images dir in the generated epub contains only block stems. Are their any clues, @mojavelinux ? You can verify it by unzipping the attached epub and check sample-content.xhtml for images-xxx.
EPUB3 incudes mathml as part of the standard. So we can support stems through the mathml backend of mathematical. I will add this later.
EPUB3 incudes mathml as part of the standard.
Unfortunately, this is not widely supported, which is why I have not taken advantage of it in Asciidoctor EPUB3 yet. We're starting to see some support from EPUB3 readers, but it is very limited. It's best for most people to stick with images for now.
It seems that generated inline stem images are not copied to the resultant epub.
That is correct. Asciidoctor EPUB3 currently doesn't process inline images. This needs to be fixed first. See https://github.com/asciidoctor/asciidoctor-epub3/issues/30
Due to the difficulties of embeding svgs in epub3, I would recommend use the png format for epubs.
I disagree. I think SVG is a better choice, especially in this setting where the screen resolution can vary widely.
What I was pointing out is that we cannot assume how you want the equation to be formatted. Right now, you can use scaledwidth for that purpose. However, I'm open to adding support for an epubwidth attribute to allow fine-grained control over the width. We can then support a wide range of units, like with pdfwidth.
It should not be the responsibility of this extension to handle sizing of the image. The only thing this extension should worry about is passing on the attributes that are used for that purpose. So the extension should pass on width, scaledwidth, pdfwidth, and epubwidth attributes if set. The width attribute is only meant to be for informational purposes only, but still important to pass on.
To clarify, we will take up the issue of how the image is arranged in the EPUB3 document in the asciidoctor-epub3 project.
I do not object to the SVG idea. SVG is much better than png since it's scalable. As long as the epubwidth attributes is added, we can add the proper support in this extension. 😄
I'll amend my comment slightly to say that this extension certainly can worry about the size of the image that is created. It just shouldn't worry about the precise sizing applied by the layout. It should only pass along that information.
For example, I noticed that the inline images have a fixed width as returned by mathematical. However, I can't determine how that width is decided. I think experience using this extension will guide us about what to do.