Section 35.2 Private Solutions File
Suppose an author distributes a textbook with an open license, and so makes the PreTeXt source available publicly (perhaps as a condition of the license). Perhaps the author also intends
<hint> provided with
<exercise> to assist students, and having them available as knowls in HTML output is a great way to make them easily available, but not immediately visible. But the author has also written some, or many,
<solution> for the
<exercise>, but these are only meant for instructors, and not for students. See the discussion at Section 34.1 for more background.
One approach is to distribute an Instructor Version or Solution Manual only on request, and only as a PDF. The ability to provide a watermark on every page (via switches in the LaTeX conversion) allows you to include a personalized message such as
Issued to Charles Darwin. Do Not Copy.
It would be a trivial technical exercise to remove this, but perhaps the moral imperative (in an extra
<preface> as well?) would dissuade most from distributing further?
But with an open-source project, how can you distribute the exercise without distributing the
<solution>? After multiple unsatisfactory experiments, we have arrived at the following solution. You author a separate PreTeXt document with
<solution> that you wish to keep private. You might put this in a different, private, git repository that you only share with your co-authors. Here is how you can construct and employ this file. Here we use the word solution generically to mean any of
For a large project you may have many private solutions and one big file is unwieldy. The solution is to modularize the file as described in Section 5.2. Then you can organize your “file” of solutions into multiple files, perhaps organized by
<section>. The carch is that the include facility requires each separate file to only have a single top-level (root) element. For this purpose use the
<pi:privatesolutionsdivision> element, which is designed for only this purpose. You can nest this element arbitrarily deep.
Note that an
<task> may be authored with no solutions and then does not need a
<statement>. Now, if you add private solutions to such an exercise or task, the markup will be incorrect. As of 2020-06-24 we make no extra effort to warn, or fix, this situation. A likely consequence will be that these private solutions are not rendered (but you might see a problem number where they should appear). Similar advice applies to
<task>, and especially to non-terminal
<task> which can never hold solutions.
You will have noticed that you have a lot of freedom to make a completely disorganized private solutions file, or even many disorganized files. There is no structure to prevent this—you are on your own. Ourselves, we would keep the solutions in order of appearance, modularize a big project logically, and use comments liberally. But you can always search on the common value of
@ref to locate the pieces.
Warning 35.2.2. Keep Your Private Solutions Private!
If you are using git (and why wouldn't you?) it could be an easy mistake to include your private solutions in a public repository accidentally with a careless commit. We would place our private solutions in a directory close to our source tree, but not within the material tracked by git. And we would build our solutions manual with private solutions by copying the necessary files to some scratch directory, where they get deleted later, after the PDF result has been preserved for use.