Book versions with and without solutions to exercises¶
It is easy to turn solutions to exercises on or off by the options
--without_solutions (for !bsol environments) and --without_answers
(for !bans environments). One often wants to publish a book
without solutions to exercises, but also make versions with solutions.
One possibility is to password protect the versions with solutions.
It can be wise to create a very complicated filename for the files that may be shown in a browser with the URL visible for a class. One possibility is to create a 40 long SHA1 string as filename and start it with a dot to also make it invisible in most operating systems.
hash=82dee82e1274a586571086dca04d00308d3a0d86
html=.trash<built-in function hash>
doconce format html book --html_output=$html ...
Password protected files¶
The file following file, called password.html, presents an empty page
with a button for providing a password, and if approved, the first
page of the book opens up.
<html>
<body>
<!-- password protected HTML page --->
<script>
function passWord() {
var testV = 1;
var pass1 = prompt('Please enter your password',' ');
while (testV < 3) {
if (!pass1)
history.go(-1);
if (pass1.toLowerCase() == "PASSWORD") {
alert('You Got it Right!');
window.open('DESTINATION.html');
break;
}
testV += 1;
var pass1 =
prompt('Access denied - password incorrect!', 'Password');
}
if (pass1.toLowerCase()!="password" & testV ==3)
history.go(-1);
return " ";
}
</script>
<center>
<form>
<input type="button" value="Enter Protected Area" onClick="passWord()">
</form>
</center>
</body>
</html>
Suppose your HTML file with solutions that you want to password protect has the
name book-sol.html. Then you can simply do
cp password.html book-sol.html
doconce replace DESTINATION "$html" book-sol.html
doconce replace PASSWORD "s!m!art|pass@word" book-sol.html
A PDF file can easily be password protected with the use of the pdftk
tool. If book.pdf is with solutions, book-sol.pdf will also require
a password a!4:
pdftk book.pdf output book-sol.pdf owner_pw foo user_pw "a!4"
Separating the source files from published documents¶
The primary repository organization described in this document has the
DocOnce source files in doc/src, while compiled and published
documents appear in doc/pub. If the book is published without
solutions to exercises, one will often avoid readers to dive into the
DocOnce source files in the repository and find solutions. The author
has two methods for dealing with this problem.
The first method is simple, but not safe. The idea is to rename
doc/src to doc/.src. That is, the source tree has a name starting
with a dot (.src) such that the directory is invisible on Unix
systems. However, it is visible on GitHub, and any ls -a command
will list the source tree. A reader who really wants to find solutions
in the DocOnce source files will most likely locate the files...
Another, completely safe method is to move the .src or src
directory tree to a new, private repository when the book is to be published.
The make* scripts must then the updated such that the directory
where the documents are published becomes correct.
One can also start out with a private repository for the source files and a public repository for the published files. This author, however, prefers to use one repository when developing major parts of a book and then migrate the source tree to a private repository when solutions are to be protected from the public.
