Develop a public/private approach to exercises and solutions

[rbeezer]

Experiment with Tom Judson's AATA, and document in the Author's Guide. Following is from pretext-dev discussion group.

---

Mostly for Tom Judson and his AATA project, but good for everybody to read, I think.

Tom has solutions to many of his exercises, and I have contributed solutions to the Sage exercises. We don't want students to see them. Ever. Tom will send a personally-watermarked solutions manual PDF to an instructor who asks. Yes, I know you can remove the watermark. Its more of a moral warning against redistribution.

Generating these has been a real fiddle. I won't explain the current kludge. But working through Alex's WW-static made me think.

1. Author the narrative, exercises, solutions, etc, in-situ, and manage in a private GitHub repository with just "trusted" collaborators having any kind of access (read/write).

2. Maintain an identical copy, without solutions, available in a public repository.

3. Author edits can happen on the private version, keeping commits with solutions separate from commits without solutions. A non-solution commit can be "cherry-picked" from the private to the public. ("cherry-pick" is a git command to copy a changeset/commit from one repository to another, or branch to branch within a repository.)

4. Public pull requests won't touch solutions. They can be managed on the public versions. Once added to the official public version, they can be "cherry-picked" from the public to the private.

For small changes, such as on a mature project like AATA, I think this would work well. Step 3 might cause a merge conflict when a change to an exercise uses the "solution" for context, but maybe not. Massive changes in Step 3, like re-arranging files or whole exercises divisions would definitely not work well. So perhaps we need:

5. An XML-to-XML transform that strictly copies private files, but drops solutions. This could migrate a changed private to a faithfully changed public, that could then be the basis of a new commit, functionally identical to the massive changes in private in the first place.

Such a transform does have inevitable small changes, like "CDATA" goes away, and all "special" characters become escaped versions, plus attributes get re-ordered and reformatted. So it might be desirable to maintain each version in a "normalized" form so that these changes do not occur (note - this says nothing about whitespace, except right around attributes). And re-normalization only needs to happen as part of massive changes.

Implications for AATA

A. We might want to put tikz files into their own text files, and "xi:include" them with parse="text". This would remove any need for authoring to deal with ampersands, less-than, greater-than as problem XML characters. I think this could be automated.

B. We could incorporate all our exercises into the chapters they come from, rather than including them (the current kludge). This would dramatically clean up the source directory to be primarily the 24 chapters, one per file. This could be automated during a normalization step.

Tom - I can handle 5, A, and B. (Not right away!) What do you think of the workflow described in 3 and 4?

Rob

[rbeezer]

Implemented for AATA. Needs a write-up in Author's Guide. Principles should be:

1. Author solution with statement.
2. Very few source files, like whole chapters.

Then get two repositories like we have for AATA, or suggest maybe a ref/id sort of scheme, though this may not work very well.

[rbeezer]

A long-running, never-merged git branch is the current solution. Implemented and in production for AATA, but of course, it is private.

Documented in Publisher's Guide, with work at c19b8d7932c879bfe1494e88d6fe57ea331274f6