Directory and file structure

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.

Book versions with and without solutions to exercises

Password protected files

Separating the source files from published documents