finished aside-margin-pretext post

_posts/2024-07-20-aside-margin-pretext.md

@@ -5,7 +5,21 @@ tags: pretext
 katex: True
 ---
 
-here is my (under-construction) post about how I made asides appear in the margin of pretext-generated pdfs 
+Asides are a neat feature in [PreTeXt books](https://pretextbook.org/)  -- in the web version, they show up as cute li'l notes floating semi-transparently in the margin. However, in LaTeX builds, [asides get dumped into plain text with no particular styling](https://github.com/PreTeXtBook/pretext/issues/1501). This is sad so I decided to fix it.
+
+## Existing aside-like styling code
+
+The way PreTeXt renders stuff into LaTeX is specified in [`pretext-latex.xsl`](https://github.com/PreTeXtBook/pretext/blob/master/xsl/pretext-latex.xsl) (and, of course, the parent sheets from which it inherits). Look for `<xsl:template match="&ASIDE-LIKE;" mode="environment">` -- they're simultaneously specifying the handling of `aside`, `historical`, and `biographical` by using that entity and some clever `<xsl:value-of>` stuff.
+
+I'm not going to reproduce the entire chunk here; suffice it to say that it uses `\tcbset` to define a new style, then uses `\newtcolorbox`[^1] to define the `aside` environment. This is the approach that I wanted to follow-but-change.
+
+Generally speaking, the way you modify stuff like this is by writing [extra stylesheets](https://pretextbook.org/doc/guide/html/publisher-extra-stylesheet.html). By importing the default stylesheet, you can just override the particular things you want to edit without having to recreate the entire stylesheet. (One note about this documentation, though, is that I had better luck using `@xsl` as an attribute of the `<target>` element than I did with using `<xsl>` as a sub-element of the `<target>` element.)
+
+## My edits
+
+Here is the xsl that I ultimately came up with. It generates cute li'l margin notes in smallish font that have a thin line at top and bottom to set them off:
+
+![Screenshot of cute li'l margin note](/images/aside-margin-note.png)
 
 ```xsl
 <xsl:template match="aside" mode="environment">
@@ -25,16 +39,26 @@ here is my (under-construction) post about how I made asides appear in the margi
 </xsl:template>
 ```
 
-could work for all aside-like but I only use asides
+A couple of things to say about this.
+
+- I had to specifically add `\usepackage{marginnote}` though nominally `tcolorbox` relies on it. 
+
+- I chose not to replicate the `&ASIDE-LIKE;` and `<xsl:value-of>` stuff, because I only ever use asides. It would be easy enough to make this work for all aside-like, though.
+
+- There's a bunch of `tcolorbox` styling in there, which I mostly stole from the `tcolorbox` documentation. The only things I think are particularly important for this application are `width=\marginparwidth` (which is probably self-explanatory) and the `if odd page or oneside` stuff.
+
+    - On that note, depending on how your document gets generated, you may have to swap `flushleft` and `flushright` to get the correct behavior.
 
-by default, asides get dumped into plain text with no particular styling
+    - Also on that note, you may have to specifically set your `marginparwidth` in your `geometry` preamble. In particular, I was using the autocomplete feature to only specify the left margin and the text width, and then the marginparwidth was wrong.
 
-xelatex and pdflatex behave differently wrt the \marginnote command so you have to use pdflatex
+- Another big difference between my implementation and the original PreTeXt implication is that I don't handle a title. My asides don't have titles, and it turned out that even having an *empty* title messed up my formatting a bit, so I just ignore them.
 
-pretext-generated aside signature is {m m m +b}
+- The signature of the `aside` environment that PreTeXt is expecting is `{m m m +b}` -- that is, three mandatory arguments and then the body. It's important to match that signature in the new environment, even if you're not going to use those arguments, which are:
+    1. the display name of the element, in this case `Aside`
+    2. the title of the aside
+    3. the label for the element, whether autogenerated or specified by `@xml:id`
 
-an empty title fucks up the styling
+- I was pulling out my hair for a while until I finally figured out that `xelatex` and `pdflatex` [behave slightly differently](https://bsky.app/profile/sbagley.bsky.social/post/3kxjtu5ccab25) in how they place a `\marginnote`. Add `latex-engine="pdflatex"` to `project.ptx` in whatever targets use latex.
 
-may have to swap flushright and flushleft depending on your document
 
-may need to fiddle with marginparwidth depending on how you're using geometry
+[^1]: Much to everyone's disappointment, that's New T Color Box, not Newt Color Box.