Css bundling

[ascholerChemeketa]

Draft for @rbeezer to poke at the XSL.

Look for @Rob in publisher-variables.xml for my failed attempt to set an html-theme variable via key(). The workaround version is right below.

The publication-structural.xml file is set to build the new default-modern themes via <css theme="...">. Anything that has <css style="..."> will be built using old CSS with a warning. It can be used without node, including changing the palette (see pretext.py for test palette options). Any other theme (salem, denver, tacoma) will require node is installed and doing npm install one time from the script/cssbuilder directory.

You can rebuild just the theme with -c theme on the pretext script.

This RS PR is related:
RunestoneInteractive/rs#575
It is not required, but it enables dark mode on RS components and other minor adjustments to make RS components look more like the PTX around them.

Needs:

• Oscar is still doing some testing/development
• More documentation
• Check on CLI - Oscar says it should be ready to go
• Rebase - integrate any very recent CSS
• Update other examples/guide to use new themes?

[rbeezer]

XSL review, as requested:

mode="iframe-dark-mode-enabled-check": This creates an attribute, conditionally. For consistency, let's name it what it produces not what it does. Templates make stuff, they are not procedures. Perhaps: mode="iframe-dark-mode-attribute" (And now I see where it goes. In a long list of mode="*-attribute")

<xsl:value-of select="$extra-body-classes"/>: why did this move out of an attribute?

<xsl:template name="light-dark-toggle">: "light-dark-button"?

<xsl:value-of select="$publication/common/mermaid/@theme"/>: publisher file should make global variables. It should not be interrogated directly elsewhere.

"Only for used for"

name="html-theme-html-hook": "hook" doesn't help me. More interrogation of the publisher file.

Everything involving $rs-fileroot could/should go on a separate commit, I think. And I think we can do it now and let it settle down.

This looks suspect to me:
<xsl:variable name="html-theme-option-table" select="exsl:node-set($html-theme-option-list)"/>
Though I'm going to guess you tried my suggestion already. $html-theme-option-list is already a variable. Not sure what exsl:node-set() is going to do to it. Replace $html-theme-option-table by $html-theme-option-list in subsequent?

-    extension-element-prefixes="exsl str dyn"
+    xmlns:func="http://exslt.org/functions"
+    extension-element-prefixes="exsl str dyn func"

does func get used? (I can't find it, maybe I'm not looking properly.)

<xsl:with-param name="optname" select="'provide-dark-mode'"></xsl:with-param> make it an empty element

--- a/xsl/utilities/report-publisher-variables.xsl
+++ b/xsl/utilities/report-publisher-variables.xsl
@@ -43,6 +43,8 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- into output unnecessarily -->
 <xsl:stylesheet
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
+    xmlns:exsl="http://exslt.org/common"
+    extension-element-prefixes="exsl"
 >
 
 <!-- DEBUGGING -->
@@ -51,6 +53,7 @@ along with MathBook XML.  If not, see <http://www.gnu.org/licenses/>.
 <!-- Standard conversion groundwork -->
 <xsl:import href="../publisher-variables.xsl"/>
 <xsl:import href="../pretext-assembly.xsl"/>
+<xsl:import href="../pretext-common.xsl"/>

Importing -common here is a red flag.

[ascholerChemeketa]

Thanks for the review and tips.

Just added a series of commits to fix the issues listed. One issue per commit.

$rs-fileroot is cherry -picked from #2197 which was closed already

I did make progress on the html-theme selection via a key. It sill feels like there is one more variable than should be needed, but I can't figure out how to skip the one now called html-theme-temp

[rbeezer]

Thanks for all the fixups, I'll look again at teh key() stuff soon.

$rs-fileroot is cherry -picked from #2197 which was closed already

I really don't want existing changes repeated. You are always welcome to rebase on the HEAD to get whatever you need and force-push here. And anyway, I'd prefer that once things are ready-to-go in any event.

[bnmnetp]

@ascholerChemeketa - The runestone side is merged and I just published runestone-7.4.5 with your changes.

[ascholerChemeketa]

@rbeezer Oscar might have some minor tweaks, but I think this is ready to go.

The rebased commits are arranged in logical chunks of content. They are NOT atomic and usable changes to the code. Aside from the documentation, you pretty much need all of them for it to work.

There will be some minor work to reconcile this with #2298 and #2299. If those go first I will update this. If this goes first I will update them.

If you (or anyone else) wants to take a test drive of end product, check out the PR and build the sample book or article. They should work fine without Node.js.

To test out other themes, you will need Node.js installed. Then install the needed dependencies by switching to the pretext/script/cssbuilder and doing npm install. The CLI should handle that automatically.
(@oscarlevin can you confirm that CLI will init cssbuilder package if necessary?)

Then change the publication/html/css/@theme to denver and do a rebuild, or just a rebuild of the theme -c theme. Further documentation is in the docs.

[oscarlevin]

Yes, the CLI is all ready for this and will automatically run an npm install in the right spot if someone tries to build with a theme that needs node. The CLI can also just update the theme with pretext build --theme.

There are a few minor tweaks I'd like to make to the denver and greeley themes, but these can happen after this is merged if needed.

[rbeezer]

There will be some minor work to reconcile this with #2298 and #2299. If those go first I will update this. If this goes first I will update them.

I am definitely trying to get #2298 in just as soon as possible.

[ascholerChemeketa]

Just rebased to 8f175d7 and force-pushed.

@rbeezer I have lots of flexibility for the next two weeks. I'm happy to answer questions just about whenever to help you figure something out without having to put this down and do a context switch back later. Ping me via email.

[ascholerChemeketa]

Warning - after rebasing I tested out various builds. Sample book no parts did not build, but I think this might be another instance of versioning interacting poorly with a special purpose template that weeps the document.

I get:

PTX:ERROR   : processing with /mnt/f/Programming/pretext/xsl/utilities/report-publisher-variables.xsl has failed

Traceback (most recent call last):
  File "/mnt/f/Programming/pretext/pretext/pretext", line 852, in <module>
    main()
  File "/mnt/f/Programming/pretext/pretext/pretext", line 730, in main
    ptx.html(
  File "/mnt/f/Programming/pretext/pretext/pretext.py", line 3826, in html
    build_or_copy_theme(xml, pub_file, stringparams, tmp_dir)
  File "/mnt/f/Programming/pretext/pretext/pretext.py", line 3676, in build_or_copy_theme
    theme_name = get_publisher_variable(xml, pub_file, stringparams, 'html-theme-name')
  File "/mnt/f/Programming/pretext/pretext/pretext.py", line 4797, in get_publisher_variable
    xsltproc(reporting_xslt, xml_source, temp_file, None, params)
  File "/mnt/f/Programming/pretext/pretext/pretext.py", line 4146, in xsltproc
    raise (e)
  File "/mnt/f/Programming/pretext/pretext/pretext.py", line 4142, in xsltproc
    raise (texc)
  File "/mnt/f/Programming/pretext/pretext/pretext.py", line 4105, in transform
    result_tree = xslt(src_tree, **stringparams)
  File "src/lxml/xslt.pxi", line 583, in lxml.etree.XSLT.__call__
  File "src/lxml/etree.pyx", line 332, in lxml.etree._ExceptionContext._raise_if_stored
lxml.etree.XSLTApplyError: Cannot resolve URI /mnt/f/Programming/pretext/xsl/gen/datafile/stack-overflow-survey.xml

Somehow when get_publisher_variable runs on sample-book-no-parts, somehow it tries to go looking for the encoded datafiles in the wrong directory.

I can try doing some more debugging if needed. But it doesn't look like this is based on anything I changed and I am sure you have a much better idea what might be going on than I do.

[rbeezer]

Sample book no parts did not build

~/mathbook/mathbook/pretext/pretext -vv -c all -f html -p ~/mathbook/mathbook/examples/sample-book/publication-noparts.xml  ~/mathbook/mathbook/examples/sample-book/sample-book.xml

runs for me with no errors. Without this PR, and with it (fetched, no rebase, no edits, no etc). The "noparts" source file is orphaned and will be removed any day now, just there while Runeestone Saturday builds transitioned. Is that the problem?

[ascholerChemeketa]

Ahh, yes, that is the problem, I used the no-parts source file. Sorry for the false alarm.

[rbeezer]

OK, making progress on this one. Lots to like: dark mode, and I like the sharper boxes on Runestone stuff.

• A (static) program can have margins and width, including when made a part of a sidebyside. So the inline @style on .code-box needs to be restored.
• Fonts have been selected with care. For example, Inconsolata is what is used for default LaTeX. If out-of-the-box choices are going to be changed, I think a -dev discussion is in order. I've made a beta (link below) that can be used for the basis of a discussion.
• I'd like the crude interface in pretext to call a single well-named function from the library/module in pretext.py. Please arrange the theme option to call one ptx.*, not several.
• # empty image names in sample book were breaking my build: does this belong here? How is it "breaking"? Whose build is this?
• Can you rotate the two commits affecting samples to the tip? I had to do that for testing.
• Can you integrate CSS update prebuilts 2024-12-16 #2324 into a force-push here? I'll let Node instructions update #2325 sit for now, and I can cherry-pick from that.

[ascholerChemeketa]

Thanks for the review, will do.

Incosolata should still be the default font for all monospace blocks. If you see something like either of these:


They are using this list of fonts, which has Incosolata as the first option:
--font-monospace: Inconsolata, Consolas, Monaco, monospace;
I'll dig into it to confirm however.

I don't see the link to the beta but that might be moot.

[ascholerChemeketa]

Done with requested changes. Did a force push that integrated all the changes into existing commits. I kept a backup copy with the changes in separate commits in case that is what you prefer.

• A (static) program can have margins and width, including when made a part of a sidebyside. So the inline @Style on .code-box needs to be restored.

The removed inline styles were never emitted when part of a sidebyside - the sidebyside manages the layout in that case. (See https://pretextbook.org/examples/sample-article/html/section-side-by-side.html#subsection-sbs-other-panels)

I don't think I realized that a program could have a width outside that context (should have checked the schema!). The logic behind removing them was in case a theme is trying to override the default styling (e.g. widening programs).

Added back logic to add the inline styles when the author has set a width other than 100%. I believe this is the best way to honor author intent first and theme intent if the author does not specify anything.

• Fonts have been selected with care. For example, Inconsolata is what is used for default LaTeX. If out-of-the-box choices are going to be changed, I think a -dev discussion is in order. I've made a beta (link below) that can be used for the basis of a discussion.

Cleaned up a potential issue with the fonts. Confirmed that preformatted blocks are using Inconsolata.

• I'd like the crude interface in pretext to call a single well-named function from the library/module in pretext.py. Please arrange the theme option to call one ptx.*, not several.
• # empty image names in sample book were breaking my build: does this belong here? How is it "breaking"? Whose build is this?

Yes, that should have turned into a question for -dev or a separate PR. I encountered it while testing CSS for ebooks. Removed from here.

• Can you rotate the two commits affecting samples to the tip? I had to do that for testing.
• Can you integrate CSS update prebuilts 2024-12-16 #2324 into a force-push here? I'll let Node instructions update #2325 sit for now, and I can cherry-pick from that.

[rbeezer]

Trying to get this out the door! Can't find the blurb for -announce. I'm pretty sure I saw one...

[oscarlevin]

Not sure where the -announce blurb is, but if you ping me between merging this and posting on announce, you can include that the features are available in CLI v2.11.0.

[ascholerChemeketa]

@rbeezer Just sent you the blurb. I had started it, then got derailed with #2325 part way through. While that improves the node/npm docs, the announce blurb should make sense without that PR. The URL the blurb points to for node in the Guide is the page that got hoisted into its own appendix.

[rbeezer]

Finally! Its in. Will announce and update website sometime in the next few hours.

No changes to code. Slight repackaging of commits. Two follow-on commits with minor oversights. Also, look at e7a370b. I think it is critical to not hard-code file paths with forward slashes, lest Windows gets confused (its OK for XPath stuff). I'm resisting using the Pathlib module. ;-)

Thanks for all your hard work on this. Let's try to tidy up any loose ends over the next two weeks.

[oscarlevin]

In the process of releasing 2.11.0, the test for building slides failed, since copy_html_css_js (line 3874 of the pretext script) is not defined. I'll work on fixing this ASAP, but won't release a new CLI version until it can build all its formats.

[oscarlevin]

Okay, I think that line should just be copy_html_js(tmp_dir), which does build and things look right. But should reveal also call build_or_copy_theme(...)?

[oscarlevin]

Fix at #2337

[rbeezer]

Hah. Forgot to close this! ;-) If appropriate, discussion can continue here.