Skip to main content
Logo image

PreFigure Author’s Guide

David Austin

Section 4.2 Authoring diagrams within PreTeXt

PreTeXt authors will notice that the design of PreFigure is very much inspired by PreTeXt. In fact, it is possible to write PreFigure source directly inside a PreTeXt document. There are just a few things to be aware of.
The diagram in Figure 4.2.1 was created inside a PreTeXt document, as we will explain.
Figure 4.2.1. A PreFigure diagram created inside a PreTeXt document as shown in Listing 4.2.2.
Listing 4.2.2 shows a portion of a PreTeXt document containing PreFigure source. First, notice that we use a PreTeXt <image> element and place a PreTeXt <prefigure> element inside of it. The <prefigure> element needs to have the attribute @xmlns="https://prefigure.org", which serves to effectively isolate any PreFigure source from the rest of the document, and a @label giving the diagram a name.
Listing 4.2.2. PreFigure source inside a PreTeXt document.
<image width="60%">
  <prefigure xmlns="https://prefigure.org"
             label="prefigure-rectangle">
    <diagram dimensions="(300,300)" margins="5">
      <coordinates bbox="(0,0,10,10)">
        <grid-axes/>
        <rectangle center="(5,5)" dimensions="(6,6)"/>
        <label anchor="(0.5,0.5)" alignment="ne"
               clear-background="yes">
          The derivative is <m>\deriv{y}{x}</m>.
        </label>
      </coordinates>
    </diagram>
  </prefigure>
</image>
Rather than a publication file, as described in Section 4.1, default behaviors can be specified in the PreTeXt <docinfo> element as shown in Listing 4.2.3. Including this has the effect of applying the publication file given in Listing 4.1.1.
Listing 4.2.3. Within a PreTeXt document, PreFigure publication data is included inside <docinfo>.
<docinfo>
  <macros>
    \newcommand{\deriv}[2]{\displaystyle \frac{d#1}{d#2}}
    \newcommand{\real}{\Bbb R}
  </macros>
  <prefigure-preamble xmlns="https://prefigure.org">
    <graph stroke="green"/>
    <point style="diamond" size="5" fill="blue" outline="yes"/>
  </prefigure-preamble>
</docinfo>
Notice that the macros defined inside <docinfo/macros>, which are available throughout the entire PreTeXt document, are also made available for creating PreFigure labels. In addition, three more macros will be automatically added:
\newcommand{\lt}{&lt;}
\newcommand{\gt}{&gt;}
\newcommand{\amp}{&amp;}
Furthermore, you may add a <prefigure-preamable> element inside <docinfo> to change the default appearance of specified graphical components. The <prefigure-preamble> element needs the same namespace attribute @xmlns="https://prefigure.org" as the <prefigure> element.
The PreTeXt document that created Figure 4.2.1 has a <prefigure-preamble> with a single <rectangle> element having attributes @stroke="black" and @fill="green". The <macros> includes the macro to create the label \(\frac{dy}{dx}\text{.}\)

Workflow.

When you first create a PreFigure diagram, you will most likely build it several times to get some details straightened out. If the diagram sits inside a lengthy PreTeXt document, it would be inconvenient to recompile the entire document just to see the effect of some changes on a single diagram. For this reason, you may wish to use PreFigure as a standalone application to go through several build cycles before including it in the PreTeXt source. Here are some suggestions for easing this process.
Within your PreTeXt source, create a prefigure directory that will contain a separate file for each of your PreFigure diagrams. Within the <diagram> tag in each source file, include the namespace attribute @xmlns="https://prefigure.org". You may build PreFigure output directly from the source until you are mostly satisfied with the result.
To include this into your PreTeXt source, you will need to do a couple of things.
  • First, make sure the root XML element in the file that will include the diagram has the attribute @xmlns:xi="http://www.w3.org/2001/XInclude".
  • Within an <image> element, include a child <prefigure> element with the namespace @xmlns and @label attributes, as described above.
  • Finally, within the PreFigure element, include a child to include your PreFigure source, such as <xi:include href="prefigure/my_diagram.xml"/>.
PrevTopNext