Merge branch 'main' into dev

vkbo · Oct 17, 2023 · 7710878 · 7710878
2 parents d68d215 + 60b977f
commit 7710878
Show file tree

Hide file tree

Showing 55 changed files with 3,209 additions and 2,810 deletions.
diff --git a/.github/workflows/test_mac.yml b/.github/workflows/test_mac.yml
@@ -1,4 +1,4 @@
-name: macOS
+name: MacOS
 
 on:
   push:

diff --git a/.gitignore b/.gitignore
@@ -10,6 +10,7 @@ setup.iss
 /novelwriter.desktop
 /novelWriter.pyw
 /setup/macos/Info.plist
+.venv
 
 # Translations
 /novelwriter/assets/i18n/*.qm

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,59 @@
 # novelWriter Changelog
 
+## Version 2.1 [2023-10-17]
+
+### Release Notes
+
+The primary focus of this release has been a complete redesign of the Build Tool, that is, the tool
+that assembles your project into a manuscript document. The new tool, called the "Manuscript Build
+Tool" allows you to define multiple build definitions for your project. The build definitions are
+edited in a new Manuscript Build Settings dialog, with a lot more options than the old tool.
+
+The reason for this redesign is a long list of feature requests that could not easily be
+accommodated in the old, much simpler tool. Far from all the features have been added yet, but now
+that the new tool is in place, they will be gradually added in the coming releases.
+
+The key feature added in this release is the extended control you now have for selecting exactly
+what part of your project is included in a given build definition. You have the same filters for
+selecting documents and notes, and turning on or off root folders as before, but you can now easily
+override on a per-document basis what is included or excluded in addition to the filter.
+
+A second major improvement is a better tool to format your manuscript headings. You no longer have
+to look up formatting codes and add them manually. Instead, there is now a heading format editor in
+the Build Settings dialog for creating the header format, with syntax highlighting included.
+
+#### Other Changes
+
+Among other features is a new option to duplicate documents and folders in the project tree. The
+duplicate feature is available from the right-click menu. A proper light colour theme has also been
+added. In most cases it will be the same as the default theme, depending on your platform.
+
+There are other, minor improvements as well, and a lot of code improvements under the hood. For a
+full list of changes, see the detailed changelogs.
+
+_These Release Notes also include the changes from the 2.1 Beta 1 and 2.1 RC 1 releases._
+
+### Detailed Changelog
+
+**Usability**
+
+* A widget has been added to the Build Manuscript tool main window to show some select build
+  settings for the selected build definition. This should make it a little easier to find the
+  wanted build definition if there are many available. PR #1516.
+* All columns on the Writing Stats tool now uses the same fixed width font. Issue #1442, PR #1518.
+
+**Documentation**
+
+* The documentation has received significant updates for the 2.1 release. PR #1531.
+
+**Packaging and Installation**
+
+* Python 3.7 support has officially been dropped. Python 3.7 has reached end of life, and dropping
+  it relaxes some restrictions on development. PR #1515.
+* MacOS and Windows is now tested against Python 3.11, and 3.12 has been added to Linux. PR #1515.
+
+----
+
 ## Version 2.1 RC 1 [2023-08-31]
 
 ### Release Notes
@@ -160,7 +214,7 @@ such a document. In addition, the "Change Label" context menu entry has been cha
   underscores. The spell checker relies on RegEx for splitting words, and RegEx considers the
   underscore a word character. Issue #1415. PR #1417.
 * Fixed an issue where escaped markup characters were not being cleaned up when building HTML and
-    ODT outputs. Issue #1412. PR #1418.
+  ODT outputs. Issue #1412. PR #1418.
 
 **Usability Fixes**
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -35,7 +35,7 @@
 time.tzset()
 
 needs_sphinx = "5.0"
-extensions = []
+extensions = ["sphinx_design"]
 templates_path = ["_templates"]
 source_suffix = ".rst"
 master_doc = "index"

diff --git a/docs/source/images/fig_build_build.png b/docs/source/images/fig_build_build.png
diff --git a/docs/source/images/fig_build_settings_headings.png b/docs/source/images/fig_build_settings_headings.png
diff --git a/docs/source/images/fig_build_settings_selections.png b/docs/source/images/fig_build_settings_selections.png
diff --git a/docs/source/images/fig_editor.png b/docs/source/images/fig_editor.png
diff --git a/docs/source/images/fig_editor_search.png b/docs/source/images/fig_editor_search.png
diff --git a/docs/source/images/fig_header_levels.png b/docs/source/images/fig_header_levels.png
diff --git a/docs/source/images/fig_manuscript_build.png b/docs/source/images/fig_manuscript_build.png
diff --git a/docs/source/images/fig_novel_tree_view.png b/docs/source/images/fig_novel_tree_view.png
diff --git a/docs/source/images/fig_outline_view.png b/docs/source/images/fig_outline_view.png
diff --git a/docs/source/images/fig_project_merge_tool.png b/docs/source/images/fig_project_merge_tool.png
diff --git a/docs/source/images/fig_project_split_tool.png b/docs/source/images/fig_project_split_tool.png
diff --git a/docs/source/images/fig_project_tree_detailed.png b/docs/source/images/fig_project_tree_detailed.png
diff --git a/docs/source/images/fig_project_tree_view.png b/docs/source/images/fig_project_tree_view.png
diff --git a/docs/source/images/fig_references.png b/docs/source/images/fig_references.png
diff --git a/docs/source/images/fig_viewer.png b/docs/source/images/fig_viewer.png
diff --git a/docs/source/images/python_win_install.png b/docs/source/images/python_win_install.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -18,18 +18,13 @@ storage for robustness.
 
 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. See the :ref:`a_breakdown_storage` section for more details.
+project structure is stored in a single project XML file. Other meta data is saved as JSON files.
+See the :ref:`a_breakdown_storage` section for more details.
 
 Any operating system that can run Python 3 and has 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
+novelWriter. It runs fine on Linux, Windows and MacOS, and users have tested it on other platforms
 as well. novelWriter can also be run directly from the Python source, or installed from packages or
-the pip tool. See :ref:`a_started` for more details.
-
-.. note::
-   Release 1.5 introduced a few changes that will require you to make some minor modifications to
-   some of the headings in your project. It should be fairly quick and straightforward. Please see
-   the :ref:`a_prjfmt_1_3` section for more details.
+with pip. See :ref:`a_started` for more details.
 
 **Useful Links**
 
@@ -56,17 +51,18 @@ the pip tool. See :ref:`a_started` for more details.
    int_introduction
    int_overview
    int_started
-   int_source
    int_howto
    int_customise
+   int_glossary
 
 .. toctree::
    :maxdepth: 1
    :caption: Using novelWriter
    :hidden:
 
    usage_breakdown
-   usage_interface
+   usage_project
+   usage_writing
    usage_format
    usage_shortcuts
    usage_typography
@@ -79,14 +75,15 @@ the pip tool. See :ref:`a_started` for more details.
 
    project_overview
    project_structure
-   project_notes
-   project_export
+   project_references
+   project_manuscript
 
 .. toctree::
    :maxdepth: 1
-   :caption: Under the Hood
+   :caption: Additional Topics
    :hidden:
 
    tech_locations
    tech_storage
+   tech_source
    tech_tests
diff --git a/docs/source/int_customise.rst b/docs/source/int_customise.rst
@@ -17,14 +17,14 @@ Spell Check Dictionaries
 ========================
 
 novelWriter uses Enchant_ as the spell checking tool. Depending on your operating system, it may or
-may not load installed spell check dictionaries.
+may not load all installed spell check dictionaries automatically.
 
 Linux and MacOS
 ---------------
 
 On Linux and MacOS, you generally only have to install hunspell or aspell dictionaries on your
 system like you do for other applications. See your distro or OS documentation for how to do this.
-These dictionaries should then show up as available spell check languages in novelWriter.
+These dictionaries should show up as available spell check languages in novelWriter.
 
 Windows
 -------
@@ -40,7 +40,6 @@ This assumes your user profile is stored at ``C:\Users\<USER>``. The last one or
 not exist, so you may need to create them.
 
 .. 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!
@@ -54,8 +53,9 @@ not exist, so you may need to create them.
 Syntax and GUI Themes
 =====================
 
-Adding your own GUI and syntax themes is relatively easy. The themes are defined by simple plain
-text config files with meta data and colour settings.
+Adding your own GUI and syntax themes is relatively easy, altough 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.
@@ -78,16 +78,16 @@ folders are created the first time you start novelWriter.
 Once the files are copied there, they should show up in :guilabel:`Preferences` with the label you
 set as ``name`` inside the file.
 
-.. note::
-   In novelWriter 2.0 the ``icontheme`` value was added to GUI themes. Make sure you set this value
-   in existing custom themes. Otherwise it defaults to ``typicons_light``, which may not match your
-   theme colour scheme.
+.. 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.
 
 
 Gustom GUI and Icons Theme
 --------------------------
 
-A GUI theme conf file consists of the follwing settings:
+A GUI theme ``.conf`` file consists of the follwing settings:
 
 .. code-block:: cfg
 
@@ -136,7 +136,7 @@ Omitted values are not loaded and will use default values.
 Custom Syntax Theme
 -------------------
 
-A syntax theme conf file consists of the follwing settings:
+A syntax theme ``.conf`` file consists of the follwing settings:
 
 .. code-block:: cfg
 
@@ -166,7 +166,6 @@ A syntax theme conf file consists of the follwing settings:
    replacetag     =   0,   0,   0
    modifier       =   0,   0,   0
 
-
 In the Main section, you must define at least the ``name`` setting. The Syntax colour values are
-RGB numbers on the format ``r, g, b`` where each is an integer from  to 255. Omitted values are set
+RGB numbers on the format ``r, g, b`` where each is an integer from  to 255. Omitted values default
 to black, except ``background`` which defaults to white,
diff --git a/docs/source/int_glossary.rst b/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 references 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 header 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 is 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.