30 Dialectica new house style outputs

Dialectica outputs are compiled: from a markdown manuscript, image files, bibliography files and Dialectica’s template (itself a collection of files), it creates PDFs and HTML outputs. The compilation environment is the collection of software tools to do this: Pandoc, LaTeX, Quarto, and a few others. Instead of asking everybody to install these tools on their various Linux/Windows/Mac machines, and asking everybody to update them to the same version, we are using a “containerized” environment that is the same for all, no matter which machine you have.

Let’s briefly explain how this works, including key terms. In the old days, computers came with an ‘installation disk/DVD/USB key’ that had your computer system (Windows, Mac, Linux) and perhaps some basic software (a text editor). Using the disk/DVD/USB key, you set up the system on the machine, and then used the computer. And in the old days, you’d give each copyeditor a computer of the same model, with the same installation disk/DVD/USB key. We’re doing to do exactly that, except that our company computer is virtual and will be simulated by your own computer. The Docker application is the software that enables to do that.

The Docker application works with images and containers. We’ll have:

an image of Dialectica’s compilation environment. This is like the old disk/DVD/USB, but in one file that’ll be downloaded from the internet. It contains all the software needed to create Dialectica outputs (Pandoc, LaTeX, etc.). It’s called an “image” in the sense that when we clone a hard drive’s contents we call the result an “image” of the hard drive. For Dialectica, the image will be named philosophie-ch/dltc-env and include a Linux system with the tools.
a container in which the image is installed. The container is like a small company computer, except that instead of being a real machine, the Docker app simulates it on your own computer. That is, the Docker app takes reserves some of your system’s resources (the processor, some memory, some temporary disk space), and simulates a mini computer with them, called a “container”. For Dialectica, your container will be named dltc-env and be a virtual Linux machine with Pandoc, LaTeX and other tools installed.

Once your container (virtual company computer) is created, it can be started or stopped. This is just like turning the company computer on and off.

The container (virtual company computer) is isolated from your actual system and filesystem, so it doesn’t change anything in your system, it doesn’t crash your system if it crashes, and you won’t see its internal files on your file browser.

There is one exception though: the container will have access to the dialectica workshouse folder on your own filesystem. That allows it to read manuscript markdown files, bibliography files, etc. in order to generate outputs, and then to write the generated outputs (PDF or HTML files) in your filesystem so you can view them.

Moreover, in the advanced text editor we’ll use (Visual Studio Code aka VSCode), you’ll be able to run a Terminal on the container (virtual company machine) itself. This allows you to tell the container to generate outputs.

30.1 Setting up your system

Dialectica copyediting requires:

Docker, to run a container containing the actual environment
Git, to clone the repository of the script to download and start the compilation environment
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. 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.

30.1.1 Installing git, docker, VSCode

The following instructions need to be executed only once per machine. Here we will install and set up Docker, Git, and VSCode in your machine.

30.1.1.1 Windows

Download and install git
Check that git is working in PowerShell. If you get no errors with the command below, then git is working correctly:
```
git --version
```
Download, install, and open Docker Desktop. When installing Docker, choose the option to use WSL 2.

When you install Docker, you can use the recommended settings and select “Continue without signing in”.
Open PowerShell (you have it installed by default) and check that you have wsl version 2 or above with
```
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

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.

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.
Now, in PowerShell, check that docker is working with:
```
docker run hello-world
```

If you don’t get any errors, then docker is working in your machine

Install VSCode

30.1.1.2 Mac

Install brew

For this, usually it’s a single command to execute in a terminal; just follow the instructions in the page

Install git using brew. In a terminal, do:
```
brew install git
```
Check that git is working, in a terminal. If you get no errors with the command below, then git is working correctly:
```
git --version
```
Download and install Docker Desktop. Make sure to pick your correct processor (Mac Intel Chip or Mac Apple Chip). ¹

When you install Docker, you can use the recommended settings and select “Continue without signing in”.
Configure Docker. Launch the Docker application and open “Settings”.
1. In the “General” tab, check that the following options are enabled: “VirtioFS”, “Use Virtualization framework”, and “Use Rosetta for x86/amd64 emulation on Apple Silicon”. (These settings may not appear on Intel Chip macs; if they don’t ignore this step.)
2. 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.
Check that docker is working. In a terminal, run:
```
docker run hello-world
```
If you get no errors, Docker is working correctly. If you do, try running Docker (in Applications). Docker’s whale icon should appear in your system icon bar (i.e. alongside icons for Wifi, Bluetooth etc.).
Download and install VSCode

30.1.1.3 Linux

Install git

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 their derivatives), do sudo apt install git in a terminal

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 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)

You can use Docker without siging in.

Check that docker is working, in a terminal. If you get no errors with the command below, then docker is working correctly:
```
docker run hello-world
```
Install VSCode

30.1.2 Setup: pulling the docker image and starting a container

Once you have the necessary dependencies (git, docker, VSCode) are up and running on 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. Make sure that you have at least 10 GB of free space in your machine:

Using a terminal, first clone the git repository where the start script is:

# cd to your preferred location. For example:
# mkdir ~/gitrepos
# cd ~/gitrepos
git clone https://github.com/Philosophie-ch/dltc-env
cd dltc-env

Now copy the .env.template file into .env and edit its contents:
```
cp .env.template .env
code .env
```
This will open the file .env in VSCode. In VSCode you may see a message “Git repositories were found… do you want to open them?”, you can close it or ignore it.

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 (namely, within your Github folder). If you use the file explorer, you will however not immediately see the .env. To see it in the file explorer, you need to enable viewing hidden files. The way to do this depends on which system you are using. On the other hand, if you are viewing the contents of dltc-env in the VSCode text editor (for isntance, if you typed the code .env command above), the file explorer within VSCode will show you the .env files. If you are viewing the files that way, you do not need to enable viewing hidden files.

The contents of .env look like this:
```
ARCH="amd64"  # put "arm64" if on an Apple Silicon Mac (M1, M2, etc.; non-Intel)
DLTC_WORKHOUSE_DIRECTORY="/YOUR/PATH/TO/Dropbox/philosophie-ch/dltc-workhouse"
DOCKERHUB_TOKEN="token_in_the_institutional_setup_page"
```
This is a key-value file. ARCH, DLTC_WORKHOUSE_DIRECTORY, DOCKERHUB_TOKEN are keys, and the strings within quotes, amd64, /YOUR/PATH..., “token_in_the…” are their values. You need to put the values appropriate to your local system. You should set the values as follows, and save the file:

2.1 ARCH: the “architecture” of your machine. If you are on a Windows machine, a Linux machine, or a Mac with Intel chips (not Apple Silicon), leave this to amd64. If you have a Mac with Apple Silicon chip, set it to arm64.

2.2 DLTC_WORKHOUSE_DIRECTORY: the full path, on your local machine, to the dltc-workhouse folder inside Dropbox. Here’s one way to get it. Open a Terminal. Navigate (using cdcommands ) to that folder, and run the command pwd (‘present working directory’). It will display the full path to that folder, e.g. /Users/janedoe/Dropbox/Philosophie-ch/dltc-workhouse/ on a Mac.

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, “Passwords” section.

Do not forget to save .env when you have done this.
Now you can execute the start script. From the folder dltc-env, in Linux and Mac run:
```
./dltc-env-start.sh
```
(Equivalently: sh dltc-env-start.sh. When a file is a script, for safety reasons it cannot be launched just by typing the file name, you have to either launch the shell script executor sh followed by the name of the script, or, you have to precede the script by its path. Since here, the script dltc-env-start.sh is in your current folder, the path to it is: ./. The dot is the current folder, and the slash separates the folder name, ., from the script file name, dltc-env-start.sh. This is why the full path is ./dltc-env-start.sh.)

On Windows, run:
```
.\dltc-env-start.ps1
```
(The idea is as before, . is the current folder and \ the (Windows-style) separator. There is probably an equivalent such as ps dltc-env-start.ps1 but I don’t know it.)

The last command downloads an “image” of Dialectica’s “compilation environment” (a mini Linux system containing Pandoc, LaTeX and other utilities), and it runs this image in a mini-machine simulated by your computer called a Docker “container”. The first time you execute this command it will take a while as it needs to download the image, which is about 5-10Gb. But this will only happen the first time it’s used, and where there are updates of the images online.

If the compilation environment starts correctly, you will see a message like the following:

Logged in to Docker Hub as philosophiech

latest-arm64: Pulling from philosophiech/dltc-env
ce9ebea987c2: Pull complete 
42ca1070b43f: Pull complete 
3d93737c6ee5: Pull complete 
...
61e48dddaaa9: Pull complete 
Digest: sha256:bc24161a6b997899ce3881246ee17a4aeae03e6885ab77e1b18cdb2092dc2248
Status: Downloaded newer image for philosophiech/dltc-env:latest-arm64
docker.io/philosophiech/dltc-env:latest-arm64

Successfully pulled latest dltc-env image for arm64; now logged out of Docker Hub

Starting dltc-env container, please wait...
[+] Running 1/2
⠴ Network dltc-env_default  Created                                     0.5s 
✔ Container dltc-env        Started                                     0.5s 

...success!

Careful that the last line success may display even if there was an error! If you encounter one of the errors below, try to fix it and run the script again.

Errors you may encounter when running the dltc-env-start script:

The error message: “dltc-env-start: No such file or directory”. Your terminal is not located in the dltc-env folder, itself in your GitHub repositories folder. Use cd commands to change its location to the dltc-env folder.
The error message: “DLTC_WORKHOUSE_DIRECTORY does not exist.”

If you get this error there must be something wrong with the path you put as the value of DLTC_WORKHOUSE_DIRECTORY in the .env file. If you’re not sure what’s wrong, try the steps of finding out the full path of Dialectica’s workhouse folder before, and check you have saved .env.
The following error:
```
! dltc-env The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested 0.0s 
```
This is because the value for ARCH in the .env file is wrong, so the script has downloaded an image that cannot be ran on your machine. Double-check it. Once you have fixed it, you should (1) delete the container and its image and then (2) re-run the script. To delete the container and its image: open the Docker app, go the Containers tab (box-like icon on the left tab), look if the list contains an item named dltc-env, and click the Trash icon next to it; then go to the Images tab (empty cube icon on the left tab), look whether it contains an item named philosphie-ch/dtlc-env and click the Trash icon next to it. If these items don’t show up, you have nothing to delete. Once you’ve deleted any container/image remaining, you can start the script again.

An error like the following:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

Successfully pulled latest dltc-env image for arm64; now logged out of Docker Hub

Starting dltc-env container, please wait...
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

...success!

(Note that the “success” messages are incorrect here.) This “Cannot connect to the Docker daemon error” is because Docker (the application that runs the compilation environment ‘image’ in a ‘container’) is not started. Launch the Docker application and try running the dltc-env-start script again.

An error message like the following:

MacBook-Air:dltc-env sannahirvonen$ ./dltc-env-start.sh
Logged in to Docker Hub as philosophiech

latest-amd64: Pulling from philosophiech/dltc-env
29202e855b20: Pull complete 
04c6e9d3a90b: Pull complete 
...
write /var/lib/docker/tmp/GetImageBlob1011053309: input/output error

Successfully pulled latest dltc-env image for amd64; now logged out of Docker Hub

Starting dltc-env container, please wait...
[+] Running 1/1
✘ Container dltc-env  Error while Removing                               10.3s 
Error response from daemon: container 4ccdac99d0fb7b215bebca79fc1b752d14a1e78575efa547b9fd46a1a4dac282: driver "overlay2" failed to remove root filesystem: unlinkat /var/lib/docker/overlay2/4d90b7b3fe97f8cb8470efce26625765b4dcc6699b73ee56d041859dc9071f9b: read-only file system
[+] Running 1/1
✘ dltc-env Error                                                          0.1s 
Error response from daemon: error creating temporary lease: write /var/lib/desktop-containerd/daemon/io.containerd.metadata.v1.bolt/meta.db: input/output error: unknown

...success!

We don’t know why this happens. But if it does, try deleting the container and image and restarting the script. To do this, open Docker app. Go the Containers tab (box-like icon on the left tab), look if the list contains an item named dltc-env, and click the Trash icon next to it; then go to the Images tab (empty cube icon on the left tab), look whether it contains an item named philosphie-ch/dtlc-env and click the Trash icon next to it. If these items don’t show up, you have nothing to delete. Once you’ve deleted any container/image remaining, you can start the script again.

An error message like the following:
```
Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: error mounting "/host_mnt/Users/janedoe/.gitconfig" to rootfs at "/home/copyeditor/.gitconfig": mount /host_mnt/Users/janedoe/.gitconfig:/home/copyeditor/.gitconfig (via /proc/self/fd/7), flags: 0x5000: not a directory: unknown: Are you trying to mount a directory onto a file (or vice-versa)? Check if the specified host path exists and is the expected type
```
This is because Git is badly configured. More precisely, you have a .gitconfig folder at the base of your user directory, while .gitconfig should be a file. (It won’t show up in the browser because ‘.xxx’ items are hidden, but you can see it with the option ‘show hidden files’ or by running the ls command in a terminal located at the root of your user directory). We have encoutered this error and we don’t know why it happens.

We solved it by removing the folder and creating an empty .gitconfig file. On Linux/MacOS, remove the folder with:
```
rm -r ~/.gitconfig
```
And create an empty .gitconfig file with:
```
touch ~/.gitconfig
```

30.1.3 Starting and stopping the compilation environment container

The compilation environment that produces output runs in a ‘Docker container’ that can be started or stopped. It’ll stop if you close Docker or restart your computer. Optionally, you can stop the container when you finish working on your copyediting tasks and restart it when you start again. (If you don’t stop it, it won’t slow down your computer in any noticeable way but it’ll use a bit of memory but shouldn’t slow down your computer in a noticeable way.)

Starting and stopping containers can be done from the terminal or from the Docker app. From the terminal, use:

docker stop dltc-env

to stop it, and

docker start dltc-env

to start it again.

From the Docker app, go to Containers tab: a box icon on the top left. (Don’t forget to close the Settings if you haven’t.) In the list of containers you should see one called dltc-env. It’s greyed out if stopped, green if started. In the Actions column, there’s a play or stop icon you can use to start or stop it.

30.1.4 Setup: VSCode

While not strictly mandatory, it is highly recommended to use Visual Studio Code (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 lightweight, not tied to any specific programming or writing language, and doesn’t need specific programming languages installed.

For this subsection, it is recommended that you create a GitHub account, and then connect to it in VSCode.²

Create an account on GitHub.

Now set up VSCode. VSCode has a “profile” functionality: you can create distinct profiles, where each profile has its own set of tools (“extensions”). Initially, there’s only the “default” profile. We recommend you create a specific “dialectica copyeditor” profile.

Create a ‘profile’ to manage the extensions you need for copyediting.
In the vertical toolbar to the left, click on the cogwheel (Settings) and choose Profiles > Create profile…
Give a name to your profile e.g., “dltc-copyediting” and use the default options

You can switch profiles by going to the Settings cogwheel > Profiles.

Next, we install useful Extensions in this profile.

Install the “Dev Containers” extension (by Microsoft). On the left toolbar, click on “Extensions” (the cube pile), and search for “Dev Containers”. It should show up with an “Install” button. Install it.
Install the “Remote Explorer” extension (by Microsoft). On the left toolbar, click on “Extensions” (the cube pile), search for “Remote Explorer” and install it. (If you don’t see an install button, that means it’s already been automatically installed at the previous step; you can move on to the next step.)
Connect VSCode to the Dialectica container. This requires that the container is started (see above). On the left bar, you should see a Remote Explorer tab (a screen with the >< logo). Click on it, it display a navigation column on the left. You should find a “Dev Containers” section there, and within it, the dtlc-env container name. (If you don’t already see the name, click on “Dev Containers” to expand it. If after that you still don’t see it, make sure the container is started.) Hover on the dltc-env and click on the right arrow just next to it (“Attach in Current Window”). You get a warning that attaching to a container may execute arbitrary code: accept (“Got it”).

This has ‘connected’ the present VSCode window to the container (i.e., the virtual company computer that runs Dialectica’s compilation environment to generate output).

Finally, install some extensions that are useful for copyediting in markdown and LaTeX and Quarto, and to preview outputs.

On the left toolbar, click “Extensions”. Search and install all of the following:

LaTeX Workshop (by James Yu)
Markdown All in One (by Yu Zhang)
Quarto (by Quarto)
HTML Preview (by George Oliveira)

Other recommended extensions are:

Error Lens (by Alexander)

30.1.5 Optional extra setup: connect VSCode to GitHub

Optionally, connect VSCode to GitHub.

Install “GitHub Pull Requests and Issues” extension. On the left toolbar, click on Extensions, and search and install the “GitHub Pull Requests and Issues” extension.
Connect to your GitHub account. On the left toolbar, look down for ‘Accounts’, and connect to your GitHub account. (If you’re on a public Wifi this may not work; use a private one or your mobile hotspot.)
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. Tell VSCode not to report your activity to Microsoft (they spy us enough already). Click on the cogwheel icon at the bottom of the vertical toolbar on the left, and go to “Settings”. On the page that appears, use the search bar at the top to search for “telemetry”, and set the “Telemetry Level” to “off”.

If you have a GitHub pro account, we also recommend:

GitHub Copilot (by GitHub)
GitHub Copilot Chat (by GitHub)

If you have a university student account and email, you can be granted a GitHub pro account for free. Copilot is an AI assistant that can help you code in general, including help you with Markdown and LaTeX, both directly in VSCode when you edit files and in a chat button provided by the Chat extension (that will appear in the left toolbar).

30.1.6 Checking that your setup is right

Whenever you start VSCode:

Make sure that you’re using the profile you created. If you did create a specific profile for dialectica copyediting, you should see an acronym for it (e.g. “DL”) on the Settings cogwheel at the bottom left. If you didn’t and are using the default profile, you’re fine.
Make sure that the Extensions installed above are installed “inside” the container. This explained below.
If you have connected VSCode to GitHub, check that you’re connected to your GitHub account (in “Accounts”), and that you’re using the profile you created (in “Settings >> Profiles”).

To ensure that VSCode Extensions are installed “inside” the container:

Click the “Extensions” button of the left toolbar. Clear any search in the search bar. Now, you will see a “Local - Installed” section that lists the extensions we’ve installed. (Note that this section is collapsible: if there’s a > next to “Local Installed”, click on it to expand.) You might see that some extensions bear a blue label “Install in container”. If they do, click on the label to install these extensions “within” the container. If none shows that label, you’re fine. Beware that you might need to scroll down to review all extensions in the “Local - Installed” section.
Check that your current window is “attached” to Dialectica’s container. The bottom of VSCode’s window is a status bar. To its left there is a >< icon that tells what the window is connected to. If it shows >< Container philosophiech/dltc-env..., your window is attached to Dialectica’s container (the virutal company computer that will produce outputs). If it’s just a green >< symbol, it’s not attached. You need to attach it as follows:
- Click the “Remote Explorer” (screen with the >< logo) on the left toolbar. It opens a navigation column. At the top you should see a “Dev Containers” section. (It’s collapsible: if you see the > symbol left of “Dev Containers”, click it to expand.) You should see the container named dtlc-env with a green badge. If there’s no green badge on it, the Dialectica container isn’t connected. Click the right arrow right next to dltc-env (it says “Attach in current window” if you hover the mouse pointer over it for a few seconds).
- If all goes well, after the window reopens you should see >< Container philosophiech/dltc-env... in the bottom status bar, on the left.

30.1.7 Working ‘inside’ a container

Once you attached a VSCode window in a container, you’re working inside that container. What does that mean? In VSCode you can run commands on a terminal. Normally, terminal commands are run on your own system. But when a VSCode window is attached to a container, its terminal runs commands on that container—that is, on the virtual company computer we’ve just created.

Things you do inside the container stay in the container, so even if you broke it nothing bad would happen. The one exception is the dltc-workhouse folder. Within the container, there’s a user home folder than contains a folder called dltc-workhouse folder. That folder is the dialectica folder of your system. It’s shared between your own system and the container. You do not want to damage or delete them. Beware in particular of rm (remove) commands, which deletes files and folders without seeking confirmation.

Now, let’s view the dltc-workhouse folder in VSCode. On the leftbar select the Explorer icon (a documents icon). You will see an “Open folder” button. It opens a search bar at the top, which should already list some options (namely, folders in the container), including dltc-workhouse. Click on that; the window will reopen and now the Explorer on the left should show you the files within the dltc-workhouse folder.

Then, let’s try the terminal within VSCode. If you don’t already see the Terminal at the bottom of your VSCode window, go to the menu Terminal > New Terminal. It’ll create one at the bottom. You’ll see a line:

copyeditor@dltc-env:~/dltc-workhouse$

This is a “prompt”: it waits for your to run a command. It consists of three parts: username, here copyeditor (that’s your identifier within the container), current location, here ~/dltc-workhouse and the $ sign (meaning ‘waiting for your command!’). What is the current location? A terminal is always ‘located’ in some folder, this is the place ‘where’ command are run. Here your location is within the container. The ~ is an abbreviation for the user’s home folder; here it is the home folder of the user copyeditor within the container.

Note: your container is a virtual Linux machine. So, it’s terminal uses Linux / MacOS terminal commands (cd, ls, cp, rm), not the Windows ones (cd but otherwise dir, copy, del).

See Appendix A on how to use a terminal, in particular how to navigate to relocate it in a different folder. Note that you can always run:

pwd

To display the full path of your “present working directory”, that is, the folder the terminal is located at.

Let’s now try generating an output. Relocate the terminal within an article folder. Choose an article in progress, not a finished one! The article folder should contain a proper master.md file (if you can’t find an article in progress with one, see details below on how to create one). Run:

dltc-make off1html

This should generate a HTML output of the article in the same folder. (If in doubt, delete the current HTML output and run the command again.)

Tip. There are several ways you can relocate a VSCode terminal to a specific folder. You can use the cd commands. But you can also use the two following options. Note that these clear up the window, closing any files you might have open, so only use them if you want a clean window:

Use the Explorer (click the Explorer icon on the leftbar), browse the folders, right-click a folder an select “Open in Integrated Terminal”. Note however that this creates a clean window, so it closes any files you have already open in VSCode.
Open the folder in question as root folder. Above we’ve opened the dltc-workshouse folder, so VSCode’s Explorer on the left shows you all the folders it contains. You could decide to open some specific issue or article folder as your base folder instead. In the menu select File > Open Folder…. This opens a search bar when you can search and select a folder to open. When the window refreshes with that folder as base folder, your terminal is then located in that folder.

30.1.8 A warning

Be careful when you run commands in dltc-workhouse and its subfolders. While the container in general is isolated from your system (hence whatever you change or install in it doesn’t affect your sytem), the exception is the dltc-workhouse, which is the one containing the article files on your system. You do not want to damage or delete them. Beware in particular of rm (remove) commands, which deletes files and folders without seeking confirmation.

We can install new tools or modify existing ones in the environment depending on the needs of the copyediting team. Please contact Luis Bordo at luis.bordo@philosophie.ch for any such request.

30.1.9 Advanced: using the container directly from a terminal

Additionally, if you know what you’re doing, you can start a shell within the container without using VSCode. With this, you can use the terminal directly to compile articles. Altough rather clumsy as an approach, this would allow you to, for example, keep using RStudio to work on copyediting tasks and then compiling the articles separatedly in a terminal using the container.

From anywhere in your system, do:

docker exec -ti --volume="YOUR/PATH/TO/Dropbox/philosophie-ch/dltc-workhouse:/home/copyeditor/dltc-workhouse" philosophiech/dltc-env:latest bash

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.

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.

30.1.10 Troubleshooting Installation

30.1.10.1 Common issues

Problem: In VSCode, connected to the container, you don’t see any file in ‘dltc-workhouse’ when you open it

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_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 to “C:/Users/…”.

Problem: while working in the container, you see an error with code “-9”, or anything related to being “out of memory”

Solution: you’re running a heavy task inside the container, and it’s eating up a lot of resources in your machine, so docker is killing the task. This could happen, for example, when compiling PDFs with the big bibliography file. Go to your Docker settings and allow your containers a higher limit on the CPU (or “cores”) and on “memory” (RAM). At least 3/4 of the highest limit should be enough in most cases, but if it’s not enough you can go up to 100%. Just note that if you do this (allowing 100% use of resources), the task is very intense and you’re on an old computer, your machine could crash.

30.1.10.2 Installing WSL version 2 on Windows

Note: if you don’t feel comfortable modifying the options of your machine’s BIOS or UEFI, get in contact with Luis Bordo at luis.bordo@philosophie.ch to guide you through personally. Otherwise, follow the instructions below.

Enable ‘virtualization’. To do this, we need to go to the computer’s BIOS or UEFI. If you know how to do this, do it as you know and ignore the instructions below. Otherwise, follow these steps. WARNING: this will restart your computer:
1. Go to Settings
2. Go to Update and Security (or a setting with a similar name)
3. Go to “Recovery”
4. Click on Restart now in the section “Advanced start-up”
  1. Click on “Troubleshoot”
  2. Click on “Advanced Options”
  3. Click on on the option that mentions either “UEFI” or “BIOS”
  4. Click on “Restart”. This will restart your computer and automatically send you to the BIOS or UEFI settings
5. Now this depends on your specific machine, but under some field called “Security”, you should find a sub-field called “Virtualization”. Inside this sub-field you should Enable all options
6. Save and exit the BIOS or UEFI. IMPORTANT: you need to SAVE before exiting, otherwise you will need to redo the steps above
7. To check that virtualization is enabled, go to the Task Manager, to the Tab TODO

Enable ‘wsl version 2’. Open PowerShell as Administrator, and then:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

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

31 Generating outputs

By “Terminal” we mean a command line interface. See Appendix A on how to use it.

The commands below to generate outputs must be run within the Dialectica container. The simplest way to do it is to connect VSCode to a container and use the terminal provided by VSCode. See Section 30.1.7.

Unless otherwise indicated, file paths below are given relative to the base (“root”) of Dialectica’s workhouse folder (dltc-workhouse).

Since you’re working inside a container, and the container is a virtual Linux machine, you use Linux (/MacOS) terminal commands. This means in particular that paths are written with forward slashes:

2021/2021-03-issue/02-doe

Not with backslash as in Windows (2021\2021-03-issue\02-doe), even if your computer has a Windows system.

31.1 Prepare an article or issue folder

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.

31.1.1 Create a master file

Copy a master.md file into your article folder. You can take one from another article in the same issue, or the template one at template/X.X/copyeditors-scripts. Beware: you can take the master file in the issue folder, but if you do so you’ll need to modify paths in the imports field (see below).

Open the file in text editor. It should already contain an imports metadata field that consists of a list of one or more files (each item on a single line starting with a dash), for instance:

imports:
- 01-author.md
- 02-author.md

You should amend it to contain just one item referring to your file. If your markdown file is smith_j-2023.md you should make it:

imports:
- smith_j-2023.md

Note on issue master files. Issues have master files too, where located in issue folders. Their imports field normally contain a list of all article files for that issue, including which subfolder they’re in, for instance:

imports:
- 01-jones/jones_s-2023.md
- 02-smith/smith_j-2023.md
- ...

Therefore, if you copy an issue master file within an article folder, or the other way round, you should make sure you add (issue master file) or remove (article master file) the subfolders names as required.

31.2 Generate outputs

31.2.1 Run a command in the terminal

You can generate outputs by running the dltc-make command in a terminal inside the container containing the compilation environment.

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 with cd to the folder where your article is.

See Appendix A for help.

31.2.2 Short rendering commands

Rendering commands can be executed in a article’s folder or in an issue folder. All these commmands must be added to dltc-make, e.g.:

dltc-make offprints

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.

Article folder rendering commands
Command	Output
(empty)	article in HTML
`offpdf` `off1pdf`	article in PDF
`offtex` `off1tex`	article in LaTeX. Useful to debug when the PDF generation crashes: try `lualatex smith_j-2020.tex` to see error messages.
`refs`	generate a list of references cited in the article. Saved as `<article_name>.bib.txt`. Only works when the references have been turned into citations and a bibtex file is provided.

Issue folder rendering commands
Command	Output
(empty)	first article in HTML
`all`	issue pdf, all articles PDF + HTML
`allhtml`	all offprints (=articles) in HTML
`offprints` `off`	all offprints HTML and PDF
`vol` `volpdf`	issue PDF
`off2` `off2html`	HTML of the second article (i.e. second item in the masterfile’s `imports` list).
`off2pdf`	PDF of the second article (i.e. second item in the masterfile’s `imports` list).
`off7tex`	LaTeX of seventh article
`voltex`	LaTeX of the issue
`refs`	generate list of references cited for each article. Saved as `<article_name>.bib.txt`. Only works when for articles where references have been turned into citations and given in bibtex files.
`bare` `baretex`	Issue covers only, PDF (`bare`) or LaTeX (`baretex`). articles (also `baretex`). Useful for cover design.

31.2.3 Rendering options

Proof mode

Add --proof or -p at the end of your command (separated by a space):

dltc-make off2 --proof
dltc-make off3pdf -p

This only affects PDF output.

Verbose or quiet

Add --verbose or -v to get a detailed log of the rendering process. Useful for debug. You can save the output in a log file like so:

dltc-make off2pdf -v 2> out.log

The 2> tells the computer to “redirect” the error/information 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 display error or output messages. If you don’t want to see anything just “redirect” the output to a file with sh make.sh … 2> out.log.

Single letter options can be combined: -pv is short for --proof —verbose.

31.2.4 Long rendering commands

Rendering commands can also be given in key-value form:

dltc-make mode=offprint chapter=3 format=pdf

mode includes “offprint” aka “off”, “vol” aka “issue”, “bare” , “refs”
format includes pdf, html, tex aka latex (also epub, jats but we don’t generate these yet)
chapter includes chapter numbers.

The advantage is that you can specify multiple modes and formats separated by commas:

dltc-make mode=off,refs chapter=3,4,5

Rendering options like --proof can be combined with long rendering commands.

31.3 Advice on HTML vs PDF

HTML is best when you start working on an article because it’s much faster and less error-prone than PDF. HTML only fails to produce an output if your document’s metadata is ill-formed or if there’s a bug in 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.

To check which processor you have, click on the Apple icon in the top left corner of your screen and select “About This Mac” from the dropdown menu. Look for the “Processor” field in the window that opens.↩︎
If you encounter some issue with these instructions, check out the [official VSCode documentation instead][https://code.visualstudio.com/docs/sourcecontrol/github].↩︎