diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..36352de --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,8 @@ +{ + "recommendations": [ + "yzhang.markdown-all-in-one", + "james-yu.latex-workshop", + "quarto.quarto", + "george-alisson.html-preview-vscode" + ] +} diff --git a/chapters/copyediting/12-cop-preliminaries.qmd b/chapters/copyediting/12-cop-preliminaries.qmd index 8d9c5b1..6fc013a 100644 --- a/chapters/copyediting/12-cop-preliminaries.qmd +++ b/chapters/copyediting/12-cop-preliminaries.qmd @@ -7,7 +7,7 @@ production chain. ### Skills -- Use a text editor (RStudio will do). +- Use a text editor (VSCode or RStudio will do). - Optionally, use [RStudio's visual editor](https://quarto.org/docs/visual-editor/). This provides a MS Word-like way of editing a markdown document: @@ -93,60 +93,68 @@ To these we add a few other folders for resources shared among copyeditors: ## New Workflow Start [Draft] -Note: below, when saying "in a terminal", we mean either PowerShell on Windows, or your default terminal in Mac or Linux. -All of the commands provided should work in all PowerShell (Windows), zsh (Mac) and bash (Linux). - - -The association is setting up a standardized compilation environment for Dialectica. -The environment is encapsulated in a *docker container* and includes all of the tools needed for the copyediting work, including pandoc, LaTeX, Lua, Quarto, and the fonts. -The idea is that you will only need to interact with the container in your local machine, as if it was a "box" containing the Dialectica copyediting tools, without needing to install each tool separatedly. -In this way, all of the copyeditors can share a single complete environment (i.e., the versions of all of the tools used by the team will be the same), minimizing compiling problems and compatibility issues. -This also allows for issues to be fixed in a centralized manner, as new versions of the environment (with fixed issues) will affect everyone. - -Follow the steps here everytime you want to start working using the Dialectica compilation environment. -This section assumes you have already set up your machine as explained in [@sec-dltc-env-setup]. - -1. First make sure that docker is running. In a terminal, do: -```sh -docker ps -``` -If there are no errors, then docker is running. If not, try the following to start docker: - - - On Windows, open Docker Desktop - - On Mac, in a terminal, do `colima start` - - On Linux, in a terminal, do `sudo service docker start` - - Now wait until docker starts, and do `docker ps` again - -2. Now check if you have the latest version of the image of the compilation environment. Every new release will be announced on the Team News, and they shouldn't happen very often. If a new version has been released, or if you're unsure if you have the last version, in a terminal do the following. For this, you will need the `access token` which you can find in the Institutional Setup page in our Google Drive: -```sh -docker login -u philosophiech -# Paste the access token as the password -docker pull philosophiech/dltc-env:latest -# Wait until the pull is complete, and check with -docker image ls -``` -**NOTE**: terminals often hide the characters when you type in passwords. Just copy and paste the access token when asked for the password and it will work. - - If you downloaded a new image, you need to stop any container created with the old one. For this, go to the root of the git repository (where the docker compose file is) and do -```sh -# On Windows and Linux -docker compose down -# On Mac -docker-compose down -``` - -3. From step 1, if you do have the latest image, and if in the output of `docker ps` you see the name "philosophiech/dltc-env:latest", then the compilation environment is ready to be used - - If not, in a terminal, navigate to the root of the git repository you cloned (where the docker compose file is), and do: -```sh -git pull - -# On Windows and Linux -docker compose up -d -# On Mac -docker-compose up -d -``` -Now if you do `docker ps` you should see the name of the container ("philosophiech/dltc-env:latest"). - -4. Start VSCode, select "Remote Explorer" on the vertical toolbar to the left, select "Dev Containers" on the dropdown menu above, then hover above "compilation-env" and click on the arrow next to it. You can now "Open Folder" and choose "dltc-workhouse", which is the same folder you have in Dropbox. - -All set, you're ready to work. Remember that you can open a terminal inside VSCode (in the menu above: Terminal >> New Terminal), which will give you a terminal *inside* the container. Here you'll find all of the tools you need (pandoc, LaTeX, Lua, quarto, dltc-make, and the fonts). +Note: below, when saying "in a terminal", we mean either +PowerShell on Windows, or your default terminal in Mac or Linux. +All of the commands provided should work in all PowerShell +(Windows), zsh (Mac) and bash (Linux). + + +The association is setting up a standardized compilation +environment for Dialectica. +The environment is encapsulated in a *docker container* and +includes all of the tools needed for the copyediting work, +including pandoc, LaTeX, Quarto, and the fonts. +The idea is that you will only need to interact with the +container in your local machine, as if it was a "box" containing +the Dialectica copyediting tools, without needing to install each +tool separatedly. + +In this way, all of the copyeditors can share a single complete +environment (i.e., the versions of all of the tools used by the +team will be the same), minimizing compiling problems and +compatibility issues. +This also allows for issues to be fixed in a centralized manner, +as new versions of the environment (with fixed issues) will +affect everyone. + +Follow the steps here everytime you want to start working using +the Dialectica compilation environment. +This section assumes you have already set up your machine as +explained in [@sec-dialectica-new-house-outputs]. + +1. First make sure that docker is running. In a terminal, do: + + ```sh + docker ps + ``` + + If there are no errors, then docker is running. If not, try the + following to start docker: + + - On Windows and Mac, open Docker Desktop, and make sure + that the "whale" icon appears in your tray + - On Linux, in a terminal, do `sudo service docker start` + + Wait until docker starts, and do `docker ps` again. + +2. In the output of `docker ps` you should see a container with + the name `dltc-env` running. + + If you opted to stop the container last time you were working, + then you won't see it in the output and you need to start it + up again: + + ```sh + docker start dltc-env + ``` + +3. Start VSCode, select "Remote Explorer" on the vertical + toolbar to the left, select "Dev Containers" on the dropdown + menu above, then hover above "compilation-env" and click on + the arrow next to it. You can now "Open Folder" and choose + "dltc-workhouse", which is the same folder you have in + Dropbox. + +All set, you're ready to work. Remember that you can open a +terminal inside VSCode (in the menu above: Terminal >> New Terminal), which will give you a terminal *inside* the container. Here you'll find all of the tools you need (pandoc, LaTeX, Lua, quarto, dltc-make, and the fonts). diff --git a/chapters/dialectica/61-dialectica-new-house-outputs.qmd b/chapters/dialectica/61-dialectica-new-house-outputs.qmd index 6e8b60a..dcd13af 100644 --- a/chapters/dialectica/61-dialectica-new-house-outputs.qmd +++ b/chapters/dialectica/61-dialectica-new-house-outputs.qmd @@ -2,28 +2,31 @@ The association is setting up a standardized compilation environment for Dialectica. This environment essentially encapsulate all of the tools -needed for the copyediting work, including pandoc, LaTeX, Lua, and +needed for the copyediting work, such as pandoc, LaTeX, and Quarto. ## Setting up your system Dialectica copyediting requires: -- Git, to clone [the repository of the compilation - environment](https://github.com/Philosophie-ch/dltc-compilation-env) - Docker, to run a container containing the actual environment -- VSCode, to connect to and use the container +- Git, to clone [the repository of the script to download and start the compilation environment](https://github.com/Philosophie-ch/dltc-env) +- Recommended: VSCode, to comfortably connect and use the environment + to edit articles Briefly put, to set up, you need to install git and docker, and then be -able to connect to a running container using the VSCode extension "Dev -Containers". How to do this up will depend on your specific Operaitng -System. If you know how to do this on your own, just skip the steps -below and go chapter 3. Note that VSCode replaces RStudio as a more -modern general text editor, better suited to interact with modern -software tools (such as docker) and languages other than R (such as -Markdown, LaTeX, and HTML). - -For any problem not covered here, please contact Luis Bordo at +able to connect to a running container. In this guide, we'll use VSCode +as it makes it very easy to work inside docker containers, but you're free +to work in a different editor and use the container directly from your +terminal if you wish. + +How to setup will depend on your specific Operating System. If you know how +to install and configure git, docker and VSCode on your own, just skip this +section and go chapter 3. Note that in this guide, VSCode replaces RStudio +as an alternative better suited to interact with modern software tools (such +as docker) and languages other than R (such as Markdown, LaTeX, and HTML). + +For guidance or any problem not covered here, please contact Luis Bordo at `luis.bordo@philosophie.ch`. ### Installing git, docker, VSCode @@ -38,33 +41,40 @@ Here we will install and set up Docker, Git, and VSCode in your machine. 2. Check that git is working in PowerShell. If you get no errors with the command below, then git is working correctly: -``` powershell -git --version -``` + ``` powershell + git --version + ``` 3. Download, install, and open [Docker - Desktop](https://www.docker.com/products/docker-desktop/) - 1. When installing Docker, choose the option to use WSL 2 + Desktop](https://www.docker.com/products/docker-desktop/). + When installing Docker, choose the option to use WSL 2. + 4. Open PowerShell (you have it installed by default) and check that you have `wsl` version 2 or above with -``` powershell -wsl --version -``` + ``` powershell + wsl --version + ``` - If you don't, do `wsl --install`, wait, and do again `wsl --version` - If you still don't have wsl version 2 or above, go to the Troubleshooting section below 5. Check that Docker is configured to run with WSL 2: open Docker - Desktop, go to Settings, and mark the checkbox for using WSL 2 if - it's not marked already + Desktop, go to Settings, and mark the checkbox for using WSL 2 + if it's not marked already. + + Additionally, in the settings, increase the CPU and memory + limits of the containers to be at a minimum of 3/4 of your + machine's resources. For example, if you have an 8 core CPU and + 16 GB of RAM, you could set the limits to 7 cores and 14 GB of + RAM. 6. Now, in PowerShell, check that docker is working with: -``` powershell -docker run hello-world -``` + ```powershell + docker run hello-world + ``` If you don't get any errors, then docker is working in your machine @@ -74,51 +84,55 @@ If you don't get any errors, then docker is working in your machine 1. Install [brew](https://brew.sh/) -- For this, usually it's a single command to execute in a terminal; - just follow the instructions in the page +- For this, usually it's a single command to execute in a + terminal; just follow the instructions in the page 2. Install `git` using brew. In a terminal, do: -``` zsh -brew install git -``` - -3. Check that git is working, in a terminal. If you get no errors with - the command below, then git is working correctly: + ``` zsh + brew install git + ``` -``` zsh -git --version -``` +3. Check that git is working, in a terminal. If you get no errors + with the command below, then git is working correctly: -4. Download and install [Docker - Desktop](https://www.docker.com/products/docker-desktop/), make sure - to pick your correct processor (Mac Intel Chip or Mac Apple Chip) + ``` zsh + git --version + ``` -- To check which processor you have, **TODO** +5. Download, install, and configure [Docker + Desktop](https://www.docker.com/products/docker-desktop/). + Make sure to pick your correct processor (Mac Intel Chip or Mac + Apple Chip). + To check which processor you have: -5. Install `colima` using brew. This will allow us to use the docker - engine on its own without relying on Docker Desktop. In a terminal: + First, click on the Apple icon in the top left corner of your + screen. Second, select "About This Mac" from the dropdown menu. + Third, in the window that opens, look for the "Processor" field -``` zsh -brew install colima -echo "export DOCKER_HOST=unix:///$HOME/.colima/docker.sock" >> $HOME/.zsh_profile -colima start -``` + To configure Docker, open "Settings". In the "General" tab, + make sure that the following options are enabled: "VirtioFS", + "Use Virtualization framework", and "Use Rosetta for x86/amd64 + emulation on Apple Silicon". -6. Install `docker-compose` using brew. In a terminal: + Additionally, in the settings, increase the CPU and memory + limits of the containers to be at a minimum of 3/4 of your + machine's resources. For example, if you have an 8 core CPU and + 16 GB of RAM, you could set the limits to 7 cores and 14 GB of + RAM. -``` zsh -brew install docker-compose -``` -7. Check that docker is working, in a terminal. If you get no errors - with the command below, then docker is working correctly: +5. Check that docker is working, in a terminal. In general, + whenever you want to use Docker, you have to start the Docker + application and see that the "whale" icon shows in your system + tray. If you get no errors with the command below, then docker + is working correctly: -``` zsh -docker run hello-world -``` + ``` zsh + docker run hello-world + ``` -8. Install [VSCode](https://code.visualstudio.com/Download) +6. Download and install [VSCode](https://code.visualstudio.com/Download) #### Linux @@ -126,155 +140,150 @@ docker run hello-world - You most likely have it by default already. You can test this by doing `git --version` in a terminal -- If you don't have it, install it using your distribution's package - manager. For example, in Debian and Ubuntu (and Ubuntu-based - distributions), do `sudo apt install git` in a terminal +- If you don't have it, install it using your distribution's + package manager. For example, in Debian and Ubuntu (and their + derivatives), do `sudo apt install git` in a terminal -2. Follow [the official Docker - instructions](https://docs.docker.com/engine/install/#server) to - install Docker Engine in your Linux distribution +2. Follow [the official installation instructions for Docker] + (https://docs.docker.com/engine/install/#server) to + install **Docker Engine** in your Linux distribution - Follow [the post-installation - steps](https://docs.docker.com/engine/install/linux-postinstall/) to + steps](https://docs.docker.com/engine/install/ + linux-postinstall/) to use docker in your terminal without needing to write `sudo` everytime - If you opt out from following these post-installation steps, you - will need to adapt the docker comands in this document (i.e., append - `sudo` to all of them, everytime) + will need to adapt the docker comands in this document (i.e., + append `sudo` to all of them, everytime) -3. Check that docker is working, in a terminal. If you get no errors +3. Check that docker is working, in a terminal. If you get no + errors with the command below, then docker is working correctly: -``` bash -docker run hello-world -``` + ``` bash + docker run hello-world + ``` 4. Install [VSCode](https://code.visualstudio.com/Download) -### Setup: pulling the docker image, cloning the git repository - -**NOTE**: for the moment, the compilation environment will **not** work -on Mac if you have an Apple Silicon chip. This will be fixed soon -enough. For the moment, you can follow this guide to set up what you -need (git, docker, VSCode, and the VSCode extensions). +### Setup: pulling the docker image and starting a container Once you have installed up all of the necessary dependencies (git, -docker, VSCode) and they work in your machine, we proceed as follows. -The terminal commands below should work in any shell in any operating -system (PowerShell in Windows, zsh in Mac, bash in Linux). +docker, VSCode) and they work in your machine, we proceed by +using a script made to automatically download the latest version +of the docker image containing the compilation environment, and +start it. The terminal commands below should work in any shell in +any operating system (PowerShell in Windows, zsh in Mac, bash in +Linux). + +Note that these instructions are the same as the ones in [the +repository's README](https://github.com/Philosophie-ch/dltc-env). +Make sure that you have at least 10 GB of free space in your +machine: + +1. Using a terminal, first clone the git repository where the + start script is: + + ```sh + # cd to your preferred location. For example: + # mkdir ~/gitrepos + # cd ~/gitrepos + git clone https://github.com/Philosophie-ch/dltc-env.git + cd dltc-env + ``` -1. Using a terminal, first login to the dockerhub account of the - association. For this, you will need the `access token` which you - can find in the Institutional Setup in our Google Drive: +2. Now copy the `.env.template` file into `.env` and edit its + contents: -``` sh -docker login -u philosophiech -# Paste the access token as the password -``` + ```sh + cp .env.template .env + ``` -**NOTE**: terminals often hide the characters when you type in -passwords. Just copy and paste the access token when asked for the -password and it will work. + Now open .env with your preferred text editor. You need to set + the values of the following fields: -- For Mac users: if this command fails, try the following quick fix - and then try again: + 2.1 `ARCH`: the architecture of your machine. If you are on a + Mac with an Apple Silicon chip, set this to "arm64". Otherwise, + leave it as is ("amd64", which is for Macs with Intel chips, + Windows, and Linux) -``` sh -mv ~/.docker/config.json ~/.docker/config.json_bkp -``` + 2.2 `DLTC_WORKHOUSE_DIRECTORY`: the full path, on your local + machine, to the 'dltc-workhouse' folder inside Dropbox -- (cont.) Don't do this if you were using Docker before outside of the - association. There's a cleaner (but a bit longer) fix, at the - section "solution 3" of [this - article](https://sparkbyexamples.com/docker/docker-error-storing-credentials-err-exec-docker-credential-desktop-executable-file-not-found-in-path-out/) + 2.3 `DOCKERHUB_TOKEN`: the **login token** (not the "password") + for the dockerhub account. You can find it in the + "Institutional set-up" page in our Google Drive -2. Now you need to pull the latest image that contains the Dialectica - compilation environment: + **NOTE**: you can navigate with your usual file explorer to the + "dltc-env" folder, which will be located where you cloned it in + step 1. The `.env` file is a hidden file, so you would need to + enable viewing hidden files to see it. -``` sh -docker pull philosophiech/dltc-env:latest -``` +3. Now you can execute the start script: -**NOTE**: this may take a while, as the image is quite heavy (\~15GB). + ```sh + # On Linux and Mac + ./dltc-env-start.sh -3. While you wait for the pull to finish, using a terminal, go to - somewhere in your file system and use `git` to clone the Dialectica - compilation environment repository. It is recommended to create a - 'gitrepos' folder in your home folder, so you don't need to remember - where you put the git repository everytime. The instructions that - follow later will assume that you did so. In a terminal, do: - -``` sh -# First, navigate to your home folder -cd ~ -# Second, create a folder in which you'll put git repositories -mkdir gitrepos -cd gitrepos -# Third, clone the git repository containing the source code of the compilation environment -git clone https://github.com/Philosophie-ch/dltc-compilation-env.git -# This will creat a folder called 'dltc-compilation-env'. This folder is the *root* of the repository -cd dltc-compilation-env -``` + # On Windows + .\dltc-env-start.ps1 + ``` -4. At the root of the repository, follow the instructions of the - README.md file there to set up an `.env` file in your local machine. - You can either open this README file from your file explorer, or - from the terminal directly doing `cat README.md`. You will need to - create a .env file by copying `.env.template`, and then modifying it - with your preferred text editor: + The first time you do this it will take a while as it needs to + download the image, which contains a full LaTeX installation. + This will not happen often, but you will also need to execute + this script any time there is an update to the compilation + environment. -``` sh -cp .env.template .env -cat README.md -# Do the necessary modifications explained in README.md and save the .env file -``` + **OPTIONAL**. Whenever you finish working on your copyediting + tasks, you can stop the container containing the compilation + environment. To do this, execute this on a terminal: -5. Once you have set up your `.env` file, you're ready to use the - docker compose file (also at the root of the repository) to start a - container. + ```sh + docker stop dltc-env + ``` -``` bash -# On Windows and Linux -docker compose up -d -# On Mac -docker-compose up -d -``` + And to use the container again: -We do this because we cannot directly use docker images on their own, -first we need to start a container from them. After this step, you're -ready to start using the new container you created from the image you -pulled from dockerhub. + ```sh + docker start dltc-env + ``` -There are many ways to use a running container, but for our puroses, the -easiest is to use VSCode. +After this step, you'ready to start using the new container created +from the docker image that the start script pulled from dockerhub. +There are many ways to use a running container, but for our +purposes, the easiest is to use VSCode. ### Setup: VSCode -While not strictly mandatory, it is highly recommended to replace -RStudio with VSCode for the copyediting work. VSCode is a modern, -general text editor suited for all tasks programming and writing. It has -support for state-of-the-art software tools such as Docker, and through -its vast market of extensions, provides better support for Markdown, -LaTeX, and HTML than RStudio (which is designed to work with the R -programming language). +While not strictly mandatory, it is highly recommended to use +VSCode for the copyediting work. VSCode is a modern, general text +editor suited for all tasks programming and writing. It has support +for state-of-the-art software tools such as Docker, and through its +vast market of extensions, provides great support for Markdown, +LaTeX, HTML, and Quarto. It is language agnostic and lightweight, +not needing any specific programming language dependencies. For this subsection, it is recommended that you create a -[GitHub](https://github.com/) account, and then connect to it in VSCode. -So, after creating your account, open VSCode. +[GitHub](https://github.com/) account, and then connect to it in +VSCode. So, after creating your account, open VSCode: -1. Now connect VSCode to your GitHub account. To do this, look on the - vertical toolbar to the left and down for 'Accounts', and connect to - your GitHub account. Then, clicking again on 'Accounts', enable both - 'Settings Sync' and 'Turn on Cloud Changes'. This will synchronize - your VSCode settings in any device you connect it to your account. +1. Connect VSCode to your GitHub account. To do this, look on the + vertical toolbar to the left and down for 'Accounts', and + connect to your GitHub account. Then, clicking again on + 'Accounts', enable both 'Settings Sync' and 'Turn on Cloud + Changes'. This will synchronize your VSCode settings in any + device you connect it to your account. - Recommended: click on the cogwheel icon at the bottom of the vertical toolbar on the left, and go to "Settings". Look on the - search bar for "telemetry", and set the "Telemetry Level" to "off". - We don't need Microsoft spying (more than it already does) on us. + search bar for "telemetry", and set the "Telemetry Level" to + "off". We don't need Microsoft spying (more than it already + does) on us. -2. Then, it is recommended that you create a 'profile' to manage the - extensions you need for copyediting. +2. Then, it is recommended that you create a 'profile' to manage + the extensions you need for copyediting. - In the vertical toolbar to the left, below 'accounts', click on Settings \>\> Profiles \>\> Create profile... @@ -299,7 +308,7 @@ Other recommended extensions are: - GitHub Copilot (by GitHub) - GitHub Copilot Chat (by GitHub) -To use the last tool, you need a GitHub pro account. If you have a +To use the last two tool, you need a GitHub pro account. If you have a university student account and email, [you can be granted a pro account for free](https://education.github.com/pack). Copilot is an AI assistant that can help you code in general, including help you with Markdown and @@ -323,15 +332,15 @@ extensions are installed *inside* the container (in "Extensions"). (looks like a computer screen). At the top, there will be a drop-down menu in which you can select "Dev Containers". -6. You will now see the name "compilation-env dltc-env". If you hover +6. You will now see the name "dltc-env dltc-env". If you hover with the mouse, you'll see an arrow whose name is "Attach in Current Window". Click it, and VSCode will start running inside the container (you can check that by looking at the bottom left of the VSCode window). 7. Now you can work as usual, but inside this container you have all of - the necessary tools available, including a full LaTeX environment - with all possible dependencies, pandoc, and quarto. + the necessary tools available, including a full LaTeX environment, + pandoc, and quarto. In general, be careful with what you do even inside the container. While the container is relatively isolated from your machine, **it is @@ -355,8 +364,8 @@ dltc-make This command essentially replaces the old `make.sh` and `make.bat` scripts, and it's used in exactly the same way. The advantage is that -you don't need to copy the `make` files, just call the command. For -example, you just navigate to the folder where your article for +we don't need to copy the `make` files in every folder. For example, +now we can just navigate to the folder where your article for copyediting is, and then... ``` sh @@ -382,9 +391,12 @@ docker exec -ti --volume="YOUR/PATH/TO/Dropbox/philosophie-ch/dltc-workhouse:/ho If this worked properly, you should see your prompt change to `copyeditor@dltc-env`. Here, you can now navigate to `~/dltc-workhouse`, -where you will find the usual Dropbox files for copyediting. If there's -enough demand, we can install additional tools in the container. Please -contact Luis Bordo at `luis.bordo@philosophie.ch` for any such request. +where you will find the usual Dropbox files for copyediting. + +Note that you can execute the command above in an integrated terminal in +any other editor (such as RStudio). This will give you a shell inside +the container with access to all the tools you need for the copyediting +work. ### Troubleshooting @@ -397,8 +409,8 @@ Solution: this is most likely due to not properly setting your `.env` file. Go to the folder in which you cloned the GitHub repository for the compilation environment, copy the `.env.template` file to a new file called `.env`. Now open this file, and change the value of -"DLTC_WORKHOUSE" to the full path of where the dltc-workhouse folder -(inside Dropbox) is. +"DLTC_WORKHOUSE_DIRECTORY" to the full path of where the +dltc-workhouse folder (inside Dropbox) is. Note that, for Windows, you need to change "\\" for "/" in the path name. That is, if your folder is in "C:\\Users\\...", you must change it @@ -434,11 +446,11 @@ follow the instructions below. to the Tab **TODO** 2. Enable 'wsl version 2'. Open PowerShell as Administrator, and then: -``` powershell -dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart + ``` powershell + dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart -wsl --set-default-version 2 -``` + wsl --set-default-version 2 + ``` - If something goes wrong, follow the instructions given in PowerShell - To check if all of this worked, do `wsl --version` in Powershell @@ -449,7 +461,7 @@ By "Terminal" we mean a command line interface. See Appendix -@sec-terminal-help on how to use it. All file paths are given relative to the base ("root") of Dialectica's -workhouse folder. For instance: +workhouse folder ("dltc-workhouse"). For instance: ``` template/1.1/scripts/make.sh @@ -467,257 +479,14 @@ instead: template\1.1\scripts\make.sh ``` -## Setting up your system - -### Pre-requisites - -You will need the following (2 to 8 Gb disk space): - -- **Pandoc** version 3+. *\~240Mb* - -- A **LaTeX distribution**.[^61-dialectica-new-house-outputs-1] - *\~200Mb (custom) to \~5Gb (full)* - -- **Fonts**: STIX Two, Libertinus (incl. Libertinus Display) and - VenusSBExtended available in `dialectica-workhouse/resources/fonts`. - *\<1Mb* - -- On **MacOS**, Apple's **Command line tools for Xcode**. *\~2.5Gb* - -- (Optional but recommended) **RStudio**, a markdown editor with a - visual mode, a built-in terminal, and the ability to run scripts - that generate HTML / PDF versions of your manuscript. *\~1Gb* - -- (Optional but recommended) on **Windows, latexmk**, a command-line - program we use to generate PDFs. It is part of LaTeX but not always - installed by default. *\~100Mb, if you need to install Perl* - -[^61-dialectica-new-house-outputs-1]: LaTeX is called a 'distribution' - or 'installation' because it's not a single program but a large - collection of programs and 'packages' that work together to generate - PDFs. - -#### How to check what's installed - -To check whether Pandoc, LaTeX and latexmk are installed, you can run -the following on a terminal (see Appendix -@sec-terminal-help on how to -do this). For Pandoc: - -``` bash -pandoc -v -``` - -For LaTeX: - -``` bash -pdflatex -version -``` - -For latexmk: - -``` bash -latexmk -v -``` - -If you get error messages, they are not installed. If you get version -numbers, they are installed. This works on all systems. - -### MacOS only - -**To install Apple's Command Line Tools**. This is necessary even if -you're not going to use the command line your self: it installs the -software needed to run the "scripts" (short instruction files) that -render our outputs. Open the Terminal (in Applications \> Utilities), -type the following and hit Enter: - -``` bash -xcode-select --install -``` - -If you get the error message "command line tools already installed", -it's already installed, you can close the terminal. Otherwise it will -download and install for some time. When it's finished, close the -terminal. - -### Optional: install tools with a package manager - -Package managers are tools to install and update software. Typically -terminal tools [see @sec-terminal-help] but Linux has graphical ones -too. - -- At installation time, they spare you looking up the software's - website, downloading, running the installer. Instead you just run a - simple command like `choco install pandoc` on the terminal and the - manager installs Pandoc for you. -- Later, they allow you to update *all* the software you've installed - with them at once. No need to go back to the websites, download - again etc. You run a command like `choco upgrade all`. -- Less relevant for us: it handles 'dependencies', ie if the software - you're installing needs another, it'll install the latter too. - -For instance on MacOS you'd install LaTeX, Pandoc and RStudio by typing -just one command on the terminal: `brew install mactex pandoc rstudio`. - -- On Linux, there's a package manager pre-installed and you'll - probably know what it is. In "Debian" distributions, Ubuntu - included, it's [APT](https://en.wikipedia.org/wiki/APT_(software)) - (`apt-get install pandoc`). There are graphical user interfaces for - it: Software center in Ubuntu, Synaptic in Linux Mint, and others. - -- On MacOS, install [Homebrew](https://brew.sh). Note: sometimes - you'll see `--cask` in the command (compare `brew install pandoc` vs - `brew install –cask rstudio`). The rule of thumb is that graphical - programs are `--cask`, command line programs aren't. But don't - worry, if you omit `--cask` the installation typically works anyway. - You can formally check whether it's needed by searching the software - on [homebrew](https://formulae.brew.sh)'s depository. - -- On Windows, install [Chocolatey](https://chocolatey.org). Important: - don't forget that it can't be run in the basic CMD terminal but only - in the "Windows Powershell" with administrator privileges. Search it - in the start menu, right-click and chose "Run as administrator". - -If unsure what the package name of some software is you can search it -online (e.g. "Ubuntu package texlive"). It'll probably land you on the -right page of their online package lists: -[debian](https://www.debian.org/distrib/packages#view), -[ubuntu](https://packages.ubuntu.com), -[homebrew](https://formulae.brew.sh), -[chocolatey](https://community.chocolatey.org/packages). - -### Common to all platforms - -#### Pandoc - -Download and install from [Pandoc's -website](https://pandoc.org/installing.html). - -Command line users: run `brew install pandoc` (MacOS, Homebrew), -`choco install pandoc` (Win, Chocolatey) or `apt-get install pandoc` -(APT, Linux) in a terminal. - -#### LaTeX - -Use either [MikTeX](https://miktex.org/download) or -[TexLive](https://tug.org/texlive/) (whose Mac version is called -[MacTeX](https://www.tug.org/mactex/)). - -- For MikTeX: download the installer, launch it. Select "install only - for this user", and for installing packages on the fly, select "Ask - me first". -- For TexLive, non-Mac: download [the network - installer](https://tug.org/texlive/acquire-netinstall.html), launch - it. When/if offered the choice, choose to install "all" or - "everything". This can take \~30 minutes depending on download - speed. -- For TexLive, Mac users: download [the - installer](https://www.tug.org/mactex/). - -MikTeX's advantage is that it downloads any needed packages on the fly, -so it's quicker to install and will get whatever you need. **So be aware -that if you use MikTeX, you first PDFs generation will open a window -asking you to confirm the download of packages and take a long time as -MikTeX download missing pages**. Don't worry, subsequent PDF generations -are much faster. - -TexLive's full install is large (5Gb) and takes \~30 mins but you're -done once and for all---well, for one year, as it is updated yearly. - -Command-line users: - -- Homebrew: `brew install --cask mactex`. Cannot install MikTeX (as of - Jan 2023). MikTeX doesn't need brew anyway, it self-updates. -- Chocolatey: `choco install miktex` or - `choco install texlive --params "'/scheme:full'"`. -- Linux: depends on package managers, e.g. - `sudo apt-get install miktex` or - `sudo apt-get install texlive-full`. However, you might need to add - 'Software sources' to do this: see e.g. the MikTeX webpage. - -#### Fonts - -Dialectica's fonts are located in -`dialectica-workhouse\resources\fonts`. Open a file browser and navigate -to the folder of a desired font (for Stix Two, `STIX Two fonts\OTF`). -Select all the files and, depending on system: - -**To install fonts**, open the Finder and navigate to the folder where -the fonts are located (`dialectica-workhouse/resources/fonts`). Open the -folder of the desired font (for Stix Two, `STIX Two fonts/OTF`). -Double-click each file there (regular, italic, bold, ...), and in the -windows that appear, select "Install font". You can check that the fonts -are installed by opening the Font Book (in the Applications folder, or -Cmd + Space and search for Font Book) and selecting the User tab. - -- (Windows) right-click and select "Install fonts", -- (Mac) Enter or right-click \> Open. Select "Install font" in the - windows that open. You can check that they are installed by opening - the Font Book app. -- (Linux) depends on distribution. On Ubuntu, for instance, - double-click on the font files opens a font viewer with the option - to install. If that doesn't work on your distribution, try an online - search. - -#### RStudio (optional) - -See [RStudio's download page](https://posit.co/downloads/) for -installation instructions. Command line users also install it with -package managers (e.g. `brew install rstudio`). RStudio needs R (a -statistics programming language), so you might need to install it too -(e.g. `brew install r rstudio`). - -When installed, note that RStudio includes: - -- a *file browser* on the left -- a *terminal* at the bottom, under the 'Terminal' tab. (The 'Console' - is something else). -- when editing markdown files, the `Source` and `Visual` tabs at the - top left of the editor. These allows you to edit files in visual - mode rather than markdown. Limitation: the visual mode can't be used - if the manuscript contains "numbered examples lists". -- when editing markdown files, an 'Outline' panel on the right side of - the editor. Useful to navigate a manuscript. - -RStudio might be intimidating at first: it's not a word processor but a -"development environment" for the statistics programming language R. -It's not just used to write programs, however, but also write documents -that embed compuations: a webpage with a graph that is daily updated, or -a scientific article that includes algorithms and data to reproduce its -results. So don't worry: you will mostly be using its markdown editor -here, which is powerful but simple. Some of the development features are -handy too, like the file browser and the ability to run scripts to -generate our outputs. - ## Prepare an article or issue folder -You'll need to add a few files to your article working folder to be able -to generate outputs. - -- A 'maker script', i.e. a mini program that tells the computer how to - generate your outputs.\ - This is the file titled `make.sh`. +You'll need to add the following file to your article working folder +to be able to generate outputs. - A *master file*, which contains issue-level metadata needed to generate your article outputs. -### Ensure your folder contains the maker script - -Check whether your working article folder contains a file title -`make.sh`. If it does, you're good. - -If it doesn't, you should make a copy of it in your work article folder. -You can find it in `template/X.X/copyeditors-scripts`, where `X.X` -stands for the most recent template version. (That is the highest you -find, e.g. 1.2.) But this file is the same for each article and issue -that uses the *same* version of the *Dialectica* template, so you can -also copy it from other *article* folder in the same year. - -Beware of copying `make.sh` from an *article* folder, not the *issue* -folder that contains it. (Article-folders `make.sh` tell the computer: -go three folder up and find the template engine; issue-folders `make.sh` -tell it: go *two* folders up and find the template engine; that's why -issue maker files don't work in article folders and conversely.) - ### Create a master file Copy a `master.md` file into your article folder. You can take one from @@ -762,53 +531,32 @@ remove (article master file) the subfolders names as required. ## Generate outputs -### With RStudio on Windows - -On Windows, you might be able to generate outputs from RStudio directly -without running a command. If that fails, skip to the next sections and -run a command instead. - -**Setup.** In RStudio, open your article's project and go to the menu -Build \> Configure Build Tools. Enter the following choices: - -- Project build tools: "Makefile" -- Makefile directory: leave as default (Project Root). -- Additional argument: empty to generate html, or any of the rendering - commands detailed below [@sec-house-outputs-rendering-commands]. - -**Generate**. Once that is done, go to Build \> Build all (or use -Shift-Ctrl + B) to generate the desired output. - -Go back to Build \> Configure Build Tools if you want to change the -format you're generating, e.g. enter `offpdf —proof` in Additional -argument to generate a proof PDF. - ### Run a command in the terminal -In all systems, you can generate outputs by running the `sh make.sh` -command in a terminal. +You can generate outputs by running the `dltc-make` command in a +terminal inside the container containing the compilation environment. -- In RStudio, if you've created a project for your article, it's best - to use the Terminal within RStudio itself. See Tools \> Terminal. - This terminal will be "located in" the project's folder, so you can - just take `sh make.sh` to generate a html output. +- In VSCode (or RStudio), if you've created a project for your + article, it's best to use the integrated terminal (in the + "Terminal" menu in VSCode, "Tools" in RStudio). + Make sure that you are "located in" the project's folder by + executing `pwd`. If the path doesn't correspond to your project's, + then navigate with `cd` to where your project is. - If you're using a separate terminal application, you'll need to - "navigate" to the folder where your article is. See - @sec-terminal-help for help. + navigate with `cd` to the folder where your article is. + +See @sec-terminal-help for help. ### Short rendering commands {#sec-house-outputs-rendering-commands} Rendering commands can be executed in a *article*'s folder or in an -*issue* folder. All these commmands must be added to `sh make.sh`, e.g.: +*issue* folder. All these commmands must be added to `dltc-make`, e.g.: ``` bash -sh make.sh offprints +dltc-make offprints ``` -or used in the "additional argument" of RStudio's configure build tools -in Windows, as explained above. - Single-article outputs will be named after the source file, e.g. `smith_j-2020.pdf`. Issue outputs will be named after the issue DOI, e.g. `dial.v74.i1.pdf` or `dial.v75.i2-book.pdf`. @@ -886,8 +634,8 @@ Proof mode space): : ``` bash - sh make.sh off2 --proof - sh make.sh off3pdf -p + dltc-make off2 --proof + dltc-make off3pdf -p ``` : This only affects PDF output. @@ -899,12 +647,11 @@ Verbose or quiet like so: ``` bash - sh make.sh off2pdf -v 2> out.log + dltc-make off2pdf -v 2> out.log ``` The `2>` tells the computer to "redirect" the error/information - output to a file named `out.log`. This works in Windows and Linux / - MacOS terminals. + output to a file named `out.log`. You can make the output quieter with `--quiet` or `-q`. Though certain programs executed during the rendering process may still @@ -919,7 +666,7 @@ Single letter options can be combined: `-pv` is short for Rendering commands can also be given in key-value form: ``` bash -sh make.sh mode=offprint chapter=3 format=pdf +dltc-make mode=offprint chapter=3 format=pdf ``` - `mode` includes "offprint" aka "off", "vol" aka "issue", "bare" , @@ -934,7 +681,7 @@ The advantage is that you can specify multiple modes and formats separated by commas: ``` -sh make.sh mode=off,refs chapter=3,4,5 +dltc-make mode=off,refs chapter=3,4,5 ``` Rendering options like `--proof` can be combined with long rendering @@ -950,5 +697,3 @@ the "filters" we use to format outputs. PDF is best for the latter typesetting stages when you need to check that the fine-grained outputs look right, that advanced LaTeX formulas or images work correctly, that there is no awkward page break and so on. - -## {#sec-dltc-env-setup}