README.md (3054B)
1 # How to compare against LaTeX 2 3 The tools in this directory can be used to create reference images 4 using LaTeX, and to compare them against the screenshots taken from a 5 browser. 6 7 ## Execution environment 8 9 ### Docker environment 10 11 If you don't want to ensure the presence of all required tools, or 12 want to make sure that you create reproducible results, simply run 13 14 dockers/texcmp/texcmp.sh 15 16 from the root of your KaTeX directory tree. 17 This will build a suitable docker image unless such an image already 18 exists. It will then use a container based on that image to generate 19 all the images described below. 20 21 Note that the files and directories created in the source tree from 22 within the docker will be owned by root, so you might have trouble 23 deleting them later on. Be sure you can obtain superuser permissions 24 on your computer or know someone who can, just to be safe. 25 26 ### Native environment 27 28 If you want to avoid the overhead of creating a docker container, or 29 the even larger overhead of setting up docker and creating the initial 30 image, then you may instead execute the commands 31 32 cd dockers/texcmp 33 npm install 34 node texcmp.js 35 36 from the root of your KaTeX directory tree. Required tools include the 37 `pdflatex` tool of a standard TeX distribution as well as the 38 `convert` tool from ImageMagick. 39 40 Note that this approach will use `/tmp/texcmp` as a temporary directory. 41 The use of a single directory name here can lead to conflicts if 42 multiple developers on the same machine try to use that directory. 43 44 Also note that different software configurations can lead to different results, 45 so if reproducibility is desired, the Docker approach should be chosen. 46 47 ## Generated files 48 49 After running either of the above commands, you will find two 50 (possibly new) subdirectories inside `test/screenshotter`, 51 called `tex` and `diff`. 52 53 ### Rasterized documents 54 55 `test/screenshotter/tex` will contain images created by `pdflatex` by 56 plugging the test case formula in question into the template 57 `test/screenshotter/test.tex`. This is essentially our reference of 58 how LaTeX renders a given input. 59 60 ### Difference images 61 62 `test/screenshotter/diff` will contain images depicting the difference 63 between the LaTeX rendering and the Firefox screenshot. Black areas 64 indicate overlapping print. Green areas are black in LaTeX but white 65 in Firefox, while it's the other way round for red areas. Colored 66 input is first converted to grayscale, before being subject to the 67 coloring just described. The pictures will be aligned in such a way 68 as to maximize the overlap between the two versions (i.e. the amount 69 of black output). The result will then be trimmed so it can easily be 70 pasted into bug reports. 71 72 ## Command line arguments 73 74 Both `texcmp.sh` and `texcmp.js` will accept the names of test cases 75 on the command line. This can be useful if one particular test case 76 is affected by current development, so that the effects on it can be 77 seen more quickly. 78 79 Examples: 80 81 dockers/texcmp/texcmp.sh Sqrt SqrtRoot 82 node dockers/texcmp/texcmp.js Baseline