Usage example

[sdavids]

Please provide a usage example for your Docker image.

Something along the lines of:

$ mkdir /tmp/test && cd "$_"
$ cat << 'EOF' >main.tex
\documentclass{article}
\begin{document}
Test
\end{document}
EOF
$ docker run --rm <????> \
  -v "/tmp/test:<????>" \
  <????>
  kjarosh/latex:2024.3

Maybe also an example where the input is mounted readonly and one provides an output directory:

$ mkdir /tmp/out
$ mkdir /tmp/in && cd "$_"
cat << 'EOF' >main.tex
\documentclass{article}
\begin{document}
Test
\end{document}
EOF
$ docker run --rm <????> \
  -v "/tmp/in:<????>:ro" \
  -v "/tmp/out:<????>" \
  <????>
  kjarosh/latex:2024.3

[kjarosh]

Thank you for the suggestion! I've added Usage section which describes how to quickly compile a document with a one-liner and refreshed the CI/CD configs a bit.

Regarding the readonly mount, I've decided to not include this explicitly, because it's an advanced usage, and usually users who want to do such thing are experienced enough to do that on their own. Especially that the current usage covers mounting, selecting the working directory, and specifying the output directory.

However, I've added a paragraph about how to recompile the document automatically on file change, and how to change the engine, so hopefully that makes it easier to use the image.

[sdavids]

This page has not been updated:

https://hub.docker.com/r/kjarosh/latex

[kjarosh]

Done, thanks for pointing that out

[sdavids]

Please add -aux-directory=/tmp and -silent to your usage example.

One is usually not interested in the interim junk and hundreds of lines of debug output.

---

$ docker run --rm -v "$PWD:/src" -w /src -u "$UID:$GID" kjarosh/latex:2024.3 latexmk -pdf -output-directory=out main.tex
$ tree --noreport out
out
├── main.aux
├── main.fdb_latexmk
├── main.fls
├── main.log
├── main.pdf
└── main.xdv

⇓

$ docker run --rm -v "$PWD:/src" -w /src -u "$UID:$GID" kjarosh/latex:2024.3 latexmk -silent -pdf -aux-directory=/tmp -output-directory=out main.tex
$ tree --noreport out
out
└── main.pdf

Note: -aux-directory=/tmp absolute path; -output-directory=out relative path to -w /src

[kjarosh]

Please add -aux-directory=/tmp and -silent to your usage example.

One is usually not interested in the interim junk and hundreds of lines of debug output.

Added -auxdir=out/aux so that auxiliary files are placed in a subdirectory. I get that people usually aren't interested in seeing or dealing with aux files, but they make incremental building possible and without them rebuilding the project would take a lot longer.

Regarding -silent/-quiet, that unfortunately disables error messages, so users would not see what went wrong in case of an error, and they would have to check the log file; additionally, -silent along with ignoring aux files would mean that users virtually have no way of seeing what went wrong during build. Due to that I've decided not to include that option in the command, but I mentioned it along with some other options as potentially interesting.