From b91348de166f3379e0cc075dfa3d15efc85e02d2 Mon Sep 17 00:00:00 2001 From: Alex Povel Date: Sat, 20 Feb 2021 15:29:13 +0100 Subject: [PATCH 1/7] Add initial VSCode Remote-Containers config --- .devcontainer/Dockerfile | 1 + .devcontainer/devcontainer.json | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+) create mode 100644 .devcontainer/Dockerfile create mode 100644 .devcontainer/devcontainer.json diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 0000000..8bf5699 --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1 @@ +FROM alexpovel/latex diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..b946c24 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,18 @@ +{ + "name": "LaTeX", + "build": { + "dockerfile": "Dockerfile", + }, + // Set *default* container specific settings.json values on container create. + "settings": { + "terminal.integrated.shell.linux": "/bin/bash" + }, + // Add the IDs of extensions you want installed when the container is created. + "extensions": [ + "James-Yu.latex-workshop" + ], + "containerEnv": { + "CI": "true", + "LANG": "" + }, +} \ No newline at end of file From 139c57601fb0e0500e87ae739f2825c8517dc63a Mon Sep 17 00:00:00 2001 From: Alex Povel Date: Sat, 20 Feb 2021 19:42:36 +0100 Subject: [PATCH 2/7] Add configs and changes to make LaTeX Workshop and Remote Containers work --- .devcontainer/devcontainer.json | 53 ++++++++++++++- .gitignore | 5 +- .vscode/settings.json | 35 ++++++++++ chapters/mainmatter/usage.tex | 114 ++++++++++++++++++++------------ cookbook.cls | 3 +- cookbook.tex | 4 ++ 6 files changed, 167 insertions(+), 47 deletions(-) create mode 100644 .vscode/settings.json diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index b946c24..9e899d1 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -12,7 +12,58 @@ "James-Yu.latex-workshop" ], "containerEnv": { + // Inside the container, we want to compile like we are in CI, hence define this + // variable. It's important for the Makefile to select the correct behaviour. "CI": "true", - "LANG": "" + // The base image has this locale: + // $ docker run --rm --entrypoint="locale" alexpovel/latex + // LANG= + // LANGUAGE= + // LC_CTYPE="POSIX" + // LC_NUMERIC="POSIX" + // LC_TIME="POSIX" + // LC_COLLATE="POSIX" + // LC_MONETARY="POSIX" + // LC_MESSAGES="POSIX" + // LC_PAPER="POSIX" + // LC_NAME="POSIX" + // LC_ADDRESS="POSIX" + // LC_TELEPHONE="POSIX" + // LC_MEASUREMENT="POSIX" + // LC_IDENTIFICATION="POSIX" + // LC_ALL= + // *However*, starting this very same container in VSCode's Remote Containers, + // the locale changes to: + // $ locale + // locale: Cannot set LC_CTYPE to default locale: No such file or directory + // locale: Cannot set LC_MESSAGES to default locale: No such file or directory + // locale: Cannot set LC_ALL to default locale: No such file or directory + // LANG=en_US.UTF-8 + // LANGUAGE= + // LC_CTYPE="en_US.UTF-8" + // LC_NUMERIC="en_US.UTF-8" + // LC_TIME="en_US.UTF-8" + // LC_COLLATE="en_US.UTF-8" + // LC_MONETARY="en_US.UTF-8" + // LC_MESSAGES="en_US.UTF-8" + // LC_PAPER="en_US.UTF-8" + // LC_NAME="en_US.UTF-8" + // LC_ADDRESS="en_US.UTF-8" + // LC_TELEPHONE="en_US.UTF-8" + // LC_MEASUREMENT="en_US.UTF-8" + // LC_IDENTIFICATION="en_US.UTF-8" + // LC_ALL= + // There's three errors because the container doesn't seem to have the correct + // locale files: + // $ locale -a + // locale: Cannot set LC_CTYPE to default locale: No such file or directory + // locale: Cannot set LC_MESSAGES to default locale: No such file or directory + // locale: Cannot set LC_COLLATE to default locale: No such file or directory + // C + // C.UTF-8 + // POSIX + // This leads to `lualatex` erroring out, see also https://tex.stackexchange.com/q/374303/120853 + // Using "POSIX" is possible and brings us back to vanilla container locale: + "LC_ALL": "POSIX" }, } \ No newline at end of file diff --git a/.gitignore b/.gitignore index 4886a17..467caf4 100644 --- a/.gitignore +++ b/.gitignore @@ -154,7 +154,10 @@ testing.tex # Some weird junk file from VSCode LaTeX Workshop? __latexindent_temp.tex -.vscode/ +# Include settings file, but nothing else, since that is used as part of the cookbook +.vscode/* +!.vscode/settings.json + organisational/ # Used to generate the 'dirty directory tree' diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..1645fdb --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,35 @@ +{ + "latex-workshop.latex.recipes": [ + { + "name": "lualatex", + "tools": [ + "lualatex" + ] + }, + { + "name": "latexmk", + "tools": [ + "latexmk" + ] + } + ], + "latex-workshop.latex.tools": [ + { + "name": "lualatex", + "command": "lualatex", + "args": [ + "--shell-escape", + "%DOC%" + ] + }, + { + "name": "latexmk", + "command": "latexmk", + "args": [ + // latexmk doesn't need a file argument, but provide it to avoid running + // on *all* found tex files + "%DOC%" + ] + } + ] +} \ No newline at end of file diff --git a/chapters/mainmatter/usage.tex b/chapters/mainmatter/usage.tex index dc0fb6a..79b47f2 100644 --- a/chapters/mainmatter/usage.tex +++ b/chapters/mainmatter/usage.tex @@ -393,61 +393,82 @@ \subsection{Editor} \subsubsection{Visual Studio Code} -Using the \href{https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop}{\emph{LaTeX Workshop}} extension for Visual Studio Code is recommended. +The repository of this document comes with a \href{https://github.com/microsoft/vscode-dev-containers}{\texttt{.devcontainer}} directory. +In it is all the configuration necessary to run your development environment \emph{inside} the Docker container entirely. +To make the magic work, install the \href{https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers}{\emph{Remote -- Containers}} extension. +Follow the instructions there on how to download all prerequisites, like of course Docker. +Visual Studio Code will detect the remote container configuration of this repository automatically. +If not, run the steps manually: +\begin{enumerate} + \item Open the command palette (\keys{\ctrl{} + \shift{} + P} --- the command palette is one of the defining, core features of Visual Studio Code, it's great!). + \item Run \menu{Remote-Containers: Reopen in container}. +\end{enumerate} +Your development environment is now \emph{inside} the container. +Hence, if you ran for example \texttt{latexmk} in the console, it executes the container version. +This is exactly what we want and previously did using the \texttt{docker run} command. + +\paragraph{Extensions} +There is a small problem. On its own, Visual Studio Code has no concept of \LaTeX{}, since out of the box, it is much closer to being an editor than an \abb{integrated_development_environment}. You increase the program's capabilities by choosing and installing extensions. - +Using the \href{https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop}{\emph{LaTeX Workshop}} extension for Visual Studio Code is recommended. +For the container environment, it is installed automatically from the settings found in \texttt{devcontainer.json}. The \emph{LaTeX Workshop} extension turns Visual Studio Code into a \LaTeX{} \abb{integrated_development_environment}. -However, some configuration is needed to make it work alongside the Docker solution. -\emph{LaTeX Workshop} works using \emph{recipes}, which in turn use \emph{tools}. -These recipes can be chains like -\begin{center} - \texttt{pdflatex \textrightarrow{} bibtex \textrightarrow{} pdflatex \textrightarrow{} pdflatex} . -\end{center} -As argued earlier in \cref{ch:compilation_steps}, that is not a workflow we want to employ here. -We use our own recipe, which simply calls a tool based on Docker. -Open the Visual Studio Code settings by either: +It works using \emph{recipes}, which in turn use \emph{tools}. +The extension comes with a pre\-/defined \texttt{latexmk} tool: +\begin{enumerate} + \item Open the command palette. + \item Run \menu{LaTeX Workshop: Build with recipe > latexmk}. +\end{enumerate} +This just runs \texttt{latexmk} within the container. +As usual using Docker, your host machine does not need a \LaTeX{} installation for this to work. +If you want, you can stop here --- running \texttt{latexmk} is all that is ever needed. + +\paragraph{Settings} +You can configure \emph{everything} in Visual Studio Code, including its extensions, in the settings. +Open them by either: \begin{itemize} - \item opening the command palette (\keys{\ctrl{} + \shift{} + P}) and looking for \emph{Preferences: Open Settings (JSON)} - (the command palette is one of the defining, core features of Visual Studio Code, it's great!), or + \item The command palette at \menu{Preferences: Open Settings (JSON)}, or \item navigating to \menu{File > Preferences > Settings}, then opening as \abb{js_object_notation}. \end{itemize} -In there, add the new recipe and tool, making sure to enter them into the preexisting lists (Visual Studio Code is very helpful in notifying you of errors, like duplicate keys): -\begin{minted}{json} - "latex-workshop.latex.recipes": [ - { - "name": "Docker", - "tools": [ - "docker" - ] - }, -\end{minted} -as well as -\begin{minted}{json} - "latex-workshop.latex.tools":[ - { - "name": "docker", - "command": "docker", - "args": [ - "run", - "--rm", - "--volume=%DIR%:/tex", - "alexpovel/latex", - "%DOCFILE%" - ] - }, -\end{minted} -Note the use of \texttt{\%DOCFILE\%}: -We are \emph{in} the container at this point, so must not use the \emph{host} full path \texttt{\%DOC\%}, since that does not exist in the container. -Inside the container, we are in the correct working directory already (\texttt{/tex}), so just the filename suffices (\texttt{\%DOCFILE\%}). -You can now run +For example, as discussed at the end of \cref{ch:compilation_steps}, you might want to have a recipe that only runs \texttt{lualatex}, once. +This is \textbf{already taken care of} for this repository: +\inputminted{json}{./.vscode/settings.json} +These are \emph{Workspace Settings}, which \href{https://code.visualstudio.com/docs/getstarted/settings}{take precedence over (global) user settings}. +As such, they also override all the recipes \emph{LaTeX Workshop} usually comes with. +You will have to define more recipes yourself. + +With the new recipes, you can now run \begin{center} - \menu{LaTeX Workshop: Build with recipe > Docker} + \menu{LaTeX Workshop: Build with recipe > lualatex} \end{center} from the command palette. Notice the freedom and flexibility you have for defining many more recipes. In fact, alongside \texttt{latexmk} and classic \texttt{make}, you now have more potential flexibility and automation than one could possibly need. -For example, I have a recipe that runs \emph{just} \texttt{lualatex}, as discussed at the end of \cref{ch:compilation_steps}. + +Using the above \emph{Remote -- Containers} approach, the entire development chain happens inside the container, with your working directory mounted into it. +This enables: +\begin{itemize} + \item the \emph{LaTeX Workshop} extension to work fully: + \begin{itemize} + \item SyncTeX works: + \begin{itemize} + \item \keys{\ctrl{} + Click} into the \abb{portable_document_format} preview goes to the source code + \item \menu{LaTex Workshop: SyncTeX from cursor} (command palette) goes the other way. + \end{itemize} + \item Highlighting infos, warnings and errors (\emph{Problems} pane) works + \item \href{https://github.com/James-Yu/LaTeX-Workshop/wiki/Intellisense}{IntelliSense} works, providing autocompletion for: + \begin{itemize} + \item citations (\texttt{autocite} \iecfeg{etc.}) --- check out the \emph{Citation Browser} in the command palette! + \item references (\texttt{cref} \iecfeg{etc.}) + \item and more, like commands + \end{itemize} + \end{itemize} + \item Your files are persisted normally, despite the container being ephemeral. + \item Tools like \texttt{make} work from within the Visual Studio Code terminal. + For example, run \texttt{make clean} to clear everything not tracked by git. + This is very convenient for a cold start, because \LaTeX{} sometimes gets stuck if auxiliary files are corrupted. +\end{itemize} \paragraph{More Settings} For more control, you might want to keep the extension from compiling on every document save: @@ -455,3 +476,8 @@ \subsubsection{Visual Studio Code} "latex-workshop.latex.autoBuild.run": "never" \end{minted} See \href{https://github.com/James-Yu/LaTeX-Workshop/wiki/Compile#latex-recipes}{the official documentation} for more. + +\subsubsection{Other Editors} + +You will have to incorporate the \texttt{docker} commands shown in \cref{ch:using-docker} manually. +Most editors do not support container\-/native developing, so you will go the old\-/school route. diff --git a/cookbook.cls b/cookbook.cls index f358969..d839c50 100644 --- a/cookbook.cls +++ b/cookbook.cls @@ -777,7 +777,8 @@ isbn=false,% ]{biblatex}% -\addbibresource{bib/bibliography.bib}% *.bib file goes here +% The `\addbibresource` command moved to the root *.tex file to work for VSCode's +% LaTeX Workshop extension. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Special Treatment for anything in \nocite{*} diff --git a/cookbook.tex b/cookbook.tex index ffd98c3..a6e145c 100644 --- a/cookbook.tex +++ b/cookbook.tex @@ -70,6 +70,10 @@ chapters/backmatter,% }% +% The following occurs here so VSCode's 'LaTeX Workshop' extension can find all bib +% resources (it doesn't seem to look into class files): +\addbibresource{bib/bibliography.bib}% *.bib file goes here + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Titlepage and document metadata content: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% From b06661bc7c6cc8fc8ad712f475fee3293b617c98 Mon Sep 17 00:00:00 2001 From: Alex Povel Date: Sun, 21 Feb 2021 09:44:26 +0100 Subject: [PATCH 3/7] Add recommended VSCode extensions for this repo --- .gitignore | 3 ++- .vscode/extensions.json | 11 +++++++++++ chapters/mainmatter/usage.tex | 1 + 3 files changed, 14 insertions(+), 1 deletion(-) create mode 100644 .vscode/extensions.json diff --git a/.gitignore b/.gitignore index 467caf4..91bd5ae 100644 --- a/.gitignore +++ b/.gitignore @@ -154,9 +154,10 @@ testing.tex # Some weird junk file from VSCode LaTeX Workshop? __latexindent_temp.tex -# Include settings file, but nothing else, since that is used as part of the cookbook +# Include settings files, but nothing else, since that is used as part of the cookbook .vscode/* !.vscode/settings.json +!.vscode/extensions.json organisational/ diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..366d3b5 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,11 @@ +{ + // See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations. + // Extension identifier format: ${publisher}.${name}. Example: vscode.csharp + // List of extensions which should be recommended for users of this workspace. + "recommendations": [ + "ms-vscode-remote.remote-containers", + "James-Yu.latex-workshop" + ], + // List of extensions recommended by VS Code that should not be recommended for users of this workspace. + "unwantedRecommendations": [] +} \ No newline at end of file diff --git a/chapters/mainmatter/usage.tex b/chapters/mainmatter/usage.tex index 79b47f2..4f6cf82 100644 --- a/chapters/mainmatter/usage.tex +++ b/chapters/mainmatter/usage.tex @@ -396,6 +396,7 @@ \subsubsection{Visual Studio Code} The repository of this document comes with a \href{https://github.com/microsoft/vscode-dev-containers}{\texttt{.devcontainer}} directory. In it is all the configuration necessary to run your development environment \emph{inside} the Docker container entirely. To make the magic work, install the \href{https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers}{\emph{Remote -- Containers}} extension. +Visual Studio Code automatically prompts you to install it when you first open this repository, as configured in \texttt{.vscode/extensions.json}. Follow the instructions there on how to download all prerequisites, like of course Docker. Visual Studio Code will detect the remote container configuration of this repository automatically. If not, run the steps manually: From a9de6fe835b89c69c60e724bacf1807be23804a5 Mon Sep 17 00:00:00 2001 From: Alex Povel Date: Sun, 21 Feb 2021 10:41:16 +0100 Subject: [PATCH 4/7] Fix file import --- chapters/frontmatter.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/frontmatter.tex b/chapters/frontmatter.tex index 333aa5b..b0c7cdf 100644 --- a/chapters/frontmatter.tex +++ b/chapters/frontmatter.tex @@ -18,7 +18,7 @@ \subtitle{An alternative title page style} % % Run this file again, since it contains the \renewcommand definitions - \input{chapters/other/titlepage.tex} + \subimport{other/}{titlepage.tex} \makeatother \maketitle% Print alternative title page From 32e8fd0bb7a9909cd62c5664ebaf3adc56ced0da Mon Sep 17 00:00:00 2001 From: Alex Povel Date: Sun, 21 Feb 2021 10:47:02 +0100 Subject: [PATCH 5/7] Enable linting Doesn't currently work with any files other than root; also, see https://github.com/James-Yu/LaTeX-Workshop/issues/2393 --- .vscode/settings.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 1645fdb..c20a484 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -31,5 +31,6 @@ "%DOC%" ] } - ] + ], + "latex-workshop.chktex.enabled": true } \ No newline at end of file From 09d9bf982aff1522a296354ce30d68ddda3e23c9 Mon Sep 17 00:00:00 2001 From: Alex Povel Date: Sun, 21 Feb 2021 10:47:36 +0100 Subject: [PATCH 6/7] Switch from subinclude to plain import LaTeX Workshop does not support subincludefrom, but works with import/subimport --- cookbook.tex | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/cookbook.tex b/cookbook.tex index a6e145c..5d23a20 100644 --- a/cookbook.tex +++ b/cookbook.tex @@ -60,15 +60,6 @@ %\usepackage{showframe}% Uncomment for debugging (show frames) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -% Included parts are listed here. -% Auxiliary files are kept, retaining references, page numbers etc., but -% compilation speeds are accelerated by only including small document parts. -% Uncomment only the part work is currently done on, comment out all others. -\includeonly{% - chapters/frontmatter,% - chapters/mainmatter,% - chapters/backmatter,% -}% % The following occurs here so VSCode's 'LaTeX Workshop' extension can find all bib % resources (it doesn't seem to look into class files): @@ -111,7 +102,7 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{document} - \subincludefrom{chapters/}{frontmatter} - \subincludefrom{chapters/}{mainmatter} - \subincludefrom{chapters/}{backmatter} + \import{chapters/}{frontmatter} + \import{chapters/}{mainmatter} + \import{chapters/}{backmatter} \end{document} From 4ca684d937c7810efbc875464eb845dc3af6e291 Mon Sep 17 00:00:00 2001 From: Alex Povel Date: Sun, 21 Feb 2021 11:06:36 +0100 Subject: [PATCH 7/7] Extend lualatex recipe Enable SyncTeX and recording to fls file --- .vscode/settings.json | 3 +++ chapters/mainmatter/usage.tex | 2 ++ 2 files changed, 5 insertions(+) diff --git a/.vscode/settings.json b/.vscode/settings.json index c20a484..efefa06 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -19,6 +19,8 @@ "command": "lualatex", "args": [ "--shell-escape", + "--synctex=1", + "--recorder", "%DOC%" ] }, @@ -32,5 +34,6 @@ ] } ], + "latex-workshop.latex.recipe.default": "lastUsed", "latex-workshop.chktex.enabled": true } \ No newline at end of file diff --git a/chapters/mainmatter/usage.tex b/chapters/mainmatter/usage.tex index 4f6cf82..1b7e781 100644 --- a/chapters/mainmatter/usage.tex +++ b/chapters/mainmatter/usage.tex @@ -424,6 +424,7 @@ \subsubsection{Visual Studio Code} This just runs \texttt{latexmk} within the container. As usual using Docker, your host machine does not need a \LaTeX{} installation for this to work. If you want, you can stop here --- running \texttt{latexmk} is all that is ever needed. +Hit \keys{\ctrl{} + \Alt{} + B} to build the project again, using the last used recipe. \paragraph{Settings} You can configure \emph{everything} in Visual Studio Code, including its extensions, in the settings. @@ -464,6 +465,7 @@ \subsubsection{Visual Studio Code} \item references (\texttt{cref} \iecfeg{etc.}) \item and more, like commands \end{itemize} + \item Auto\-/Formatting (\keys{\shift{} + \Alt{} + F}) works (\emph{LaTeX Workshop} uses \ctanpackage{latexindent}) \end{itemize} \item Your files are persisted normally, despite the container being ephemeral. \item Tools like \texttt{make} work from within the Visual Studio Code terminal.