| 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 <path to perfbook dir>:/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 <container image tag> \ |
| --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 <path to perfbook dir>:/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! |