Update docs

vkbo · Mar 10, 2024 · 5df6c85 · 5df6c85
1 parent 05dc300
commit 5df6c85
Show file tree

Hide file tree

Showing 30 changed files with 352 additions and 258 deletions.
diff --git a/source/about/docs.rst b/source/about/docs.rst
@@ -12,6 +12,7 @@ PDF Manuals
 
 A selection of PDF manuals are available here for download, including for earlier versions of novelWriter:
 
+| :download:`novelWriter-2.3.pdf`
 | :download:`novelWriter-2.2.pdf`
 | :download:`novelWriter-2.1.pdf`
 | :download:`novelWriter-2.0.pdf`

diff --git a/source/about/novelWriter-2.3.pdf b/source/about/novelWriter-2.3.pdf
diff --git a/source/docs/fileformatspec15.pdf b/source/docs/fileformatspec15.pdf
diff --git a/source/docs/images/fig_build_build.png b/source/docs/images/fig_build_build.png
diff --git a/source/docs/images/fig_build_settings_headings.png b/source/docs/images/fig_build_settings_headings.png
diff --git a/source/docs/images/fig_build_settings_selections.png b/source/docs/images/fig_build_settings_selections.png
diff --git a/source/docs/images/fig_manuscript_build.png b/source/docs/images/fig_manuscript_build.png
diff --git a/source/docs/images/fig_project_merge_tool.png b/source/docs/images/fig_project_merge_tool.png
diff --git a/source/docs/images/fig_project_split_tool.png b/source/docs/images/fig_project_split_tool.png
diff --git a/source/docs/images/fig_welcome.jpg b/source/docs/images/fig_welcome.jpg
diff --git a/source/docs/index.rst b/source/docs/index.rst
@@ -4,15 +4,15 @@
 Documentation
 *************
 
-| **Release Version:** 2.2.1
-| **Release Date:** Saturday, 27 January 2024
-| **Docs Updated:** Saturday, 27 January 2024
+| **Release Version:** 2.3
+| **Release Date:** Sunday, 10 March 2024
+| **Docs Updated:** Sunday, 10 March 2024
 
-**PDF:** :download:`novelWriter-2.2.pdf <../about/novelWriter-2.2.pdf>` [ :ref:`Older Versions <main_about_docs>` ]
+**PDF:** :download:`novelWriter-2.3.pdf <../about/novelWriter-2.3.pdf>` [ :ref:`Older Versions <main_about_docs>` ]
 
-novelWriter is an open source 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 is designed to be a simple text
+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.
 
@@ -28,13 +28,14 @@ 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
-as well. novelWriter can also be run directly from the Python source, or installed from packages or
-with pip. See :ref:`a_started` for more details.
+as well. novelWriter can be run directly from the Python source, or installed from packages or with
+pip. 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
@@ -71,7 +72,6 @@ with pip. See :ref:`a_started` for more details.
    usage_format
    usage_shortcuts
    usage_typography
-   usage_projectformat
 
 .. toctree::
    :maxdepth: 1
@@ -85,7 +85,15 @@ with pip. See :ref:`a_started` for more details.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Additional Topics
+   :caption: Additional Details
+   :hidden:
+
+   more_projectformat
+   more_counting
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Technical Topics
    :hidden:
 
    tech_locations

diff --git a/source/docs/int_customise.rst b/source/docs/int_customise.rst
@@ -36,7 +36,8 @@ and add dictionaries yourself.
 
 A small tool to assist with this can be found under :guilabel:`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.
+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**
 
@@ -139,10 +140,10 @@ In the Main section you must at least define the ``name`` and ``icontheme`` sett
 ``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
+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  to 255.
-Omitted values are not loaded and will use default values.
+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
@@ -174,15 +175,20 @@ A syntax theme ``.conf`` file consists of the following settings:
    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
 
 In the Main section, you must define at least the ``name`` setting. The Syntax colour values are
-RGB numbers of the format ``r, g, b`` where each is an integer from  to 255. Omitted values default
-to black, except ``background`` which defaults to white,
+RGB(A) numbers of the format ``r, g, b, a`` where each is an integer ``0`` from to ``255``. The
+fourth value is the alpha channel (transparency), which can be omitted.
+
+Omitted syntax colours default to black, except ``background`` which defaults to white.
 
 .. versionadded:: 2.2
-   The `shortcode` syntax colour entry was added, so you need to update your custom themes if you
-   made any before version 2.2.
+   The `shortcode` syntax colour entry was added.
+
+.. versionadded:: 2.3
+   The `optional` syntax colour entry was added.
diff --git a/source/docs/int_glossary.rst b/source/docs/int_glossary.rst
@@ -50,7 +50,7 @@ Glossary
    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
+      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

diff --git a/source/docs/int_howto.rst b/source/docs/int_howto.rst
@@ -25,7 +25,7 @@ Managing the Project
    :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 also rearrange them here of you wish. See :ref:`a_ui_tree_split_merge` for more details.
+   can rearrange them here of you wish. See :ref:`a_ui_tree_split_merge` for more details.
 
 
 Layout Tricks
@@ -42,7 +42,7 @@ Layout Tricks
    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.
+   to match. Especially if you don't use the same font in your manuscript as in the editor.
 
 
 Organising Your Text
@@ -56,20 +56,25 @@ Organising Your Text
 
    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 (added in novelWriter 2.0).
+   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 the scene heading for hard scene breaks and section headings
+   In such cases you may want to use a scene heading for hard scene breaks and a section heading
    for soft scene breaks. The :guilabel:`Build Manuscript` tool will let you add separate
    formatting for the two when you generate your manuscript. You can for instance add the common
    "``* * *``" for hard breaks and select to hide section breaks, which will just insert an empty
    paragraph in their place. See :ref:`a_manuscript_settings` for more details.
 
+   Keep in mind that this is not what the section heading is intended for, so the app will not
+   understand the section heading as a scene, but it will be formatted correctly in the manuscript.
+
 
 Other Tools
 ===========

diff --git a/source/docs/int_introduction.rst b/source/docs/int_introduction.rst
@@ -8,9 +8,18 @@ Key Features
 .. _Markdown: https://en.wikipedia.org/wiki/Markdown
 
 At its core, novelWriter is a multi-document plain text editor. It uses a markup syntax inspired by
-Markdown_ to apply simple formatting to the text. It 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.
+Markdown_ to apply simple formatting to the text. It also allows for some extended formatting codes
+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 to organise 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 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
@@ -20,10 +29,10 @@ There are two kinds of documents in your project: :term:`Novel Documents` are do
 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 headers up into multiple documents, or
-merge multiple documents into single documents. This makes it easier to use variations of the
+You can at any point split the individual documents by their headings up into multiple documents,
+or merge multiple documents into single documents. This makes it easier to use variations of the
 Snowflake_ method for writing. You can start by writing larger structure-focused documents, like
-one per act for instance, and later effortlessly split these up into scenes by their headers.
+one per act for instance, and later effortlessly split these up into chapters or scenes.
 
 Below are some key features of novelWriter.
 
@@ -45,15 +54,15 @@ Below are some key features of novelWriter.
    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 a few documents and then
-   later split them into multiple documents based on their headers.
+   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**
-   As of novelWriter 2.0, you can have multiple Novel type root 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.
+   You can have multiple Novel type root 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 plot elements**
+**Keep track of your story elements**
    All notes in your project can be assigned a :term:`tag` that you can :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.
@@ -69,10 +78,10 @@ Below are some key features of novelWriter.
 **Get an overview of your story elements**
    Under the document viewer panel you will find a series of tabs that shows 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 when you don't need it
-   to free up space.
+   on which categories you are using in your story. This panel can be hidden to free up space when
+   you don't need it.
 
-**Building your manuscript**
+**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, you can use the :guilabel:`Build Manuscript` tool to
    do so. The tool lets you select what information you want to include in the generated document,

diff --git a/source/docs/int_overview.rst b/source/docs/int_overview.rst
@@ -11,9 +11,9 @@ Overview
       :width: 220
 
 novelWriter is built as a cross-platform application using `Python 3 <https://www.python.org/>`_ as
-the programming language, and `Qt 5 <https://www.qt.io/>`_ for the user interface.
+the programming language, and `Qt 5 <https://www.qt.io/>`_ framework for the user interface.
 
-novelWriter is built for Linux first, and this is where it works best. However, it also runs fine
+novelWriter is built for Linux first, so this is where it works best. However, it also runs fine
 on Windows and MacOS due to the cross-platform framework it's built on. The author of the
 application doesn't own a Mac, so on-going Mac support is dependent on user feedback and user
 contributions.
@@ -22,7 +22,7 @@ Spell checking in novelWriter is provided by a third party library called
 `Enchant <https://abiword.github.io/enchant/>`_. Please see the section on :ref:`a_custom_dict` for
 how to install spell checking languages.
 
-For install instructions, see :ref:`a_started`.
+For install instructions for novelWriter, see :ref:`a_started`.
 
 
 Using novelWriter
@@ -58,12 +58,6 @@ read on.
    your language, and other special characters. If you use any symbols aside from these, their
    intended use is explained here.
 
-:ref:`a_prjfmt` – Optional
-   This chapter is more technical and has an overview of changes made to the way your project data
-   is stored. The format has changed a bit from time to time, and sometimes the changes require
-   that you make small modifications to your project. Everything you need to know is listed in this
-   chapter.
-
 
 Organising Your Projects
 ========================
@@ -90,3 +84,11 @@ meta data for it to extract.
 :ref:`a_manuscript` - Recommended Reading
    This chapter explains how the :guilabel:`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.
diff --git a/source/docs/int_started.rst b/source/docs/int_started.rst
@@ -6,7 +6,7 @@ Getting Started
 
 .. _Enchant: https://abiword.github.io/enchant/
 .. _GitHub: https://github.com/vkbo/novelWriter
-.. _main website: https://novelwriter.io
+.. _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/
@@ -15,9 +15,10 @@ Getting Started
 .. _AppImage: https://appimage.org/
 
 Ready-made packages and installers for novelWriter are available for all major platforms, including
-Linux, Windows and MacOS. See below for install instructions for each platform.
+Linux, Windows and MacOS, from the `Downloads page`_. See below for install instructions for each
+platform.
 
-You can also install novelWriter from the Python Package Index (PyPi). See :ref:`a_started_pip`.
+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.
 
@@ -32,7 +33,7 @@ Installing on Windows
 =====================
 
 You can install novelWriter with both Python and library dependencies embedded using the Windows
-Installer (setup.exe) file from the `main website`_, or from the Releases_ page on GitHub_.
+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
@@ -51,8 +52,8 @@ multiple installations has been known to cause problems.
 Installing on Linux
 ===================
 
-A Debian package can be downloaded from the `main website`_, or from the Releases_ page on GitHub_.
-This package should work on both Debian, Ubuntu and Linux Mint, at least.
+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.
 
@@ -112,8 +113,8 @@ completely standalone images for the app that include the necessary environment
 They can of course be run on any Linux distro, if you prefer this to native packages.
 
 .. note::
-   novelWriter generally don'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
+   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.
 
 
@@ -123,14 +124,14 @@ Installing on MacOS
 ===================
 
 You can install novelWriter with both its Python and library dependencies embedded using the DMG
-application image file from the `main website`_, or from the Releases_ page on GitHub_. Installing
-it should be straightforward.
+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
+* 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.
 
@@ -149,7 +150,7 @@ Installing from PyPi
 ====================
 
 novelWriter is also available on the Python Package Index, or PyPi_. This install method works on
-all supported operating systems.
+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