### Install Qt Tools for Ubuntu/Debian Source: https://github.com/vkbo/novelwriter/blob/main/i18n/README.md Installs the necessary Qt development tools, specifically `qttools5-dev-tools`, on Ubuntu or Debian-based systems. This package provides essential utilities like `lupdate` required for managing Qt translation files. ```bash sudo apt install qttools5-dev-tools ``` -------------------------------- ### Markdown Formatting Examples Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/user_interface/manuscript.rst Examples demonstrating how formatting tags are used within markdown-like structures for chapter and scene titles. ```markdown Chapter {Chapter}: {Title} ``` ```markdown Scene {Chapter}.{Scene}: {Title} ``` -------------------------------- ### Install Test Dependencies Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/technical/tests.rst Installs all necessary packages for running tests, including pytest and pytest-qt, by referencing the requirements file located in the 'tests' directory. ```bash pip install -r tests/requirements.txt ``` -------------------------------- ### Install Documentation Dependencies Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/technical/source.rst Installs the Python packages required to build the project's documentation, typically using Sphinx. These are listed in the docs/requirements.txt file. ```bash pip install -r docs/requirements.txt ``` -------------------------------- ### Install Dependencies from Source Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/technical/source.rst Installs project dependencies, such as PyQt6 for the GUI and PyEnchant for spell checking, from the requirements.txt file. This is crucial for running novelWriter from source. ```bash pip install -r requirements.txt ``` -------------------------------- ### Build Wheel Package Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/technical/source.rst Builds a wheel (.whl) file for the novelWriter package from the source code using the installed build tool. This artifact can then be installed. ```bash python -m build --wheel ``` -------------------------------- ### Example Novel Document with References Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/usage/tags_and_references.rst An example demonstrating how to use various tags within a Markdown document to link to characters, plots, and other elements. ```Markdown ## Chapter 1 @pov: Jane ### Scene 1 @char: John, Sam @plot: Main Once upon a time ... ``` -------------------------------- ### Build Sample Project File Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/technical/source.rst Creates the sample.zip file in the assets folder. This file is necessary for the application's functionality to create new projects from example files. ```bash python pkgutils.py sample ``` -------------------------------- ### Install Wheel Package Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/technical/source.rst Installs the generated wheel package locally using pip, allowing novelWriter to be run from the built artifact. Replace the version number with your specific build. ```bash pip install --user dist/novelWriter-2.0.7-py3-none-any.whl ``` -------------------------------- ### Install Build Tool Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/technical/source.rst Installs the Python Packaging Authority's build tool, which is necessary for creating distributable Python packages like wheels from source code. ```bash pip install build ``` -------------------------------- ### Branching Strategy for Pull Requests Source: https://github.com/vkbo/novelwriter/blob/main/CONTRIBUTING.md Explains how to pick the correct branch for submitting pull requests, differentiating between pre-releases, full releases, and new features. ```text ## Picking the Correct Branch for a Pull Request Pre-releases are made from the `main` branch, and full 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**. New features are only accepted on full releases, so a feature pull request must be made to the `main` branch. However, if the `main` branch is very close to a new full release, pull requests may not be merged until the release is completed. ``` -------------------------------- ### Pull Request Checklist Source: https://github.com/vkbo/novelwriter/blob/main/CONTRIBUTING.md A checklist to ensure pull requests adhere to project standards, including branch usage, descriptions, and version control. ```text ## Pull Request Check List Make sure the pull request follows these rules: * 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. * 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. ``` -------------------------------- ### Example Usage of Spacing and Page Breaks Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/usage/advanced_formatting.rst Demonstrates how to use the [vspace] and [new page] codes for controlling layout in novelWriter. ```md This is a text paragraph. [vspace:2] This is another text paragraph, but there will be two empty paragraphs between them. [new page] This text will start on a new page if the build format supports pages. ``` -------------------------------- ### Example Cover Page Layout Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/usage/advanced_formatting.rst An example of a cover page structure using Markdown with custom NovelWriter formatting tags. This demonstrates how to include author information, address, and dynamically inserted word counts using the defined shortcodes. ```md Jane Smith 42 Main Street 1234 Capital City [vspace:5] #! Example >> **By Jane Smith** << >> Word Count: [field:textWords] << ``` -------------------------------- ### Build Translation Files Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/technical/source.rst Generates the .qm translation files required for internationalization when running novelWriter from source. This process requires the Qt Linguist tool to be installed. ```bash python pkgutils.py qtlrelease ``` -------------------------------- ### Default Light Theme Configuration File Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/more/customise.rst An example of a .conf file defining a color theme for novelWriter. It includes meta-data, base colors, project-specific colors, UI palette, GUI elements, and syntax highlighting rules. ```cfg [Main] name = Default Light Theme mode = light author = Veronica Berglyd Olsen credit = Veronica Berglyd Olsen url = https://github.com/vkbo/novelWriter [Base] base = #fcfcfc default = #303030 faded = #6c6c6c red = #a62a2d orange = #b36829 yellow = #a39c34 green = #296629 cyan = #269999 blue = #3a70a6 purple = #b35ab3 [Project] root = blue folder = yellow file = default title = green chapter = red scene = blue note = yellow active = green inactive = red disabled = faded [Palette] window = base:D105 windowtext = default base = base alternatebase = #e0e0e0 text = default tooltipbase = #ffffc0 tooltiptext = #15150d button = #efefef buttontext = default brighttext = base highlight = #3087c6 highlightedtext = base link = blue linkvisited = blue accent = #3087c6 [GUI] helptext = #5c5c5c fadedtext = #6c6c6c errortext = red [Syntax] background = base text = default line = default:32 link = blue headertext = green headertag = green:L135 emphasis = orange dialog = blue altdialog = red note = yellow:D125 hidden = faded shortcode = blue keyword = red tag = green value = green optional = blue spellcheckline = red errorline = green replacetag = green modifier = blue texthighlight = yellow:72 ``` -------------------------------- ### Example Note Document with Tag Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/usage/tags_and_references.rst Demonstrates how to define a tag for a character within a note document. It shows the @tag keyword format, including an optional display name, and explains its automatic indexing as a project character. ```md # Character: Jane Doe @tag: Jane | Jane Doe Some information about the character Jane Doe. ``` -------------------------------- ### Markdown Alignment and Indentation Example Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/usage/alignment_and_indent.rst Demonstrates novelWriter's Markdown syntax for right, left, and center alignment using `>>` and `<<` markers. It shows how these markers are applied to paragraphs with multiple lines and forced line breaks. ```md >> I am the very model of a modern Major-General << I've information vegetable, animal, and mineral I know the kings of England, and I quote the fights historical From Marathon to Waterloo, in order categorical ``` -------------------------------- ### Markdown Example with Custom Comment Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/usage/comments.rst Demonstrates a markdown code block containing a scene structure with a custom comment syntax '%~' used by NovelWriter. This highlights how the tool processes specific comment formats within markdown. ```md ### Scene %~ This text is ignored. This text is a regular paragraph. ``` -------------------------------- ### List Available Commands Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/technical/source.rst Lists the available custom commands for building packages and assets in novelWriter using the pkgutils.py script. This is the first step to understanding the build utilities. ```bash python pkgutils.py --help ``` -------------------------------- ### Plain Comments Example Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/usage/comments.rst Demonstrates the use of plain comments, which start with '%' as the first character. These comments are ignored by default in word counts and manuscript generation but can be displayed in the document viewer. ```markdown ### Scene A regular text paragraph in the scene. % A comment you've added for your own notes. Another regular text paragraph in the scene. ``` -------------------------------- ### Python Coding Standards Source: https://github.com/vkbo/novelwriter/blob/main/CONTRIBUTING.md Details the Python coding style guide and specific requirements for contributions, including formatting, type annotations, and internationalization. ```python ## General Rules These are the guidelines for the project. The source code of novelWriter broadly follows the [PEP8](https://www.python.org/dev/peps/pep-0008) style guide, but with a few exceptions. ### Tests * New code must not break any existing tests. * New code must come with tests that cover the code in full. If the code has branches that only runs on some OSes, they must be covered when test are run on that OS. The test suite runs on Linux, Windows and MacOS. ### Code Formatting * Do not run automatic formatting tools like `black` or `ruff` on the code. Auto-formatting using `ruff` is planned, but there are a couple of features missing in it, so it is currently only used for linting. Auto-formatting with `isort` is configured in `pyproject.toml` and can be used. * The pull request code *must* pass the `ruff` linting rules specified in `pyproject.toml`. * In general, do not make large scale formatting changes to the code. ### Type Annotations * All functions and parameters must be type annotated, and so must variables and attributes if the type cannot be inferred from the initial value. Typing rules are set in `pyproject.toml` and a pull request must pass `pyright` with these settings. * Do not use the `Any` type when an actual type exists. `Any` is allowed for functions that actually handles any kind of input and returns a standard type. * Do not use deprecated capitalised annotations like `Dict`, `List`, `Tuple`, etc. * Type annotated code must be runnable on all supported Python versions. ### Internationalisation * All comments and docstrings in the code must be in English. * All text presented to the user must be wrapped in calls to Qt's translation framework, and the spelling of this text *must* be UK English. US English spelling is not allowed for these strings. * Commit descriptions and pull requests must also be in English. ### Line Length * Source code lines can extend to the upper limit of 99 characters. 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. Readability has priority. * 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. ``` -------------------------------- ### Build HTML Documentation Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/technical/source.rst Generates the HTML version of the project documentation. This command is executed from the root source folder and uses the make utility. ```bash make -C docs html ``` -------------------------------- ### Story Structure Comments Example Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/features/story_comments.rst Demonstrates the usage of '%Story.' comments for annotating story structure. These comments allow for metadata extraction and structural analysis, with examples like inciting incident, complication, crisis, and resolution. ```markdown ### Scene %Synopsis: Carol overcomes her fear of giving a speech. %Story.incite: Carol is pleased to be invited to a conference to see her boss deliver a keynote. %Story.complication: Carol's boss calls in sick and asks her to deliver a big speech. %Story.crisis: Carol has a fear of appearing on stage. %Story.resolution: Carol engages the help of a coach who helps her overcome her fears and delivers a great speech. ``` -------------------------------- ### Meta Data and Comments in NovelWriter Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/usage/introduction.rst NovelWriter allows for the inclusion of meta-data and author comments within plain text documents. Meta-data lines, starting with '@', are used for information like characters, point of view, or location. Author comments, starting with '%', are ignored in the final output. ```NovelWriter Syntax % This is an author's comment, not part of the story. @character: John Doe @pov: John Doe @location: The Old Library This is a scene description. ``` -------------------------------- ### Run Basic Tests Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/technical/tests.rst Executes all available tests for the novelWriter project by running the pytest command from the root of the source folder. ```bash pytest ``` -------------------------------- ### Markdown Alignment with Forced Line Breaks Example Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/usage/alignment_and_indent.rst Illustrates novelWriter's Markdown syntax for centering text when forced line breaks (`[br]`) are used within a paragraph. This example shows how the alignment markers encompass the entire block, treating it as a single line for alignment purposes. ```md >> I am the very model of a modern Major-General[br] I've information vegetable, animal, and mineral[br] I know the kings of England, and I quote the fights historical[br] From Marathon to Waterloo, in order categorical << ``` -------------------------------- ### Build English PDF Documentation Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/technical/source.rst This command initiates the process of building the documentation for novelWriter into a PDF format using Python and LaTeX. The 'en' argument specifies the English language, and the output is placed in the assets folder, accessible via the Help menu. To build for all languages, replace 'en' with 'all'. ```bash python pkgutils.py docs-pdf en ``` -------------------------------- ### Story Notes Example Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/features/story_comments.rst Illustrates the use of '%Note.' comments for general annotations, such as consistency checks. These comments are free-form and can be filtered independently from story structure comments. ```markdown ### Scene %Synopsis: Carol overcomes her fear of giving a speech. %Note.consistency: This is the first time in the story Carol gives a speech. ``` -------------------------------- ### Ignored Text Example Source: https://github.com/vkbo/novelwriter/blob/main/docs/source/usage/comments.rst Demonstrates how to mark text paragraphs or lines to be completely ignored during manuscript generation or previews by prefixing them with '%~'. This is useful for temporary removal of content. ```markdown %~ This entire paragraph will be ignored by novelWriter. ```