Extra XSL needs to know how to find entities.ent

[sean-fitzpatrick]

Right now if we need to use extra XSL, we can do <xsl:import pretext-href="pretext-latex.xsl"/> and pretext-href is aware of where the xsl lives when we do pip install pretextbook.

But there isn't a similar mechanism for pointing to the entities.ent file, so at the moment, we need to put a copy of this file in with our extra XSL. This is OK, but not a good long term solution, since entities.ent will change over time.

It would be great if we could replace <!ENTITY % entities SYSTEM "entities.ent"> with something that is aware of the copy of this file that is installed with the CLI.

(Brad Miller reported at the drop-in that he knows how to do this, if needed.)

[StevenClontz]

I'd like a similar pattern to @pretext-href expanding to @href. I'm not sure what the <!ENTITY % entities SYSTEM "entities.ent"> is (an element? something else?), but maybe there's a way to allow something like <!PRETEXT-ENTITY> we can expand.

[oscarlevin]

It would be reasonable to assume that every custom xsl sheet should know about the entities.ent file. We should just insert this in every stylesheet we process, pointing to the static entities.ent file.

I say that not really knowing what sort of "thing" it is, and I don't know what happens if there is a duplicate of it.

[StevenClontz]

We should just insert this in every stylesheet we process, pointing to the static entities.ent file.

This might be an issue with a dev who's editing a custom/updated entities file.

[sean-fitzpatrick]

A dev could presumably change whatever the modified line becomes, back to something that points to a file they're using.

At drop-in Brad mentioned using "Python resources" to accomplish this.

[rbeezer]

entities.ent is a file in the xsl directory. Almost every stylesheet will depend on it.

Basically it is a bunch of literal shortcuts or aliases or macros. Short text that gets expanded into longer text. Helps with categories of blocks and some other conveniences. Have a peek, it may be self-evident.

Authors don't need to know about it, not even developers so much.

So it is critically necessary, but mostly invisible. I have no good idea why it is causing these sorts of errors, other than not being where it should be.

Rob

[sean-fitzpatrick]

In my case, the errors are because my extra xsl includes tcolorbox templates for things like & DEFINITION-LIKE, which is one of those things that gets expanded by entities.ent.

Probably I could safely replace this with definition and then nothing will go looking for the file until the primary xsl sheets are in use and then we're ok.

But ideally it would work as is.

If I'm using xsltproc or pretext/pretext/pretext, my extra xsl is in pretext/user and I just need to use ../entities.ent, and everything works fine.

To use the CLI, I can put a copy of entities.ent where my extra xsl knows to find it (but then I miss any changes that might be pushed to PreTeXt) or I need to point to where this file lives when the CLI is installed.

[bnmnetp]

This sounds like it may be a job for the pkg_resources package -- One function of this package is to provide you with absolute paths to resources that you bundle inside your pip installable package regardless of where it may end up being installed.

For example, I use it in runestone build to tell me where templates needed to build the books live, where javascript files are located, etc. All of these are distributed in the runestone package you install from pypi.

Note: In looking for the docs it appears that pkg_resources is being replaced by importlib.metadata

[StevenClontz]

Please ignore the terrible hacks we're currently using at https://github.com/PreTeXtBook/pretext-cli/blob/main/pretext/static/__init__.py

The problem is that package resources need not actually live as raw files on disk (could be within a ZIP) which has (presumably) screwy interactions with XSLT imports. So #180 will have us deliver a ZIP of XSL and install them to ~/.pretext/version/xsl. This will include entities.ent (which we can provide a path to as part of the library and use it to expand a fakey entities reference like we do with pretext-href.

[StevenClontz]

Asked at https://stackoverflow.com/questions/72706627/how-can-i-insert-an-entity-element-using-python-and-lxml

[StevenClontz]

I don't see an easy way to do this. Instead a hack: we're copying your custom XSL to a temporary directory anyway, so we'll provide the official entities.ent provided by pretext as entities.ent in that directory unless you provide one yourself.

[sean-fitzpatrick]

That seems like a fairly elegant hack :-)

Easy enough for publishers: no need to include a path to the file; just include it by the filename.

[StevenClontz]

Closed by dc464689ffe58763f8747763b8d5f26d5262fdfb