Update usage documentation and incorporate last usage file from old doc

docs/source/index.rst

@@ -34,10 +34,9 @@ storage for robustness.
 
    Main Page <self>
    More Documents <https://novelwriter.io/more/>
-   howto
 
 .. toctree::
-   :caption: Using novelWriter
+   :caption: Getting Started
    :hidden:
 
    usage/introduction
@@ -48,12 +47,13 @@ storage for robustness.
    usage/tags_and_references
    usage/alignment_and_indent
    usage/advanced_formatting
+   usage/front_back_matter
+   usage/howto
 
 .. toctree::
    :caption: The User Interface
    :hidden:
 
-   user_interface/introduction
    user_interface/projects
    user_interface/editor_viewer
    user_interface/split_and_merge

docs/source/project_structure.rst

@@ -1,156 +0,0 @@
-.. _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. Emphasis can be enabled in
-**Preferences**.
-
-
-.. _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.
-
-.. 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
-   a_references for more details.
-
-The syntax for the four basic heading types, and the three special types, is listed in section
-:ref:`docs_usage_headers_levels`. 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:`docs_usage_headers_levels`.
-
-**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:`docs_usage_headers_levels`. 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 titles, 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:`docs_usage_formatting_breaks`.
-
-.. 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:`docs_ui_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 in it. 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.
-
-You can also add the author name and address above this if this is required by the manuscript
-format you use, and additional space added before the title.
-
-This is the title page novelWriter generates automatically for a new project as of version 2.6:
-
-.. code-block:: md
-
-   Jane Doe[br]
-   Address 1[br]
-   Address 2 <<
-
-   [vspace:5]
-
-   #! My Novel
-
-   >> **By Jane Doe** <<
-
-   >> Word Count: [field:textWords] <<
-
-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:`docs_usage_formatting_breaks`.
-
-
-.. _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:`docs_ui_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

docs/source/usage/basic_formatting.rst

@@ -25,7 +25,7 @@ paragraph.
 
 It is important that you actually follow this rule. You should not, for instance, mimic indented
 paragraphs manually in the editor. This, and a lot of other formatting options that can be
-applied to text paragraphs in the :ref:`Manuscript Tool <docs_manuscript>` depends on paragraphs
+applied to text paragraphs in the :ref:`Manuscript Tool <docs_ui_manuscript>` depends on paragraphs
 being separated by blank lines.
 
 :bdg-success:`Correct`

docs/source/usage/chapters_and_scenes.rst

@@ -30,7 +30,10 @@ Heading Levels
 
    An illustration of how heading levels correspond to the novel structure.
 
-Four levels of headings are understood for novel documents:
+Four levels of headings are understood for novel documents. You can pick and choose from these as
+you want, but if your story has chapters, you should use these headings to indicate them. If you
+also add scene headings, you have better control of how your scene separators are formatted in your
+manuscript.
 
 ``# Title Text``
    This is a heading level one. This heading indicates the start of a new partition. Partitions are
@@ -40,7 +43,7 @@ Four levels of headings are understood for novel documents:
 ``## Chapter Title``
    This is a heading level two. This heading indicates the start of a new chapter. Chapter numbers
    can be inserted automatically when building the manuscript, so you don't have to do this in the
-   title. See :ref:`docs_manuscript_numbers` for more details.
+   title. See :ref:`docs_ui_manuscript_head_numbers` for more details.
 
 ``### Scene Title``
    This is a heading level three. This heading indicates the start of a new scene. Scene numbers or
@@ -72,13 +75,19 @@ may want to keep the use cases in mind while writing.
 ``###! Scene Title``
    This is an alternative scene heading that can be formatted differently in the **Manuscript
    Build** tool. It is intended for separating "soft" and "hard" scene breaks. Aside from this, it
-   behaves identically to a regular scene heading. See :ref:`docs_features_scene_breaks` for more
+   behaves identically to a regular scene heading. See :ref:`docs_ui_manuscript_head_hard_soft`
-   details.
+   for more details.
 
 The formatting of these headings can be customised quite extensively in the
-:ref:`Manuscript Tool <docs_manuscript>`, which is covered in a separate part of the documentation.
+:ref:`Manuscript Tool <docs_ui_manuscript>`, which is covered in a separate part of the
+documentation.
 
 .. note::
 
    The space after the ``#`` or ``!`` character is mandatory. The syntax highlighter will change
    colour and font size when the heading is correctly formatted.
+
+Page breaks can be automatically added before titles, 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:`docs_usage_formatting_breaks` for more details.

docs/source/usage/comments.rst

@@ -158,6 +158,6 @@ on your keyboard with your cursor somewhere in the paragraph.
 
    ### Scene
 
-   %~ This text is completely ignored.
+   %~ This text is ignored.
 
    This text is a regular paragraph.

docs/source/usage/front_back_matter.rst

@@ -0,0 +1,77 @@
+.. _docs_usage_front_back_matter:
+
+*********************
+Front and Back Matter
+*********************
+
+Front and back matter documents are documents that go before and after your main story text. They
+can include pages like your cover page, content tables, prologues, epilogues, etc. These special
+pages and sections are supported to some extent by novelWriter.
+
+
+.. _docs_usage_front_back_matter_title:
+
+The Title Page
+==============
+
+It is recommended that you add a document at the very top of each **Novel** root folder with the
+novel title in it. 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.
+
+You can also add the author name and address above this if this is required by the manuscript
+format you use, and additional space added before the title.
+
+:bdg-info:`Example`
+
+This is the title page novelWriter generates automatically for a new project as of version 2.6:
+
+.. code-block:: md
+
+   Jane Doe[br]
+   Address Line 1[br]
+   Address Line 2 <<
+
+   [vspace:5]
+
+   #! My Novel
+
+   >> **By Jane Doe** <<
+
+   >> Word Count: [field:textWords] <<
+
+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.
+
+
+.. _docs_usage_front_back_matter_pages:
+
+Additional Pages
+================
+
+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 :ref:`docs_usage_formatting_breaks` for more details.
+
+
+.. _docs_usage_front_back_matter_unnumbered:
+
+Unnumbered Chapters
+===================
+
+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.
+
+Unnumbered chapters are useful for prologue and epilogue chapters, and also for interlude chapters
+if you use those in your text. There is a separate formatting feature for such chapter titles in
+the **Manuscript Build** tool. See the :ref:`docs_ui_manuscript` page for more details.
+
+
+:bdg-info:`Example`
+
+.. code-block:: md
+
+   ##! Unnumbered Chapter Title
+
+   Chapter Text

docs/source/usage/howto.rst

@@ -1,4 +1,4 @@
-.. _docs_more_howto:
+.. _docs_usage_howto:
 
 *************
 Tips & Tricks

docs/source/usage/organising_project.rst

@@ -85,6 +85,10 @@ Root Folder Types
    The custom root folder type can be used for tracking anything else not covered by the above
    options.
 
+**Templates**
+   Any document added under this root folder will be made available as template options when
+   creating new documents. See :ref:`docs_usage_project_documents_templates` for more details.
+
 **Archive**
    If you don't want to delete a document, or put it in the **Trash** folder where it may be
    deleted, but still want it out of your main project, you can put it in this folder. The contents
@@ -120,21 +124,41 @@ documents.
 
 .. _docs_usage_project_documents:
 
-Project Documents
+Documents
-=================
+=========
 
-New documents can be created from the toolbar in the project tree, or by pressing :kbd:`Ctrl+N`.
+You can add documents anywhere you want in your project structure. You can even add documents as
-This will open the create new item menu and let you choose between a number of pre-defined
+child items of other documents, just like if they were folders. This makes it easy to associate a
-documents and folders. You will be prompted for a label for the new item.
+set of scenes with their chapter. You can also do this in your notes, where you for instance may
+have a hierarchy of your locations.
 
-You can always rename an item by selecting **Rename Item** from the **Project** menu, or by
+The name on a document in the project tree is not linked to any headings in the document text.
-pressing :kbd:`F2` when a document or folder is selected.
+Think of the document name as a file name. You can rename a document, or any other item in the
+project, at any time.
 
-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:`docs_ui_split_merge` for more details on
-the latter two.
 
+Documents come in two types:
+
+**Novel Documents**
+   These are the documents that make up your story or novel. They can only be added under a root
+   folder of type **Novel**. You can technically also add them under **Archive**. See
+   :ref:`docs_usage_headers` for more details about how these documents are handled by novelWriter.
+
+**Project Notes**
+   These are the documents where you keep your notes. You can add them anywhere in your project,
+   including under **Novel** type folders. If you do add them there, they are not treated as a part
+   of the story by default.
+
+You can convert between the two types of documents where the types are allowed. You can also
+convert folders into documents, which may sometimes be convenient.
+
+Another convenient feature is that documents can be split into sub-documents by its containing
+headings, or multiple documents merged into one. This is particularly convenient if you start out
+with larger structural documents, like one containing all chapters and scenes in an act, and then
+split those. See :ref:`docs_ui_split_merge` for more details.
+
+
+.. _docs_usage_project_documents_templates:
 
 Document Templates
 ------------------

docs/source/user_interface/introduction.rst

@@ -1,10 +0,0 @@
-.. _docs_manuscript:
-
-************
-Introduction
-************
-
-.. _docs_manuscript_numbers:
-
-Automatic Numbering
-===================

docs/source/user_interface/manuscript.rst

@@ -110,10 +110,53 @@ 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.
 
+.. csv-table:: Heading Formats
+   :header: "Code", "Description"
+   :class: "tight-table"
+
+   "``{BR}``",             "Insert a line break."
+   "``{Title}``",          "Insert the original title text."
+   "``{Chapter}``",        "Insert a chapter number."
+   "``{Chapter:Word}``",   "Insert a chapter number as a word."
+   "``{Chapter:URoman}``", "Insert a chapter number as an upper case Roman numeral."
+   "``{Chapter:LRoman}``", "Insert a chapter number as an lower case Roman numeral."
+   "``{Scene}``",          "Insert a scene number within the current chapter."
+   "``{Scene:Abs}``",      "Insert a scene number unique to the whole manuscript."
+   "``{Char:POV}``",       "Insert the point-of-view character's :ref:`display name <docs_usage_tags_refs_tags>`."
+   "``{Char:Focus}``",     "Insert the focus character's :ref:`display name <docs_usage_tags_refs_tags>`."
+
 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.
 
 
+.. _docs_ui_manuscript_head_numbers:
+
+Automatic Numbering
+^^^^^^^^^^^^^^^^^^^
+
+The headings formatter also allows you to automatically insert chapter and scene numbers into your
+heading formats. The automatic chapter number counter will skip all chapter headings marked as
+unnumbered using the heading format described in :ref:`docs_usage_headers_levels`.
+
+Scene numbers are mostly intended for use in a draft manuscript. You can either insert absolute
+scene numbers that counts every scene in the novel, or you can insert per-chapter scene numbers
+that reset to 1 for each chapter.
+
+:bdg-info:`Example`
+
+This will create a chapter title on the format "Chapter 1: Title Text":
+
+.. code-block:: md
+
+   Chapter {Chapter}: {Title}
+
+This will create a scene title on the format "Scene 1.1: Title Text":
+
+.. code-block:: md
+
+   Scene {Chapter}.{Scene}: {Title}
+
+
 Scene Separators
 ^^^^^^^^^^^^^^^^
 
@@ -127,7 +170,7 @@ the desired separator text as the format. If the format is any piece of static t
 be treated as a separator.
 
 
-.. _docs_ui_manuscript_head_hard:
+.. _docs_ui_manuscript_head_hard_soft:
 
 Hard and Soft Scenes
 ^^^^^^^^^^^^^^^^^^^^