% Copyright 2024 Remy Blank <remy@c-space.org>
% SPDX-License-Identifier: MIT

# Install & upgrade

## Install

- **Install the [required packages](#requirements).** Everything else will be
  installed automatically when
  [starting the local server](edit.md#edit-documents).

- **Set up your account** if you haven't done so yet.
  - You should have received a login link of the form
    `https://t-doc.org#?token=...`. Navigate to that link to log in.
  - In the navigation bar, select "<i class="fa-user tfa"></i> &rarr;
    <i class="fa-gear tfa"></i> Settings", click one of the "Add login
    with ..." buttons and follow the process. You will then be able to log in
    with that account.

- **Generate a repository access password** if this is the first time you access
  a t-doc repository.
  - Go to [`t-doc.org`](https://t-doc.org/) and ensure you are logged in.
  - In the navigation bar, select "<i class="fa-user tfa"></i> &rarr;
    <i class="fa-gear tfa"></i> Settings", then open "Repository access".
  - Click "Reset" to generate the password. Keep the dialog open for the next
    step.

- **Edit the Mercurial configuration** for your user. If the file doesn't exist
  yet, create it as an empty plain-text file.

  - **Windows:** `%USERPROFILE%\.hgrc` (typically `C:\Users\USERNAME\.hgrc`)
  - **macOS:** `$HOME/.hgrc` (typically `/Users/USERNAME/.hgrc`)
  - **Linux:** `$HOME/.hgrc` (typically `/home/USERNAME/.hgrc`)

  Copy the `[auth]` section from the dialog above (if you generated a new
  password) or from another install (if you already had a password), and paste
  it into the configuration. Also, add a `[ui]` section and specify your
  username (substitute `FIRST` and `LAST` with your first and last name, and
  `EMAIL` with your email address, e.g. `Joe Smith <joe@example.com>`). Save the
  file.

  ```{code-block} ini
  [auth]
  t-doc.prefix = https://rc.t-doc.org/
  t-doc.username = USER_ID
  t-doc.password = PASSWORD

  [ui]
  username = FIRST LAST <EMAIL>
  ```

## Upgrade

- The [local server](edit.md#edit-documents) indicates when upgrades are
  available.
  - Check the changes introduced in new t-doc versions in the
    [release notes](/release-notes.md).
  - Restart the local server. When prompted, accept the upgrade.
- Check for upgrades to the [required packages](#requirements) and install them
  when available.

## Requirements

t-doc requires the following software to be installed:

- [Python](https://www.python.org/) 3.14
- [Mercurial](https://www.mercurial-scm.org/), for managing source files
- (Optional) [Graphviz](https://graphviz.org/), when using the
  {rst:dir}`graphviz` directive
- (Optional) [Xournal++](https://xournalpp.github.io/), when using the
  {rst:role}`xopp` role

### Windows

- (Optional, Windows 10) Install
  [Windows Terminal](https://github.com/microsoft/terminal) (it's already
  installed on Windows 11 and later).

  ```{code-block} shell-session
  winget install --exact --id Microsoft.WindowsTerminal
  ```

- Install [Python](https://www.python.org/).

  ```{code-block} shell-session
  winget install --exact --id Python.Python.3.14
  ```

  - Check that Python can be launched from the command-line, by running:

    ```{code-block} shell-session
    python
    ```

    If this opens the Microsoft Store, open Windows settings, search for "App
    execution aliases", and disable the "App Installer" entries for `python.exe`
    and `python3.exe`.

- Install the remaining packages. [TortoiseHg](https://tortoisehg.bitbucket.io/)
  is used as a Mercurial client.

  ```{code-block} shell-session
  winget install --exact --id TortoiseHg.TortoiseHg
  winget install --exact --id Graphviz.Graphviz
  winget install --exact --id Xournal++.Xournal++
  ```

#### Upgrades

- Upgrade Python.

  - If a new minor version of Python is recommended (e.g. 3.13.5 is installed
    and 3.14 is recommended), install the new version.

    ```{code-block} shell-session
    winget install --exact --id Python.Python.3.14
    ```

  - Otherwise, upgrade the installed minor version.

    ```{code-block} shell-session
    winget upgrade --exact --id Python.Python.3.14
    ```

- Upgrade the other packages.

  ```{code-block} shell-session
  winget upgrade --exact --id Microsoft.WindowsTerminal
  winget upgrade --exact --id TortoiseHg.TortoiseHg
  winget upgrade --exact --id Graphviz.Graphviz
  winget upgrade --exact --id Xournal++.Xournal++
  ```

### macOS

- Install the [required packages](#requirements) manually or via a package
  manager like [Homebrew](https://brew.sh/).

### Linux

- Install the [required packages](#requirements) via your system's package
  manager.