search

PreTeXtBook / pretext

PreTeXt: an authoring and publishing system for scholarly documents
https://pretextbook.org
Other
264 stars 206 forks source link

PreTeXt documentation gives incorrect image instructions #1970

Closed kaince closed 1 year ago

kaince commented 1 year ago

Instead of putting images in the same folder as html files or an "images" folder as the guide says, they must be in your root folder in a subfolder named "external" in order to correctly build using the PreTeXt GitHub Codespace.

Alex-Jordan commented 1 year ago

Thanks, could you give a link to the place in the guide with outdated information?

This sounds like a mix of outdated information in the guide with one additional misunderstanding. I'll try to fix both things if you can show me where you were looking first.

kaince commented 1 year ago

Thanks for the quick response! I believe I had followed the instructions in Subsection 4.14.1: Raster Images and Subsection 4.14.2: Vector Graphics and tried placing my .svg and .png/.jpg images in various folders and specifying those folders (e.g. <image source="images/fig1" width="10%"> or the same code but adding a file extension) but to no avail until they were placed in the /external folder. I'm guessing there's a way of specifying a path to the default folder for images that I missed?

Alex-Jordan commented 1 year ago

Thanks for the links. I will review what's written there and correct anything that is out of date or could be made more clear sometime soon.

I'm assuming that your project has a "publisher" file (but if not, skip to next paragraph). Often called publisher.ptx, publisher.xml, publication.ptx, etc. In that file there is a source/directories element that can have the attribute external. I'm guessing that yours has external="../external" which says there is a folder named "external" and that path is relative to your project's root source file. This is where all external assets are assumed to live. So when your source has <image source="images/fig1"/> it is assumed that images/fig1 is within that external folder. (Some people are naming this "assets" as in external="../assets".) If you leave off a file extension on an image, it looks for the "right" option for the current output format. So you might have fig1.svg for HTML but also have fig1.png for some other output format.

If you don't have a publisher file, it may be defaulting to assuming external="../external". But the bests thing for you would be to get a publisher file in place.

Publisher files are covered more in the guide.

kaince commented 1 year ago

You're absolutely right; I have a publisher file (included by default with the Codespace created from the instructions on the pretext-codespace GitHub page), but somehow although the default code is

<source webwork-problems="../generated-assets/webwork/webwork-representations.ptx"><directories external="../assets" generated="../generated-assets"/></source>

storing files in the ../output/web/external folder allows them to be read. I tried placing images in ../assets and that somehow didn't work.

I apologize for the miscommunication in my initial post, as I had published it while away from computer; it should have specified the output/web/external folder as the image location that worked, not ../external.

I'll close this issue for now; thanks again.

Alex-Jordan commented 1 year ago

If the image files are in that assets folder when you run pretext build web, they will (should) be copied to the right place in the output/web folder. Let's continue any troubleshooting using the pretext-support discussion group:

https://groups.google.com/forum/#!forum/pretext-support

In the meantime I will still review and update the guide doc.