Section 51.2 Testing Procedures
When developing a new feature or trying to fix a bug, it can be helpful to test a “before” version of some output format versus a current or “after” version. Sometimes you can lay the groundwork for a new feature by adding some code which has zero effect, but leaves a place where a small addition enables the feature. Then you can be somewhat confident your additions will also not ruin existing (desirable) behavior. Here are some suggestions for doing this with PreTeXt.
- Make a “before” version before you start. Or do a
git stash saveto put away uncommitted changes and then make that initial version. Usegit stash popto bring the changes back. You can also temporarilygit checkout 1234abcdsome commit, andgit checkout topic-branchto come back. You can havesample-article.tex.oldaround to compare with a new and constantly updatedsample-article.tex. I routinely remove*.texbetween tests, so the*.tex.oldversion is named so it does not get deleted. - The
sample-article.xmldocument is meant to have one of most everything and lots of extreme examples. If your changes affect chapters, and other aspects of a book, then thesample-book.xmldocument can also be used. - Be careful about adding new content since you can get a lot of automatically-generated id’s that change, making it hard to see real changes. By managing location (early in a list of commits) and building at specific commits you can test new code that needs new sample uses.
- LaTeX output is one big file. Use the
debug.chunkstring parameter, set to0to get one big HTML file. - Use the
debug.datedfilesstring parameter set tonoso that file headers (knowls!) do not all have spurious changes. git diff sample-article.tex.old sample-article.texworks well, and oftentimes it works even better with--word-diff. You really want your test output off in some scratch directory. If not, be careful, and you may need the--no-indexoption so you are not fooled by no apparent changes. (Those options need a double-dash to lead, they look like one right now.)- Having
<today/>and<timeofday/>in your test document you can be sure there is always at least one or two changes, and prevent some confusion due to mistakes. - When testing HTML output, especially for chunking or knowls, putting two versions in different parallel directories will allow git to compare the entire directories with
git diff /tmp/before /tmp/after. - Every number is hard-coded in HTML output, so changes to numbering are best tested there. The LaTeX conversion may react differently (a mix of hard-coded and automatically-generated numbers), so should also be tested.
It can be very surprising how many subtle bugs can be revealed by very small, or very few, changes discovered by these procedures.
