Instruction in ReadMe on how to compile the documentation is not working

[AlexanderZeilmann]

Prerequisites

• [X] Put an X between the brackets on this line if you have done all of the following:
  • Check that you are using the latest version of kaobook.
  • Check that your issue isn't already filed: https://github.com/fmarotta/kaobook/issues

Description

Compiling the documentation as described in the ReadMe does not work.

Minimal Working Example

From the ReadMe:

cd into the root of the repository, and run

pdflatex -output-directory examples/documentation main # The .tex is optional
biber -output-directory examples/documentation main
pdflatex -output-directory examples/documentation main
pdflatex -output-directory examples/documentation main
pdflatex -output-directory examples/documentation main

This fails because there is no main.tex in the root of the repo:

$ pdflatex -output-directory examples/documentation main
This is pdfTeX, Version 3.14159265-2.6-1.40.21 (TeX Live 2020) (preloaded format=pdflatex)
 restricted \write18 enabled.
entering extended mode
! I can't find file `main'.
<*> main

(Press Enter to retry, or Control-D to exit)
Please type another input file name:

If I cd examples/documentation/ and run pdflatex there I get

$ pdflatex main
This is pdfTeX, Version 3.14159265-2.6-1.40.21 (TeX Live 2020) (preloaded format=pdflatex)
 restricted \write18 enabled.
entering extended mode
(./main.tex
LaTeX2e <2020-10-01> patch level 4
L3 programming layer <2021-02-18>

! LaTeX Error: File `kaobook.cls' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: cls)

Copying the main.tex file to the root does not work either because then paths to the packages

\usepackage{kaobiblio}
\usepackage{mdftheorems}
\usepackage{plaintheorems}

and to the files

\input{chapters/options.tex}
\input{chapters/textnotes.tex}
\input{chapters/figsntabs.tex}
\input{chapters/references.tex}

are wrong.

Expected behavior: It would be great if there were only one command necessary to compile the documentation (including the glossary and nomenclature). Maybe this can be done with latexmk or make.

Actual behavior: Described above.

[fmarotta]

Weird, the commands work on my machine. But I agree that having to run just one command would be better. I'll try to set up latexmk

[AlexanderZeilmann]

Okay, I just figured out what is going on:

For me, the .tex extension was not optional.

So

pdflatex -output-directory examples/documentation main.tex

starts the compilation, but after some time fails with

! LaTeX Error: File `kaobiblio.sty' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: sty)

Enter file name:

---

Then I installed kaobook as described in these instructions. Now kaobiblio.sty is found and for some reason the .tex extension is also optional.

As you probably have kaobook installed like this, it explains why it worked for you.

So the problem is fixed for me, but I guess most users will not have kaobook installed like this.

[fmarotta]

Thanks for the report. Having the packages inside a separate styles directory made the code slightly more organised, but loading the packages with something like \usepackage{styles/kaobiblio} made it very difficult to pass custom options to these packages. So I started loading them like \usepackage{kaobiblio} in all the examples, which resulted in the present issue. Moreover, I discovered that my edit also caused errors on Overleaf.

I think that the best option is to move the packages to the root of the repository, so that they can be called with \usepackage{kaobiblio} and everything, including the custom options and the compilation method proposed in the README (except possibly for the optional extension), should work again. I have now implemented this strategy: the two packages mdftheorems.sty and plaintheorems.sty were merged into a single package kaotheorems.sty (the framed option can be passed to this package to activate the behaviour of mdftheorems.sty, as mentioned in the updated documentation), while the other two packages, environments.sty and packages.sty, have been merged into the kao.sty package.

[fmarotta]

I was referring to these commits: d411f681b167e91daf4e4d15cfb7089871f6c1e1, 660fc2803808514829b1d75ff6be7223665bc2df, 4183b4e938c1ad2b9f91317d2b75d9d4e065f959

[AlexanderZeilmann]

Impressive reorganization! Thank you!

I just tested it and it works for me. Closing this issue.