docfill: An Inverse of docstrip

This note is to help think through the design issues around undoing the effect of docstrip. It is essentially a sketch of a computer program that I need to write.

I love using docstrip to write for my classes. It is a magical tool which allows one to create multiple $\LaTeX$ documents from a single source file. My most common usage pattern is to store all the documents related to a single course in a single “master” document. docstrip takes that master document and splits it up in to a variety of “derivative” tex files.

Here is a concrete example. Often, I’ll have a version of a quiz with solutions (for my TAs) and a version without solutions (for my students). docstrip can store both versions and then separate them out in to two files.

The problem that I’m currently facing is this: I would like my TAs to create their own solutions and include those solutions in the master document. Unfortunately, the TAs work in Overleaf which doesn’t support docstrip¹. The work around that I’m currently imagining is an “inverse” of docstrip. Let’s call this hypothetical program docfill. I would like the TAs to be able to modify the derivative files, and then use docfill to propagate those changes back to the master docstrip file.

Let’s suppose that we have the following simple setup. The full example is available as example.zip. Our master files are the following.

This docstrip setup will produce two derivative files.

And now, the TAs get to work, and they produce the following modified derivative files.

The relevant bit of the example-handout-SOLUTIONS.dtx file is here.

 \begin{question}
 Evaluate $\displaystyle \int_0^1 e^x\ dx$.
 %% START: WORKSHEET 1 QUESTION 1 SOLUTION
 \begin{solution}
 
 \end{solution}
 %% END: WORKSHEET 1 QUESTION 1 SOLUTION
 \end{question}

TA A modifies this derivative file and we get the following bit of example-handout-SOLUTIONS-TA-A.tex.

 \begin{question}
 Evaluate $\displaystyle \int_0^1 e^x\ dx$.
 %% START: WORKSHEET 1 QUESTION 1 SOLUTION
 \begin{solution}
    We calculate:
    \[ 
        \int_0^1 e^x\ dx
        = \left[ e^x \right]_0^1
        = e^1 - e^0 = e - 1
    \]
 \end{solution}
 %% END: WORKSHEET 1 QUESTION 1 SOLUTION
 \end{question}

I would like to move this change back to the original master example.dtx file. Another way to think of this problem is that I want to produce a patch of example.dtx which will then produce example-handout-SOLUTIONS-TA-A.tex.

The full contents of example.dtx.

\begin{document}
    \begin{questions}
        \begin{question}
            Evaluate $\displaystyle \int_0^1 e^x\ dx$.
            %% START: WORKSHEET 1 QUESTION 1 SOLUTION
            %<*solutions> %% (fold)
                \begin{solution}

                \end{solution}
            %</solutions> %% (end)	
            %% END: WORKSHEET 1 QUESTION 1 SOLUTION
        \end{question}

        \begin{question}
            Evaluate $\displaystyle \int_1^{\infty} \frac{1}{x^2}\ dx$.
            %% START: WORKSHEET 1 QUESTION 2 SOLUTION
            %<*solutions> %% (fold)
                \begin{solution}

                \end{solution}
            %</solutions> %% (end)	
            %% END: WORKSHEET 1 QUESTION 2 SOLUTION
        \end{question}

    \end{questions}
\end{document}

Acknowledgments

Thanks to Matthew Leingang for turning me on to docstrip. Tyler Holden and I had a great conversation about this problem at the Tri-Campus Math Teaching Stream Meet-Up at UTM.

Alternatively, I could teach the TAs docstrip and git which seems rather time intensive. Both pieces of software have steep learning curves. ↩︎

Meta

Published: May 15, 2024

Last Modified: May 15, 2024

docfill: An Inverse of docstrip

Acknowledgments

Meta

Navigation Menu