Asides are a neat feature in PreTeXt books – 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. 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 (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 \newtcolorbox1 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. 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

<xsl:template match="aside" mode="environment">
    <xsl:text>%% aside: un-numbered margin note&#xa;</xsl:text>
    <xsl:text>\usepackage{marginnote}&#xa;</xsl:text>
    <xsl:text>\tcbset{ asidestyle/.style={&#xa;</xsl:text>
    <xsl:text>enhanced jigsaw, size=fbox,&#xa;</xsl:text>
    <xsl:text>colframe=black, colback=white,&#xa;</xsl:text>
    <xsl:text>boxrule=1pt, leftrule=0pt, rightrule=0pt,&#xa;</xsl:text>
    <xsl:text>arc=0pt, outer arc=1pt, boxsep=1pt, top=1pt, bottom=1pt,&#xa;</xsl:text>
    <xsl:text>nobeforeafter, width=\marginparwidth, fontupper=\scriptsize,&#xa;</xsl:text>
    <xsl:text>if odd page or oneside={flushleft upper}{flushright upper} } }&#xa;</xsl:text>
    <xsl:text>\NewDocumentEnvironment{aside}{m m m +b}&#xa;</xsl:text>
    <xsl:text>{\marginnote{\begin{tcolorbox}[&#xa;</xsl:text>
    <xsl:text>phantomlabel={#3}, asidestyle] #4 \end{tcolorbox} } }&#xa;</xsl:text>
    <xsl:text>{}&#xa;</xsl:text>
</xsl:template>

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. Fiddle with this to your liking; 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.

    • 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.

  • 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.

  • 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

  • One particularly annoying thing I had to figure out: I needed to wrap a \begin{tcolorbox} ... \end{tcolorbox} inside the \marginnote{...} command, and it turns out that \NewDocumentEnvironments don't nest particularly well if you do the thing you think you should do by specifying the beginning group and the ending group in the first and second set of {}s, respectively. The eventual solution was to use +b in the signature to make it pass in the body of the environment as argument #4 and dump everything in the beginning group.

  • I was pulling out my hair for a while until I finally figured out that xelatex and pdflatex behave slightly differently in how they place a \marginnote. Add latex-engine="pdflatex" to project.ptx in whatever targets use latex.

  1. Much to everyone's disappointment, that's New T Color Box, not Newt Color Box. ↩