1. I have installed the Steel City Comic font referring to item 1 in FAQ.txt, and rebuilt "perfbook.pdf". But it doesn't seem to have any effect. What am I missing? A. If you built "perfbook.pdf" before installing the font, you need to rebuild cartoons whose sources are .svg files. Typing "make touchsvg; make" will do the trick. 2. I prefer perfbook-1c.pdf than perfbook.pdf to read it on my tablet. Typing "make perfbook-1c.pdf" every time is a little bit cumbersome. Isn't there any simpler way? A. Actually there is! Just type "make 1c". 3. Are there other short name targets? A. "make hb" will build perfbook-hb.pdf that is useful for making hard-bound printouts. "make 2c" will build perfbook.pdf. "make help" will show you the list of official targets. "make help-full" will display all the available targets. 4. Isn't it possible to build perfbook-1c.pdf by just typing "make"? A. Yes, it is! Define an environment variable "PERFBOOK_DEFAULT" in your shell and set its value as "1c". Then, just typing "make" will build perfbook-1c.pdf. If you set "hb" to "PERFBOOK_DEFAULT", typing "make" will build perfbook-hb.pdf mentioned in #3. While you have the environment variable set, specifying a specific target (or targets) always works. 5. The Makefile cannot find pdflatex. What is it and where can I find it? A. The "pdflatex" package is a variant of Don Knuth's digital typesetting program, which you can install. Alternatively, you can use the container image described in #13 below. Otherwise, instructions follow. On Ubuntu jammy and later, the following list should cover necessary packages (except for -doc packages): texlive-publishers texlive-pstricks texlive-science texlive-fonts-extra xfig librsvg2-bin graphviz gnuplot On Ubuntu focal, install inkscape instead of librsvg2-bin. On Fedora, installing the following set of packages suffices: texlive-collection-plaingeneric texlive-collection-binextra texlive-collection-latexextra texlive-collection-fontsextra texlive-collection-fontutils transfig graphviz librsvg2-tools gnuplot On other Linux distributions such as RHEL/CentOS and Scientific Linux, where support of TeX Live packages is insufficient, the aforementioned container image provides the needed support. Again, see #14 below. Of course, you can install upstream TeX Live. See: https://www.tug.org/texlive/quickinstall.html NOTE: In doing so, you might end up in having redundant texlive packages of your choice of distribution to satisfy dependency of other packages. Besides TeX Live, you need the following list of packages: fig2dev (or transfig) graphviz librsvg2-tools (or librsvg2-bin, rsvg-convert, etc.) gnuplot Note: For building on Git repo prior to January 2024, you need inkscape as well. Preferred SVG --> PDF converter is rsvg-convert >= v2.57. rsvg-convert v2.52 should also suffice. If there is no inkscape installed, any version of rsvg-convert is used for the conversion, albeit there can be poor looking figures in the end. You can continue building perfbook without rsvg-convert if you have inkscape, that is, as long as command-line mode inkscape works reliably... 6. I cannot build perfbook, and the perfbook.log file complains about some obscure package being missing. What do I do? A. Please see #5 above. 7. Building perfbook aborts with error "You need to update a2ping". What can I do? A. a2ping 2.77p has become incompatible with up-to-date Ghostscript on most Linux distributions since September 2018 due to security fixes backported from Ghostscript 9.22 and later. a2ping 2.83p has lost compatibility with Ghostscript 9.50 due to a change in default behavior. A compatible a2ping (2.84p) is available at: https://www.ctan.org/pkg/a2ping Copy "a2ping.pl" as "a2ping" into a directory which precedes /usr/bin in your PATH setting. a2ping 2.84p is available in TeX Live 2020 or later (Including TeX Live 2019/Debian). 8. When I try to build perfbook, it hangs after printing a line reading "pdflatex 1". How can I fix this? A. On UNIX-like systems, including Linux, type control-D. Then look at the end of the perfbook.log file (or the perfbook-1c.log file if you were building single-column). The error message at the end of the log file should indicate the source of the problem. The build scripts are supposed to make this unnecessary, so if it happens, please let me know. Please send me the perfbook.log output (or perfbook-1c.log output, depending on which you were building) so that I can fix the scripts. 9. Building perfbook or some of its experimental targets with alternative fonts fails due to a lack of font packages such as "nimbus15", "newtxtt", etc.; or an old version of font package "newtx". How can I install or update them? A-1. First of all, building perfbook requires TeX Live 2019/Debian (Ubuntu Focal) or later. Upgrading your Linux distribution (e.g. to Ubuntu Jammy) is one way to upgrade TeX Live and might have many other benefits as well. However, on modern TeX Live, installing -fonts-extra consumes more than 1GB of your disk space. If you prefer to manually install individual packages on Ubuntu, refer to "Method 3" in: http://tex.stackexchange.com/questions/73016/ For font packages such as "newtxtt" and "nimbus15", you must also update font-map database. See: http://tex.stackexchange.com/questions/88423/ Following is a list of links to font packages perfbook depends on as of October 2021 which are not included in -fonts-recommended: https://www.ctan.org/pkg/newtx https://www.ctan.org/pkg/libertine https://www.ctan.org/pkg/newtxtt https://www.ctan.org/pkg/nimbus15 https://www.ctan.org/pkg/courier-scaled https://www.ctan.org/pkg/inconsolata https://www.ctan.org/pkg/newtxsf https://www.ctan.org/pkg/gnu-freefont https://www.ctan.org/pkg/dejavu Note 1: Manually installing a font package newer than the one already exists in your TeX installation is a tricky business and should be avoided unless you have a very good knowledge of the infamously complex TeX font system. In most cases, upgrading TeX installation should be your way to go. Note 2: Most font packages on the CTAN site provide .zip archives which will automatically put the files in a relatively right place. Note that font packages should be copied to the TEXMFLOCAL directory rather than to the TEXMFHOME directory. Note 3: On Fedora and upstream TeX Live, you can install font packages one by one using the following command (example of newtx). On Fedora: sudo dnf install texlive-newtx On upstream TeX Live (assuming user mode installation): tlmgr install newtx A-2. Figures drawn using Inkscape and added in the SVG format need fonts accessible via the fontconfig scheme. The "Steel City Comic" font mentioned in #1 of FAQ.txt is one of such fonts and is mandatory. There are SVG figures which use other font families listed below: - DejaVu Sans - DejaVu Sans Mono - FreeMono - Liberation Sans - Liberation Mono These are treated as "nice-to-have" fonts and even if some of them are missing, conversion of those figures into PDF can go on using fallback fonts. You will see info-level messages from make runs: Nice-to-have font family 'DejaVu Sans Mono' not found. in .svg --> .pdf conversions if that happens. As for Ubuntu, packages listed in #5 should cover all the font families listed above. As for Fedora, installing packages listed below should suffice: - dejavu-fonts-all - liberation-fonts 10. Building perfbook fails with a warning of version mismatch of epigraph. What can I do? A. It is a known issue of TeX Live releases prior to 2020. This answer assumes Ubuntu, but it should work on other distros. 1. Download package archive from CTAN mirror: http://mirrors.ctan.org/macros/latex/contrib/epigraph.zip 2. Install it by following instructions at: https://help.ubuntu.com/community/LaTeX#Installing_packages_manually B. Instead of above manual steps, you could install the package using a script in this repository, './utilities/install_latex_package.sh'. For example: $ ./utilities/install_latex_package.sh epigraph 11. Is it possible to generate SyncTeX database file? A. Yes, it is. Setting an environment variable: $ export LATEX_OPT="-synctex=1" and doing "make clean; make" will generate perfbook.synctex.gz. This will enable SyncTeX search (.pdf <-> .tex) with a SyncTeX-supporting combination of pdf viewer and editor. Notes: - For an introduction of SyncTeX search (gedit <-> evince), see: https://help.gnome.org/users/evince/stable/index.html.en#synctex Other combinations of SyncTeX-supporting viewers and editors may work. - You need to install gedit-plugins and enable SyncTeX plugin in gedit's preference. - You need to open one of LaTeX sources (e.g. perfbook.tex) in gedit before doing inverse search from evince. - The environment variable LATEX_OPT works for other build targets such as perfbook-1c.pdf, perfbook-hb.pdf, etc. To enable forward search from gedit, run e.g.: $ utilities/synctex-forward.sh 1c - Changes made by utilities/synctex-forward.sh can be reverted by running: $ utilitied/synctex-forward.sh Please make sure to revert the changes before doing "git commit" of the other updates you've made. 12. After upgrading the userspace RCU library, and all of the code samples making use of that library are now broken. A. The userspace RCU library sometimes breaks ABI, which requires that the binaries dynamically linking to it be rebuilt. Try removing the old binaries ("make clean") and then rebuilding ("make"). 13. I want a stable environment to build perfbook.pdf. Can't I just use some container image? A. You can find a template Dockerfile under the docker/ subdirectory. You can pull the container image built from it as follows: docker pull akiyks/perfbook-build:latest It can be run with the command: docker run --rm -it -v :/work \ akiyks/perfbook-build:latest Note: The prebuilt container image assumes rootless mode. If you run root-mode docker, you can still run the image by adding the option: -u $(id -u):$(id -g) to the "docker run" command. You can build a container image on your own: cd docker docker build -t \ --build-arg uid=$(id -u) --build-arg gid=$(id -g) . For those prefer a Fedora-based container image, akiyks/perfbook-build:fedora is also available. It is built from docker/Dockerfile.fedora. If you have podman already installed, you can run the image with podman. podman runs in rootless mode by default. Use the following command to run (Note the ":z" in the -v flag): podman run --rm -it -v :/work:z \ akiyks/perfbook-build:fedora Your updates under /work will have your host uid in host's POV. 14. It looks as if answers above all assume building under GNU/Linux hosts. Wouldn't it be possible to build under non-GNU/Linux systems? A. As you might expect, perfbook's build scripts have been developed and tested on GNU/Linux hosts, especially assuming utility commands of FSF/GNU origin. That said, it should be possible to build on non-GNU/Linux systems as long as GNU compatible utility commands are usable. Here is a list of requirements: - GNU make - /usr/bin/env - date: format options of either GNU or BSD flavor - sed: repeat patterns \? and \+ - grep: -z option (optional) Among requirements above, features of date and sed are checked automatically at the beginning of make runs after "make clean". The check can be done manually by running: make precheck There may be cases where GNU compatible commands are installed with different names such as: - GNU make: gmake - GNU date: gdate - GNU sed: gsed - GNU grep: ggrep Those alternative names can be specified via make variables: gmake DATE=gdate SED=gsed GREP=ggrep or via environment variables: export DATE=gdate; export SED=gsed; exprot GREP=ggrep; gmake Again, building under non-GNU/Linux systems is tested only sparingly and you might encounter errors we are not aware of. Code samples under CodeSamples/ were originally written for Linux and a QNX compat layer was added in 2022. Compat layers for other OSes are more than welcome!