4 Preliminaries

This chapter explains what you need to set up a markdown production chain.

4.1 What you need

4.1.1 Skills

Use a text editor (VSCode or RStudio will do).
Optionally, use RStudio’s visual editor. This provides a MS Word-like way of editing a markdown document: no need to view the source code. An easy entry into markdown and a nicer way to edit. See Section 6.5.
Optionally, how to use the command line interface. The very basics are enough: navigate to a directory, run a command. See Appendix A.

4.1.2 Software

All the software needed is free: Pandoc, LaTeX and optionally RStudio.

See the Dialectica chapter on generating outputs to set yourself up Chapter 30.

4.2 Working folder

Create a working folder for your journal. This may be shared between copyeditors if you’re a team. We suggest a structure such as this:

tree/copyediting
└── 2023-v51
    ├── 01-i01
    │   ├── 01-ehrenfest-afanassjewa
    │   │   └── history
    │   └── 02-estrin
    └── 03-i02
        ├── 01-ehrenfest-afanassjewa
        │   └── history
        └── 02-estrin
            └── history
tree/published
└── 2023-v50
    ├── 01-i01
    │   ├── 01-ayrton
    │   │   └── history
    │   └── 02-berdichevsky
    │       └── history
    └── 03-i02
        ├── 01-borg
        │   └── history
        └── 02-daubechies
            └── history
tree/guide
tree/resources
└── fonts
tree/template
├── 1.0
│   ├── defaults
│   ├── filters
│   ├── metadata
│   └── scripts
└── 1.1
    ├── defaults
    ├── filters
    ├── metadata
    └── scripts

We’re dividing the articles in two stages, copyediting and published. We could further divide copyediting into copyediting proper (language, style) and production (typesetting) but these tend to be intertwined in markdown production.

‘Copyediting’ and ‘published’ folders are organized by year-volume and month-issue.

Each article has its own folder, with a history subfolder to keep track of the author’s original submissions and revisions.

To these we add a few other folders for resources shared among copyeditors:

template: template engine to produce the journal. This might change over the years, so it is organized by versions. Each issue includes metadata that indicate which version of the template was used. It includes scripts that copyeditors may need to copy or use.
guide: this guide
resources: resources such as fonts, logos, documentation.

4.3 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, 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 Chapter 30.

First make sure that docker is running. In a terminal, do:
```
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.

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:
```
docker start dltc-env
```
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).