diff --git a/README.md b/README.md index 3baf988..4f000b0 100644 --- a/README.md +++ b/README.md @@ -15,101 +15,6 @@ It is available for [**download**](https://collaborating.tuhh.de/alex/latex-git- This very README is also made available for [download as a PDF](https://collaborating.tuhh.de/alex/latex-git-cookbook/-/jobs/artifacts/master/raw/README.pdf?job=README.pdf), converted from Markdown using [pandoc](https://pandoc.org/) with the [*Eisvogel*](https://github.com/Wandmalfarbe/pandoc-latex-template) template. -## Possible issues and pitfalls - -Many nights were lost over issues involving GitLab CI/CD, but also plain LaTeX. -Here is a non-exhaustive list --- a bit like a gallery of failure --- of the most common ones. -Hopefully, it spares you some despair. - -- You run into [a similar error as](https://tex.stackexchange.com/q/233583/120853): - - ```plaintext - ! Package pgfplots Error: Sorry, the requested column number '1' in table 'dat. - csv' does not exist!? Please verify you used the correct index 0 <= i < N.. - ``` - - This can happen if you use `pgfplotstable` for plotting from tabular data, be it - inline or from an outside file. - If you use [`matlab2tikz`](https://github.com/matlab2tikz/matlab2tikz), you might also - run into the above error, since it potentially uses inline tables. - - In the [class file](cookbook.cls#983), there is a line reading: - - ```tex - \pgfplotstableset{col sep=comma}% If ALL files/tables are comma-separated - ``` - - This is a *global* default for all tables, assuming that they are comma-separated. - The default is whitespace, which `matlab2tikz` uses, hence it breaks. - You can override the column separator either in the above global option, or manually - for each plot: - - ```tex - % See https://tex.stackexchange.com/a/251245/120853 - \addplot3[surf] table [col sep=comma] {dat.csv}; - ``` - -- When using package [`fontspec`](https://ctan.org/pkg/fontspec) - (or its derivative [`unicode-math`](https://ctan.org/pkg/unicode-math)), - compilation fails with - - ```text - ! error: (type 2): cannot find file '' - ! ==> Fatal error occurred, no output PDF file produced! - ``` - - It is possible that the font cache is corrupted after moving fonts around. - For example, if previously all fonts were in a flat `./fonts/` subdirectory of your - document root, and then you decide to sort them into `./fonts/sans/` etc., the luatex - cache will still point to the old ones. - - See [here](https://tex.stackexchange.com/a/311455/120853) - and also, similarly, [here](https://tex.stackexchange.com/a/453878/120853) - for a solution: - delete the `.lua` and `.luc` files of the fonts in question from `luatex-cache/generic/fonts/`. - For MiKTeX 2.9 on Windows 10, this was found in - `%USERPROFILE%\AppData\Local\MiKTeX\2.9\luatex-cache`. -- The error is or is similar to: - - ```text - ! Undefined control sequence. - l.52 \glsxtr@r - ``` - - With an `*.aux` file mentioned in the error message as well. - Here, an auxiliary file got corrupted in an unsuccessful run and simply needs to be - deleted. - Do this manually or using `latexmk -c`. -- Concerning `glossaries-extra`: - - - Using `\glssetcategoryattribute{}{indexonlyfirst}{true}`. - For all items in ``, it is meant to only add the very first reference to - the printed glossary. - If this reference is within a float, this breaks, and nothing shows up in the - '`##2`' column. - - The way the document was set up, most symbols are currently affected. - However, in an actual document, it is highly unlikely you will be referencing/using - (with `\gls{}`) symbols the first time in floating objects. - Therefore, this problem is likely not a realistic issue. - - - In conjunction with `subimport`: - That package introduces a neat structure to have subdirectories and do nested imports - of `*.tex` files. - But that might not be worth it, since it breaks many referencing functionalities in - for example TeXStudio. - - More importantly, it seems to cause `glossaries-extra` to no longer recognize - which references have occurred. - We currently call `selection=all` in `\GlsXtrLoadResources` to load all stuff found - in the respective `*.bib` file, regardless of whether it has actually been called - at some point (using `\gls{}` *etc.*). - This is a bit like if `biblatex` did not recognize cite commands and we just pulled - every single item in the bibliography file. - Some people use gigantic `*.bib` files, shared among their projects. - If suddenly every entry showed up in the printed document despite *not* being - referenced (be it a glossary or a bibliography item), chaos would ensue. - ## Appendix ### Hints for source files