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.
You have attempted of activities on this page.
