Skip to main content
Chemistry LibreTexts

3.6: Command substitution and inserts

  • Page ID
    555708
  • ​

    ​

    \( \newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \)

    \( \newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}} \)

    \( \newcommand{\dsum}{\displaystyle\sum\limits} \)

    \( \newcommand{\dint}{\displaystyle\int\limits} \)

    \( \newcommand{\dlim}{\displaystyle\lim\limits} \)

    \( \newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\)

    ( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\)

    \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\)

    \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\)

    \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\)

    \( \newcommand{\Span}{\mathrm{span}}\)

    \( \newcommand{\id}{\mathrm{id}}\)

    \( \newcommand{\Span}{\mathrm{span}}\)

    \( \newcommand{\kernel}{\mathrm{null}\,}\)

    \( \newcommand{\range}{\mathrm{range}\,}\)

    \( \newcommand{\RealPart}{\mathrm{Re}}\)

    \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\)

    \( \newcommand{\Argument}{\mathrm{Arg}}\)

    \( \newcommand{\norm}[1]{\| #1 \|}\)

    \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\)

    \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\AA}{\unicode[.8,0]{x212B}}\)

    \( \newcommand{\vectorA}[1]{\vec{#1}}      % arrow\)

    \( \newcommand{\vectorAt}[1]{\vec{\text{#1}}}      % arrow\)

    \( \newcommand{\vectorB}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \)

    \( \newcommand{\vectorC}[1]{\textbf{#1}} \)

    \( \newcommand{\vectorD}[1]{\overrightarrow{#1}} \)

    \( \newcommand{\vectorDt}[1]{\overrightarrow{\text{#1}}} \)

    \( \newcommand{\vectE}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash{\mathbf {#1}}}} \)

    \( \newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \)

    \(\newcommand{\longvect}{\overrightarrow}\)

    \( \newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}} \)

    \(\newcommand{\ket}[1]{\left| #1 \right>}\)
    \(\newcommand{\bra}[1]{\left< #1 \right|}\)
    \(\newcommand{\braket}[2]{\left< #1 \vphantom{#2} \right| \left. #2 \vphantom{#1} \right>}\)
    \(\newcommand{\braopket}[3]{\left< #1 \vphantom{#2}\vphantom{#3} \right| #2 \vphantom{#1}\vphantom{#3} \left| #3 \vphantom{#1}\vphantom{#2} \right>}\)
    \(\newcommand{\qmvec}[1]{\mathbf{\vec{#1}}}\)
    \(\newcommand{\op}[1]{\hat{\mathbf{#1}}}\)
    \(\newcommand{\expect}[1]{\langle #1 \rangle}\)
    \(\newcommand{\dfn}[1]{\emph{\textbf{#1}}}\)

    \(\newcommand{\avec}{\mathbf a}\) \(\newcommand{\bvec}{\mathbf b}\) \(\newcommand{\cvec}{\mathbf c}\) \(\newcommand{\dvec}{\mathbf d}\) \(\newcommand{\dtil}{\widetilde{\mathbf d}}\) \(\newcommand{\evec}{\mathbf e}\) \(\newcommand{\fvec}{\mathbf f}\) \(\newcommand{\nvec}{\mathbf n}\) \(\newcommand{\pvec}{\mathbf p}\) \(\newcommand{\qvec}{\mathbf q}\) \(\newcommand{\svec}{\mathbf s}\) \(\newcommand{\tvec}{\mathbf t}\) \(\newcommand{\uvec}{\mathbf u}\) \(\newcommand{\vvec}{\mathbf v}\) \(\newcommand{\wvec}{\mathbf w}\) \(\newcommand{\xvec}{\mathbf x}\) \(\newcommand{\yvec}{\mathbf y}\) \(\newcommand{\zvec}{\mathbf z}\) \(\newcommand{\rvec}{\mathbf r}\) \(\newcommand{\mvec}{\mathbf m}\) \(\newcommand{\zerovec}{\mathbf 0}\) \(\newcommand{\onevec}{\mathbf 1}\) \(\newcommand{\real}{\mathbb R}\) \(\newcommand{\twovec}[2]{\left[\begin{array}{r}#1 \\ #2 \end{array}\right]}\) \(\newcommand{\ctwovec}[2]{\left[\begin{array}{c}#1 \\ #2 \end{array}\right]}\) \(\newcommand{\threevec}[3]{\left[\begin{array}{r}#1 \\ #2 \\ #3 \end{array}\right]}\) \(\newcommand{\cthreevec}[3]{\left[\begin{array}{c}#1 \\ #2 \\ #3 \end{array}\right]}\) \(\newcommand{\fourvec}[4]{\left[\begin{array}{r}#1 \\ #2 \\ #3 \\ #4 \end{array}\right]}\) \(\newcommand{\cfourvec}[4]{\left[\begin{array}{c}#1 \\ #2 \\ #3 \\ #4 \end{array}\right]}\) \(\newcommand{\fivevec}[5]{\left[\begin{array}{r}#1 \\ #2 \\ #3 \\ #4 \\ #5 \\ \end{array}\right]}\) \(\newcommand{\cfivevec}[5]{\left[\begin{array}{c}#1 \\ #2 \\ #3 \\ #4 \\ #5 \\ \end{array}\right]}\) \(\newcommand{\mattwo}[4]{\left[\begin{array}{rr}#1 \amp #2 \\ #3 \amp #4 \\ \end{array}\right]}\) \(\newcommand{\laspan}[1]{\text{Span}\{#1\}}\) \(\newcommand{\bcal}{\cal B}\) \(\newcommand{\ccal}{\cal C}\) \(\newcommand{\scal}{\cal S}\) \(\newcommand{\wcal}{\cal W}\) \(\newcommand{\ecal}{\cal E}\) \(\newcommand{\coords}[2]{\left\{#1\right\}_{#2}}\) \(\newcommand{\gray}[1]{\color{gray}{#1}}\) \(\newcommand{\lgray}[1]{\color{lightgray}{#1}}\) \(\newcommand{\rank}{\operatorname{rank}}\) \(\newcommand{\row}{\text{Row}}\) \(\newcommand{\col}{\text{Col}}\) \(\renewcommand{\row}{\text{Row}}\) \(\newcommand{\nul}{\text{Nul}}\) \(\newcommand{\var}{\text{Var}}\) \(\newcommand{\corr}{\text{corr}}\) \(\newcommand{\len}[1]{\left|#1\right|}\) \(\newcommand{\bbar}{\overline{\bvec}}\) \(\newcommand{\bhat}{\widehat{\bvec}}\) \(\newcommand{\bperp}{\bvec^\perp}\) \(\newcommand{\xhat}{\widehat{\xvec}}\) \(\newcommand{\vhat}{\widehat{\vvec}}\) \(\newcommand{\uhat}{\widehat{\uvec}}\) \(\newcommand{\what}{\widehat{\wvec}}\) \(\newcommand{\Sighat}{\widehat{\Sigma}}\) \(\newcommand{\lt}{<}\) \(\newcommand{\gt}{>}\) \(\newcommand{\amp}{&}\) \(\definecolor{fillinmathshade}{gray}{0.9}\)

    Command substitution lets you run a small Perl expression and insert its output into the PGML prompt. This is useful for inserting images, computed strings, or helper-generated markup. Variables used in substitution are typically defined in the Setup block.

    Command substitution is powerful, but it should not be the first solution to a formatting or clarity problem. In most cases, PGML lists, tables, or explicit text are easier to read and easier to maintain. Use substitution only when the content genuinely depends on computed or conditional output.

    Use this when: you need to insert computed output or helper-generated markup that PGML cannot express directly.

    Copy and edit

    $ct = Real(21.2);
    $rows = [
    	[ "Sample", "Ct (cycles)" ],
    	[ "Control", 18.2 ],
    	[ "Treatment", 21.2 ],
    ];
    
    BEGIN_PGML
    [@ DataTable($rows, caption => "qPCR results") @]*
    The Ct for Treatment is [____]{$ct}.
    END_PGML
    

    Common failure and fix

    Broken: [@ DataTable($rows) @]
    Fix: [@ DataTable($rows) @]*
    

    Syntax

    [@ some_perl_expression() @]
    

    If the substitution produces output that is already formatted as PG/HTML, follow it with a star:

    [@ some_perl_expression() @]*
    
    Syntax: use it for and avoid it for.
    Use it for Avoid it for
    Computed intermediate values or helper-generated tables. Basic formatting that PGML already supports.
    Reusable PG helpers that return formatted output. Simple text that can be typed directly.

    Common uses

    • Insert a computed intermediate value into a worked solution line.
    • Insert a table or figure generated by helper functions.
    • Use a specialized PG helper when PGML does not provide a direct syntax.

    Example: computed text inside math mode

    BEGIN_PGML
    To solve [: x + [$a] = [$b] x :], subtract [:x:] from both sides to get
    [: [$a] = ([$b]-1) x = [@ $b - 1 @] x :].
    END_PGML
    

    HTML in variables is escaped by default

    If you store HTML markup in a Perl variable (for example, $label = "<span style='color:red'>Warning</span>") and insert it with [$label], PGML will escape the angle brackets and the student will see the raw tags instead of styled text.

    To pass HTML through unescaped, append an asterisk:

    [$label]*
    

    This tells PGML to treat the variable's output as pre-formatted HTML, the same trailing * used after [@ ... @]* eval blocks. Use it whenever a variable contains <span>, <div>, <sup>, <sub>, or any other HTML tags that should render as markup.

    Avoid MODES() inside eval blocks

    A common mistake is to use MODES(HTML => '...') inside a [@ ... @] eval block, expecting it to emit raw HTML. In practice, MODES(...) returns 1 in eval context, so the student sees the number 1 instead of the intended content.

    If you need mode-dependent output, build it in the Perl setup section and insert the result with [$var]*, or use PGML tag wrappers and raw HTML outside eval blocks.

    MathJax color commands

    TeX color macros such as \color{} and \textcolor{} do not reliably render in PGML because MathJax may wrap them in tex2jax_ignore spans. If you need colored text in a prompt, use HTML <span style="color:..."> instead. For a fuller discussion of MathJax rendering constraints, see Text Coloring and Emphasis.

    Blocked HTML tags

    PGML's HTML whitelist does not allow raw <table>, <tr>, <td>, or <th> tags. If you write them in PGML output they will be stripped or trigger warnings. Use niceTables.pl for any tabular layout. For more on the tag whitelist and workarounds, see Making Tables with niceTables.

    Images and links (LibreTexts constraint)

    Images can be inserted via helper functions and command substitution, but the textbook content in this repository avoids HTML links because LibreTexts provides its own table of contents and in-platform navigation. Keep prompts self-contained and do not rely on linking out to other pages.

    Treat this as an advanced escape hatch: keep substitutions small, readable, and easy to test.

    Next, depending on what you are doing:


    This page titled 3.6: Command substitution and inserts was last modified on Fri, 27 Feb 2026 15:28:31 GMT and is shared under a CC BY 4.0 license and was authored, remixed, and/or curated by Neil R. Voss.