add more details to the 02.delete-me.md about figures and latex math?

[ctb]

I'm poking around my new manubot paper, and a few things tripped me up. I've worked through them, but thought I might mention them here and (if I'm right about them :) I would be happy to add to the

First, it seems like you can do inline LaTeX math with single $ - e.g. $ equation $ works just fine! (True?)

But the only examples in rootstock/content/02.delete-me.md use double $$.

Second, it looks like you can put png, pdf, and svg figures in quite nicely! yay! However,

• if they are stored locally and not in github, it looks like they have to be in the content/images/ subdirectory, or at least cannot be in content/. True?
• on first glance, the examples in rootstock/content/02.delete-me.md use only absolute URL references, which is probably not what everyone wants - relative paths/URLs are handy for branches etc!
• on first glance, the examples are also only bitmap examples, which is probably ALSO not what everyone wants

I'd be happy to submit a PR to enrich 02.delete-me.md with a few extra words to indicate that PDF is fine, and that relative URLs are fine (perhaps with an example), and that inline LaTeX is fine. But I wanted to check that I'm right about the above stuff before starting a PR!

And, of course... thanks for manubot! It's awesome!

[ctb]

oh, and it looks like SVG is handled better than PDF for vector graphics. Is that a recommendation that should be added?

(by "handled better" I mean that at least in my local build + local web browse in Firefox, the PDF shows up with an inline PDF browser, while the SVG looks like a normal image.)

[dhimmel]

Thanks for the feedback @ctb. Nice to see where our current documentation leaves uses wondering.

One constant question is how much we should document, versus how much we should point users to look at the Pandoc docs. On one hand duplicating docs is not ideal. On the other hand, we want to provide users with examples in delete-me of common constructs and features. I do think most of what you mention should be demonstrated or more explicit in delete-me and possibly USAGE.

First, it seems like you can do inline LaTeX math with single $ - e.g. $ equation $ works just fine

yes as per https://pandoc.org/MANUAL.html#extension-tex_math_dollars:

Anything between two $ characters will be treated as TeX math. The opening $ must have a non-space character immediately to its right, while the closing $ must have a non-space character immediately to its left, and must not be followed immediately by a digit. Thus, $20,000 and $30,000 won't parse as math. If for some reason you need to enclose text in literal $ characters, backslash-escape them and they won't be treated as math delimiters.

For display math, use $$ delimiters. (In this case, the delimiters may be separated from the formula by whitespace.)

it looks like SVG is handled better than PDF for vector graphics. Is that a recommendation that should be added?

Yes. This I think is more general, browsers don't do well using PDFs as images. We should mention this in the docs like preferred image formats:

• vector images: .svg
• raster images (diagrams, plots, rasterized svgs): .png
• raster images (photographs, microscopy figures): .jpg

This is general to scientific images on the web, but many users might not be aware of the nuances.

• if they are stored locally and not in github, it looks like they have to be in the content/images/ subdirectory, or at least cannot be in content/. True?

Yes, must be in content/images with a relative path like images/path-to-image.png. Subdirectories in images probably okay. Using local images causing these images to get copied to many locations. Therefore, I tend to prefer using URLs for images that include the commit hash (or any other versioning or content-addressing). The reason for versioning is so the authors must update the image URL in the manuscript to change the image (an explicit decision). Therefore legacy versions of the manuscript, continue to use the legacy images and not the most current image.

I'd be happy to submit a PR to enrich 02.delete-me.md with a few extra words

That would be much appreciated, even if it only goes part of the way and you'd like us to clean it up / finalize it.

[dhimmel]

on first glance, the examples are also only bitmap examples, which is probably ALSO not what everyone wants

There should be an SVG example in 02.delete-me.md:

![
**A vector `.svg` image loaded from GitHub.**
The parameter `sanitize=true` is necessary to properly load SVGs hosted via GitHub URLs.
White background specified to serve as a backdrop for transparent sections of the image.
](https://raw.githubusercontent.com/manubot/resources/master/test/vector.svg?sanitize=true "Vector image"){#fig:vector-image height=2.5in .white}