Release 2.4 (#1827)

Signed-off-by: Veronica Berglyd Olsen <1619840+vkbo@users.noreply.github.com>

.flake8

@@ -0,0 +1,5 @@
+[flake8]
+ignore = E133,E221,E226,E228,E241,W503,ANN101,ANN102,ANN401
+per-file-ignores=tests/*:ANN
+max-line-length = 99
+exclude = docs/*

.github/FUNDING.yml

@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+# github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+# patreon: # Replace with a single Patreon username
+# open_collective: # Replace with a single Open Collective username
+ko_fi: jadzia626
+# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+# liberapay: # Replace with a single Liberapay username
+# issuehunt: # Replace with a single IssueHunt username
+# otechie: # Replace with a single Otechie username
+# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,16 @@
+---
+name: Bug Report
+about: Create a report to help us improve
+title: ""
+labels: bug
+---
+
+**Note**: Issues without a description will not be considered.
+Please also check if an issue already exists on this problem.
+Please provide a description covering the following points, if applicable:
+
+* A clear and concise description of what the bug is.
+* Steps to reproduce the behaviour
+* A clear and concise description of what you expected to happen.
+* If applicable, add screenshots to help explain your problem.
+* If the error dialog popped up, copy/paste the content here.

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,15 @@
+---
+name: Feature Request
+about: Suggest an idea for this project
+title: ""
+labels: enhancement
+---
+
+**Note**: Feature requests without a description will not be considered.
+Please also check if an issue already exists on this feature.
+Please provide a description covering the following points, if applicable:
+
+* A clear and concise description of what the problem is. Ex. I'm always frustrated when ...
+* A clear and concise description of what you want to happen.
+* A clear and concise description of any alternative solutions or features you've considered.
+* If applicable, add screenshots to help explain your request.

.github/pull_request_template.md

@@ -0,0 +1,24 @@
+<!--
+Please check the following before you make a pull request:
+
+* The branch you are making the pull request from (in your own fork) has a unique and descriptive
+  name. Do not make a pull request directly from your copy of `main`.
+* If you are submitting translation files, only submit the files that you have added translations
+  to, not the other .ts files that may have been updated in the process.
+* Make sure your contribution follows the style guide and other requirements mentioned in the
+  CONTRIBUTING.md file in the repository.
+* Fill in the Summary section below, and if relevant, mention the issue numbers related to the PR.
+-->
+
+**Summary:**
+
+**Related Issue(s):**
+
+**Reviewer's Checklist:**
+
+* [ ] The header of all files contain a reference to the repository license
+* [ ] The overall test coverage is increased or remains the same as before
+* [ ] All tests are passing
+* [ ] All flake8 checks are passing and the style guide is followed
+* [ ] Documentation (as docstrings) is complete and understandable
+* [ ] Only files that have been actively changed are committed

.github/workflows/build.yml

@@ -0,0 +1,99 @@
+name: Build
+
+on: workflow_dispatch
+
+jobs:
+  buildAssets:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Python Setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          architecture: x64
+
+      - name: Install Packages (apt)
+        run: |
+          sudo apt update
+          sudo apt install qttools5-dev-tools latexmk texlive texlive-latex-extra
+
+      - name: Checkout Source
+        uses: actions/checkout@v4
+
+      - name: Install Packages (pip)
+        run: pip install -r docs/source/requirements.txt
+
+      - name: Build Assets
+        run: python pkgutils.py qtlrelease sample manual
+
+      - name: Upload Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: nw-assets
+          path: |
+            novelwriter/assets/sample.zip
+            novelwriter/assets/manual.pdf
+            novelwriter/assets/i18n/*.qm
+          if-no-files-found: error
+          retention-days: 1
+
+  buildLinux:
+    needs: buildAssets
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+        linux-tag: ["manylinux_2_24_x86_64", "manylinux_2_28_x86_64"]
+    steps:
+      - name: Python Setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          architecture: x64
+
+      - name: Install Packages (pip)
+        run: pip install python-appimage
+
+      - name: Checkout Source
+        uses: actions/checkout@v4
+
+      - name: Download Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: nw-assets
+          path: novelwriter/assets
+
+      - name: Build AppImage
+        run: python pkgutils.py build-appimage --linux-tag ${{ matrix.linux-tag }} --python-version ${{ matrix.python-version }}
+
+      - name: Upload Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: AppImage-${{ matrix.python-version }}-${{ matrix.linux-tag }}
+          path: dist_appimage
+          if-no-files-found: error
+          retention-days: 1
+
+  buildMac:
+    needs: buildAssets
+    runs-on: macos-12
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download Artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: nw-assets
+          path: novelwriter/assets
+
+      - name: Build App Bundle
+        run: ./setup/macos/build.sh
+
+      - name: Upload DMG
+        uses: actions/upload-artifact@v4
+        with:
+          name: MacOS-DMG
+          path: dist_macos
+          if-no-files-found: error
+          retention-days: 1

.github/workflows/i18n.yml

@@ -0,0 +1,32 @@
+name: i18n
+
+on:
+  push:
+    branches:
+      - i18n/*
+
+jobs:
+  buildI18n:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Python Setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          architecture: x64
+      - name: Install Packages (apt)
+        run: |
+          sudo apt update
+          sudo apt install qttools5-dev-tools
+      - name: Checkout Source
+        uses: actions/checkout@v4
+      - name: Build Assets
+        run: python pkgutils.py qtlrelease
+      - name: Upload Artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: nw-i18n
+          path: |
+            novelwriter/assets/i18n/*.qm
+          if-no-files-found: error
+          retention-days: 7

.github/workflows/syntax.yml

@@ -0,0 +1,30 @@
+name: Flake8
+
+on:
+  push:
+    branches:
+      - main
+      - release
+  pull_request:
+    branches:
+      - main
+      - release
+
+jobs:
+  checkSyntax:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Python Setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3
+          architecture: x64
+      - name: Checkout Source
+        uses: actions/checkout@v4
+      - name: Install flake8
+        run: pip install -r requirements-dev.txt
+      - name: Syntax Check
+        run: |
+          flake8 --version
+          flake8 novelwriter --count --show-source --statistics
+          flake8 tests --count --show-source --statistics --extend-ignore ANN

.github/workflows/test_linux.yml

@@ -0,0 +1,43 @@
+name: Linux
+
+on:
+  push:
+    branches:
+      - main
+      - release
+  pull_request:
+    branches:
+      - main
+      - release
+
+jobs:
+  testLinux:
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Python Setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          architecture: x64
+      - name: Install Packages (apt)
+        run: |
+          sudo apt update
+          sudo apt install libenchant-2-dev qttools5-dev-tools aspell-en
+      - name: Checkout Source
+        uses: actions/checkout@v4
+      - name: Install Dependencies (pip)
+        run: |
+          pip install -U -r requirements.txt -r tests/requirements.txt
+      - name: Run Build Commands
+        run: python pkgutils.py qtlrelease sample
+      - name: Run Tests
+        run: |
+          export QT_QPA_PLATFORM=offscreen
+          pytest -v --cov=novelwriter --timeout=60
+      - name: Upload to Codecov
+        uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/test_mac.yml

@@ -0,0 +1,37 @@
+name: MacOS
+
+on:
+  push:
+    branches:
+      - main
+      - release
+  pull_request:
+    branches:
+      - main
+      - release
+
+jobs:
+  testMac:
+    runs-on: macos-latest
+    steps:
+      - name: Python Setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          architecture: x64
+      - name: Install Packages (brew)
+        run: |
+          brew install enchant
+      - name: Checkout Source
+        uses: actions/checkout@v4
+      - name: Install Dependencies (pip)
+        run: |
+          pip install -U pyobjc -r requirements.txt -r tests/requirements.txt
+      - name: Run Tests
+        run: |
+          export QT_QPA_PLATFORM=offscreen
+          pytest -v --cov=novelwriter --timeout=60
+      - name: Upload to Codecov
+        uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/test_win.yml

@@ -0,0 +1,33 @@
+name: Windows
+
+on:
+  push:
+    branches:
+      - main
+      - release
+  pull_request:
+    branches:
+      - main
+      - release
+
+jobs:
+  testWin:
+    runs-on: windows-latest
+    steps:
+      - name: Python Setup
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          architecture: x64
+      - name: Checkout Source
+        uses: actions/checkout@v4
+      - name: Install Dependencies (pip)
+        run: |
+          pip install -U -r requirements.txt -r tests/requirements.txt
+      - name: Run Tests
+        run: |
+          pytest -v --cov=novelwriter --timeout=60
+      - name: Upload to Codecov
+        uses: codecov/codecov-action@v4
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -1,26 +1,46 @@
 # Setup/Install
 /MANIFEST
-/dist/
 /build/
 /deploy/
+/dist/
+/dist_*/
 *.spec
 *.egg-info
+setup.iss
+/novelwriter.desktop
+/novelWriter.pyw
+/setup/macos/Info.plist
+.venv
+
+# Translations
+/novelwriter/assets/i18n/*.qm
+.qmake.stash
+i18n/*.qm
+i18n/*.qph
 
 # Documentation
 /docs/build/
-/docs/source/_*
+/novelwriter/assets/help/
+/novelwriter/assets/manual.pdf
+*.qch
+*.qhc
+.~lock.*
 
 # Python Temp
 __pycache__
+*.pyc
 
 # Sample Project
+/novelwriter/assets/sample.zip
 /sample/cache
 /sample/meta
 *.bak
 *.lock
+ToC.txt
 
 # PyTest
 /prof/
+/htmlcov/
 /tests/temp
 /tests/lipsum/cache
 /tests/lipsum/meta
@@ -29,3 +49,7 @@ __pycache__
 
 # Coverage
 /.coverage
+/coverage.*
+
+# Other
+/test.py

.travis.yml

@@ -1,32 +0,0 @@
-os: linux
-dist: bionic
-services:
-  - xvfb
-language: python
-cache: bundler
-addons:
-  apt:
-    packages:
-      - libenchant-dev
-      - python3-pyqt5
-      - python3-pyqt5.qtsvg
-python:
-  - "3.6"
-  - "3.7"
-  - "3.8"
-install:
-  - pip install --upgrade pip
-  - pip install -r requirements.txt
-# - pip install pytest-faulthandler
-  - pip install PyVirtualDisplay
-  - pip install pytest-xvfb
-  - pip install pytest-cov
-  - pip install pytest-qt
-  - pip install codecov
-script:
-  - python -m pytest --cov=nw -m "project|core|gui" -v
-after_success:
-  - codecov
-after_failure:
-  - cat /sys/fs/cgroup/memory/memory.max_usage_in_bytes
-

CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at issues (at)
+novelwriter.io. All complaints will be reviewed and investigated promptly and
+fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# Contributing Guide
+
+When contributing to this repository, please first discuss the change you wish to make with the
+owner. Either via the issue tracker or on the discussions page. Especially if it is regarding new
+features. If you just want to make a minor correction, like fix a typo or similar, feel free to
+just make a pull request directly.
+
+**The following contributions are welcome:**
+
+* Bugfixes for new or existing bugs. Please also report new bugs in the issue tracker even if you
+  also provide a fix. It makes it easier to keep track of what has been fixed and when.
+* Translations made via the [Crowdin project page](https://crowdin.com/project/novelwriter).
+* Improvements to the documentation. Particularly if the documentation is unclear. Please don't
+  make any larger changes to the documentation without discussing if with the maintainer first.
+* Adaptations, installation or packaging features targeting specific operating systems.
+
+**Please do not:**
+
+* Make a pull request that restructures or reformats existing code. If you think some part of the
+  code could be improved, please make an issue thread or start a discussion. The same applies to
+  any text document in the repository.
+
+## Picking the Correct Branch for a Pull Request
+
+The `main` branch is the default branch. For general changes, please make a new branch in your own
+fork from the current `main` branch. Do not make pull requests from your copy of the `main` branch.
+
+As of April 2024, releases are made from the `release` branch. If you are submitting a fix to a
+current release you must do so from the `release` branch. If you make such a fix on the `main`
+branch, **it cannot be included in a patch release**. This also applies to the documentation for
+the latest release published on the main website.
+
+**Also check the following:**
+
+* Make sure your code passes all tests and conforms to the style guide. You can check that the
+  code generally conforms by running the Python linting tool `flake8` from the root of the project
+  folder, although it doesn't check everything. The same check is also run on pull requests.
+* Please provide a description of the changes in the pull request under the summary section of the
+  pull request template, and reference any related issues by providing the issue number.
+* Do not change the version number.
+* Do not submit files that were not actively changed but have otherwise been modified. This is
+  mostly an issue with translation files. The language tool may update all files in the `i18n`
+  folder.
+
+## Code of Conduct
+
+There is a code of conduct. Please follow it in all your interactions with the project.
+
+### Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers
+pledge to making participation in our project and our community a harassment-free experience for
+everyone, regardless of age, body size, disability, ethnicity, gender identity and expression,
+level of experience, nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+Please see the [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) file for the full text.
+
+## Code Style Guide
+
+The source code of novelWriter broadly follows the [PEP8](https://www.python.org/dev/peps/pep-0008)
+style guide, but with a few exceptions. Some key points are listed below.
+
+**Line Length:**
+
+* Source code lines can extend to the upper limit of 99 characters allowed by PEP8. 79 characters
+  is the recommended line length in PEP8, but this is often too restrictive. 99 characters are
+  acceptable when that is more practical. Readability has priority. Generally, if a code statement
+  requires multiple lines, the lines should wrap at 79 characters if possible. If wrapping can be
+  avoided by going to 99, then that is generally preferable.
+* For text files, the text should be wrapped at 99 character. The exception is markdown image tags
+  and urls which can run past that limit.
+
+**Variable and Function Names**
+
+* PEP8 allows for camelCase for consistency with existing code. The Qt library uses camelCase, so
+  the novelWriter source code does too.
+* The exception to the above is for constants. They should always be in upper snake case, like PEP8
+  states.
+
+**Spaces, Indentation and Alignment**
+
+* Only indentation by multiples of 4 spaces is allowed.
+* No trailing spaces should occur on any line in the source code, including empty lines.
+* All common line wrapping methods are allowed in the code, but avoid deep indentations.
+* Aligning operators and attributes in columns with multiple spaces is not allowed by PEP8. The
+  rule is relaxed a bit here. Alignment is allowed when populating large dictionaries or setting
+  many class attributes. It does improve readability in such cases, but should not be overused.
+
+**Type Annotation**
+
+* All functions must be properly type annotated, and a return type stated in all cases.
+* Do not use `List`, `Dict`, `Tuple`, etc, annotations that were deprecated in Python 3.9. You can
+  install the `flake8-pep585` extension to make sure you don't forget. This is also checked by the
+  syntax action run on pull requests.
+* If annotations require a more recent Python version than the minimum version stated in the
+  project's `pyproject.toml`, hide it under an `if TYPE_CHECKING` condition so that the code can
+  still run on older versions. It's OK to require a more recent version for development.
+
+### Linting with `flake8`
+
+A good tool for checking Python code for errors and code style is `flake8`. The documentation is
+available [here](https://flake8.pycqa.org/en/latest/).
+
+The `.flake8` file in the root of this project has the following settings for that matches the
+required code style:
+
+```conf
+[flake8]
+ignore = E133,E221,E226,E228,E241,W503
+max-line-length = 99
+exclude = docs/*
+```
+
+The command line equivalent, with reporting, is:
+```bash
+flake8 . --count --ignore E133,E221,E226,E228,E241,W503 --max-line-length=99 --show-source --statistics
+```
+
+Passing this check is required before contributions are merged. This is checked automatically when
+you make a pull request. You can run the `flake8` command locally to check beforehand. The full
+command will give you a detailed description of the code lines that do not conform to the standard.
+
+Two of the ignored errors are due to the relaxed restriction on column alignment, these are the
+E221 and E241 error codes.
+
+The code E226 is ignored because it doesn't actually follow the
+[PEP8 recommendation](https://www.python.org/dev/peps/pep-0008/#other-recommendations)
+of grouping longer equations by operator precedence like `2*a + 3*b` instead of `a * a + 3 * b`.
+Generally, don't use spaces around `*`, `/` and `**`, but _do_ use spaces around `+` and `-`.
+The same applies to the modulo operator `%`, hence E228 is also ignored.

CREDITS.md

@@ -0,0 +1,70 @@
+# Credits
+
+## Main Developer
+
+* Veronica Berglyd Olsen (@vkbo)
+
+## Contributors
+
+* Concept: Marian Lückhof (@Number042)
+* Internationalisation: Bruno Meneguello (@bkmeneguello)
+* Setup and Packaging: Rachel Powers (@Ryex)
+
+For other contributions, see the project's [Contributors](https://github.com/vkbo/novelWriter/graphs/contributors) page.
+
+## Artwork
+
+The artwork on the Welcome dialog was created by [Louis Durrant](https://louisdurrant.art).
+
+## Translations
+
+The default language is English (UK) with English (US) as an option. These are the original
+translators for the languages currently available:
+
+* Dutch: Martijn van der Kleijn (@mvdkleijn)
+* French: Jan Lüdke (@jyhelle)
+* German: Myian (@heymyian)
+* Italian: Riccardo Mangili
+* Japanese: hebekeg (@hebekeg)
+* Latin American Spanish: Tommy Marplatt (@tmarplatt)
+* Norwegian: Veronica Berglyd Olsen (@vkbo)
+* Portuguese: Bruno Meneguello (@bkmeneguello)
+* Simplified Chinese: Qianzhi Long (@longqzh)
+
+Additional larger translation contributions:
+
+* French: Albert Aribaud (@aaribaud)
+
+Translations are managed on [Crowdin](https://crowdin.com/project/novelwriter), and more
+contributions are listed on the project's [Members](https://crowdin.com/project/novelwriter/members) page.
+
+## Libraries
+
+The following libraries are dependencies of novelWriter:
+
+* [Qt5](https://www.qt.io) by Qt Company
+* [PyQt5](https://www.riverbankcomputing.com/software/pyqt) by Riverbank Computing
+* [Enchant](https://abiword.github.io/enchant) by Dom Lachowicz
+* [PyEnchant](https://pyenchant.github.io/pyenchant) by Dimitri Merejkowsky
+
+## Assets
+
+Some of the assets bundled with novelWriter were adapted from the following sources:
+
+* [Typicons](https://github.com/stephenhutchings/typicons.font) icons by Stephen Hutchings (CC BY-SA 4.0)
+* [Tomorrow](https://github.com/chriskempson/base16) syntax themes by Chris Kempson (MIT License)
+* [Owl](https://github.com/sdras/night-owl-vscode-theme) syntax themes by Sarah Drasner (MIT License)
+* [Solarized](https://github.com/altercation/solarized) themes by Ethan Schoonover (MIT License)
+
+## Fonts
+
+The font used for the main novelWriter logo, mimetype and text banners is Pridi. Other fonts are
+used on buttons and icons.
+
+* Pridi by Cadson Demak (Open Font License, Version 1.1)
+* Source Sans Pro by Paul D. Hunt (SIL Open Font License)
+
+## Special Mentions
+
+Additional thanks to @johnblommers who was an early user and who has provided a lot of very useful
+feedback over the years.

MANIFEST.in

@@ -1,3 +1,6 @@
+include pkgutils.py
 include LICENSE.md
-recursive-include nw/assets *
-recursive-include sample *.nwx *.nwd
+include CREDITS.md
+include CHANGELOG.md
+recursive-include novelwriter/assets *
+recursive-include setup *

README.md

@@ -1,213 +1,72 @@
 # novelWriter
 
-[![Build Status](https://travis-ci.com/vkbo/novelWriter.svg?branch=master)](https://travis-ci.com/vkbo/novelWriter)
-[![codecov](https://codecov.io/gh/vkbo/novelWriter/branch/master/graph/badge.svg)](https://codecov.io/gh/vkbo/novelWriter)
-[![Documentation Status](https://readthedocs.org/projects/novelwriter/badge/?version=latest)](https://novelwriter.readthedocs.io/en/latest/?badge=latest)
+[![Linux](https://github.com/vkbo/novelWriter/actions/workflows/test_linux.yml/badge.svg?branch=main)](https://github.com/vkbo/novelWriter/actions/workflows/test_linux.yml)
+[![Windows](https://github.com/vkbo/novelWriter/actions/workflows/test_win.yml/badge.svg?branch=main)](https://github.com/vkbo/novelWriter/actions/workflows/test_win.yml)
+[![MacOS](https://github.com/vkbo/novelWriter/actions/workflows/test_mac.yml/badge.svg?branch=main)](https://github.com/vkbo/novelWriter/actions/workflows/test_mac.yml)
+[![Flake8](https://github.com/vkbo/novelWriter/workflows/flake8/badge.svg)](https://github.com/vkbo/novelWriter/actions)
+[![CodeCov](https://codecov.io/gh/vkbo/novelWriter/branch/main/graph/badge.svg)](https://codecov.io/gh/vkbo/novelWriter)
 
-<img align="left" style="margin: 0 16px 4px 0;" src="assets/icons/96x96/novelwriter.png">
-novelWriter is a markdown-like text editor designed for writing novels and larger projects of many smaller plain text documents.
-It uses its own flavour of markdown that supports a meta data syntax for comments, synopsis and cross-referencing between files.
-The idea is to have a simple text editor which allows for easy organisation of text files and notes, built on a plain text file project repository for robustness.
-The plain text storage is suitable for version control software, and also well suited for file synchronisation tools.
-The core project structure is stored in a project XML file.
-Other meta data is primarily saved in JSON files.
+<img align="left" style="margin: 0 0 4px 0;" src="https://raw.githubusercontent.com/vkbo/novelWriter/main/setup/novelwriter_readme.png">
 
-The full documentation is available at [novelwriter.readthedocs.io](https://novelwriter.readthedocs.io/).
+novelWriter is a plain text editor designed for writing novels assembled from many smaller text
+documents. It uses a minimal formatting syntax inspired by Markdown, and adds a meta data syntax
+for comments, synopsis, and cross-referencing. It's designed to be a simple text editor that allows
+for easy organisation of text and notes, using human readable text files as storage for robustness.
 
-### Note
+The project storage is suitable for version control software, and also well suited for file
+synchronisation tools. All text is saved as plain text files with a meta data header. The core
+project structure is stored in a single project XML file. Other meta data is primarily saved as
+JSON files.
 
-The application is still under initial development, but all core features have now been added.
-The core functionality has been in place for a while, and novelWriter is being used for writing projects by the author and collaborators.
+For more details, and how to install and use novelWriter, please see the main website and
+documentation.
 
-No new major features will be added at this time, until the application is stable.
-Until then, novelWriter is in a beta state.
-Please report any issues you may encounter in the repository issue tracker.
-
-You should be able to use novelWriter for real projects, but as with all software, please make regular backups.
-There is a built in backup feature that can pack the entire project into a zip file on close.
-Please check the documentation for further details.
-
-
-## License
-
-This is Open Source software, and novelWriter is licensed under GPLv3.
-See the [GNU General Public License website](https://www.gnu.org/licenses/gpl-3.0.en.html) for more details, or consult the [LICENSE](LICENSE.md) file.
-
-Bundled assets have the following licenses:
-
-* The Typicon-based icon themes by Stephen Hutchings are licensed under [CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/). The icons have been altered in size and colour for use with novelWriter, and some additional icons added. The original icon set is available at [stephenhutchings/typicons.font](https://github.com/stephenhutchings/typicons.font).
-* The Cantarell font by Dave Crossland is licensed under [OPEN FONT LICENSE Version 1.1](http://scripts.sil.org/OFL). It is available at [Google Fonts](https://fonts.google.com/specimen/Cantarell).
-* The Tomorrow syntax themes use colour schemes taken from Chris Kempson's collection of code editor themes, licensed with the [MIT License](https://github.com/chriskempson/tomorrow-theme/blob/master/LICENSE.md), and the main repo is available at [chriskempson/tomorrow-theme](https://github.com/chriskempson/tomorrow-theme).
-* Likewise, the Owl syntax themes use colours from Sarah Drasner's code editor themes, licensed with the [MIT License](https://github.com/sdras/night-owl-vscode-theme/blob/master/LICENSE), and the main repo is available at [sdras/night-owl-vscode-theme](https://github.com/sdras/night-owl-vscode-theme).
-
-
-## Markdown Flavour
-
-novelWriter is **not** a full-feature Markdown editor.
-It allows for a minimal set of formatting needed for writing text documents for novels.
-These are currently limited to:
-
-* Headings level 1 to 4 using the `#` syntax only.
-* Emphasised, strongly emphasised, and very strongly emphasised text. These are rendered as italicised, bold, and bold italicised text, respectively.
-* Strikethrough text.
-* Hard line breaks using two or more spaces at the end of a line.
-
-That is it.
-Features not supported in the editor are also not exported when using the export tool.
-
-In addition, novelWriter adds the following, which is otherwise not supported by Markdown:
-
-* A line starting with `%` is treated as a comment and not rendered on exports unless requested.
-  Comments do not count towards the word count.
-* A set of meta data keyword/value sets starting with the character `@`.
-  This is used for tagging and inter-linking documents.
-* Non-breaking spaces are supported as long as your system is using at least Qt 5.9.
-  For earlier version, non-breaking spaces are converted to normal spaces when saving the document.
-  This is done by the Qt library.
-  From Qt 5.9 and on, it is possible to extract the raw text from a document, which preserves non-breaking spaces.
-* Tabs may be rendered, depending on export format.
-  With Qt 5.10 or higher, the width of a tab in pixels can be changed in Preferences.
-
-The core export format of novelWriter is HTML5.
-You can also export the entire project as a single novelWriter flavour document.
-In addition, other exports to Open Document, PDF, and plain text is offered through the Qt library, although with limitations to formatting.
-
-Even though novelWriter can export to Open Document, the result is actually better when using the HTML output and then importing the HTML document into for instance Libre Office.
-The HTML output is also suitable for conversion with tools like Pandoc.
+**Project Links**
 
+* Website: [novelwriter.io](https://novelwriter.io)
+* Documentation: [docs.novelwriter.io](https://docs.novelwriter.io)
+* Internationalisation: [crowdin.com/project/novelwriter](https://crowdin.com/project/novelwriter)
+* PyPi Project: [pypi.org/project/novelWriter](https://pypi.org/project/novelWriter)
+* Social Media: [fosstodon.org/@novelwriter](https://fosstodon.org/@novelwriter)
 
 ## Implementation
 
-The application is written in Python3 using Qt5 via PyQt5.
-It is developed on Linux, but it should in principle work fine on other operating systems as well as long as dependencies are met.
-It is regularly tested on Windows 10.
+novelWriter is written with Python 3 (3.8+) using Qt5 and PyQt5 (5.10+), and is released on Linux,
+Windows and macOS. It can in principle run on any Operating System that also supports Qt, PyQt and
+Python.
 
-The application can be started from the source folder with one of the commands:
-```
-./novelWriter.py
-python novelWriter.py
-python3 novelWriter.py
-```
+## Project Contributions
 
-It also takes a few parameters for debugging and such, which can be listed with the switch `--help`.
+Please don't make feature pull requests without first having discussed them with the maintainer.
+You can make a feature request in the issue tracker, or if the idea isn't fully formed, start a
+discussion on the discussion page. Please also don't make pull requests to reformat or rewrite
+existing code unless there is a very good reason for doing so.
 
-In the root assets folder there are icons and scripts and a template for setting up a launcher on Gnome desktops.
-You may need to modify those scripts slightly, but as they are, they work on Debian and Ubuntu.
-For other operating systems, please consult your operating system documentation for how to make those.
-Feel free to submit more if you are able to make them.
+Fixes and patches are welcome. Contributions related to packaging and installing novelWriter will
+also be appreciated, but please make an issue or a discussion topic first. Before contributing any
+code, please also read the full
+[Contributing Guide](https://github.com/vkbo/novelWriter/blob/main/CONTRIBUTING.md).
 
+Project credits are available in [CREDITS.md](https://github.com/vkbo/novelWriter/blob/main/CREDITS.md).
 
-## Package Dependencies
+**Note:** As of April 2024 only pre-releases are made from the `main` branch. Full releases are
+made from the `release` branch. So if you're submitting a fix to a current release, **including
+changes to documentation**, they must be made to the `release` branch.
 
-It is recommended that novelWriter runs with Qt 5.10 or later, and Python 3.6 or later.
-Running with Qt as low as 5.2.1 and Python 3.4.3 has been tested, and worked in the past, but there are no guarantees that this will keep working as these are not a part of the test builds.
+### Translations
 
-For the apt package manager on Debian systems, the following Python3 packages are needed:
+New translations are always welcome. This project uses Crowdin to maintain translations, and you
+can contribute translations at the [Crowdin project page](https://crowdin.com/project/novelwriter).
+If you have any questions, feel free to post them to the
+[Translations of novelWriter](https://github.com/vkbo/novelWriter/issues/93) issue thread.
 
-* `python3-pyqt5` for the GUI
-* `python3-pyqt5.qtsvg` may need to be installed separately
-* `python3-lxml` for writing project files
+For more details, and how to use Qt Linguist for translations, see the
+[i18n instructions](https://github.com/vkbo/novelWriter/blob/main/i18n/README.md).
 
-These are optional, but recommended:
+## Licence
 
-* `python3-enchant` for better spell checking
-
-Alternatively, the packages can be installed with `pip` by running
-```
-pip install -r requirements.txt
-```
-in the application folder.
-
-You can also do them one at a time, skipping the ones you don't need:
-```
-pip install pyqt5
-pip install lxml
-pip install pyenchant
-```
-
-PyQt/Qt should be at least 5.3, but ideally 5.10 or higher for nearly all features to work.
-Exporting to markdown requires PyQt/Qt 5.14.
-There are no known minimum for lxml, but the code was originally written with 4.2.
-The optional spell check library must be at least 3.0.0 to work with Windows.
-On Linux, 2.0.0 also works fine.
-
-If no external spell checking tool is installed, novelWriter will use a basic spell checker based on standard Python package `difflib`.
-Currently, only English dictionaries are available for this spell checker, but more can be added to the `nw/assets/dict` folder.
-See the [nw/assets/dict/README.md](README.md) file in that folder for how to generate more dictionaries.
-Note that the difflib-based option is both slow and limited.
-
-Note: On Windows, make sure Python3 is in your PATH if you want to launch novelWriter from command line.
-You can also right click the `novelWriter.py` file, create a shortcut, then right click again, select "Properties" and change the target to your python executable and `novelWriter.py`.
-
-It should look something like this:
-```
-C:\...\AppData\Local\Programs\Python\Python38\python.exe novelWriter.py
-```
-
-## Key Features
-
-The text documents of novelWriter use a format similar to markdown, but with a few extensions and a few omissions.
-Project meta data is stored as XML.
-
-### Colour Themes
-
-The editor has syntax highlighting for the features it supports, and includes a set of different syntax highlighting themes.
-The GUI also has an optional dark theme in addition to the default system theme.
-
-Note that the dark theme may not render all elements of the GUI as dark colours if you are running an early version of Qt5.
-This is not due to a bug in novelWriter, but due to the fact that the the styling options in the Qt API in some versions were incomplete.
-
-New themes can easily be added to the `nw/assets/themes` folder.
-Have a look in the existing folders for examples of how to define the colours.
-
-### Auto-Saving and Document Stats
-
-Open documents and the project file itself is saved regularly on a timer.
-The status of this is indicated by two indicators on the right hand side of the status bar.
-Unsaved changes are in yellow, and saved is indicated by green in the default theme.
-Latest word count for the document and project is shown next to these indicators in the status bar.
-The counts are updated regularly, but not as-you-type.
-
-### Easy Organising of Project Files
-
-The structure of the project is shown on the left hand side of the main GUI.
-Project files are organised into root folders, indicating what class of file they are.
-The most important root folder is the Novel folder, which contains all of the files that makes up the finished novel.
-Each root folder can have subfolders.
-Folders have no impact on the project structure, they are purely tools for organising the files in whatever way the user needs.
-
-The editor supports four levels of headings, which determines what level the following text belongs to.
-Headings of level one signify a book or partition title.
-Headings of level two signify the start of a new chapter.
-Headings of level three signify the start of a new scene.
-Headings of level four can be used internally in each scene to separate sections.
-
-Each novel file can be assigned a layout format, which shows up as a flag next to the item in the project tree.
-These are mostly to help the user see what they contain, but they also have some impact on the format of the exported document.
-See the documentation for further details.
-
-#### Project Notes
-
-Supporting note files can be added for the story plot, characters, locations, story timeline, etc.
-These have their separate root folders.
-These are optional files.
-
-### Visualisation of Story Elements
-
-The different notes can be assigned tags, which other files can refer back to using special meta keywords.
-This information can be used to display an outline of the story, showing where each scene connects to the plot, and which characters, etc. occur in them.
-In addition, the tags themselves are clickable in the document view pane, and control-clickable in the editor.
-They make it possible to quickly navigate between the documents while editing.
-
-## Contribution
-
-If you want to contribute to novelWriter, please follow the coding convention laid out in the [Style Guide](docs/markdown/style.md).
-They broadly follow Python PEP8, but there are a few modifications.
-
-## Screenshot
-
-**novelWriter with default system theme:**
-![Screenshot 1](docs/source/images/screenshot_default.png)
-
-**novelWriter with dark theme:**
-![Screenshot 2](docs/source/images/screenshot_dark.png)
+This is Open Source software, and novelWriter is licenced under GPLv3. See the
+[GNU General Public License website](https://www.gnu.org/licenses/gpl-3.0.en.html) for more
+details, or consult the [License](https://github.com/vkbo/novelWriter/blob/main/LICENSE.md)
+document. Bundled assets and their licences are listed in the
+[Credits](https://github.com/vkbo/novelWriter/blob/main/CREDITS.md) document.

assets/icons/novelwriter.svg

@@ -1,184 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<svg
-   xmlns:dc="http://purl.org/dc/elements/1.1/"
-   xmlns:cc="http://creativecommons.org/ns#"
-   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
-   xmlns:svg="http://www.w3.org/2000/svg"
-   xmlns="http://www.w3.org/2000/svg"
-   xmlns:xlink="http://www.w3.org/1999/xlink"
-   id="svg8"
-   version="1.1"
-   viewBox="0 0 270.93333 270.93334"
-   height="1024"
-   width="1024">
-  <defs
-     id="defs2">
-    <linearGradient
-       id="linearGradient1470">
-      <stop
-         style="stop-color:#7a9cb8;stop-opacity:1"
-         offset="0"
-         id="stop1466" />
-      <stop
-         style="stop-color:#5978a6;stop-opacity:1"
-         offset="1"
-         id="stop1468" />
-    </linearGradient>
-    <rect
-       x="60.484347"
-       y="205.79962"
-       width="130.57787"
-       height="65.785888"
-       id="rect852" />
-    <rect
-       id="rect1474"
-       height="28.631245"
-       width="177.70083"
-       y="18.019813"
-       x="13.463703" />
-    <rect
-       id="rect852-7"
-       height="65.785889"
-       width="130.57787"
-       y="205.79962"
-       x="60.484348" />
-    <rect
-       id="rect1544"
-       height="65.785889"
-       width="130.57787"
-       y="205.79962"
-       x="60.484348" />
-    <rect
-       x="60.484348"
-       y="205.79962"
-       width="130.57787"
-       height="65.785889"
-       id="rect1570" />
-    <rect
-       x="13.463703"
-       y="18.019813"
-       width="177.70083"
-       height="28.631245"
-       id="rect1587" />
-    <filter
-       style="color-interpolation-filters:sRGB;"
-       id="filter1444">
-      <feFlood
-         flood-opacity="0.498039"
-         flood-color="rgb(0,0,0)"
-         result="flood"
-         id="feFlood1434" />
-      <feComposite
-         in="flood"
-         in2="SourceGraphic"
-         operator="in"
-         result="composite1"
-         id="feComposite1436" />
-      <feGaussianBlur
-         in="composite1"
-         stdDeviation="3"
-         result="blur"
-         id="feGaussianBlur1438" />
-      <feOffset
-         dx="6"
-         dy="6"
-         result="offset"
-         id="feOffset1440" />
-      <feComposite
-         in="SourceGraphic"
-         in2="offset"
-         operator="over"
-         result="composite2"
-         id="feComposite1442" />
-    </filter>
-    <filter
-       style="color-interpolation-filters:sRGB;"
-       id="filter1456">
-      <feFlood
-         flood-opacity="0.498039"
-         flood-color="rgb(0,0,0)"
-         result="flood"
-         id="feFlood1446" />
-      <feComposite
-         in="flood"
-         in2="SourceGraphic"
-         operator="in"
-         result="composite1"
-         id="feComposite1448" />
-      <feGaussianBlur
-         in="composite1"
-         stdDeviation="3"
-         result="blur"
-         id="feGaussianBlur1450" />
-      <feOffset
-         dx="6"
-         dy="6"
-         result="offset"
-         id="feOffset1452" />
-      <feComposite
-         in="SourceGraphic"
-         in2="offset"
-         operator="over"
-         result="composite2"
-         id="feComposite1454" />
-    </filter>
-    <radialGradient
-       xlink:href="#linearGradient1470"
-       id="radialGradient1474"
-       cx="111.19364"
-       cy="67.111206"
-       fx="111.19364"
-       fy="67.111206"
-       r="130.96873"
-       gradientUnits="userSpaceOnUse"
-       gradientTransform="matrix(2.2584252,1.5089457,-0.74487144,1.1148423,-169.6027,-163.93817)" />
-  </defs>
-  <metadata
-     id="metadata5">
-    <rdf:RDF>
-      <cc:Work
-         rdf:about="">
-        <dc:format>image/svg+xml</dc:format>
-        <dc:type
-           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
-        <dc:title></dc:title>
-      </cc:Work>
-    </rdf:RDF>
-  </metadata>
-  <g
-     style="display:inline"
-     id="layer1">
-    <rect
-       ry="21.166666"
-       rx="21.166666"
-       y="5.8208332"
-       x="5.8208332"
-       height="259.29166"
-       width="259.29166"
-       id="rect1467"
-       style="display:inline;fill:url(#radialGradient1474);fill-opacity:1;stroke:#517995;stroke-width:2.64583;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
-  </g>
-  <g
-     id="layer2"
-     style="display:inline">
-    <path
-       id="rect1406"
-       style="fill:#a11212;fill-opacity:1;stroke:#7e1b1b;stroke-width:9.99999;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter1444)"
-       d="m 312,200 c -44.32,0 -80,35.68 -80,80 v 199.99805 a 279.99999,279.99999 0 0 0 0,0.002 279.99999,279.99999 0 0 0 0,0.0195 v 199.98242 c 0,44.31999 35.68,80 80,80 44.32,0 80,-35.68001 80,-80 v -200 a 120,120 0 0 1 120,-120 120,120 0 0 1 120,120 V 762.83789 H 792 V 480.00195 a 279.99999,279.99999 0 0 0 -280,-280 279.99999,279.99999 0 0 0 -0.81055,0 279.99999,279.99999 0 0 0 -133.46484,34.29688 C 363.30011,213.54621 339.29632,200 312,200 Z m 231.46094,563.22656 c -0.62174,0.0972 -1.2172,0.22317 -1.7793,0.37696 0.5621,-0.15379 1.15756,-0.27973 1.7793,-0.37696 z m -1.7793,0.37696 c -0.5621,0.15378 -1.09071,0.33534 -1.58008,0.53906 0.48937,-0.20372 1.01798,-0.38528 1.58008,-0.53906 z m 338.85742,-0.37696 c 0.62174,0.0972 1.2172,0.22317 1.7793,0.37696 -0.5621,-0.15379 -1.15756,-0.27973 -1.7793,-0.37696 z m 1.7793,0.37696 c 0.5621,0.15378 1.09071,0.33534 1.58008,0.53906 -0.48938,-0.20372 -1.01798,-0.38528 -1.58008,-0.53906 z"
-       transform="scale(0.26458333)" />
-    <path
-       id="path897"
-       style="display:inline;fill:#730d0d;fill-opacity:1;stroke:#590d0d;stroke-width:9.99999;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter1456)"
-       d="m 632,762.83789 v 0.16406 h -85.58398 c -5.49302,0 -9.91602,2.2329 -9.91602,5.00586 0,0.52294 0.15913,1.02696 0.45117,1.5 h -0.44531 c 0.30916,2.03607 1.24102,3.99791 2.81641,5.57227 l 165.59961,165.49414 c 3.92061,3.91808 10.23371,3.91812 14.15429,0 L 884.67773,775.08008 c 1.57569,-1.57463 2.50725,-3.53578 2.81641,-5.57227 h -0.44531 c 0.29216,-0.47304 0.45117,-0.97706 0.45117,-1.5 0,-2.77296 -4.42304,-5.00586 -9.91602,-5.00586 H 792 v -0.16406 z"
-       transform="scale(0.26458333)" />
-    <rect
-       style="fill:#c32222;fill-opacity:1;stroke:none;stroke-width:2.64583;stroke-linejoin:round;stroke-opacity:1"
-       id="rect914"
-       width="10.583333"
-       height="119.0625"
-       x="69.849998"
-       y="67.997917"
-       rx="5.2916665"
-       ry="5.2916665" />
-  </g>
-</svg>

assets/icons/x-novelwriter-project.svg

@@ -1,207 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<svg
-   xmlns:dc="http://purl.org/dc/elements/1.1/"
-   xmlns:cc="http://creativecommons.org/ns#"
-   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
-   xmlns:svg="http://www.w3.org/2000/svg"
-   xmlns="http://www.w3.org/2000/svg"
-   xmlns:xlink="http://www.w3.org/1999/xlink"
-   id="svg8"
-   version="1.1"
-   viewBox="0 0 270.93333 270.93334"
-   height="1024"
-   width="1024">
-  <defs
-     id="defs2">
-    <linearGradient
-       id="linearGradient2515">
-      <stop
-         style="stop-color:#f7f7f7;stop-opacity:1"
-         offset="0"
-         id="stop2511" />
-      <stop
-         style="stop-color:#e5e5e5;stop-opacity:1"
-         offset="1"
-         id="stop2513" />
-    </linearGradient>
-    <rect
-       x="60.484347"
-       y="205.79962"
-       width="130.57787"
-       height="65.785888"
-       id="rect852" />
-    <rect
-       id="rect1474"
-       height="28.631245"
-       width="177.70083"
-       y="18.019813"
-       x="13.463703" />
-    <rect
-       id="rect852-7"
-       height="65.785889"
-       width="130.57787"
-       y="205.79962"
-       x="60.484348" />
-    <rect
-       id="rect1544"
-       height="65.785889"
-       width="130.57787"
-       y="205.79962"
-       x="60.484348" />
-    <rect
-       x="60.484348"
-       y="205.79962"
-       width="130.57787"
-       height="65.785889"
-       id="rect1570" />
-    <rect
-       x="13.463703"
-       y="18.019813"
-       width="177.70083"
-       height="28.631245"
-       id="rect1587" />
-    <filter
-       id="filter1444"
-       style="color-interpolation-filters:sRGB">
-      <feFlood
-         id="feFlood1434"
-         result="flood"
-         flood-color="rgb(0,0,0)"
-         flood-opacity="0.498039" />
-      <feComposite
-         id="feComposite1436"
-         result="composite1"
-         operator="in"
-         in2="SourceGraphic"
-         in="flood" />
-      <feGaussianBlur
-         id="feGaussianBlur1438"
-         result="blur"
-         stdDeviation="3"
-         in="composite1" />
-      <feOffset
-         id="feOffset1440"
-         result="offset"
-         dy="6"
-         dx="6" />
-      <feComposite
-         id="feComposite1442"
-         result="composite2"
-         operator="over"
-         in2="offset"
-         in="SourceGraphic" />
-    </filter>
-    <filter
-       id="filter1456"
-       style="color-interpolation-filters:sRGB">
-      <feFlood
-         id="feFlood1446"
-         result="flood"
-         flood-color="rgb(0,0,0)"
-         flood-opacity="0.498039" />
-      <feComposite
-         id="feComposite1448"
-         result="composite1"
-         operator="in"
-         in2="SourceGraphic"
-         in="flood" />
-      <feGaussianBlur
-         id="feGaussianBlur1450"
-         result="blur"
-         stdDeviation="3"
-         in="composite1" />
-      <feOffset
-         id="feOffset1452"
-         result="offset"
-         dy="6"
-         dx="6" />
-      <feComposite
-         id="feComposite1454"
-         result="composite2"
-         operator="over"
-         in2="offset"
-         in="SourceGraphic" />
-    </filter>
-    <radialGradient
-       xlink:href="#linearGradient2515"
-       id="radialGradient2517"
-       cx="605.42725"
-       cy="623.97186"
-       fx="605.42725"
-       fy="623.97186"
-       r="410"
-       gradientTransform="matrix(2.4110274,1.7617596,-0.719517,0.98463462,-776.23441,-1372.7537)"
-       gradientUnits="userSpaceOnUse" />
-  </defs>
-  <metadata
-     id="metadata5">
-    <rdf:RDF>
-      <cc:Work
-         rdf:about="">
-        <dc:format>image/svg+xml</dc:format>
-        <dc:type
-           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
-        <dc:title></dc:title>
-      </cc:Work>
-    </rdf:RDF>
-  </metadata>
-  <g
-     id="layer3"
-     style="display:inline">
-    <path
-       clip-path="none"
-       transform="scale(0.26458333)"
-       d="m 192,22 c -44.32,0 -80,35.680002 -80,80 v 820 c 0,44.32002 35.68,80 80,80 h 640 c 44.31999,0 80,-35.67998 80,-80 V 213.44727 L 720.55469,22 Z"
-       style="fill:url(#radialGradient2517);fill-opacity:1;stroke:#999999;stroke-width:20;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
-       id="rect1481" />
-    <path
-       id="path1490"
-       style="display:inline;fill:#e0e0e0;fill-opacity:1;stroke:#999999;stroke-width:5.29167;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
-       d="M 241.30037,56.474215 190.64713,5.8204593 V 35.307549 c 0,11.726333 9.44034,21.166666 21.16667,21.166666 z" />
-    <g
-       aria-label=".nwx"
-       transform="matrix(1.7893481,0,0,1.782571,-45.41919,-191.90571)"
-       id="text850"
-       style="font-size:5.64444px;line-height:1.25;font-family:'Fira Sans';-inkscape-font-specification:'Fira Sans, Normal';letter-spacing:0px;word-spacing:0px;white-space:pre;shape-inside:url(#rect852);display:inline;fill:#666666;fill-opacity:1">
-      <path
-         d="m 63.088865,241.76928 q 0,-1.36426 0.909505,-2.27376 0.930175,-0.93018 2.480467,-0.93018 1.550291,0 2.459796,0.93018 0.909504,0.9095 0.909504,2.27376 0,1.34359 -0.909504,2.27376 -0.909505,0.9095 -2.459796,0.9095 -1.550292,0 -2.480467,-0.9095 -0.909505,-0.93017 -0.909505,-2.27376 z"
-         style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:42.3333px;font-family:Roboto;-inkscape-font-specification:'Roboto, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#666666;fill-opacity:1"
-         id="path856" />
-      <path
-         d="m 84.75161,226.78312 q -2.542479,0 -3.782712,2.14974 v 15.79231 h -5.973791 v -22.36554 h 5.601721 l 0.206705,2.56314 q 2.397785,-2.97656 6.428544,-2.97656 3.162595,0 5.105627,1.88103 1.943033,1.88102 1.963703,6.55256 v 14.34537 h -5.994461 v -14.26269 q 0,-2.14973 -0.930175,-2.91454 -0.909505,-0.76482 -2.625161,-0.76482 z"
-         style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:42.3333px;font-family:Roboto;-inkscape-font-specification:'Roboto, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#666666;fill-opacity:1"
-         id="path858" />
-      <path
-         d="m 126.96089,222.35963 -5.68441,22.36554 h -5.00227 l -4.25814,-14.07665 -4.23746,14.07665 h -4.9816 l -5.705078,-22.36554 h 5.767088 l 2.95589,14.22134 4.05143,-14.22134 h 4.32014 l 4.09277,14.20067 2.91455,-14.20067 z"
-         style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:42.3333px;font-family:Roboto;-inkscape-font-specification:'Roboto, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#666666;fill-opacity:1"
-         id="path860" />
-      <path
-         d="m 134.77436,222.35963 3.65869,6.65592 3.76204,-6.65592 h 6.3872 l -6.36653,10.93472 6.63525,11.43082 h -6.3872 l -4.01009,-7.04866 -3.94808,7.04866 h -6.42854 l 6.63525,-11.43082 -6.36654,-10.93472 z"
-         style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:42.3333px;font-family:Roboto;-inkscape-font-specification:'Roboto, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#666666;fill-opacity:1"
-         id="path862" />
-    </g>
-  </g>
-  <g
-     id="g2509"
-     transform="matrix(1.2371037,0,0,1.2371037,206.3182,37.341857)">
-    <path
-       transform="matrix(0.16895991,0,0,0.18329422,-134.6942,-19.491243)"
-       id="rect1406-1"
-       style="display:inline;fill:#a11212;fill-opacity:1;stroke:#7e1b1b;stroke-width:9.99999;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter1444)"
-       d="m 145.18984,56.414257 c -44.32,0 -79.999998,35.68 -79.999998,80.000003 v 199.99805 a 279.99999,279.99999 0 0 0 0,0.002 279.99999,279.99999 0 0 0 0,0.0195 v 199.98242 c 0,44.31999 35.679998,80 79.999998,80 44.32,0 80,-35.68001 80,-80 v -200 a 120,120 0 0 1 120,-120 120,120 0 0 1 120,120 v 282.83592 h 160 V 336.41621 a 279.99999,279.99999 0 0 0 -280,-280.000003 279.99999,279.99999 0 0 0 -0.81055,0 279.99999,279.99999 0 0 0 -133.46484,34.29688 c -14.4245,-20.75262 -38.42829,-34.29883 -65.72461,-34.29883 z M 376.65078,619.64082 c -0.62174,0.0972 -1.2172,0.22317 -1.7793,0.37696 0.5621,-0.15379 1.15756,-0.27973 1.7793,-0.37696 z m -1.7793,0.37696 c -0.5621,0.15378 -1.09071,0.33534 -1.58008,0.53906 0.48937,-0.20372 1.01798,-0.38528 1.58008,-0.53906 z m 338.85742,-0.37696 c 0.62174,0.0972 1.2172,0.22317 1.7793,0.37696 -0.5621,-0.15379 -1.15756,-0.27973 -1.7793,-0.37696 z m 1.7793,0.37696 c 0.5621,0.15378 1.09071,0.33534 1.58008,0.53906 -0.48938,-0.20372 -1.01798,-0.38528 -1.58008,-0.53906 z" />
-    <path
-       transform="matrix(0.16895991,0,0,0.18329422,-134.6942,-19.491243)"
-       id="path897"
-       style="display:inline;fill:#730d0d;fill-opacity:1;stroke:#590d0d;stroke-width:9.99999;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1;filter:url(#filter1456)"
-       d="m 465.18984,619.25215 v 0.16406 h -85.58398 c -5.49302,0 -9.91602,2.2329 -9.91602,5.00586 0,0.52294 0.15913,1.02696 0.45117,1.5 h -0.44531 c 0.30916,2.03607 1.24102,3.99791 2.81641,5.57227 l 165.59961,165.49414 c 3.92061,3.91808 10.23371,3.91812 14.15429,0 L 717.86757,631.49434 c 1.57569,-1.57463 2.50725,-3.53578 2.81641,-5.57227 h -0.44531 c 0.29216,-0.47304 0.45117,-0.97706 0.45117,-1.5 0,-2.77296 -4.42304,-5.00586 -9.91602,-5.00586 h -85.58398 v -0.16406 z" />
-    <rect
-       style="display:inline;fill:#c32222;fill-opacity:1;stroke:none;stroke-width:1.75982;stroke-linejoin:round;stroke-opacity:1"
-       id="rect914"
-       width="6.7583966"
-       height="82.482399"
-       x="-118.27303"
-       y="1.2969339"
-       rx="3.3791983"
-       ry="3.6658845" />
-  </g>
-</svg>

assets/installDebian.sh

@@ -1,28 +0,0 @@
-#!/bin/bash
-
-cd ..
-
-EXEC=$(pwd)/novelWriter.py
-EXEC=$(echo $EXEC | sed 's_/_\\/_g')
-
-sed "s/%%exec%%/$EXEC/g" assets/novelwriter.desktop > /usr/share/applications/novelwriter.desktop
-
-cp -v assets/icons/24x24/novelwriter.png     /usr/share/icons/hicolor/24x24/apps/
-cp -v assets/icons/48x48/novelwriter.png     /usr/share/icons/hicolor/48x48/apps/
-cp -v assets/icons/96x96/novelwriter.png     /usr/share/icons/hicolor/96x96/apps/
-cp -v assets/icons/256x256/novelwriter.png   /usr/share/icons/hicolor/256x256/apps/
-cp -v assets/icons/512x512/novelwriter.png   /usr/share/icons/hicolor/512x512/apps/
-cp -v assets/icons/1024x1024/novelwriter.png /usr/share/icons/hicolor/1024x1024/apps/
-cp -v assets/icons/novelwriter.svg           /usr/share/icons/hicolor/scalable/apps/
-cp -v assets/icons/x-novelwriter-project.svg /usr/share/icons/hicolor/scalable/mimetypes/application-x-novelwriter-project.svg
-cp -v assets/mime/x-novelwriter-project.xml  /usr/share/mime/packages/
-
-update-mime-database /usr/share/mime/
-update-icon-caches /usr/share/icons/hicolor/24x24/apps/
-update-icon-caches /usr/share/icons/hicolor/48x48/apps/
-update-icon-caches /usr/share/icons/hicolor/96x96/apps/
-update-icon-caches /usr/share/icons/hicolor/256x256/apps/
-update-icon-caches /usr/share/icons/hicolor/512x512/apps/
-update-icon-caches /usr/share/icons/hicolor/1024x1024/apps/
-update-icon-caches /usr/share/icons/hicolor/scalable/apps/
-update-icon-caches /usr/share/icons/hicolor/scalable/mimetypes/

assets/installUbuntu.sh

@@ -1,21 +0,0 @@
-#!/bin/bash
-
-cd ..
-
-EXEC=$(pwd)/novelWriter.py
-EXEC=$(echo $EXEC | sed 's_/_\\/_g')
-
-sed "s/%%exec%%/$EXEC/g" assets/novelwriter.desktop > /usr/share/applications/novelwriter.desktop
-
-cp -v assets/icons/24x24/novelwriter.png     /usr/share/icons/hicolor/24x24/apps/
-cp -v assets/icons/48x48/novelwriter.png     /usr/share/icons/hicolor/48x48/apps/
-cp -v assets/icons/96x96/novelwriter.png     /usr/share/icons/hicolor/96x96/apps/
-cp -v assets/icons/256x256/novelwriter.png   /usr/share/icons/hicolor/256x256/apps/
-cp -v assets/icons/512x512/novelwriter.png   /usr/share/icons/hicolor/512x512/apps/
-#cp -v assets/icons/1024x1024/novelwriter.png /usr/share/icons/hicolor/1024x1024/apps/
-cp -v assets/icons/novelwriter.svg           /usr/share/icons/hicolor/scalable/apps/
-cp -v assets/icons/x-novelwriter-project.svg /usr/share/icons/hicolor/scalable/mimetypes/application-x-novelwriter-project.svg
-cp -v assets/mime/x-novelwriter-project.xml  /usr/share/mime/packages/
-
-update-mime-database /usr/share/mime/
-update-icon-caches /usr/share/icons/*

assets/novelwriter.desktop

@@ -1,10 +0,0 @@
-[Desktop Entry]
-Type=Application
-Encoding=UTF-8
-Name=novelWriter
-Comment=Multi-document markdown editor for novels
-Exec=%%exec%% %f
-Icon=novelwriter
-Categories=GTK;GNOME;Office;
-Terminal=false
-MimeType=application/x-novelwriter-project

codecov.yml

@@ -3,8 +3,8 @@ codecov:
 
 coverage:
   precision: 2
-  round: up
-  range: "70...100"
+  round: nearest
+  range: "70...95"
 
   status:
     project:
@@ -20,5 +20,3 @@ parsers:
       loop: yes
       method: no
       macro: no
-
-comment: false

docs/markdown/style.md

@@ -1,24 +0,0 @@
-# Code Style Guide
-
-The source code of novelWriter broadly follows the style guide [PEP8](https://www.python.org/dev/peps/pep-0008/), but with a few modifications and exceptions.
-
-### Source Code Exceptions
-
-* Methods are camelCase, not underscore based.
-  The reason is partially because of the maintainers personal preference, and partially because that is what Qt5 and PyQt5 uses.
-  The maintainer generally, across multiple programming languages, uses underscores for defining namespaces.
-* The maximum length of a code line is 99 characters, not 79.
-  The reason for this is that novelWriter is almost entirely made up of classes, meaning nearly all lines of code already have 8 leading spaces.
-  A 79 character limitation is too strict, and causes too many wrapped lines.
-  99 characters is suitable for GitHub diff readability, and therefore the preferred limit.
-  It is also permitted under PEP8 as the maximum.
-  Comments and docstrings should comply with the 72 character limit.
-* Aligning code with additional spaces is acceptable in those cases where it improves readability.
-  Otherwise, the PEP8 standard should be applied.
-
-### Documentation
-
-The documentation does not adhere to the 80 character limit either.
-The standard used in documentation is one line break after each sentence.
-This is an alternative style that greatly improves readability of diffs as re-wrapping text is not needed when inserting new text in paragraphs.
-Instead, the diff will show changes to each sentence.

docs/source/_static/custom.css

@@ -0,0 +1,14 @@
+span.guilabel {
+    font-weight: 400;
+}
+
+.nw-sidebar-title {
+    height: unset;
+    max-height: unset;
+    flex-direction: column;
+    justify-content: center;
+    gap: .25rem;
+    font-size: 1.25rem;
+    font-weight: normal;
+    text-align: center;
+}

docs/source/_templates/sidebar-title.html

@@ -0,0 +1,3 @@
+{% if docstitle %}
+<p class="nw-sidebar-title">{{ docstitle }}</p>
+{% endif %}

docs/source/conf.py

@@ -1,173 +1,84 @@
-# -*- coding: utf-8 -*-
-#
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
+"""
+Configuration file for the Sphinx documentation builder.
+Documentation: http://www.sphinx-doc.org/en/master/config
+"""
 
-# -- Path setup --------------------------------------------------------------
+# -- Imports -----------------------------------------------------------------
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath("."))
+import os
+import time
+import datetime
 
-
-# -- Project information -----------------------------------------------------
+# -- Project Information -----------------------------------------------------
 
 project = "novelWriter"
-copyright = "2018-2020, Veronica Berglyd Olsen"
+copyright = f"{datetime.date.today().year}"
 author = "Veronica Berglyd Olsen"
 
-# The short X.Y version
-version = "0.10.0"
-# The full version, including alpha/beta/rc tags
-release = "0.10.0"
+initFile = os.path.join(
+    os.path.dirname(__file__), os.pardir, os.pardir,
+    "novelwriter", "__init__.py"
+)
+with open(initFile) as inFile:
+    for aLine in inFile:
+        if aLine.startswith("__version__"):
+            release = aLine.split('"')[1].strip()
+            break
+    else:
+        release = "unknown"
 
+version = release.partition("-")[0]
 
-# -- General configuration ---------------------------------------------------
+# -- General Configuration ---------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = "1.0"
+os.environ["TZ"] = "Europe/Oslo"
+time.tzset()
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
-# ones.
-extensions = [
-]
-
-# Add any paths that contain templates here, relative to this directory.
+needs_sphinx = "5.0"
+extensions = ["sphinx_design"]
 templates_path = ["_templates"]
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = [".rst", ".md"]
 source_suffix = ".rst"
-
-# The master toctree document.
 master_doc = "index"
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
+today_fmt = "%A, %d %B %Y at %H:%M"
+language = "en"
 exclude_patterns = []
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = None
+# -- Options for HTML Output -------------------------------------------------
 
-
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = "default"
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-# html_theme_options = {}
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
+html_theme = "sphinx_book_theme"
+html_title = f"Version {release}"
 html_static_path = ["_static"]
-
-# Custom sidebar templates, must be a dictionary that maps document names
-# to template names.
-#
-# The default sidebars (for documents that don"t match any pattern) are
-# defined by theme itself.  Builtin themes are using these templates by
-# default: ``["localtoc.html", "relations.html", "sourcelink.html",
-# "searchbox.html"]``.
-#
-# html_sidebars = {}
-
-
-# -- Options for HTMLHelp output ---------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = "novelWriterdoc"
-
-
-# -- Options for LaTeX output ------------------------------------------------
-
-latex_elements = {
-    # The paper size ("letterpaper" or "a4paper").
-    #
-    # "papersize": "letterpaper",
-
-    # The font size ("10pt", "11pt" or "12pt").
-    #
-    # "pointsize": "10pt",
-
-    # Additional stuff for the LaTeX preamble.
-    #
-    # "preamble": "",
-
-    # Latex figure (float) alignment
-    #
-    # "figure_align": "htbp",
+html_css_files = ["custom.css"]
+html_theme_options = {
+    "logo": {
+        "image_light": "_static/novelwriter-light.png",
+        "image_dark": "_static/novelwriter-dark.png",
+    },
+    "show_toc_level": 2,
+    "show_navbar_depth": 1,
+    "repository_url": "https://github.com/vkbo/novelwriter",
+    "navigation_with_keys": True,
+    "use_repository_button": True,
+    "use_issues_button": True,
+    "pygment_light_style": "tango",
+    "pygment_dark_style": "dracula",
+}
+html_sidebars = {
+    "**": ["navbar-logo", "sidebar-title", "sbt-sidebar-nav"],
 }
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
-    (master_doc, "novelWriter.tex", "novelWriter Documentation",
-     "Veronica Berglyd Olsen", "manual"),
-]
+# -- Options for LaTeX Output ------------------------------------------------
 
-
-# -- Options for manual page output ------------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, "novelwriter", "novelWriter Documentation",
-     [author], 1)
-]
-
-
-# -- Options for Texinfo output ----------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
-    (master_doc, "novelWriter", "novelWriter Documentation",
-     author, "novelWriter", "Markdown-like editor for novels.",
-     "Miscellaneous"),
-]
-
-
-# -- Options for Epub output -------------------------------------------------
-
-# Bibliographic Dublin Core info.
-epub_title = project
-
-# The unique identifier of the text. This can be a ISBN number
-# or the project homepage.
-#
-# epub_identifier = ""
-
-# A unique identification for the text.
-#
-# epub_uid = ""
-
-# A list of files that should not be packed into the epub file.
-epub_exclude_files = ["search.html"]
+latex_elements = {
+    "papersize": "a4paper",
+    "pointsize": "11pt",
+    "preamble": (
+        "\\usepackage[utf8]{inputenc}\n"
+        "\\DeclareUnicodeCharacter{2212}{\\textendash}\n"
+    ),
+    "figure_align": "htbp",
+}
+latex_logo = "_static/novelwriter-pdf.png"
+latex_documents = [(
+    master_doc, "manual.tex", "User Guide", author, "manual"
+)]

docs/source/export.rst

@@ -1,112 +0,0 @@
-##################
-Exporting Projects
-##################
-
-The novelWriter project can be exported in various formats using the build tool available from :menuselection:`Project --> Build Project` or by pressing :kbd:`F5`.
-
-*****************
-Header Formatting
-*****************
-
-The titles for the four levels of story structure can be formatted collectively in the export tool.
-This is done through a series of keyword–replace steps.
-
-The keyword ``%title%`` will always be replaced by the text you put after the ``#`` characters in your document.
-
-The keywords ``%ch%`` and ``%chw%`` is replaced by a number, or a number word, respectively.
-The number is incremented by one each time the build tool sees a new heading of level two in a file with layout "Chapter".
-If the file has layout "Unnumbered", the counter is *not* incremented.
-The latter is useful for for instance Prologue and Epilogue chapters.
-
-Likewise, the keywords ``%sc%`` and ``%sca%`` are number counters for scene files.
-These are incremented each time a heading of level three is encountered.
-The former keyword is reset to one for each new chapter, while the latter is not reset but counts from first scene encountered in the project.
-
-If you want to insert a line break in your title format, add two backslashes ``\\``.
-
-.. note::
-   Header formatting only applies to novel files.
-   Headings in note files will will be left as-is, but heading levels 1 through 4 are converted to the correct heading level in the respective output formats.
-
-****************
-Scene Separators
-****************
-
-If you don't want any titles for your scenes (and for your sections if you have them), you can leave the boxes empty, and an empty paragraph will be inserted between the scenes or sections instead.
-Alternatively, if you want a separator between them, like the common "\*\*\*", you can also enter that in the box.
-In fact, if the format is a piece of static text, it will always be treated as a separator.
-
-**************
-File Selection
-**************
-
-Which files are selected for export can be controlled from the options on the left side of the dialog window.
-The switch for "Include novel files" will select any file that isn't classified as a note.
-That is, files with layout "Book", "Page", "Partition", "Chapet", "Unnumbered", or "Scene".
-The switch for "Include note files" will select any file that is a note.
-That is, files with layout "Note".
-This is allows for exporting just the novel, just your notes, or both, as you see fit.
-
-In addition, you can select to export the synopsis comments, regular comments, keywords, and even exclude the body text itself.
-If you for instance want to export a document with an outline of the novel, you can enable keywords and synopsis export and disable body text, thus getting a document with each heading followed by the tags and references and the synopsis.
-
-If you need to exclude specific files from your exports, like draft files or files you want to take out of your build, but don't want to delete, you can uncheck the "Include when building project" option for each file in the project tree.
-An included file has a checkmark after the status icon in the "Flags" column.
-The "Build Novel Project" tool has a switch to ignore this flag if you need to collectively override these settings.
-
-**************
-Export Formats
-**************
-
-Currently, six formats are supported for exporting.
-
-OpenDocument Format
-===================
-
-This is produces an open document ``.odt`` file.
-The document produced has very little formatting, and may require further editing afterwards.
-For a better formatted office document, you may get a better result with exporting to HTML and the import that HTML document in your office word processor.
-
-PDF Format
-==========
-
-The PDF export is just a shortcut for print to file.
-
-novelWriter HTML
-================
-
-The HTML export format writes a single ``.htm`` file with minimal style formatting.
-The exported HTML file is suitable for further processing by document conversion tools like Pandoc, for importing in word processors, or for printing from browser.
-
-novelWriter Markdown
-====================
-
-This is simply a concatenation of the files selected by the filters.
-The files in the project are stacked together in the order they appear in the tree view, with comments, tags, etc. included if they are selected.
-This is a useful format for exporting the project for later import back into novelWriter.
-
-Standard Markdown
-=================
-
-If you have Qt 5.14 or higher, the option to export to plain Markdown is available.
-This feature uses Qt's own Markdown export feature.
-
-Plain Text
-==========
-
-The plain text export format writes a simple ``.txt`` file without any formatting at all.
-
-*************************
-Additional Export Options
-*************************
-
-In addition to the above document formats, the novelWriter HTML and Markdown formats can also be wrapped in a JSON file.
-The files will have a meta data entry and a body entry.
-For HTML, also the accompanying css styles are exported.
-
-The text body is saved in a two-level list.
-The outer list contains one entry per exported file, in the order they appear in the project tree.
-Each file is then split up into a lst as well, with one entry per line.
-
-These files are mainly intended for scripted post-processing for those who want that option.
-A JSON file can be imported directly into a Python dict object or a PHP array, to mentions a few options.

docs/source/index.rst

@@ -1,25 +1,95 @@
-####################################
-Welcome to novelWriter Documentation
-####################################
+######################
+novelWriter User Guide
+######################
 
-This is the documentation for novelWriter |version|.
+| **Release Version:** |release|
+| **Updated:** |today|
 
-**Contents**
+novelWriter is an open source plain text editor designed for writing novels assembled from
+individual text documents. It uses a minimal formatting syntax inspired by Markdown, and adds a
+meta data syntax for comments, synopsis, and cross-referencing. It is designed to be a simple text
+editor that allows for easy organisation of text and notes, using human readable text files as
+storage for robustness.
+
+.. figure:: images/screenshot_multi.png
+   :class: dark-light
+   :align: center
+   :width: 500
+
+The project storage is suitable for version control software, and also well suited for file
+synchronisation tools. All text is saved as plain text files, and your project data as standard
+data formats in XML and JSON. See :ref:`a_storage` for more details.
+
+Any operating system that has Python 3 and the Qt 5 libraries should be able to run novelWriter.
+It runs fine on Linux, Windows and MacOS, and users have tested it on other platforms as well.
+See :ref:`a_started` for more details.
+
+**Useful Links**
+
+* Website: https://novelwriter.io
+* Documentation: https://docs.novelwriter.io
+* Public Releases: https://releases.novelwriter.io
+* Internationalisation: https://crowdin.com/project/novelwriter
+* Source Code: https://github.com/vkbo/novelWriter
+* Source Releases: https://github.com/vkbo/novelWriter/releases
+* Issue Tracker: https://github.com/vkbo/novelWriter/issues
+* Feature Discussions: https://github.com/vkbo/novelWriter/discussions
+* PyPi Project: https://pypi.org/project/novelWriter
+* Social Media: https://fosstodon.org/@novelwriter
 
 .. toctree::
-   :maxdepth: 2
+   :hidden:
 
-   introduction
-   started
-   interface
-   projects
-   structure
-   notes
-   export
-   technical
+   Main Page <self>
 
-**Indices and Tables**
+.. toctree::
+   :maxdepth: 1
+   :caption: Introduction
+   :hidden:
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   int_introduction
+   int_overview
+   int_started
+   int_howto
+   int_glossary
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Using novelWriter
+   :hidden:
+
+   usage_breakdown
+   usage_project
+   usage_writing
+   usage_format
+   usage_shortcuts
+   usage_typography
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Organising Your Project
+   :hidden:
+
+   project_overview
+   project_structure
+   project_references
+   project_manuscript
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Additional Details
+   :hidden:
+
+   more_customise
+   more_projectformat
+   more_counting
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Technical Topics
+   :hidden:
+
+   tech_locations
+   tech_storage
+   tech_source
+   tech_tests

docs/source/int_glossary.rst

@@ -0,0 +1,64 @@
+.. _a_glossary:
+
+********
+Glossary
+********
+
+.. glossary::
+   :sorted:
+
+   Root Folder
+      A "Root Folder" is a top level folder of the project tree in novelWriter. Each type of root
+      folder has a specific icon to identify it. For an overview of available root folder types,
+      see :ref:`a_proj_roots`.
+
+   Novel Documents
+      These are documents that are created under a "Novel" :term:`root folder`. They behave
+      differently than :term:`Project Notes`, and have some more restrictions. For instance, they
+      can not exist in folders intended only for project notes. See the :ref:`a_struct` chapter for
+      more details.
+
+   Project Notes
+      Project Notes are unrestricted documents that can be placed anywhere in your project. You
+      should not use these documents for story elements, only for notes. Project notes are the
+      source files used by the Tags and References system. See the :ref:`a_references` chapter for
+      more details on how to use them.
+
+   Tag
+      A tag is a user defined value assigned as a tag to a section of your :term:`Project Notes`.
+      It is optional, and can be defined once per heading. It is set using the :term:`keyword`
+      syntax ``@tag: value``, where ``value`` is the user defined part. Each tag can be referenced
+      in another file using one of the :term:`reference` keywords. See :ref:`a_references` chapter
+      for more details.
+
+   Reference
+      A reference is one of a set of :term:`keywords<keyword>` that can be used to link to a
+      :term:`tag` in another document. The reference keywords are specific to the different
+      :term:`root folder` types. A full overview is available in the :ref:`a_references` chapter.
+
+   Project Index
+      The project index is a record of all headings in a project, with all their meta data like
+      synopsis comments, :term:`tags<tag>` and :term:`references<reference>`. The project index is
+      kept up to date automatically, but can also be regenerated manually from the
+      :guilabel:`Tools` menu or by pressing :kbd:`F9`.
+
+   Context Menu
+      A context menu is a menu that pops up when you right click something in the user interface.
+      In novelWriter, you can often also open a context menu by pressing the keyboard shortcut
+      :kbd:`Ctrl+.`.
+
+   Headings
+      Each level of headings in :term:`Novel Documents` have a specific meaning in terms of the
+      structure of the story. That is, they determine what novelWriter considers a partition, a
+      chapter, a scene or a text section. For :term:`Project Notes`, the heading levels don't
+      matter. For more details on headings in novel documents, see :ref:`a_struct_heads`.
+
+   Keyword
+      A keyword in novelWriter is a special command you put in the text of your documents. They are
+      not standard Markdown, but are used in novelWriter to add information that is interpreted by
+      the application. For instance, keywords are used for :term:`tags<tag>` and
+      :term:`references<reference>`.
+
+      Keywords must always be on their own line, and the first character of the line must always be
+      the ``@`` character. The keyword must also always be followed by a ``:`` character, and the
+      values passed to the command are added after this, separated by commas.

docs/source/int_howto.rst

@@ -0,0 +1,87 @@
+.. _a_howto:
+
+*************
+Tips & Tricks
+*************
+
+.. _Discussions Page: https://github.com/vkbo/novelWriter/discussions
+
+This is a list of hopefully helpful little tips on how to get the most out of novelWriter.
+
+.. note::
+   This section will be expanded over time. If you would like to have something added, feel free to
+   contribute, or start a discussion on the project's `Discussions Page`_.
+
+
+Managing the Project
+====================
+
+.. dropdown:: Merge Multiple Documents Into One
+   :animate: fade-in-slide-down
+
+   If you need to merge a selection of documents in your project into a single document, you can
+   achieve this by first making a new folder for just that purpose, and drag all the files you want
+   merged into this folder. Then you can right click the folder, select :guilabel:`Transform` and
+   :guilabel:`Merge Documents in Folder`.
+
+   In the dialog that pops up, the documents will be in the same order as in the folder, but you
+   can rearrange them here of you wish. See :ref:`a_ui_tree_split_merge` for more details.
+
+
+Layout Tricks
+=============
+
+.. dropdown:: Create a Simple Table
+   :animate: fade-in-slide-down
+
+   The formatting tools available in novelWriter don't allow for complex structures like tables.
+   However, the editor does render tabs in a similar way that regular word processors do. You can
+   set the width of a tab in **Preferences**.
+
+   The tab key should have the same distance in the editor as in the viewer, so you can align text
+   in columns using the tab key, and it should look the same when viewed next to the editor.
+
+   This is most suitable for your notes, as the result in exported documents cannot be guaranteed
+   to match. Especially if you don't use the same font in your manuscript as in the editor.
+
+
+Organising Your Text
+====================
+
+.. dropdown:: Add Introductory Text to Chapters
+   :animate: fade-in-slide-down
+
+   Sometimes chapters have a short preface, like a brief piece of text or a quote to set the stage
+   before the first scene begins.
+
+   If you add separate files for chapters and scenes, the chapter file is the perfect place to add
+   such text. Separating chapter and scene files also allows you to make scene files child
+   documents of the chapter.
+
+   .. versionadded:: 2.0
+
+.. dropdown:: Distinguishing Soft and Hard Scene Breaks
+   :animate: fade-in-slide-down
+
+   Depending on your writing style, you may need to separate between soft and hard scene breaks
+   within chapters. Like for instance if you switch point-of-view character often.
+
+   In such cases you may want to use different scene headings for hard and soft scene breaks. The
+   **Build Manuscript** tool will let you define a different format for scenes using the ``###``
+   and ``###!`` heading codes when you generate your manuscript. You can for instance add the
+   common "``* * *``" for hard breaks and select to soft scene breaks, which will just insert an
+   empty paragraph in their place. See :ref:`a_manuscript_settings` for more details.
+
+   .. versionadded:: 2.4
+
+
+Other Tools
+===========
+
+.. dropdown:: Convert Project to/from yWriter Format
+   :animate: fade-in-slide-down
+
+   There is a tool available that lets you convert a `yWriter <http://spacejock.com/yWriter7.html>`_
+   project to a novelWriter project, and vice versa.
+
+   The tool is available at `peter88213.github.io/yw2nw <https://peter88213.github.io/yw2nw/>`__

docs/source/int_introduction.rst

@@ -0,0 +1,121 @@
+.. _a_intro:
+
+********
+Overview
+********
+
+.. _Snowflake: https://www.advancedfictionwriting.com/articles/snowflake-method/
+.. _Markdown: https://en.wikipedia.org/wiki/Markdown
+
+At its core, novelWriter is a multi-document plain text editor. The idea is to let you edit your
+text without having to deal with formatting until you generate a draft document or manuscript.
+Instead, you can focus on the writing right from the start.
+
+Of course, you probably need *some* formatting for your text. At the very least you need emphasis.
+Most people are familiar with adding emphasis using underscores and asterisks. This formatting
+standard comes from Markdown_ and is supported by novelWriter. It also uses Markdown formatting for
+defining document headings. If you need more specialised formatting, additional formatting options
+are available using a shortcode format. See :ref:`a_fmt_shortcodes` for more details.
+
+.. admonition:: Limitations
+
+   novelWriter is designed for writing fiction, so the formatting features available are limited to
+   those relevant for this purpose. It is **not** suitable for technical writing, and it is **not**
+   a full-featured Markdown editor.
+
+   It is also not intended as a tool for organising research for writing, and therefore lacks
+   formatting features you may need for this purpose. The notes feature in novelWriter is mainly
+   intended for character profiles and plot outlines.
+
+Your novel project in novelWriter is organised as a collection of separate plain text documents
+instead of a single, large document. The idea is to make it easier to reorganise your project
+structure without having to cut and paste text between chapters and scenes.
+
+There are two kinds of documents in your project: :term:`Novel Documents` are documents that are
+part of your story. The other kind of documents are :term:`Project Notes`. These are intended for
+your notes about your characters, your world building, and so on.
+
+You can at any point split the individual documents by their headings up into multiple documents,
+or merge multiple documents into a single document. This makes it easier to use variations of the
+Snowflake_ method for writing. You can start by writing larger structure-focused documents, like
+for instance one document per act, and later effortlessly split these up into chapters or scenes.
+
+
+.. _a_intro_features:
+
+Key Features
+============
+
+Below are some key features of novelWriter.
+
+**Focus on writing**
+   The aim of the user interface is to let you focus on writing instead of spending time formatting
+   text. Formatting is therefore limited to a small set of formatting tags for simple things like
+   text emphasis and paragraph alignment. When you really want to focus on just writing, you can
+   switch the editor into **Focus Mode** where only the text editor panel itself is visible, and
+   the project structure view is hidden away.
+
+**Keep an eye on your notes**
+   The main window can optionally show a document viewer to the right of the editor. The viewer
+   is intended for displaying another scene document, your character notes, plot notes, or any
+   other document you may need to reference while writing. It is not intended as a preview panel
+   for the document you're editing, but if you wish, you can also use it for this purpose.
+
+**Organise your documents how you like**
+   You can split your novel project up into as many individual documents as you want to. When you
+   build the project into a manuscript, they are all glued together in the top-to-bottom order in
+   which they appear in the project tree. You can use as few text documents as you like, but
+   splitting the project up into chapters and scenes means you can easily reorder them using the
+   drag-and-drop feature of the project tree. You can also start out with fewer documents and then
+   later split them into multiple documents based on chapter and scene headings.
+
+**Multi-novel project support**
+   The main parts of your project is split up into top level special folders called "Root" folders.
+   Your main story text lives in the "Novel" root folder. You can have multiple such folders in a
+   project. This allows you to keep a series of individual novels with the same characters and
+   world building in the same project, and create manuscripts for them individually.
+
+**Keep track of your story elements**
+   All notes in your project can be assigned a :term:`tag` that you can then :term:`reference` from
+   any other document or note. In fact, you can add a new tag under each heading of a note if you
+   need to be able to reference specific sections of it.
+
+**Get an overview of your story**
+   It is not the documents themselves that define the chapters and scenes of your story, but the
+   headings that separate them. In the **Outline View** on the main window you can see an outline
+   of all the chapter and scene headings of your project. If they have any references in them, like
+   which character is in what chapter and scene, these are listed in additional columns.
+
+   You can also add a synopsis to each chapter or scene, which can be listed here as well. You have
+   the option to add or remove columns of information from this outline. A subset of the outline
+   information is also available in the **Novel View** as an alternative view to the project tree.
+
+**Get an overview of your story elements**
+   Under the document viewer panel you will find a series of tabs that show the different story
+   elements you have created tags for. The tabs are sorted into **Characters**, **Plots**, etc,
+   depending on which categories you are using in your story. This panel can be hidden to free up
+   space when you don't need it.
+
+**Assembling your manuscript**
+   Whether you want to assemble a manuscript, or export all your notes, or generate an outline of
+   your chapters and scenes with a synopsis included, you can use the **Build Manuscript** tool to
+   do so. The tool lets you select what information you want to include in the generated document,
+   and how it is formatted. You can send the result to a printer, a PDF, or to an Open Document
+   file that can be opened by most office type word processors. You can also generate the result
+   as HTML, or Markdown, both suitable for further conversion to other formats.
+
+
+.. _a_intro_screenshots:
+
+Screenshots
+===========
+
+.. figure:: images/screenshot_light.png
+   :class: dark-light
+
+   novelWriter with light colour theme
+
+.. figure:: images/screenshot_dark.png
+   :class: dark-light
+
+   novelWriter with dark colour theme

docs/source/int_overview.rst

@@ -0,0 +1,88 @@
+.. _a_reading:
+
+******************
+What to Read First
+******************
+
+The documentation of novelWriter is quite extensive. There are a lot of features to get used to,
+but you don't need all of them to get started.
+
+The chapters below labelled "Essential Information" are the ones you need to know to use the
+application correctly. By "correctly", it is meant: in a way so novelWriter understands the basic
+structure of your text. It collects a lot of information from your text and uses it to display the
+structure of it in various ways to help you get an overview of your project.
+
+The chapters labelled "Recommended Reading" includes additional information on how the different
+parts if the application work and what the features do. 
+
+The "Optional" and "Lookup" chapters contain additional information or lookup tables that are not
+essential for using the application.
+
+
+Using novelWriter
+=================
+
+In order to use novelWriter effectively, you need to know the basics of how it works. The following
+chapters will explain the main principles. It starts with the basics, and gets more detailed as you
+read on.
+
+:ref:`a_breakdown` – Essential Information
+   This chapter explains the basics of how the application works and what it can and cannot do.
+
+:ref:`a_ui_project` – Recommended Reading
+   This chapter will give you a more detailed explanation of how you can use the user interface
+   components to organise and view your project work.
+
+:ref:`a_ui_writing` – Recommended Reading
+   This chapter will give you a more detailed explanation of how the text editor and viewer work.
+
+:ref:`a_fmt` – Essential Information
+   This chapter covers how you should format your text. The editor is plain text, so text
+   formatting requires some basic markup. The structure of your novel is also inferred from how you
+   use headings. Tags and references are implemented by special keywords.
+
+:ref:`a_kb` – Optional / Lookup
+   This chapter lists all the keyboard shortcuts in novelWriter and what they do. Most of the
+   shortcuts are also listed next to their menu entries inside the app, or in tool tips. This
+   chapter is mostly for reference.
+
+:ref:`a_typ` – Optional
+   This chapter gives you an overview of the special typographical symbols available in
+   novelWriter. The auto-replace feature can handle the insertion of standard quote symbols for
+   your language, and other special characters. If you use any symbols aside from these, their
+   intended use is explained here.
+
+
+Organising Your Projects
+========================
+
+In addition to managing a collection of plain text files, novelWriter can interpret and map the
+structure of your novel and show you additional information about its flow and content. In order
+to take advantage of these features, you must structure your text in a specific way and add some
+meta data for it to extract.
+
+:ref:`a_proj` – Essential Information
+   This chapter explains how you organise the content of your project, and how to set up automated
+   backups of your work.
+
+:ref:`a_struct` – Essential Information
+   This chapter covers the way your novel's structure is encoded into the text documents. It
+   explains how the different levels of headings are used, and some special formatting for
+   different kinds of headings.
+
+:ref:`a_references` - Recommended Reading
+   This chapter explains how you organise your notes, and how the Tags and References system works.
+   This system lets you cross-link your documents in your project, and display these references in
+   the application interface.
+
+:ref:`a_manuscript` - Recommended Reading
+   This chapter explains how the **Manuscript Build** tool works, how you can control the way
+   chapter titles are formatted, and how scene and section breaks are handled.
+
+
+Additional Details & Technical Topics
+=====================================
+
+The Additional Details and the Technical Topics sections contain more in-depth information about
+how various bits of novelWriter works. This information is not essential to getting started using
+novelWriter.

docs/source/int_started.rst

@@ -0,0 +1,180 @@
+.. _a_started:
+
+**********************
+Setup and Installation
+**********************
+
+.. _Enchant: https://abiword.github.io/enchant/
+.. _GitHub: https://github.com/vkbo/novelWriter
+.. _Downloads page: https://download.novelwriter.io
+.. _PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter
+.. _Pre-Release PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter-pre
+.. _PyPi: https://pypi.org/project/novelWriter/
+.. _python.org: https://www.python.org/downloads/
+.. _Releases: https://github.com/vkbo/novelWriter/releases
+.. _AppImage: https://appimage.org/
+
+Ready-made packages and installers for novelWriter are available for all major platforms, including
+Linux, Windows and MacOS, from the `Downloads page`_. See below for install additional instructions
+for each platform.
+
+You can also install novelWriter from the Python Package Index (PyPi_). See :ref:`a_started_pip`.
+Installing from PyPi does not set up icon launchers, so you will either have to do this yourself,
+or start novelWriter from the command line.
+
+Spell checking in novelWriter is provided by a third party library called Enchant_. Generally, it
+should pull dictionaries from your operating system automatically. However, on Windows they must be
+installed manually. See :ref:`a_custom_dict` for more details.
+
+
+.. _a_started_windows:
+
+Installing on Windows
+=====================
+
+You can install novelWriter with both Python and library dependencies embedded using the Windows
+Installer (setup.exe) file from the `Downloads page`_, or from the Releases_ page on GitHub_.
+Installing it should be straightforward.
+
+If you have any issues, try uninstalling the previous version and making a fresh install. If you
+already had a version installed via a different method, you should uninstall that first as having
+multiple installations has been known to cause problems.
+
+.. note::
+   The novelWriter installer is not signed because Microsoft doesn't currently provide a way for
+   non-profit open source projects to properly sign their installers. The novelWriter project
+   doesn't have the funding to pay for commercial software signing certificates. You will therefore
+   see an additional warning about this when you download and run the installer.
+
+
+.. _a_started_linux:
+
+Installing on Linux
+===================
+
+A Debian package can be downloaded from the `Downloads page`_, or from the Releases_ page on
+GitHub_. This package should work on both Debian, Ubuntu and Linux Mint, at least.
+
+If you prefer, you can also add the novelWriter repository on Launchpad to your package manager.
+The Launchpad packages `are signed by the author <https://launchpad.net/~vkbo>`__.
+
+
+Ubuntu
+------
+
+You can add the Ubuntu PPA_ and install novelWriter with the following commands.
+
+.. code-block:: bash
+
+   sudo add-apt-repository ppa:vkbo/novelwriter
+   sudo apt update
+   sudo apt install novelwriter
+
+If you want the `Pre-Release PPA`_ instead, add the ``ppa:vkbo/novelwriter-pre`` repository.
+
+
+Debian and Mint
+---------------
+
+Since this is a pure Python package, the Launchpad PPA can in principle also be used on Debian or
+Mint. However, the above command will fail to add the signing key, as it is Ubuntu-specific.
+
+Instead, run the following commands to add the repository and key:
+
+.. code-block:: bash
+
+   sudo gpg --no-default-keyring --keyring /usr/share/keyrings/novelwriter-ppa-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys F19F1FCE50043114
+   echo "deb [signed-by=/usr/share/keyrings/novelwriter-ppa-keyring.gpg] http://ppa.launchpad.net/vkbo/novelwriter/ubuntu noble main" | sudo tee /etc/apt/sources.list.d/novelwriter.list
+
+Then run the update and install commands as for Ubuntu:
+
+.. code-block:: bash
+
+   sudo apt update
+   sudo apt install novelwriter
+
+.. note::
+   You may need to use the Ubuntu 20.04 (focal) packages for Debian 11 or earlier. The newer Ubuntu
+   packages use a different compression algorithm that may not be supported.
+
+.. tip::
+   If you get an error message like ``gpg: failed to create temporary file`` when importing the key
+   from the Ubuntu keyserver, try creating the folder it fails on, and import the key again:
+
+   .. code-block:: bash
+
+      sudo mkdir /root/.gnupg/
+
+
+AppImage Releases
+-----------------
+
+For other Linux distros than the ones mentioned above, the primary option is AppImage_. These are
+completely standalone images for the app that include the necessary environment to run novelWriter.
+They can of course be run on any Linux distro, if you prefer this to native packages.
+
+.. note::
+   novelWriter generally doesn't support Python versions that have reached end of life. If your
+   Linux distro still uses older Python versions and novelWriter won't run, you may want to try the
+   AppImage instead.
+
+
+.. _a_started_macos:
+
+Installing on MacOS
+===================
+
+You can install novelWriter with both its Python and library dependencies embedded using the DMG
+application image file from the `Downloads page`_, or from the Releases_ page on GitHub_.
+Installing it should be straightforward.
+
+* Download the DMG file and open it. Then drag the novelWriter icon to the :guilabel:`Applications`
+  folder on the right. This will install it into your :guilabel:`Applications`.
+* The first time you try to launch it, it will say that the bundle cannot be verified, simply press
+  the :guilabel:`Open` button to add an exception.
+* If you are not presented with an :guilabel:`Open` button in the dialog, launch the application
+  again by right clicking on the application in Finder and selecting :guilabel:`Open` from the
+  context menu.
+
+The context menu can also be accessed by option-clicking if you have a one button mouse. This is
+done by holding down the option key on your keyboard and clicking on the application in Finder.
+
+.. note::
+   The novelWriter DMG is not signed because Apple doesn't currently provide a way for non-profit
+   open source projects to properly sign their installers. The novelWriter project doesn't have the
+   funding to pay for commercial software signing certificates.
+
+
+.. _a_started_pip:
+
+Installing from PyPi
+====================
+
+novelWriter is also available on the Python Package Index, or PyPi_. This install method works on
+all supported operating systems with a suitable Python environment.
+
+To install from PyPi you must first have the ``python`` and ``pip`` commands available on your
+system. You can download Python from `python.org`_. It is recommended that you install the latest
+version. If you are on Windows, also make sure to select the "Add Python to PATH" option during
+installation.
+
+To install novelWriter from PyPi, use the following command:
+
+.. code-block:: bash
+
+   pip install novelwriter
+
+To upgrade an existing installation, use:
+
+.. code-block:: bash
+
+   pip install --upgrade novelwriter
+
+When installing via pip, novelWriter can be launched from command line with:
+
+.. code-block:: bash
+
+   novelwriter
+
+Make sure the install location for pip is in your PATH variable. This is not always the case by
+default, and then you may get a "Not Found" error when running the ``novelwriter`` command.

docs/source/interface.rst

@@ -1,197 +0,0 @@
-***************
-User Interface
-***************
-
-The user interface is kept as simple as possible to avoid distractions when writing.
-The main window contains a tree view pane with the entire structure of the project, and a small details panel below it to display additional information about the currently selected item.
-
-Edit View
-=========
-
-Editing a document can be done by either double-clicking on it, or hitting the return key when a file is selected.
-This will open the document editor, which uses a simplified markdown format, described in the section below.
-
-The document currently being edited can also be viewed in parallel in a right hand side view pane.
-To view a document, simply press :kbd:`Ctrl-R`, or select a file and go to :menuselection:`Document --> View Document` in the menu.
-The document viewed does not need to be the same document currently being edited.
-If you are viewing the same document as the one you're editing, pressing :kbd:`Ctrl-R` again will update the document with your last changes.
-
-References to tags can be opened in the view pane from the document editor by moving the cursor to a reference to a tag and hitting :kbd:`Ctrl-Enter`.
-In the view panel, the references become clickable links, and the "Referenced By" panel at the bottom will show links to all documents referring back to it.
-
-.. note::
-   The "Referenced By" panel relies on an up-to-date index of the project.
-   If anything is missing, or seems wrong, the index can always be rebuilt from :menuselection:`Tools --> Rebuild Index` or by pressing :kbd:`F9`.
-
-Both the document editor and the viewer will show the label of the document as set in the Project Tree.
-Optionally, the full project path to the file can be shown.
-This can be set the Preferences.
-
-Clicking on the document title bar will select and reveal the file in the Project Tree, making it easier to find the project location of the file in a large project.
-
-Markdown Format
-===============
-
-The document editor uses a simplified markdown format.
-That is, it supports basic formatting like emphasis (italic), strong emphasis (bold) and strikethrough text, as well as four levels of headings.
-It is commonly recommended style to differentiate between strong emphasis and emphasis by using ``**`` for strong emphasis and ``_`` for emphasis, although Markdown generally supports also ``__`` for strong emphasis and ``*`` fdr emphasis.
-However, since the differentiation makes the highlighting and conversion significantly simpler and faster, in novelWriter this is a rule, not just a recommendation.
-
-In addition to these standard markdown features, the editor also allows for comments, that is text that is ignored by the word counter and not exported or, optionally, hidden in the document viewer.
-If the first word of a comment is "Synopsis:" (with the colon), the comment is treated specially, and will show up in the Outline View.
-The editor also has a minimal set of keywords used for setting tags and references between files.
-
-.. csv-table:: Formatting Syntax
-   :header: "Format", "Description"
-   :widths: 15, 50
-
-   "``# Title``",             "Heading level one. The space after the # is mandatory."
-   "``## Title``",            "Heading level two. The space after the # is mandatory."
-   "``### Title``",           "Heading level three. The space after the # is mandatory."
-   "``#### Title``",          "Heading level four. The space after the # is mandatory."
-   "``_text_``",              "The text is rendered as emphasised text (italicised)."
-   "``**text**``",            "The text is rendered as strongly emphasised text (bold)."
-   "``~~text~~``",            "Strikethrough text."
-   "``% text...``",           "A comment. The text is not exported by default, seen in viewer, or counted towards word counts."
-   "``% Synopsis: text...``", "A synopsis comment. Shows up in the Synopsis column of the Outline View, but is otherwise treated as a comment."
-   "``@keyword: value``",     "A keyword argument followed by a value, or a comma separated list of values."
-
-Some additional rules:
-
-1. The emphasis and strikethrough formatting tags do not allow spaces between the words and the tag itself.
-   That is, ``**text**`` is valid, ``**text **`` is not.
-2. More generally, the delimiters must be on the outer edge of words.
-   That is, ``some **text in bold** here`` is valid, ``some** text in bold** here`` is not.
-3. If using both ``**`` and ``_`` to wrap the same text, the underscore must be the inner wrapper.
-   This is due to the underscore also being a valid word character, so if they are on the outside, they violate rule 2.
-
-The editor and viewer also supports markdown standard hard line breaks, and preserves non-breaking spaces.
-A hard line break is achieved by leaving two or more spaces at the end of the line.
-Alternatively, the user can press :kbd:`Ctrl-K, Return` to insert this.
-A non-breaking space is inserted with :kbd:`Ctrl-K, Space`.
-
-Thin spaces are also supported, and can be inserted with :kbd:`Ctrl-K, Shift-Space`, and the non-breaking version of it with :kbd:`Ctrl-K, Ctrl-Space`.
-
-Both hard line breaks and non-breaking spaces are highlighted by the syntax highlighter as an alternate coloured background, depending on the selected theme.
-
-Project Outline View
-====================
-
-The Project Outline View is available as the second tab on the right hand side of the main window marked "Outline".
-The Outline View provides an overview of the novel structure, displaying a tree hierarchy of the elements of the novel, that is, the level 1 to 4 headings.
-
-Various meta data and information extracted from tags can be displayed in columns in the Outline View.
-To turn on or off specific columns, right click the header and select the columns you want to show.
-The order of the columns can be rearranged by dragging them to a different position.
-
-.. note::
-   The "Title" columns cannot be disabled or moved.
-
-The information viewed in teh Outline View is based on the Project Index.
-While novelWriter does its best to keep the index up-to-date when content changes, you can always rebuild it manually by pressing :kbd:`F9`.
-
-The Outline View itself can be regenerated by pressing :kbd:`F10`.
-You can also enable automatic updating in the :menuselection:`Tools` menu, which will trigger an update whenever the index is updated.
-You may want to disable this feature if your project is very large,
-
-Synopsis Feature
-================
-
-The "Synopsis" column of the Outline View takes its information from a specially formatted comment.
-In order to flag a comment as a Synopsis, add the word "Synopsis:" as the first word of the comment.
-The ":" is required, and "synopsis" is not case sensitive.
-If it is correctly formatted, the syntax highlighter will indicate this by altering the colour of the word.
-
-.. note::
-   Only one comment can be flagged as a synopsis comment for each heading.
-   If multiple comments are flagged as a synopsis, the last one will be used.
-
-Keyboard Shortcuts
-==================
-
-Most features are available as keyboard shortcuts.
-These are as following:
-
-.. csv-table:: Keyboard Shortcuts
-   :header: "Shortcut", "Description"
-   :widths: 15, 50
-
-   ":kbd:`Alt-1`",           "Switch focus to tree view pane."
-   ":kbd:`Alt-2`",           "Switch focus to document editor pane."
-   ":kbd:`Alt-3`",           "Switch focus to document viewer pane."
-   ":kbd:`Ctrl-.`",          "Correct word under cursor."
-   ":kbd:`Ctrl-,`",          "Open the Preferences dialog."
-   ":kbd:`Ctrl-/`",          "Change block format to comment."
-   ":kbd:`Ctrl--`",          "Strikethrough selected text, or word under cursor."
-   ":kbd:`Ctrl-0`",          "Remove block formatting for block under cursor."
-   ":kbd:`Ctrl-1`",          "Change block format to header level 1."
-   ":kbd:`Ctrl-2`",          "Change block format to header level 2."
-   ":kbd:`Ctrl-3`",          "Change block format to header level 3."
-   ":kbd:`Ctrl-4`",          "Change block format to header level 4."
-   ":kbd:`Ctrl-A`",          "Select all text in document."
-   ":kbd:`Ctrl-B`",          "Format selected text, or word under cursor, with strong emphasis (bold)."
-   ":kbd:`Ctrl-C`",          "Copy selected text to clipboard."
-   ":kbd:`Ctrl-D`",          "Wrap selected text, or word under cursor, in double quotes."
-   ":kbd:`Ctrl-E`",          "If in tree view, edit a document or folder settings. (Same as :kbd:`F2`)"
-   ":kbd:`Ctrl-F`",          "Open the search bar and search for selected word, if any is selected."
-   ":kbd:`Ctrl-G`",          "Find next occurrence of word in current document. (Same as :kbd:`F3`)"
-   ":kbd:`Ctrl-H`",          "Open the search and replace bar and search for selected word, if any is selected. (On Mac, this is :kbd:`Cmd-=`)"
-   ":kbd:`Ctrl-I`",          "Format selected text, or word under cursor, with emphasis (italic)."
-   ":kbd:`Ctrl-N`",          "Create new document."
-   ":kbd:`Ctrl-O`",          "Open selected document."
-   ":kbd:`Ctrl-Q`",          "Exit novelWriter."
-   ":kbd:`Ctrl-R`",          "If in tree view, open a document for viewing. If editor pane has focus, open current document for viewing."
-   ":kbd:`Ctrl-S`",          "Save the current document in the editor."
-   ":kbd:`Ctrl-V`",          "Paste text from clipboard to cursor position."
-   ":kbd:`Ctrl-W`",          "Close the current document in the editor."
-   ":kbd:`Ctrl-X`",          "Cut selected text to clipboard."
-   ":kbd:`Ctrl-Y`",          "Redo latest undo."
-   ":kbd:`Ctrl-Z`",          "Undo latest changes."
-   ":kbd:`Ctrl-F7`",         "Toggle spell checking."
-   ":kbd:`Ctrl-F10`",        "Toggle automatic updating of project outline."
-   ":kbd:`Ctrl-Del`",        "If in tree view, move a document to trash, or delete a folder."
-   ":kbd:`Ctrl-Enter`",      "Open the tag or reference under the cursor in the view panel."
-   ":kbd:`Ctrl-Shift-,`",    "Open the Project Settings dialog."
-   ":kbd:`Ctrl-Shift-/`",    "Remove block formatting for block under cursor."
-   ":kbd:`Ctrl-Shift-1`",    "Replace occurrence of word in current document, and search for next occurrence."
-   ":kbd:`Ctrl-Shift-A`",    "Select all text in current paragraph."
-   ":kbd:`Ctrl-Shift-B`",    "Format selected text, or word under cursor, with very strong emphasis (bold and italic)."
-   ":kbd:`Ctrl-Shift-D`",    "Wrap selected text, or word under cursor, in single quotes."
-   ":kbd:`Ctrl-Shift-G`",    "Find previous occurrence of word in current document. (Same as :kbd:`Shift-F3`"
-   ":kbd:`Ctrl-Shift-I`",    "Import text to the current document from a text file."
-   ":kbd:`Ctrl-Shift-N`",    "Create new folder."
-   ":kbd:`Ctrl-Shift-O`",    "Open a project."
-   ":kbd:`Ctrl-Shift-R`",    "Close the document view pane."
-   ":kbd:`Ctrl-Shift-S`",    "Save the current project."
-   ":kbd:`Ctrl-Shift-W`",    "Close the current project."
-   ":kbd:`Ctrl-Shift-Up`",   "Move item one step up in the tree view."
-   ":kbd:`Ctrl-Shift-Down`", "Move item one step down in the tree view."
-   ":kbd:`F1`",              "Open documentation. This just tries to send the documentation URL ti your browser."
-   ":kbd:`F2`",              "If in tree view, edit a document or folder settings. (Same as :kbd:`Ctrl-E`)"
-   ":kbd:`F3`",              "Find next occurrence of word in current document. (Same as :kbd:`Ctrl-G`)"
-   ":kbd:`F5`",              "Open the Build Novel Project dialog."
-   ":kbd:`F6`",              "Open the Writing Statistics dialog."
-   ":kbd:`F7`",              "Re-run spell checker."
-   ":kbd:`F8`",              "Activate Zen Mode, hiding project tree and view panel."
-   ":kbd:`F9`",              "Re-build project index."
-   ":kbd:`F10`",             "Re-build project outline."
-   ":kbd:`F11`",             "Activate full screen mode."
-   ":kbd:`Shift-F3`",        "Find previous occurrence of word in current document. (Same as :kbd:`Ctrl-Shift-G`"
-   ":kbd:`Enter`",           "If in tree view, open a document for editing."
-
-.. note::
-   On macOS, replace :kbd:`Ctrl` with :kbd:`Cmd`.
-
-A set of insert features are also available through shortcuts, but they require a double combination of shortcuts.
-
-.. csv-table:: Keyboard Shortcuts
-   :header: "Shortcut", "Description"
-   :widths: 30, 50
-
-   ":kbd:`Ctrl-K, -`",           "Insert a short dash (en dash)."
-   ":kbd:`Ctrl-K, _`",           "Insert a long dash (em dash)."
-   ":kbd:`Ctrl-K, .`",           "Insert ellipsis."
-   ":kbd:`Ctrl-K, Return`",      "Insert a hard line break."
-   ":kbd:`Ctrl-K, Space`",       "Insert a non-breaking space."
-   ":kbd:`Ctrl-K, Shift-Space`", "Insert a thin space."
-   ":kbd:`Ctrl-K, Ctrl-Space`",  "Insert a thin non-breaking space."

docs/source/introduction.rst

@@ -1,55 +0,0 @@
-************
-Introduction
-************
-
-novelWriter is a simple, multi-document plain text editor using a modified markdown syntax to apply simple formatting.
-Additional features that are not standard markdown are available through special meta data keywords.
-These keywords make it possible to inter-link documents, and generate an overview of the entire novel project and how the various files are interconnected.
-
-Design Philosophy
------------------
-
-The user interface is intended to be as minimalistic as practically possible, while at the same time provide a complete set of features needed for writing a novel.
-
-.. note::
-   novelWriter is not intended to be a full office type word processor.
-   It doesn't support images, links, tables, and its formatting is limited to headers, and bold, italicised and underlined text.
-
-Most features are accessible through the menu and through keyboard shortcuts.
-The colour scheme of the user interface can be modified with various themes, and new themes are fairly straight forward to add.
-
-The project itself is laid out in a tree view on the left hand side of the main window.
-It has various sections, called *root folders*, for the various types of supporting files that the user may want to add to the project.
-The novel itself lives under its own root folder.
-
-Project Layout
---------------
-
-The layout of the novel itself is managed through the four supported heading levels, H1 through H4.
-H1 is used for the book title, and for partitions.
-H2 is used for chapter tiles.
-H3 is reserved for scene titles.
-H4 is for section titles within scenes, if such granularity is necessary.
-
-For the files designated as project notes, the usage of headers imply no structural meaning, and the user is free to do whatever they want.
-
-Project Export
---------------
-
-The project can at any time be exported to a range of different formats.
-Natively, novelWriter supports export to plain text file, HTML document, novelWriter flavoured markdown, standard markdown (requires Qt 5.14), and to a basic Open Document.
-In addition, printing and printing to PDF is also possible.
-The best supported export format is HTML, which can be imported or converted by a number of other tools like Pandoc, or simply imported into Libre Office and similar.
-
-Screenshot
-----------
-
-**novelWriter with default system theme:**
-
-.. image:: images/screenshot_default.png
-   :width: 800
-
-**novelWriter with dark theme:**
-
-.. image:: images/screenshot_dark.png
-   :width: 800

docs/source/more_counting.rst

@@ -0,0 +1,98 @@
+.. _a_counting:
+
+********************
+Word and Text Counts
+********************
+
+This is an overview of how words and other counts of your text are performed. The counting rules
+should be relatively standard, and are compared to Libre Office Writer rules.
+
+The counts provided in the app on the raw text is meant to be approximate. For more accurate
+counts, you need to build your manuscript in the **Manuscript Tool** and check the counts on the
+generated preview.
+
+
+Text Word Counts and Stats
+==========================
+
+These are the rules for the main counts available for for each document in a project.
+
+For all counts, the following rules apply.
+
+#. Short (–) and long (—) dashes are considered word separators.
+#. Any line starting with ``%`` or ``@`` is ignored.
+#. Trailing white spaces are ignored, including line breaks.
+#. Leading ``>`` and trailing ``<`` are ignored with any spaces next to them.
+#. Valid shortcodes and other commands wrapped in brackets ``[]`` are ignored.
+#. In-line Markdown syntax in text paragraphs is treated as part of the text.
+
+After the above preparation of the text, the following counts are available.
+
+**Character Count**
+   The character count is the sum of characters per line, including leading and in-text white space
+   characters, but excluding trailing white space characters. Shortcodes in the text are not
+   included, but Markdown codes are. Only headings and text are counted.
+
+**Word Count**
+   The words count is the sum of blocks of continuous character per line separated by any number of
+   white space characters or dashes. Only headings and text are counted.
+
+**Paragraph Count**
+   The paragraph count is the number of text blocks separated by one or more empty line. A line
+   consisting only of white spaces is considered empty.
+
+
+Manuscript Counts
+=================
+
+These are the rules for the counts available for a manuscript in the **Manuscript Tool**. The rules
+have been tuned to agree with LibreOffice Writer, but will vary slightly depending on the content
+of your text. LibreOffice Writer also counts the text in the page header, which the **Manuscript
+Tool** does not.
+
+The content of each line is counted after all formatting has been processed, so the result will be
+more accurate than the counts for text documents elsewhere in the app. The following rules apply:
+
+#. Short (–) and long (—) dashes are considered word separators.
+#. Leading and trailing white spaces are generally included, but paragraph breaks are not.
+#. Hard line breaks within paragraph are considered white space characters.
+#. All formatting codes are ignored, including shortcodes, commands and Markdown.
+#. Scene and section separators are counted.
+#. Comments and meta data lines are counted after they are formatted.
+#. Headers are counted after they are formatted with custom formats.
+
+The following counts are available:
+
+**Headings**
+   The number of headings in the manuscript.
+
+**Paragraphs**
+   The number of body text paragraphs in the manuscript.
+
+**Words**
+   The number of words in the manuscript, including any comments and meta data text.
+
+**Words in Text**
+   The number of words in body text paragraphs, excluding all other text.
+
+**Words in Headings**
+   The number of words in headings, including inserted formatting like chapter numbers, etc.
+
+**Characters**
+   The number of characters in all lines, including any comments and meta data text. Paragraph
+   breaks are not counted, but in-paragraph hard line breaks are.
+
+**Character in Text**
+   The number of characters in body text paragraphs. Paragraph breaks are not counted, but
+   in-paragraph hard line breaks are.
+
+**Characters in Headings**
+   The number of characters in headings.
+
+**Character in Text, No Spaces**
+   The number of characters in body text paragraphs considered part of a word or punctuation. That
+   is, white space characters are not counted.
+
+**Character in Headings, No Spaces**
+   The number of characters in headings considered part of a word or punctuation. That is, white
+   space characters are not counted.

docs/source/more_customise.rst

@@ -0,0 +1,199 @@
+.. _a_custom:
+
+**************
+Customisations
+**************
+
+.. _Enchant: https://abiword.github.io/enchant
+.. _Free Desktop: https://cgit.freedesktop.org/libreoffice/dictionaries/tree/
+
+There are a few ways you can customise novelWriter yourself. Currently, you can add new GUI themes,
+your own syntax themes, and install additional dictionaries.
+
+
+.. _a_custom_dict:
+
+Spell Check Dictionaries
+========================
+
+novelWriter uses Enchant_ as the spell checking tool. Depending on your operating system, it may or
+may not load all installed spell check dictionaries automatically.
+
+Linux and MacOS
+---------------
+
+On Linux and MacOS, you generally only have to install hunspell, aspell or myspell dictionaries on
+your system like you do for other applications. See your distro or OS documentation for how to do
+this. These dictionaries should show up as available spell check languages in novelWriter.
+
+Windows
+-------
+
+For Windows, English is included with the installation. For other languages you have to download
+and add dictionaries yourself.
+
+**Install Tool**
+
+A small tool to assist with this can be found under **Tools > Add Dictionaries**. It will import
+spell checking dictionaries from Free Office or Libre Office extensions. The dictionaries are then
+installed in the install location for the Enchant library and should thus work for any application
+that uses Enchant for spell checking.
+
+**Manual Install**
+
+If you prefer to do this manually or want to use a different source than the ones mentioned above,
+You need to get compatible dictionary files for your language. You need two files files ending with
+``.aff`` and ``.dic``. These files must then be copied to the following location: 
+
+``C:\Users\<USER>\AppData\Local\enchant\hunspell``
+
+This assumes your user profile is stored at ``C:\Users\<USER>``. The last one or two folders may
+not exist, so you may need to create them.
+
+You can find the various dictionaries on the `Free Desktop`_ website.
+
+.. note::
+   The Free Desktop link points to a repository, and what may look like file links inside the
+   dictionary folder are actually links to web pages. If you right-click and download those, you
+   get HTML files, not dictionaries!
+
+   In order to download the actual dictionary files, right-click the "plain" label at the end of
+   each line and download that.
+
+
+.. _a_custom_theme:
+
+Syntax and GUI Themes
+=====================
+
+Adding your own GUI and syntax themes is relatively easy, although it requires that you manually
+edit config files with colour values. The themes are defined by simple plain text config files with
+meta data and colour settings.
+
+In order to make your own versions, first copy one of the existing files to your local computer and
+modify it as you like.
+
+* The existing syntax themes are stored in
+  `novelwriter/assets/syntax <https://github.com/vkbo/novelWriter/tree/main/novelwriter/assets/syntax>`_.
+* The existing GUI themes are stored in
+  `novelwriter/assets/themes <https://github.com/vkbo/novelWriter/tree/main/novelwriter/assets/themes>`_.
+* The existing icon themes are stored in
+  `novelwriter/assets/icons <https://github.com/vkbo/novelWriter/tree/main/novelwriter/assets/icons>`_.
+
+Remember to also change the name of your theme by modifying the ``name`` setting at the top of the
+file, otherwise you may not be able to distinguish them in **Preferences**.
+
+For novelWriter to be able to locate the custom theme files, you must copy them to the
+:ref:`a_locations_data` location in your home or user area. There should be a folder there named
+``syntax`` for syntax themes, just ``themes`` for GUI themes, and ``icons`` for icon themes. These
+folders are created the first time you start novelWriter.
+
+Once the files are copied there, they should show up in **Preferences** with the label you
+set as ``name`` inside the file.
+
+.. versionadded:: 2.0
+   The ``icontheme`` value was added to GUI themes. Make sure you set this value in existing custom
+   themes. Otherwise, novelWriter will try to guess your icon theme, and may not pick the most
+   suitable one.
+
+
+Custom GUI and Icons Theme
+--------------------------
+
+A GUI theme ``.conf`` file consists of the following settings:
+
+.. code-block:: cfg
+
+   [Main]
+   name        = My Custom Theme
+   description = A description of my custom theme
+   author      = Jane Doe
+   credit      = John Doe
+   url         = https://example.com
+   license     = CC BY-SA 4.0
+   licenseurl  = https://creativecommons.org/licenses/by-sa/4.0/
+   icontheme   = typicons_light
+
+   [Palette]
+   window          = 100, 100, 100
+   windowtext      = 100, 100, 100
+   base            = 100, 100, 100
+   alternatebase   = 100, 100, 100
+   text            = 100, 100, 100
+   tooltipbase     = 100, 100, 100
+   tooltiptext     = 100, 100, 100
+   button          = 100, 100, 100
+   buttontext      = 100, 100, 100
+   brighttext      = 100, 100, 100
+   highlight       = 100, 100, 100
+   highlightedtext = 100, 100, 100
+   link            = 100, 100, 100
+   linkvisited     = 100, 100, 100
+
+   [GUI]
+   statusnone      = 100, 100, 100
+   statussaved     = 100, 100, 100
+   statusunsaved   = 100, 100, 100
+
+In the Main section you must at least define the ``name`` and ``icontheme`` settings. The
+``icontheme`` settings should correspond to one of the internal icon themes, either
+``typicons_light`` or ``typicons_dark``, or to an icon theme in your custom icons directory. The
+setting must match the icon theme's folder name.
+
+The Palette values correspond to the Qt enum values for ``QPalette::ColorRole``, see the
+`Qt documentation <https://doc.qt.io/qt-5.15/qpalette.html#ColorRole-enum>`_ for more details. The
+colour values are RGB numbers on the format ``r, g, b`` where each is an integer from ``0`` to
+``255``. Omitted values are not loaded and will use default values.
+
+
+Custom Syntax Theme
+-------------------
+
+A syntax theme ``.conf`` file consists of the following settings:
+
+.. code-block:: cfg
+
+   [Main]
+   name       = My Syntax Theme
+   author     = Jane Doe
+   credit     = John Doe
+   url        = https://example.com
+   license    = CC BY-SA 4.0
+   licenseurl = https://creativecommons.org/licenses/by-sa/4.0/
+
+   [Syntax]
+   background     = 255, 255, 255
+   text           =   0,   0,   0
+   link           =   0,   0,   0
+   headertext     =   0,   0,   0
+   headertag      =   0,   0,   0
+   emphasis       =   0,   0,   0
+   straightquotes =   0,   0,   0
+   doublequotes   =   0,   0,   0
+   singlequotes   =   0,   0,   0
+   hidden         =   0,   0,   0
+   shortcode      =   0,   0,   0
+   keyword        =   0,   0,   0
+   value          =   0,   0,   0
+   optional       =   0,   0,   0
+   spellcheckline =   0,   0,   0
+   errorline      =   0,   0,   0
+   replacetag     =   0,   0,   0
+   modifier       =   0,   0,   0
+   texthighlight  = 255, 255, 255, 128
+
+In the Main section, you must define at least the ``name`` setting. The Syntax colour values are
+RGB(A) numbers of the format ``r, g, b, a`` where each is an integer from ``0`` to ``255``. The
+fourth value is the alpha channel, which can be omitted.
+
+Omitted syntax colours default to black, except ``background`` which defaults to white, and
+``texthighlight`` which defaults to white with half transparency.
+
+.. versionadded:: 2.2
+   The ``shortcode`` syntax colour entry was added.
+
+.. versionadded:: 2.3
+   The ``optional`` syntax colour entry was added.
+
+.. versionadded:: 2.4
+   The ``texthighlight`` syntax colour entry was added.

docs/source/more_projectformat.rst

@@ -0,0 +1,133 @@
+.. _a_prjfmt:
+
+**********************
+Project Format Changes
+**********************
+
+.. _File Format Spec 1.5: _static/fileformatspec15.pdf
+.. _documentation: https://docs.novelwriter.io/
+
+Most of the changes to the file formats over the history of novelWriter have no impact on the
+user side of things. The project files are generally updated automatically. However, some of the
+changes require minor actions from the user.
+
+The key changes in the formats are listed in this chapter, as well as the user actions required,
+where applicable.
+
+.. only:: not html
+
+   A full project file format specification is available in the online documentation_.
+
+.. caution::
+   When you update a project from one format version to the next, the project can no longer be
+   opened by a version of novelWriter prior to the version where the new file format was
+   introduced. You will get a notification about any updates to your project file format and will
+   have the option to decline the upgrade.
+
+.. only:: html
+
+   **For Developers**
+
+   A full description of the current file format is available in the
+   :download:`File Format Spec 1.5 <fileformatspec15.pdf>`
+   document, available as a PDF. This document is intended for contributors to novelWriter, those
+   building project conversion tools, either to or from tne novelWriter format, and for those who
+   wish to make their own templating system.
+
+
+.. _a_prjfmt_1_5:
+
+Format 1.5 Changes
+==================
+
+This project format was introduced in novelWriter version 2.0 RC 2.
+
+This is a modification of the 1.4 format. It makes the XML more consistent in that meta data have
+been moved to their respective section nodes as attributes, and key/value settings now have a
+consistent format. Logical flags are saved as yes/no instead of Python True/False, and the main
+heading of the document is now saved to the item rather than in the index. The conversion is done
+automatically the first time a project is loaded. No user action is required.
+
+
+.. _a_prjfmt_1_4:
+
+Format 1.4 Changes
+==================
+
+This project format was introduced in novelWriter version 2.0 RC 1. Since this was a release
+candidate, it is unlikely that your project uses it, but it may be the case if you've installed a
+pre-release.
+
+This format changes the way project items (folders, documents and notes) are stored. It is a more
+compact format that is simpler and faster to parse, and easier to extend. The conversion is done
+automatically the first time a project is loaded. No user action is required.
+
+
+.. _a_prjfmt_1_3:
+
+Format 1.3 Changes
+==================
+
+This project format was introduced in novelWriter version 1.5.
+
+With this format, the number of document layouts was reduced from eight to two. The conversion of
+document layouts is performed automatically when the project is opened.
+
+Due to the reduction of layouts, some features that were previously controlled by these layouts
+will be lost. These features are instead now controlled by syntax codes, so to recover these
+features, some minor modification must be made to select documents by the user.
+
+The manual changes the user must make should be very few as they apply to document layouts that
+should be used only a few places in any given project. These are as follows:
+
+**Title Pages**
+
+* The formatting of the level one title on the title page must be changed from ``# Title Text`` to
+  ``#! Title Text`` in order to retain the previous functionality. See :ref:`a_fmt_head`.
+* Any text that was previously centred on the page must be manually centred using the text
+  alignment feature. See :ref:`a_fmt_align`.
+
+**Unnumbered Chapters**
+
+* Since the specific layout for unnumbered chapters has been dropped, such chapters must all use
+  the ``##! Chapter Name`` formatting code instead of ``## Chapter Name``. This also includes
+  chapters marked by an asterisk: ``## *Chapter Name``, as this feature has also been dropped.
+  See :ref:`a_fmt_head`.
+
+**Plain Pages**
+
+* The layout named "Plain Page" has also been removed. The only feature of this layout was that it
+  ensured that the content always started on a fresh page. In the new format, fresh pages can be
+  set anywhere in the text with the ``[NEW PAGE]`` code. See :ref:`a_fmt_break`.
+
+
+.. _a_prjfmt_1_2:
+
+Format 1.2 Changes
+==================
+
+This project format was introduced in novelWriter version 0.10.
+
+With this format, the way auto-replace entries were stored in the main project XML file changed.
+
+
+.. _a_prjfmt_1_1:
+
+Format 1.1 Changes
+==================
+
+This project format was introduced in novelWriter version 0.7.
+
+With this format, the ``content`` folder was introduced in the project storage. Previously, all
+novelWriter documents were saved in a series of folders numbered from ``data_0`` to ``data_f``.
+
+It also reduces the number of meta data and cache files. These files are automatically deleted if
+an old project is opened. This was also when the Table of Contents file was introduced.
+
+
+.. _a_prjfmt_1_0:
+
+Format 1.0 Changes
+==================
+
+This is the original file format and project structure. It was in use up to version 0.6.3.

docs/source/notes.rst

@@ -1,23 +0,0 @@
-************************
-Supporting Files (Notes)
-************************
-
-Supporting files, or notes, are any files stored in root folders that are not the Novel root folder.
-These files are intended for summaries and outlines of the various plot elements, characters, locations, and so on, of the novel.
-These are not required, but making at least minimal files for each such element, and add a tag to them, makes it possible to use the Outline View feature to see how each element intersects with each section of the novel itself, and add clickable cross-references between document in the editor and viewer.
-
-File Tags
-=========
-
-Each new heading in a note file can have a tag associated with it.
-The format of a tag is ``@tag: tagname``, where tagname is a unique identifier.
-Tags can then be referenced in the novel files, or other note files, and will show up in the Outline View and in the back-reference panel when a document is being viewed.
-
-The syntax highlighter will alert the user that the keyword is correctly used and that the tag is allowed, that is, the tag is unique.
-Duplicate tags should be detected as long as the index is up to date.
-
-The tag is the only part of these files that the application uses.
-The rest of the file is there for the writer to use in whatever way they wish.
-
-A note file can also reference other note files in the same way novel files do.
-When the note file is opened in the view pane, these become clickable links, making it easier to follow connections in the plot.

docs/source/project_manuscript.rst

@@ -0,0 +1,223 @@
+.. _a_manuscript:
+
+***********************
+Building the Manuscript
+***********************
+
+.. _Pandoc: https://pandoc.org/
+
+You can at any time build a manuscript, an outline of your notes, or any other type of document
+from the text in your project. All of this is handled by the **Manuscript Build** tool. You can
+activate it from the sidebar, the **Tools** menu, or by pressing :kbd:`F5`.
+
+.. versionadded:: 2.1
+   This tool is new for version 2.1. A simpler tool was used for earlier versions. The simpler tool
+   only allows you to define a single set of options for the build, but otherwise had much the same
+   functionality.
+
+
+.. _a_manuscript_main:
+
+The Manuscript Build Tool
+=========================
+
+.. figure:: images/fig_manuscript_build.png
+   :width: 80%
+
+   The **Manuscript Build** tool main window.
+
+The main window of the **Manuscript Build** tool contains a list of all the builds you have
+defined, a selection of settings, and a few buttons to generate preview, open the print dialog, or
+run the build to create a manuscript document.
+
+
+Outline and Word Counts
+-----------------------
+
+.. figure:: images/fig_manuscript_build_outline.png
+   :width: 80%
+
+   The **Manuscript Build** tool main window with the **Outline** visible.
+
+The **Outline** tab on the left lets you navigate the headings in the preview document. It will
+show up to scene level headings for novel documents, and level 2 headings for notes.
+
+A collapsible panel of word and character counts are also available below the preview document.
+These are calculated from the text you have included in the document, and are more accurate counts
+than what's available in the project tree since they are counted *after formatting*.
+
+For a detailed description on how they are counted, see :ref:`a_counting`.
+
+
+.. _a_manuscript_settings:
+
+Build Settings
+==============
+
+Each build definition can be edited by opening it in the **Manuscript Build Settings** dialog,
+either by double-clicking or by selecting it and pressing the edit button in the toolbar.
+
+.. tip::
+   You can keep the **Manuscript Build Settings** dialog open while testing the different options,
+   and just hit the :guilabel:`Apply` button. You can test the result of your settings by pressing
+   the :guilabel:`Preview` button in the main **Manuscript Build** window. When you're happy with
+   the result, you can close the settings.
+
+
+Document Selection
+------------------
+
+.. figure:: images/fig_build_settings_selections.png
+   :width: 80%
+
+   The **Selections** page of the **Manuscript Build Settings** dialog.
+
+The **Selections** page of the **Manuscript Build Settings** dialog allows you to fine tune which
+documents are included in the build. They are indicated by a green arrow icon in the last column.
+On the right you have some filter options for selecting content of a specific type, and a set of
+switches for which root folders to include.
+
+You can override the result of these filters by marking one or more documents and selecting to
+explicitly include or exclude them by using the buttons below the tree view. The last button can be
+used to reset the override and return control to the filter settings.
+
+In the figure, the green arrow icon and the blue pin icon indicates which documents are included,
+and the red forbidden icon indicates that a document is explicitly excluded.
+
+
+.. _a_manuscript_settings_head:
+
+Formatting Headings
+-------------------
+
+.. figure:: images/fig_build_settings_headings.png
+   :width: 80%
+
+   The **Headings** page of the **Manuscript Build Settings** dialog.
+
+The **Headings** page of the **Manuscript Build Settings** dialog allows you to set how the
+headings in your :term:`Novel Documents` are formatted. By default, the title is just copied as-is,
+indicated by the ``{Title}`` format. You can change this to for instance add chapter numbers and
+scene numbers, or insert character names, like shown in the figure above.
+
+Clicking the edit button next to a format will copy the formatting string into the edit box where
+it can be modified, and where a syntax highlighter will help indicate which parts are automatically
+generated by the build tool. The :guilabel:`Insert` button is a dropdown list of these formats, and
+selecting one will insert it at the position of the cursor.
+
+Any text you add that isn't highlighted in colours will remain in your formatted titles.
+``{Title}`` will always be replaced by the text in the heading from your documents.
+
+You can preview the result of these format strings by clicking :guilabel:`Apply`, and then clicking
+:guilabel:`Preview` in the **Manuscript Build** tool main window.
+
+
+Scene Separators
+^^^^^^^^^^^^^^^^
+
+If you don't want any titles for your scenes (or for your sections if you have them), you can leave
+the formatting boxes empty. If so, an empty paragraph will be inserted between the scenes or
+sections instead, resulting in a gap in the text. You can also switch on the :guilabel:`Hide`
+setting, which will ignore them completely. That is, there won't even be an extra gap inserted.
+
+Alternatively, if you want a separator text between them, like the common ``* * *``, you can enter
+the desired separator text as the format. If the format is any piece of static text, it will always
+be treated as a separator.
+
+
+.. _a_manuscript_settings_head_hard:
+
+Hard and Soft Scenes
+^^^^^^^^^^^^^^^^^^^^
+
+If you wish to distinguish between so-called soft and hard scene breaks, you can use the
+alternative scene heading format in your text. You can then give these headings a different
+formatting in the **Headings** settings.
+
+See :ref:`a_fmt_head` for more info on how to format headings in your text.
+
+
+Output Settings
+---------------
+
+The **Content**, **Format** and **Output** pages of the **Manuscript Build Settings** dialog
+control a number of other settings for the output. Some of these only apply to specific output
+formats, which is indicated by the section headings on the settings pages.
+
+
+.. _a_manuscript_build:
+
+Building Manuscript Documents
+=============================
+
+.. figure:: images/fig_build_build.png
+   :width: 80%
+
+   The **Manuscript Build** dialog used for writing the actual manuscript documents.
+
+When you press the :guilabel:`Build` button on the **Build Manuscript** tool main window, a special
+file dialog opens up. This is where you pick your desired output format and where to write the
+file.
+
+On the left side of the dialog is a list of all the available file formats, and on the right, a
+list of the documents which are included based on the build definition you selected. You can choose
+an output path, and set a base file name as well. The file extension will be added automatically.
+
+To generate the manuscript document, press the :guilabel:`Build` button. A small progress bar will
+show the build progress, but for small projects it may pass very fast.
+
+
+File Formats
+------------
+
+Currently, four document formats are supported.
+
+Open Document Format
+   The Build tool can produce either an ``.odt`` file, or an ``.fodt`` file. The latter is just a
+   flat version of the document format as a single XML file. Most rich text editors support the
+   former, and only a few the latter.
+
+novelWriter HTML
+   The HTML format writes a single ``.htm`` file with minimal style formatting. The HTML document
+   is suitable for further processing by document conversion tools like Pandoc_, for importing in
+   word processors, or for printing from browser.
+
+novelWriter Markup
+   This is simply a concatenation of the project documents selected by the filters into a ``.txt``
+   file. The documents are stacked together in the order they appear in the project tree, with
+   comments, tags, etc. included if they are selected. This is a useful format for exporting the
+   project for later import back into novelWriter.
+
+Standard/Extended Markdown
+   The Markdown format comes in both Standard and Extended flavour. The *only* difference in terms
+   of novelWriter functionality is the support for strike through text, which is not supported by
+   the Standard flavour.
+
+
+Additional Formats
+------------------
+
+In addition to the above document formats, the novelWriter HTML and Markup formats can also be
+wrapped in a JSON file. These files will have a meta data entry and a body entry. For HTML, also
+the accompanying CSS styles used by the preview are included.
+
+The text body is saved in a two-level list. The outer list contains one entry per document, in the
+order they appear in the project tree. Each document is then split up into a list as well, with one
+entry per paragraph it contains.
+
+These files are mainly intended for scripted post-processing for those who want that option. A JSON
+file can be imported directly into a Python dict object or a PHP array, to mentions a few options.
+
+
+.. _a_manuscript_print:
+
+Print and PDF
+=============
+
+The :guilabel:`Print` button allows you to print the content in the preview window. You can either
+print to one of your system's printers, or select PDF as your output format from the printer icon
+on the print dialog.
+
+.. note::
+   The paper format should in all cases default to whatever your system default is. If you want to
+   change it, you have to select it from the **Print Preview** dialog.

docs/source/project_overview.rst

@@ -0,0 +1,368 @@
+.. _a_proj:
+
+**************
+Novel Projects
+**************
+
+New projects can be created from the **Project** menu by selecting **Create or Open Project**. This
+will open the **Welcome** dialog, where you can select the :guilabel:`New` button that will assist
+you in creating a new project. This dialog is also displayed when you start novelWriter.
+
+A novelWriter project requires a dedicated folder for storing its files on the local file system.
+If you're interested in the details, you can have a look at the chapter :ref:`a_storage`.
+
+A list of recently opened projects is maintained, and displayed in the **Welcome** dialog. A
+project can be removed from this list by selecting it and pressing the :kbd:`Del` key or by
+right-clicking it and selecting the **Remove Project** option.
+
+.. figure:: images/fig_welcome.jpg
+
+   The project list (left) and new project form (right) of the :guilabel:`Welcome` dialog.
+
+Project-specific settings are available in **Project Settings** in the **Project** menu. See
+further details below in the :ref:`a_proj_settings` section.
+
+Details about the project's novel text, including word counts, and a table of contents with word
+and page counts, is available through the **Novel Details** dialog. Statistics about the project
+is also available in the **Manuscript Build** tool.
+
+
+.. _a_proj_roots:
+
+Project Roots
+=============
+
+Projects are structured into a set of top level folders called "Root Folders". They are visible in
+the project tree at the left side of the main window.
+
+The :term:`novel documents` go into a root folder of type **Novel**. :term:`Project notes` go into
+the other root folders. These other root folder types are intended for your notes on the various
+elements of your story. Using them is of course entirely optional.
+
+A new project may not have all of the root folders present, but you can add the ones you want from
+the project tree tool bar.
+
+Each root folder has one or more :term:`reference` :term:`keyword` associated with it that is used
+to reference them from other documents and notes. The intended usage of each type of root folder is
+listed below. However, aside from the **Novel** folder, no restrictions are applied by the
+application on what you put in them. You can use them however you want.
+
+The root folder system is closely connected to how the Tags and References system works. For more
+details, see the :ref:`a_references` chapter.
+
+
+Root Folder Types
+-----------------
+
+**Novel**
+   This is the root folder type for text that goes into the final novel or novels. This class of
+   documents have other rules and features than the project notes. See :ref:`a_struct` for more
+   details.
+
+**Plot**
+   This is the root folder type where main plots can be outlined. It is optional, but adding at
+   least brief notes can be useful in order to tag plot elements for the **Outline View**. Tags in
+   this folder can be references using the ``@plot`` keyword.
+
+**Characters**
+   Character notes go in this root folder type. These are especially important if you want to use
+   the **Outline View** to see which character appears where, which part of the story is told from
+   a specific character's point-of-view, or focusing on a particular character's storyline.
+
+   The character names can also be inserted into for instance chapter titles when you create your
+   manuscript. Tags in this type of folder can be referenced using the ``@pov`` keyword for
+   point-of-view characters, ``@focus`` for a focus character, or the ``@char`` keyword for any
+   other character present.
+
+**Locations**
+   The locations folder type is for various scene locations that you want to track. Tags in this
+   folder can be references using the ``@location`` keyword.
+
+**Timeline**
+   If the story has multiple plot timelines or jumps in time within the same plot, this folder type
+   can be used to track this. Tags in this type of folder can be references using the ``@time``
+   keyword.
+
+**Objects**
+   Important objects in the story, for instance physical objects that change hands often, can be
+   tracked here. Tags in this type of folder can be references using the ``@object`` keyword.
+
+**Entities**
+   Does your plot have many powerful organisations or companies? Or other entities that are part of
+   the plot? They can be organised here. Tags in this type of folder can be references using the
+   ``@entity`` keyword.
+
+**Custom**
+   The custom root folder type can be used for tracking anything else not covered by the above
+   options. Tags in this folder type can be references using the ``@custom`` keyword.
+
+The root folders are closely tied to the tags and reference system. Each folder type corresponds to
+the categories of tags that can be used to reference them. For more information about the tags
+listed, see :ref:`a_references_references`.
+
+.. note::
+   You can rename root folders to whatever you want. However, this doesn't change the reference
+   keyword or what they do.
+
+.. versionadded:: 2.0
+   As of version 2.0, you can make multiple root folders of each kind to split up your project.
+
+
+.. _a_proj_roots_del:
+
+Deleted Documents
+-----------------
+
+Deleted documents are moved into a special **Trash** root folder. Documents in the trash folder can
+then be deleted permanently, either individually, or by emptying the trash from the menu. Documents
+in the trash folder are removed from the :term:`project index` and cannot be referenced.
+
+A document or a folder can be moved to trash from the **Project** menu, or by pressing
+:kbd:`Ctrl+Shift+Del`. Root folders can only be removed when they are empty.
+
+
+.. _a_proj_roots_out:
+
+Archived Documents
+------------------
+
+If you don't want to delete a document, or put it in the **Trash** folder where it may be deleted
+accidentally, but still want it out of your main project tree, you can create an **Archive** root
+folder instead and move it there. It has the same effect as moving it to **Trash**, but it is safe
+from deletion.
+
+You can drag any document to this folder and preserve its settings. The document will always be
+excluded from the **Build Manuscript** tool. It is also removed from the :term:`project index`, so
+the tags and references defined in it will not show up anywhere else.
+
+
+.. _a_proj_roots_dirs:
+
+Using Folders in the Project Tree
+---------------------------------
+
+Regular folders, those that are not root folders, have no structural significance to the project.
+When novelWriter is processing the documents in a project, like for instance when you create a
+manuscript from it, these folders are ignored. Only the order of the documents themselves matter.
+
+The folders are there purely as a way for you to organise the documents in meaningful sections and
+to be able to collapse and hide them in the project tree when you're not working on those
+documents.
+
+.. versionadded:: 2.0
+   As of version 2.0 it is possible to add child documents to other documents. This is particularly
+   useful when you create chapters and scenes. If you add separate scene documents, you should also
+   add separate chapter documents, even if they only contain a chapter heading. You can then add
+   scene documents as child items to the chapters.
+
+
+.. _a_proj_roots_orphaned:
+
+Recovered Documents
+-------------------
+
+If novelWriter crashes or otherwise exits without saving the project state, or if you're using a
+file synchronisation tool that runs out of sync, there may be files in the project storage folder
+that aren't tracked in the core project file. These files, when discovered, are recovered and added
+back into the project.
+
+The discovered files are scanned for metadata that give clues as to where the document may
+previously have been located in the project. The project loading routine will try to put them back
+as close as possible to this location, if it still exists. Generally, it will be appended to the
+end of the folder where it previously was located. If that folder doesn't exist, it will try to add
+it to the correct root folder type. If it cannot figure out which root folder is correct, the
+document will be added to the **Novel** root folder. Finally, if a **Novel** does not exist, one
+will be created.
+
+If the title of the document can be recovered, the word "Recovered:" will be added as a prefix to
+indicate that it may need further attention. If the title cannot be determined, the document will
+be named after its internal key, which is a string of characters and numbers.
+
+
+.. _a_proj_roots_lock:
+
+Project Lockfile
+----------------
+
+To prevent lost documents caused by file conflicts when novelWriter projects are synchronised via
+file synchronisation tools, a project lockfile is written to the project storage folder when a
+project is open. If you try to open a project which already has such a file present, you will be
+presented with a warning, and some information about where else novelWriter thinks the project is
+also open. You will be given the option to ignore this warning, and continue opening the project at
+your own risk.
+
+.. note::
+   If, for some reason, novelWriter or your computer crashes, the lock file may remain even if
+   there are no other instances keeping the project open. In such a case it is safe to ignore the
+   lock file warning when re-opening the project.
+
+.. warning::
+   If you choose to ignore the warning and continue opening the project, and multiple instances of
+   the project are in fact open, you are likely to cause inconsistencies and create diverging
+   project files, potentially resulting in loss of data and orphaned files. You are not likely to
+   lose any actual text unless both instances have the same document open in the editor, and
+   novelWriter will try to resolve project inconsistencies the next time you open the project.
+
+
+.. _a_proj_files:
+
+Project Documents
+=================
+
+New documents can be created from the toolbar in the project tree, or by pressing :kbd:`Ctrl+N`.
+This will open the create new item menu and let you choose between a number of pre-defined
+documents and folders. You will be prompted for a label for the new item.
+
+You can always rename an item by selecting **Rename Item** from the **Project** menu, or by
+pressing :kbd:`F2` when a document or folder is selected.
+
+Other settings for project documents and folders are available from the context menu that you can
+activate by right-clicking on an it in the tree. The **Transform** submenu includes options for
+converting, splitting, or merging documents. See :ref:`a_ui_tree_split_merge` for more details on
+the latter two.
+
+
+Document Templates
+------------------
+
+If you wish to create template documents to be used when creating new project documents, like for
+instance a character note template, you can add a **Templates** root folder to your project. Any
+document added to this root folder will show up in the **Add Item** menu in the project tree
+toolbar. When selected, a new document is created with its content copied from the chosen template.
+
+.. versionadded:: 2.3
+
+
+.. _a_proj_files_counts:
+
+Word Counts
+-----------
+
+A character, word and paragraph count is maintained for each document, as well as for each section
+of a document following a :term:`heading<headings>`. The word count and change of words in the
+current session is displayed in the footer of any document open in the editor, and all stats are
+shown in the details panel below the project tree for any document selected in the project or novel
+trees.
+
+The word counts are not updated in real time, but run in the background every few seconds for as
+long as the document is being actively edited.
+
+A total project word count is displayed in the status bar. The total count depends on the sum of
+the values in the project tree, which again depend on an up to date :term:`project index`. If the
+counts seem wrong, a full project word recount can be initiated by rebuilding the project's index.
+Either from the **Tools** menu, or by pressing :kbd:`F9`.
+
+The rules for how the counts are made is covered in more detail in :ref:`a_counting`.
+
+
+.. _a_proj_settings:
+
+Project Settings
+================
+
+The **Project Settings** can be accessed from the **Project** menu, or by pressing
+:kbd:`Ctrl+Shift+,`. This will open a dialog box, with a set of tabs.
+
+
+Settings Tab
+------------
+
+The **Settings** tab holds the project name, author, and language settings.
+
+The **Project Name** can be edited here. It is used for the main window title and for generating
+backup files. So keep in mind that if you do change this setting, the backup file names will change
+too.
+
+You can also change the **Authors** and **Project Language** setting. These are only used when
+building the manuscript, for some formats. The language setting is also used when inserting text
+into documents in the viewer, like for instance labels for keywords and special comments.
+
+If your project is in a different language than your main spell checking language is set to, you
+can override the default setting here. The project language can also be changed from the **Tools**
+menu.
+
+You can also override the automatic backup setting for the project if you wish.
+
+
+Status and Importance Tabs
+--------------------------
+
+Each document or folder of type **Novel** can be given a "Status" label accompanied by a coloured
+icon, and each document or folder of the remaining types can be given an "Importance" label.
+
+These labels are there purely for your convenience, and you are not required to use them for any
+other features to work. No other part of novelWriter accesses this information. The intention is to
+use these to indicate at what stage of completion each novel document is, or how important the
+content of a note is to the story. You don't have to use them this way, that's just what they were
+intended for, but you can make them whatever you want.
+
+See also :ref:`a_ui_tree_status`.
+
+.. note::
+   The status or importance level currently in use by one or more documents cannot be deleted, but
+   they can be edited.
+
+
+Auto-Replace Tab
+----------------
+
+A set of automatically replaced keywords can be added in this tab. The keywords in the left column
+will be replaced by the text in the right column when documents are opened in the viewer. They will
+also be applied to manuscript builds.
+
+The auto-replace feature will replace text in angle brackets that is in this list. The syntax
+highlighter will add an alternate colour to text matching the syntax, but it doesn't check if the
+text is in this list.
+
+.. note::
+   A keyword cannot contain spaces. The angle brackets are added by default, and when used in the
+   text are a part of the keyword to be replaced. This is to ensure that parts of the text aren't
+   unintentionally replaced by the content of the list.
+
+
+.. _a_proj_backup:
+
+Backup
+======
+
+An automatic backup system is built into novelWriter. In order to use it, a backup path to where
+the backup files are to be stored must be provided in **Preferences**. The path defaults to a
+folder named "Backups" in your home directory.
+
+Backups can be run automatically when a project is closed, which also implies it is run when the
+application itself is closed. Backups are date stamped zip files of the project files in the
+project folder (files not strictly a part of the project are ignored). The zip archives are stored
+in a subfolder of the backup path. The subfolder will have the same name as the **Project Name** as
+defined in :ref:`a_proj_settings`.
+
+The backup feature, when configured, can also be run manually from the **Tools** menu. It is also
+possible to disable automated backups for a given project in **Project Settings**.
+
+.. note::
+   For the backup to be able to run, the **Project Name** must be set in **Project Settings**. This
+   value is used to generate the name and path of the backups. Without it, the backup will not run
+   at all, but it will produce a warning message.
+
+
+.. _a_proj_stats:
+
+Writing Statistics
+==================
+
+When you work on a project, a log file records when you opened it, when you closed it, and the
+total word counts of your novel documents and notes at the end of the session, provided that the
+session lasted either more than 5 minutes, or that the total word count changed. For more details
+about the log file, see :ref:`a_storage`.
+
+A tool to view the content of the log file is available in the **Tools** menu under **Writing
+Statistics**. You can also launch it by pressing :kbd:`F6`, or find it on the sidebar.
+
+The tool will show a list of all your sessions, and a set of filters to apply to the data. You can
+also export the filtered data to a JSON file or to a CSV file that can be opened by a spreadsheet
+application like for instance Libre Office Calc or Excel.
+
+.. versionadded:: 1.2
+   As of version 1.2, the log file also stores how much of the session time was spent idle. The
+   definition of idle here is that the novelWriter main window loses focus, or the user hasn't made
+   any changes to the currently open document in five minutes. The number of minutes can be altered
+   in **Preferences**.

docs/source/project_references.rst

@@ -0,0 +1,222 @@
+.. _a_references:
+
+*******************
+Tags and References
+*******************
+
+In novelWriter there are no forms or tables to fill in to define characters, locations or other
+elements of your story. Instead, you create :term:`project notes` which you can mark as
+representing these story elements by creating a :term:`tag`. Whenever you want to link a piece of
+your story to a note defining a story element, like a character, you create a :term:`reference`
+back to that tag. You can also cross-link your project notes in the same way.
+
+This is perhaps one of the features that makes novelWriter different from other, similar
+applications. It is therefore not always obvious to new users how this is supposed to work, so
+this chapter hopes to explain in more detail how to use this tags and references system.
+
+.. tip::
+   If you find the Tags and Reference system difficult to follow just from reading this chapter,
+   you can create a new project in the **Welcome** dialog's New project form and select  "Create an
+   example project" from the "Pre-fill project" option. The example project contains several
+   examples of tags and references.
+
+
+.. _a_references_metadata:
+
+Metadata in novelWriter
+=======================
+
+The structure of your novelWriter project is inferred from the :term:`headings` within the
+documents, not the documents themselves. See :ref:`a_struct_heads` for more details. Therefore,
+metadata is also associated with headings, and not the documents directly.
+
+If you split your project into separate documents for each scene, this distinction may not matter.
+However, there are several benefits to using documents at a larger structural scale when first
+starting your project. For instance, it may make more sense to define all your scenes, and even
+chapters, in a single document at first, or perhaps a document per act. You can later split these
+documents up using the document split feature. See :ref:`a_ui_tree_split_merge` for more details.
+
+You can do the same with your notes. You can treat each heading as an independent element of your
+notes that can be referenced somewhere else. That way you can collect all your minor or background
+characters in a single note file, and still be able to reference them individually by separating
+them with headings and assigning each a tag.
+
+
+.. _a_references_tags:
+
+How to Use Tags
+===============
+
+A "tag" in novelWriter is a word or phrase that you define as belonging to a heading. Tags are set
+by using the ``@tag`` :term:`keyword`.
+
+The basic format of a tag is ``@tag: tagName``.
+
+An alternative format of a tag is ``@tag: tagName | displayName``.
+
+``tagName`` (Required)
+   This is a unique identifier of your choosing. It is the value you use later for making
+   references back to this document, or section of the document.
+
+``displayName`` (Optional)
+   This is an optional display name used for the tag. When you build your manuscript, you can for
+   instance insert the point of view character name directly into chapter headings. By default, the
+   ``tagName`` value is used in such headings, but if you use a shortened format internally in your
+   project, you can use this to specify a more suitable format for your manuscript headings.
+
+You can only set **one** tag per heading, and the tag has to be unique across **all** documents in
+the project.
+
+After a tag has been defined, it can be referenced in novel documents, or cross-referenced in other
+notes. Tags will also show up in the **Outline View** and in the references panel under the
+document viewer when a document is open in the viewer.
+
+The syntax highlighter will indicate to you that the keyword is correctly used and that the tag is
+allowed, that is, the tag is unique. Duplicate tags should be detected as long as the index is up
+to date. An invalid tag should have a green wiggly line under it, and will not receive the colour
+that valid tags do.
+
+The tag is the only part of these notes that novelWriter uses. The rest of the document content is
+there for you to use in whatever way you wish. Of course, the content of the documents can be added
+to the manuscript, or an outline document. If you want to compile a single document of all your
+notes, you can do this from the **Manuscript Build** tool.
+
+.. versionadded:: 2.2
+   Tags are no longer case sensitive. The tags are by default displayed with the capitalisation you
+   use when defining the tag, but you don't have to use the same capitalisation when referencing
+   it later.
+
+.. versionadded:: 2.3
+   Tags can have an optional display name for manuscript builds.
+
+Example of a heading with a tag for a character of the story:
+
+.. code-block:: md
+
+   # Character: Jane Doe
+
+   @tag: Jane | Jane Doe
+
+   Some information about the character Jane Doe.
+
+When this is done in a document in a :term:`Root Folder` of type "Characters", the tag is
+automatically treated as an available character in your project with the value "Jane", and you will
+be able to reference it in any of your other documents using the reference keywords for characters.
+It will also show up in the Character tab in the Reference panel below the document viewer, and in
+the reference auto-completer menu in the editor when you fill in references. See :ref:`a_ui_view`
+and :ref:`a_references_completer`.
+
+It is the root folder type that defines what category of story elements the tag is indexed under.
+See the :ref:`a_proj_roots` section for an overview of available root folder types. They are also
+covered in the next section.
+
+
+.. _a_references_references:
+
+How to Use References
+=====================
+
+Each heading of any level in your project can contain references to tags set in project notes. The
+references are gathered by the indexer and used to generate the **Outline View**, among other
+things.
+
+References are set as a :term:`keyword` and a list of corresponding tags. The valid keywords are
+listed below. The format of a reference line is ``@keyword: value1, [value2] ... [valueN]``. All
+reference keywords allow multiple values.
+
+``@pov``
+   The point-of-view character for the current section. The target must be a note tag in a
+   **Character** type root folder.
+
+``@focus``
+   The character that has the focus for the current section. This can be used in cases where the
+   focus is not a point-of-view character. The target must be a note tag in a **Character** type
+   root folder.
+
+``@char``
+   Other characters in the current section. The target must be a note tag in a **Character** type
+   root folder. This should not include the point-of-view or focus character if those references
+   are used.
+
+``@plot``
+   The plot or subplot advanced in the current section. The target must be a note tag in a **Plot**
+   type root folder.
+
+``@time``
+   The timelines touched by the current section. The target must be a note tag in a **Timeline**
+   type root folder.
+
+``@location``
+   The location the current section takes place in. The target must be a note tag in a
+   **Locations** type root folder.
+
+``@object``
+   Objects present in the current section. The target must be a note tag in a **Object** type root
+   folder.
+
+``@entity``
+   Entities present in the current section. The target must be a note tag in an **Entities** type
+   root folder.
+
+``@custom``
+   Custom references in the current section. The target must be a note tag in a **Custom** type
+   root folder. The custom folder are for any other category of notes you may want to use.
+
+The syntax highlighter will alert the user that the tags and references are used correctly, and
+that the tags referenced exist.
+
+.. note::
+   The highlighter may be mistaken if the index of defined tags is out of date. If so, press
+   :kbd:`F9` to regenerate it, or select **Rebuild Index** from the **Tools** menu. In general, the
+   index for a document is regenerated when it is saved, so this shouldn't normally be necessary.
+
+.. tip::
+   If you add a reference in the editor to a tag that doesn't yet exist, you can right-click it and
+   select **Create Note for Tag**. This will generate a new project note automatically with the new
+   tag defined. In order for this to be possible, a root folder for that category of references
+   must already exist.
+
+One note can also reference another note in the same way novel documents do. When the note is
+opened in the document viewer, the references become clickable links, making it easier to follow
+connections in the plot. You can follow links in the document editor by clicking them with the
+mouse while holding down the :kbd:`Ctrl` key. Clicked links are always opened in the view panel.
+
+Project notes don't show up in the **Outline View**, so referencing between notes is only
+meaningful if you want to be able to click-navigate between them, or of course if you just want to
+highlight that two notes are related.
+
+.. tip::
+   If you cross-reference between notes and export your project as an HTML document using the
+   **Manuscript Build** tool, the cross-references become clickable links in the exported HTML
+   document as well.
+
+Example of a novel document with references to characters and plots:
+
+.. code-block:: md
+
+   ## Chapter 1
+
+   @pov: Jane
+
+   ### Scene 1
+
+   @char: John, Sam
+   @plot: Main
+
+   Once upon a time ...
+
+
+.. _a_references_completer:
+
+The References Auto-Completer
+-----------------------------
+
+An auto-completer context menu will show up automatically in the document editor when you type the
+character ``@`` on a new line. It will first suggest tag or reference keywords for you to add, and
+after the ``:`` has been added, suggest references from the list of tags you have already defined.
+
+You can use the auto-completer to add multiple references with a ``,`` between them, and even type
+new ones. New references can be created by right-clicking on them and selecting **Create Note for
+Tag** from the menu.
+
+.. versionadded:: 2.2

docs/source/project_structure.rst

@@ -0,0 +1,140 @@
+.. _a_struct:
+
+***************
+Novel Structure
+***************
+
+This chapter covers the structure of a novel project.
+
+There are two different types of documents in a project, **Novel Documents** and **Project Notes**.
+Active novel documents can only live in a **Novel** type root folder. You can also move them to
+**Archive** and **Trash** of course, where they become inactive.
+
+The project tree can distinguish between the different heading levels of the novel documents using
+coloured icons, and optionally add emphasis on the label, set in **Preferences** for easier
+identification.
+
+
+.. _a_struct_heads:
+
+Importance of Headings
+======================
+
+Subfolders under root folders have no impact on the structure of the novel itself. The structure is
+instead dictated by the heading level of the headings within the documents.
+
+Four levels of headings are supported, signified by the number of hashes (``#``) preceding the
+title. See also the :ref:`a_fmt` section for more details about the markup syntax.
+
+.. note::
+   The heading levels are not only important when generating the manuscript, they are also used by
+   the indexer when building the outline tree in the **Outline View** as well as in the **Novel
+   Tree**. Each heading also starts a new region where new Tags and References can be defined. See
+   :ref:`a_references` for more details.
+
+The syntax for the four basic heading types, and the three special types, is listed in section
+:ref:`a_fmt_head`. The meaning of the four levels for the structure of your novel is as follows:
+
+**Heading Level 1: Partition**
+   This heading level signifies that the text refers to a top level heading. This is useful when
+   you want to split the manuscript up into books, parts, or acts. These headings are not required.
+   The novel title itself should use the special heading level ``#!`` covered in :ref:`a_fmt_head`.
+
+**Heading Level 2: Chapter**
+   This heading level signifies a chapter. Each time you want to start a new chapter, you must add
+   such a heading. If you choose to split your manuscript up into one document per scene, you need
+   a single chapter document with just the heading. You can of course also add a synopsis and
+   reference keywords to the chapter document. If you want to open the chapter with a quote or
+   other introductory text that isn't part of a scene, this is also where you'd put that text.
+
+**Heading Level 3: Scene**
+   This heading level signifies a scene. You must provide a title text, but the title text can be
+   replaced with a scene separator or just skipped entirely when you build your manuscript. If you
+   need to distinguish between hard and soft scene breaks, there is an alternative format for
+   scenes you can use for this distinction. The formatting is covered in :ref:`a_fmt_head`. See
+   also :ref:`a_struct_heads_scenes`.
+
+**Heading Level 4: Section**
+   This heading level can be used to split up a scene, usually called a "section" in the
+   documentation and the user interface. These can be useful if you want to change references
+   mid-scene, like if you change the point-of-view character. You are free to use sections as you
+   wish, and you can filter them out of the final manuscript.
+
+Page breaks can be automatically added before partition, chapter and scene headings from the
+**Manuscript Build** tool when you build your project to a format that supports page breaks. If you
+want page breaks in other places, you have to specify them manually. See :ref:`a_fmt_break`.
+
+.. tip::
+   There are multiple options of how to process novel headings when building the manuscript. For
+   instance, chapter numbers can be applied automatically, and so can scene numbers if you want
+   them in a draft manuscript. You can also insert point-of-view character names in chapter titles.
+   See the :ref:`a_manuscript` page for more details.
+
+
+.. _a_struct_heads_title:
+
+Novel Title and Front Matter
+----------------------------
+
+It is recommended that you add a document at the very top of each **Novel** root folder with the
+novel title as the first line. You should modify the level 1 heading format code with an ``!`` in
+order to render it as a document title that is excluded from any automatic Table of Content in a
+manuscript build document, like so:
+
+.. code-block:: md
+
+   #! My Novel
+
+   >> _by Jane Doe_ <<
+
+The title is by default centred on the page. You can add more text to the page as you wish, like
+for instance the author's name and details.
+
+If you want an additional page of text after the title page, starting on a fresh page, you can add
+``[new page]`` on a line by itself, and continue the text after it. This will insert a page break
+before the text. See also :ref:`a_fmt_break`.
+
+
+.. _a_struct_heads_unnum:
+
+Unnumbered Chapter Headings
+---------------------------
+
+If you use the automatic numbering feature for your chapters, but you want to keep some special
+chapters separate from this, you can add an ``!`` to the level 2 heading formatting code to tell
+the build tool to skip these chapters when adding numbers.
+
+.. code-block:: md
+
+   ##! Unnumbered Chapter Title
+
+   Chapter Text
+
+There is a separate formatting feature for such chapter titles in the **Manuscript Build** tool as
+well. See the :ref:`a_manuscript` page for more details. When building a document of a format that
+supports page breaks, also unnumbered chapters can have a page break added just like for normal
+chapters.
+
+
+.. _a_struct_heads_scenes:
+
+Hard and Soft Scene Breaks
+--------------------------
+
+If you need two different ways to style scenes in your manuscript, like if you want to insert
+different scene separators for soft and hard scene breaks, there is an alternative scene format
+available for scene headings with a ``!`` added to the formatting code.
+
+.. code-block:: md
+
+   ### Soft Scene Transition
+
+   A soft scene break.
+
+   ###! Hard Scene Transition
+
+   A hard scene break.
+
+There is a separate formatting feature for these titles in the **Manuscript Build** tool.
+
+.. versionadded:: 2.4