Private Solutions File

Section 37.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 36.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 (see Section 26.5) 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 <hint>, <answer>, and <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 <hint>, <answer>, or <solution>.

List 37.2.1. Private Solutions File

Start with an <exercise> that you wish to provide private solutions for. Give it an @xml:id, which you will need for Item 4. Be sure the <exercise> is structured with a <statement> so a private solution may be appended.
We recommend leaving a comment inside the <exercise> to remind you that there is a private solution that may need editing if the problem <statement> changes.
Create a new PreTeXt file to hold the private solutions, presumably located away from your other source files (see Warning 37.2.2). Call it something like privatesolutions.ptx, which is what we will use below.
The first two lines of the file must be:
```
<?xml version="1.0" encoding="UTF-8" ?>
<pi:privatesolutions
  xmlns:pi="http://pretextbook.org/2020/pretext/internal">
```
(pi is the PreTeXt internal namespace.)
Now add as many <hint>, <answer>, or <solution> as you like, in any order you like, authored in the usual way. The missing piece is that you must link each solution back to the <exercise> it belongs to, with a @ref attribute whose value is the @xml:id you used to label the <exercise> in Item 1.
For example, if there is an <exercise> with @xml:id having value very-hard-problem, you might author:
```
<answer ref="very-hard-problem">
  <p>42.</p>
</answer>
```
Finish the file by closing the overall <pi:privatesolutions> element.
Now you can have all of these private solutions incorporated into your source by specifying the filename in your publication file (Section 26.1). The @private-solutions attribute of the /publication/source element should be set to this filename (Subsection 44.7.3). So you would have
```
<publication>
  <source private-solutions="path/to/privatesolutions.ptx"/>
  ...
```
The private solutions file should be available to any conversion, but most likely you will be using it with the solution manual conversion (see Section 37.1).

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.3. Then you can organize your “file” of solutions into multiple files, perhaps organized by <chapter> or <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 <exercise> or <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 @xml:id and @ref to locate the pieces.

Warning 37.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.

Prev Top Next