From 6952211607323d9bcfe944e7abd634fbda088946 Mon Sep 17 00:00:00 2001
From: Veronica Berglyd Olsen <1619840+vkbo@users.noreply.github.com>
Date: Mon, 29 Jan 2024 17:47:37 +0100
Subject: [PATCH] Update docs

---
 docs/source/int_customise.rst      |  5 +++++
 docs/source/project_references.rst | 29 +++++++++++++++++++++++------
 2 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/docs/source/int_customise.rst b/docs/source/int_customise.rst
index baa67ee1..7124b3a9 100644
--- a/docs/source/int_customise.rst
+++ b/docs/source/int_customise.rst
@@ -174,6 +174,7 @@ 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
@@ -186,3 +187,7 @@ 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.
+
+.. versionadded:: 2.3
+   The `optional` syntax colour entry was added, so you need to update your custom themes if you
+   made any before version 2.3.
diff --git a/docs/source/project_references.rst b/docs/source/project_references.rst
index 52cf6194..760a7830 100644
--- a/docs/source/project_references.rst
+++ b/docs/source/project_references.rst
@@ -47,15 +47,24 @@ 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 ``@tags`` :term:`keyword`. The full format of a tag is ``@tag: tagname``, where
-``tagname`` is an identifier of your choosing. You can only set *one* tag per heading, and the tag
-has to be unique across all documents in the project.
+by using the ``@tags`` :term:`keyword`.
 
-.. versionadded:: 2.2
-   Tags are now case insensitive.
+The full format of a tag is ``@tag: tagName, displayName``, where:
+
+``tagName`` (Required)
+   is a unique identifier of your choosing.
+
+``displayName`` (Optional)
+   is a display name that can be inserted into headings when you generate your manuscript. When you
+   build your manuscript, you can for instance insert the point of view character name into chapter
+   headings. By default, the ``tagName`` is used in headings, but if you use a shortened format
+   internally in your project, you can use this to specify a more suitable format.
+
+You can only set *one* tag per heading, and the tag has to be unique across *all* documents in the
+project.
 
 After the tags have been defined, they can then be referenced in the novel documents, or
-cross-referenced in other notes. they will also show up in the :guilabel:`Outline View` and in the
+cross-referenced in other notes. They will also show up in the :guilabel:`Outline View` and in the
 back-reference panel when a document is opened in the viewer.
 
 The syntax highlighter will indicate to you that the keyword is correctly used and that the tag is
@@ -68,6 +77,14 @@ there for you to use in whatever way you wish. Of course, the content of the doc
 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 :guilabel:`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 as a second parameter.
+
 Example of a heading with a tag for a character of the story:
 
 .. code-block:: none