Complete the usage section

2025-05-24 19:35:58 +02:00
parent 60973954ef
commit d0c838450d
7 changed files with 608 additions and 326 deletions
@@ -1,5 +1,150 @@
-.. _docs_usage_shortcodes:
+.. _docs_usage_formatting:
 *******************
 Advanced Formatting
 *******************
 Markdown formatting is somewhat limited by default, so novelWriter has some additional formatting
 codes for common use cases. These codes are all based on brackets, and some allow an additional
 value after a colon.
 This section covers all these formatting codes.
 .. _docs_usage_formatting_shortcodes:
 Formatting with Shortcodes
 ==========================
 For basic formatting, like emphasis, you should use the standard Markdown style formatting tags
 descried in :ref:`docs_usage_basics_emphasis`.
 For additional formatting options, you can use shortcodes. Shortcodes is a form of in-line codes
 that wrap the section of text to be formatted. Shortcodes can overlap and intersect.
 These shortcodes are intended for special formatting cases, or more complex cases that cannot be
 solved with simple Markdown-like formatting codes. Available shortcodes are listed below.
 .. csv-table:: Shortcodes Formats
   :header: "Syntax", "Description"
   :widths: 40, 60
   :class: "tight-table"
   "``[b]text[/b]``",     "Text is rendered as bold text."
   "``[i]text[/i]``",     "Text is rendered as italicised text."
   "``[s]text[/s]``",     "Text is rendered as strike through text."
   "``[u]text[/u]``",     "Text is rendered as underlined text."
   "``[m]text[/m]``",     "Text is rendered as highlighted text."
   "``[sup]text[/sup]``", "Text is rendered as superscript text."
   "``[sub]text[/sub]``", "Text is rendered as subscript text."
   "``[footnote:key]``",  "A reference to a :ref:`footnote comment <docs_usage_comments_footnotes>`."
 Unlike Markdown style codes, these can be used anywhere within a paragraph. Even in the middle of a
 word if you need to. You can also freely combine them to form more complex formatting.
 The shortcodes are available from the **Format** menu and in the editor toolbar, which can be
 activated by clicking the left-most icon button in the editor header.
 .. note::
   Shortcodes are not processed until you generate a preview or generate a manuscript document. So
   there is no highlighting of the text between the formatting markers. There is also no check that
   your markers make sense. You must ensure that you have both the opening and closing formatting
   markers where you want them.
 .. versionadded:: 2.2
 .. _docs_usage_formatting_breaks:
 Vertical Space and Page Breaks
 ==============================
 You can apply page breaks to partition, chapter and scene headings for novel documents from the
 **Manuscript Build** tool. If you need to add a page break or additional vertical spacing in other
 places, there are special codes available for this purpose.
 Adding more than one line break between paragraphs will **not** increase the space between those
 paragraphs when building the project. To add additional space between paragraphs, add the text
 ``[vspace]`` on a line of its own, and the **Manuscript** tool will insert a blank paragraph in its
 place.
 If you need multiple blank paragraphs just add a colon and a number to the above code. For
 instance, writing ``[vspace:3]`` will insert three blank paragraphs.
 If you need to add a page break somewhere, put the text ``[new page]`` on a line by itself before
 the text you wish to start on a new page.
 .. note::
   The page break code is applied to the text that follows it. It adds a "page break before" mark
   to the text when exporting to HTML or Open Document. This means that a ``[new page]`` which has
   no text following it, it will not result in a page break.
 :bdg-info:`Example`
 .. code-block:: 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 has pages.
 .. _docs_usage_formatting_counts:
 Inserting Word Counts in the Text
 =================================
 The cover page of a manuscript normally has the word count stated on it. Any statistics value
 collected by novelWriter can be inserted into any document using a special shortcode. You can
 insert the code for any of the available statistics values from the **Insert** menu under
 **Word/Character Count**.
 The value inserted is the actual count for your entire manuscript, so it is not populated until you
 run the **Manuscript Build** tool. Until then they will show up as "0" in the viewer panel.
 The available codes are:
 .. csv-table:: Stats Shortcodes
   :header: "Code", "Description"
   :widths: 40, 60
   :class: "tight-table"
   "``[field:allChars]``",       "Characters"
   "``[field:textChars]``",      "Characters in Text"
   "``[field:titleChars]``",     "Characters in Headings"
   "``[field:paragraphCount]``", "Paragraphs"
   "``[field:titleCount]``",     "Headings"
   "``[field:allWordChars]``",   "Characters, No Spaces"
   "``[field:textWordChars]``",  "Characters in Text, No Spaces"
   "``[field:titleWordChars]``", "Characters in Headings, No Spaces"
   "``[field:allWords]``",       "Words"
   "``[field:textWords]``",      "Words in Text"
   "``[field:titleWords]``",     "Words in Headings"
 :bdg-info:`Example`
 This is an example cover page. A similar page is automatically generated when you create a new
 project. The Word Count uses a "field" shortcode to insert a count of all words in text paragraphs
 on the cover page.
 .. code-block:: md
   Jane Smith[br]
   42 Main Street[br]
   1234 Capital City <<
   [vspace:5]
   #! Example
   >> **By Jane Smith** <<
   >> Word Count: [field:textWords] <<
@@ -3,3 +3,76 @@
 *************************
 Alignment and Indentation
 *************************
 The Markdown standard doesn't have commands for aligning text, so novelWriter adds its own syntax
 for this. It also has syntax for indentation, which is similar to Markdown block quotes.
 Paragraph Alignment and Indentation
 ===================================
 All documents have the text by default aligned to the left or justified, depending on your setting
 in **Preferences**.
 You can override the default text alignment on individual paragraphs by specifying alignment tags.
 These tags are double angle brackets. Either ``>>`` or ``<<``. You put them either before or after
 the paragraph, and they will "push" the text towards the edge the brackets point towards. This
 should be fairly intuitive.
 Indentation uses a similar syntax. But here you use a single ``>`` or ``<`` to "push" the text away
 from the edge.
 :bdg-info:`Example`
 .. csv-table:: Text Alignment and Indentation
   :header: "Syntax", "Description"
   :widths: 40, 60
   :class: "tight-table"
   "``>> Right aligned text``",        "The text paragraph is right-aligned."
   "``Left aligned text <<``",         "The text paragraph is left-aligned."
   "``>> Centred text <<``",           "The text paragraph is centred."
   "``> Left indented text``",         "The text has an increased left margin."
   "``Right indented text <``",        "The text has an increased right margin."
   "``> Left/right indented text <``", "The text has both margins increased."
 .. note::
   The text editor will not show the alignment and indentation live. But the viewer will show them
   when you open the document there. It will of course also be reflected in the document generated
   from the manuscript build tool as long as the format supports paragraph alignment.
 Alignment with Line Breaks
 ==========================
 If you have line breaks in the paragraph, the markers for all the lines are combined and used for
 the entire paragraph. For the following text, all lines will be centred:
 :bdg-info:`Example`
 .. code-block:: 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 <<
 Alignment with First Line Indent
 ================================
 If you have first line indent enabled in your Manuscript build settings, you probably want to
 disable it for text in verses. Adding any alignment tags will cause the first line indent to be
 switched off for that paragraph.
 :bdg-info:`Example`
 The following text will always be aligned against the left margin:
 .. code-block:: 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
@@ -3,3 +3,161 @@
 ******************
 Comments and Notes
 ******************
 You can add comments to your text that are not a part of the story. Regular comments are intended
 for you to add notes to yourself inside the text, which may be useful when you revise your drafts.
 However, there are several types of comments you can use.
 This section covers the basic comment types. There are a couple of advanced features that sue
 comment syntax too, but they are covered later.
 .. _docs_usage_comments_plain:
 Plain Comments
 ==============
 A plain comment is a line or paragraph that starts with the character ``%`` as its first character.
 You can put them wherever you like in your documents, and you can chose to include or exclude them
 from your manuscript.
 For the most part, novelWriter completely ignores these comments. They are not included in your
 word or character count, and are only displayed in the document viewer panel if you enable them.
 :bdg-info:`Example`
 .. code-block:: md
   ### Scene
   A regular text paragraph in the scene.
   % A comment you've added for your own notes.
   Another regular text paragraph in the scene.
 .. _docs_usage_comments_synopsis:
 Synopsis or Description Comments
 ================================
 A special kind of comments are **Synopsis** and **Short Description** comments. They are different
 from plain comments in that they can be displayed alongside other information about a scene or a
 character or other story element described in a note. As with plain comments, they can be included
 in your manuscript, but they are formatted differently than plain comments.
 .. note::
   A summary or description comment can only be used once for each heading as they are considered a
   description of the content of the text under that heading. If you add two such comments under
   the same heading, the last one will be used.
 Synopsis
 --------
 A **Synopsis** comment is intended for adding a summary of your chapters and scenes.
 :bdg-info:`Example`
 .. code-block:: md
   ### Scene
   %Synopsis: A summary of the content of the scene.
   The actual scene text.
 Short Description
 -----------------
 A **Short Description** comment behaves exactly the same as a synopsis comment, but is intended as
 a description of a story element, like a character.
 :bdg-info:`Example`
 .. code-block:: md
   # Characters
   ## Darth Vader
   %Short: A Sith Lord that used to be a Jedi.
   Your text about the character.
   ## Luke Skywalker
   %Short: A Jedi. The son of Darth Vader.
   Your text about the character.
 .. note::
   The ``%Synopsis:`` and ``%Short:`` comment prefixes are interchangeable, but when you include
   them in the manuscript, they are labelled based on the prefix, so the latter may make more sense
   for a Character note than the former.
 .. _docs_usage_comments_footnotes:
 Footnote Comments
 =================
 Footnotes are added with a shortcode, paired with a matching comment for the actual footnote text.
 The matching is done with a key that links the two. If you insert a footnote from the **Insert**
 menu, a unique key is generated for you. Shortcodes in general are covered in more detail in
 :ref:`docs_usage_formatting_shortcodes`.
 The insert feature will add the footnote shortcode marker at the position of your cursor in the
 editor panel, and create the associated footnote comment right after the paragraph. It will then
 move the cursor there so you can immediately start typing the footnote text.
 The footnote comment can be anywhere in the document, so if you wish to move them to, say, the
 bottom of the text, you are free to do so.
 Footnote keys are only required to be unique within a document, so if you copy, move or merge text,
 you must make sure the keys are not duplicated. If you use the automatically generated keys from
 the **Insert** menu, they are unique among all indexed documents. They are not guaranteed to be
 unique against footnotes in the **Archive** or **Trash** folder though, but the chance of
 accidentally generating the same key twice in a project is relatively small.
 :bdg-info:`Example`
 .. code-block:: md
   ### Scene
   This is a text paragraph with a footnote[footnote:fn1] in the middle.
   %Footnote.fn1: This is the text of the footnote.
 .. versionadded:: 2.5
 .. _docs_usage_comments_ignored:
 Ignored Text
 ============
 If you want to completely ignore some of the text in your documents, but are not ready to delete
 it, you can add ``%~`` before the text paragraph or line. This will cause novelWriter to skip the
 text entirely when generating previews or building manuscripts.
 This is a better way of removing text than converting them to regular comments, as you may want to
 include regular comments in your previews or draft manuscript.
 You can toggle the ignored text feature on and off for a paragraph by pressing :kbd:`Ctrl+Shift+D`
 on your keyboard with your cursor somewhere in the paragraph.
 :bdg-info:`Example`
 .. code-block:: md
   ### Scene
   %~ This text is completely ignored.
   This text is a regular paragraph.
@@ -45,7 +45,7 @@ however you want.
 Root Folder Types
 -----------------
-**Novel**
+**Novel** (Story)
   This is where you put the documents that are part of your story. You can create multiple Novel
   folders if you wish, but various parts of the application assumes each Novel folder belong to
   one novel.
@@ -53,35 +53,35 @@ Root Folder Types
   The Novel folder is somewhat special in that it can contain documents for chapters, scenes and
   story partitions. How this is indicated is covered in the section :ref:`docs_usage_headers`.
-**Plot**
+**Plot** (Notes)
   This is where you can keep notes and outlines of your story plots. Such notes can be
   particularly useful if you have outlines for sub plot. You can make references to these subplots
   from the scene documents, which makes it easier to track story progress.
-**Characters**
+**Characters** (Notes)
   Character notes go in this root folder type. For your main characters, you may want to make one
   document for each character. For smaller characters you can put multiple into the same document.
   In your chapters and scenes you can reference these character notes as Point of View or Focus
   characters.
-**Locations**
+**Locations** (Notes)
   The locations where your story takes place can be documented here. This, together with Plot and
   Characters are the particularly useful story elements to track, and to reference from your
   chapter and scene documents.
-**Timeline**
+**Timeline** (Notes)
   If the story has multiple plot timelines or jumps in time within the same plot, this folder type
   can be used to track this.
-**Objects**
+**Objects** (Notes)
   Important objects in the story, for instance physical objects that change hands often, can be
   tracked here.
-**Entities**
+**Entities** (Notes)
   Does your plot have many powerful organisations or companies? Or other entities that are part of
   the plot? They can be organised here.
-**Custom**
+**Custom** (Notes)
   The custom root folder type can be used for tracking anything else not covered by the above
   options.
@@ -3,3 +3,226 @@
 *******************
 Tags and References
 *******************
 One of the core features of novelWriter is its Tags and References system. This is perhaps one of
 the features that makes novelWriter different from other, similar applications. It is therefore not
 always obvious to new users how this is supposed to work.
 In novelWriter there are no forms or tables to fill in to define characters, locations or other
 elements of your story. Instead, you create documents in one of the root folders for notes. Within
 these documents you can set **tags**, like for instance for your main character. If you then want
 to annotate a scene with this character as its point-of-view, you create a **reference** to the
 tag.
 .. tip::
   If you find the Tags and Reference system difficult to follow just from reading this chapter,
   you can create a new project in the **Welcome** dialog's New project form and select "Create an
   example project" from the "Pre-fill project" option. The example project contains several
   examples of tags and references.
 .. _docs_usage_tags_refs_tags:
 How to Use Tags
 ===============
 The structure of your novelWriter project is inferred from the headings within the documents, not
 the documents themselves. See :ref:`docs_usage_headers` for more details. Therefore, metadata is
 also associated with headings, and not the documents directly.
 A "tag" in novelWriter is a word or phrase that you define as belonging to a heading. Tags are set
 by using the ``@tag`` :term:`keyword`.
 The basic format of a tag is ``@tag: TagName``.
 An alternative format of a tag is ``@tag: TagName | Display Name``.
 ``tagName`` (Required)
   This is a unique identifier of your choosing. It is the value you use later for making
   references back to the heading in the document.
 ``Display Name`` (Optional)
   This is an optional display name used for the tag. When you build your manuscript, you can for
   instance insert the point-of-view character name directly into chapter headings. By default, the
   ``tagName`` value is used in such headings, but if you use a shortened format internally in your
   project, you can use this to specify a more suitable format for your chapter headings.
 You can only set **one** tag per heading, and the tag has to be unique across **all** documents in
 the project.
 After a tag has been defined, it can be referenced in novel documents, or cross-referenced in other
 notes. Tags will also show up in the **Outline View** and in the references panel under the
 document viewer when a document is open in the viewer.
 The editor will indicate to you that the keyword is correctly used and that the tag is allowed,
 that is, the tag is unique, by adding a colour highlighting to it. An invalid tag should have a
 wiggly line under it, and will not receive the colour that valid tags do.
 The tag is the only part of these notes that novelWriter uses. The rest of the document content is
 there for you to use in whatever way you wish.
 .. 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.
 .. versionadded:: 2.6
   You can now add tags also to Novel Documents. These can be used for cross-referencing between
   chapters and scenes, and also from notes if desired.
 :bdg-info:`Example`
 Example of a heading with a tag for a character of the story:
 .. code-block:: md
   # Character: Jane Doe
   @tag: Jane | Jane Doe
   Some information about the character Jane Doe.
 When this is done in a document in a root folder of type **Characters**, the tag is automatically
 treated as an available character in your project with the value "Jane". You will then be able to
 reference "Jane" in any of your other documents using the reference keywords for characters.
 The character "Jane" will also show up in the **Character** tab in the **Reference** panel below
 the document viewer.
 .. note::
   It is the root folder type that defines what category of story elements the tag is indexed
   under. See :ref:`docs_usage_project_roots` for more details.
 .. _docs_usage_tags_refs_refs:
 How to Use References
 =====================
 Each heading of any level in your project can contain references to tags set in your notes. The
 references are gathered by the project index and used to generate the **Outline View**, among other
 things.
 References are set with a special keyword, with a list of corresponding tags. The valid keywords
 are listed below. The format of a reference line is ``@keyword: value1, [value2] ... [valueN]``.
 All reference keywords allow multiple values.
 ``@pov``
   The point-of-view character for the current section. The target must be a note tag in a
   **Character** type root folder.
 ``@focus``
   The character that has the focus for the current section. This can be used in cases where the
   focus is not the point-of-view character. The target must be a note tag in a **Character** type
   root folder.
 ``@char``
   For other characters in the current section. The target must be a note tag in a **Character**
   type root folder. This should not include the point-of-view or focus character if those
   references are used.
 ``@plot``
   The plot or subplot advanced in the current section. The target must be a note tag in a **Plot**
   type root folder.
 ``@time``
   The timelines touched by the current section. The target must be a note tag in a **Timeline**
   type root folder.
 ``@location``
   The location the current section takes place in. The target must be a note tag in a
   **Locations** type root folder.
 ``@object``
   Objects present in the current section. The target must be a note tag in a **Object** type root
   folder.
 ``@entity``
   Entities present in the current section. The target must be a note tag in an **Entities** type
   root folder.
 ``@custom``
   Custom references in the current section. The target must be a note tag in a **Custom** type
   root folder. The custom folder are for any other category of notes you may want to use.
 ``@mention``
   For anything, anyone or anyplace mentioned, but not present in the current section. It is
   intended for those cases where you reveal details about a character or place in a scene without
   otherwise being a part of it. This can be useful when checking for consistency later. Any tag in
   any root note folder can be listed under ``@mention``.
 ``@story``
   This is used when referencing a Novel Document, like a scene or chapter, from somewhere else in
   your project. It is possible to also set tags in documents in a **Novel** type folder, and this
   is the keyword you use to reference those.
 When tags and references are used correctly, it will be indicated by highlight colours in the
 editor.
 .. note::
   The highlighter may be mistaken if the index of defined tags is out of date. If so, press
   :kbd:`F9` to regenerate it, or select **Rebuild Index** from the **Tools** menu. In general, the
   index for a document is regenerated when it is saved, so this shouldn't normally be necessary.
 .. tip::
   If you add a reference in the editor to a tag that doesn't yet exist, you can right-click it and
   select **Create Note for Tag**. This will generate a new note automatically with the new tag
   defined.
 One note can also reference another note in the same way novel documents do. When the note is
 opened in the document viewer, the references become clickable links, making it easier to follow
 connections in the plot. You can follow links in the document editor by clicking them with the
 mouse while holding down the :kbd:`Ctrl` key. Clicked links are always opened in the view panel.
 Your notes don't show up in the **Outline View**, so referencing between notes is only meaningful
 if you want to be able to click-navigate between them, or of course if you just want to highlight
 that two notes are related.
 .. tip::
   If you cross-reference between notes and export your project as an HTML document using the
   **Manuscript Build** tool, the cross-references become clickable links in the exported HTML
   document as well.
 :bdg-info:`Example`
 Example of a novel document with references to characters and plots:
 .. code-block:: md
   ## Chapter 1
   @pov: Jane
   ### Scene 1
   @char: John, Sam
   @plot: Main
   Once upon a time ...
 .. _docs_usage_tags_refs_completer:
 Auto-Completion in the Editor
 -----------------------------
 An auto-completer context menu will show up automatically in the document editor when you type the
 character ``@`` on a new line. It will first suggest tag or reference keywords for you to add, and
 after the ``:`` has been added, suggest references from the list of tags you have already defined.
 You can use the auto-completer to add multiple references with a ``,`` between them, and even type
 new ones. New references can be created by right-clicking on them and selecting **Create Note for
 Tag** from the menu.
 .. versionadded:: 2.2
@@ -178,45 +178,6 @@ for the mouse or touchpad.
 Project Layout
 ==============
 This is a brief introduction to how you should structure your writing projects. All of this will be
 covered in more detail later.
 The main point of novelWriter is that you are free to organise your project documents as you wish
 into sub-folders or sub-documents, and split the text between these documents in whatever way suits
 you. All that matters to novelWriter is the linear order the documents appear at in the project
 tree (top to bottom). The chapters, scenes and sections of the novel are determined by the headings
 within those documents.
 .. figure:: images/fig_header_levels.png
   An illustration of how heading levels correspond to the novel structure.
 The four heading levels, **Level 1** to **Level 4**, are treated as follows:
 * **Level 1** is used for the novel title, and for partitions.
 * **Level 2** is used for chapter titles.
 * **Level 3** is used for scene titles -- optionally replaced by separators.
 * **Level 4** is for section titles within scenes, if such granularity is needed.
 The project tree will select an icon for the document based on the first heading in it.
 This heading level structure is only taken into account for :term:`novel documents`. For
 :term:`project notes`, the heading levels have no structural meaning, and you are free to use them
 however you want. See :ref:`a_struct` and :ref:`a_references` for more details.
 .. tip::
   You can add documents as child items of other documents. This is often more useful than adding
   folders, since you anyway may want to have the chapter heading in a separate document from your
   individual scene documents so that you can rearrange scene documents freely without affecting
   chapter placement.
 .. versionadded:: 2.6
   The heading levels for partitions, chapters and scenes only apply within novelWriter. When you
   generate your manuscript, chapters are considered as the topmost heading level, with scenes
   below it. Partitions are inserted as text elements in most formats.
 .. _a_breakdown_export:
@@ -4,44 +4,11 @@
 Formatting Your Text
 ********************
 The novelWriter text editor is a plain text editor that uses formatting codes for setting meta data
 values and allowing for some text formatting. The syntax is based on Markdown, but novelWriter is
 **not** a Markdown editor. It supports basic formatting like emphasis (italic), strong importance
 (bold) and strike through text, as well as four levels of headings. For some further complex
 formatting needs, a set of shortcodes can be used.
 In addition to formatting codes, novelWriter allows for comments, a synopsis tag, and a number of
 keyword and value sets used for :term:`tags<tag>` and :term:`references<reference>`. There are also
 some codes that apply to whole paragraphs. See :ref:`a_fmt_text` for more details.
 URLs should also be highlighted and become clickable. However, only URLs starting with "http" or
 "https" are recognised. In the editor, you must hold down the :kbd:`Ctrl` key when clicking a URL
 to follow it.
 .. _a_fmt_hlight:
 Syntax Highlighting
 ===================
 The editor has a syntax highlighter feature that is meant to help you know when you've used the
 formatting tags or other features correctly. It will change the colour and font size of your
 headings, change the text colour of emphasised text, and it can also show you where you have
 dialogue in your text.
 .. figure:: images/fig_references.png
   An example of the colour highlighting of references. "Bob" is not defined, and "@blabla" is not
   a valid reference type.
 When you use the keywords to set tags and references, these also change colour. Correct keywords
 have a distinct colour, and the references themselves will get a colour if they are valid. Invalid
 references will get a squiggly error line underneath. The same applies to duplicate tags.
 There are a number of syntax highlighter colour themes available, both for light and dark GUIs. You
 can select them from **Preferences**.
 .. _a_fmt_head:
 Headings
@@ -63,287 +30,42 @@ Text Emphasis with Markdown
 Formatting with Shortcodes
 ==========================
 For additional formatting options, you can use shortcodes. Shortcodes is a form of in-line codes
 that can be used to change the format of the text that follows and opening code, and last until
 that formatting region is ended with a closing code.
 These shortcodes are intended for special formatting cases, or more complex cases that cannot be
 solved with simple Markdown-like formatting codes. Available shortcodes are listed below.
 .. csv-table:: Shortcodes Formats
   :header: "Syntax", "Description"
   :widths: 40, 60
   :class: "tight-table"
   "``[b]text[/b]``",     "Text is rendered as bold text."
   "``[i]text[/i]``",     "Text is rendered as italicised text."
   "``[s]text[/s]``",     "Text is rendered as strike through text."
   "``[u]text[/u]``",     "Text is rendered as underlined text."
   "``[m]text[/m]``",     "Text is rendered as highlighted text."
   "``[sup]text[/sup]``", "Text is rendered as superscript text."
   "``[sub]text[/sub]``", "Text is rendered as subscript text."
 Unlike Markdown style codes, these can be used anywhere within a paragraph. Even in the middle of a
 word if you need to. You can also freely combine them to form more complex formatting.
 The shortcodes are available from the **Format** menu and in the editor toolbar, which can be
 activated by clicking the left-most icon button in the editor header.
 .. note::
   Shortcodes are not processed until you generate a preview or generate a manuscript document. So
   there is no highlighting of the text between the formatting markers. There is also no check that
   your markers make sense. You must ensure that you have both the opening and closing formatting
   markers where you want them.
 .. versionadded:: 2.2
 .. _a_fmt_comm:
 Comments and Synopsis
 =====================
 In addition to the above formatting features, novelWriter also allows for comments in documents.
 The text of a comment is always ignored by the word counter. The text can also be filtered out
 when building the manuscript or viewing the document.
 The first word of a comment, followed by a colon, can be one of a set of modifiers that indicates
 the comment is intended for a specific purpose. For instance, if the comment starts with
 ``Synopsis:``, the comment is treated in a special manner and will show up in the
 :ref:`a_ui_outline` in a dedicated column. The word ``synopsis`` is not case sensitive. If it is
 correctly formatted, the syntax highlighter will indicate this by altering the colour of the word.
 The different styles of comments are as follows:
 ``% Your comment text ...``
   This is a comment. The text is not rendered by default (this can be overridden), seen in the
   document viewer, or counted towards word counts. It is intended for you to make notes in your
   text for your own sake, whatever that may be, that isn't part of the story text. This is the
   general format of a comment.
 ``%Synopsis: Your synopsis text ...``
   This is a synopsis comment. It is generally treated in the same way as a regular comment, except
   that it is also captured by the indexing algorithm and displayed in the :ref:`a_ui_outline`. It
   can also be filtered separately when building the project to for instance generate an outline
   document of the whole project.
 ``%Short: Your short description ...``
   This is a short description comment. It is identical to the synopsis comment (they are
   interchangeable), but is intended to be used for project notes. The text shows up in the
   Reference panel below the document viewer in the last column labelled **Short Description**.
 ``%Footnote.<key>: Your footnote text ...``
   This is a special comment assigned to a footnote marker. See :ref:`a_fmt_footnote` for how to
   use them in your text.
 .. note::
   Only one comment can be flagged as a synopsis or short comment for each heading. If multiple
   comments are flagged as synopsis or short comments, the last one will be used and the rest
   ignored.
 .. _a_fmt_footnote:
 Footnotes
 =========
 Footnotes are added with a shortcode, paired with a matching comment for the actual footnote text.
 The matching is done with a key that links the two. If you insert a footnote from the **Insert**
 menu, a unique key is generated for you.
 The insert feature will add the footnote shortcode marker at the position of your cursor in the
 text, and create the associated footnote comment right after the paragraph, and move the cursor
 there so you can immediately start typing the footnote text.
 The footnote comment can be anywhere in the document, so if you wish to move them to, say, the
 bottom of the text, you are free to do so.
 Footnote keys are only required to be unique within a document, so if you copy, move or merge text,
 you must make sure the keys are not duplicated. If you use the automatically generated keys from
 the **Insert** menu, they are unique among all indexed documents. They are not guaranteed to be
 unique against footnotes in the Archive or Trash folder though, but the chance of accidentally
 generating the same key twice in a project is relatively small in the first place (1 in 810 000).
 This is what a footnote inserted into a paragraph may look like when completed:
 .. code-block:: md
   This is a text paragraph with a footnote[footnote:fn1] in the middle.
   %Footnote.fn1: This is the text of the footnote.
 .. versionadded:: 2.5
 .. _a_fmt_ignore:
 Ignored Text
 ============
 If you want to completely ignore some of the text in your documents, but are not ready to delete
 it, you can add ``%~`` before the text paragraph or line. This will cause novelWriter to skip the
 text entirely when generating previews or building manuscripts.
 This is a better way of removing text than converting them to regular comments, as you may want to
 include regular comments in your previews or draft manuscript.
 You can toggle the ignored text feature on and off for a paragraph by pressing :kbd:`Ctrl+Shift+D`
 on your keyboard with your cursor somewhere in the paragraph.
 Example:
 .. code-block:: md
   %~ This text is ignored.
   This text is a regular paragraph.
 .. _a_fmt_tags:
 Tags and References
 ===================
 The document editor supports a set of keywords used for setting tags, and making references between
 documents based on those tags.
 You must use the keyword ``@tag:`` to define a tag. The tag can be set once per section defined by
 a heading. Setting it multiple times under the same heading will just override the previous
 setting.
 ``@tag: value``
   A tag keyword followed by the tag value, like for instance the name of a character.
 References can be set anywhere within a section, and are collected according to their category.
 References are on the form:
 ``@keyword: value1, value2, ..., valueN``
   A reference keyword followed by a value, or a comma separated list of values.
 Tags and references are covered in detail in the :ref:`a_references` chapter. The keywords can be
 inserted at the cursor position in the editor via the **Insert** menu. If you start typing an ``@``
 on a new line, and auto-complete menu will also pop up suggesting keywords.
 .. _a_fmt_align:
 Paragraph Alignment and Indentation
 ===================================
 All documents have the text by default aligned to the left or justified, depending on your setting
 in **Preferences**.
 You can override the default text alignment on individual paragraphs by specifying alignment tags.
 These tags are double angle brackets. Either ``>>`` or ``<<``. You put them either before or after
 the paragraph, and they will "push" the text towards the edge the brackets point towards. This
 should be fairly intuitive.
 Indentation uses a similar syntax. But here you use a single ``>`` or ``<`` to push the text away
 from the edge.
 Examples:
 .. csv-table:: Text Alignment and Indentation
   :header: "Syntax", "Description"
   :widths: 40, 60
   :class: "tight-table"
   "``>> Right aligned text``",        "The text paragraph is right-aligned."
   "``Left aligned text <<``",         "The text paragraph is left-aligned."
   "``>> Centred text <<``",           "The text paragraph is centred."
   "``> Left indented text``",         "The text has an increased left margin."
   "``Right indented text <``",        "The text has an increased right margin."
   "``> Left/right indented text <``", "The text has both margins increased."
 .. note::
   The text editor will not show the alignment and indentation live. But the viewer will show them
   when you open the document there. It will of course also be reflected in the document generated
   from the manuscript build tool as long as the format supports paragraph alignment.
 Alignment with Line Breaks
 --------------------------
 If you have line breaks in the paragraph, the markers for all the lines are combined and used for
 the entire paragraph. For the following text, all lines will be centred:
 .. code-block:: 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 <<
 Alignment with First Line Indent
 --------------------------------
 If you have first line indent enabled in your Manuscript build settings, you probably want to
 disable it for text in verses. Adding any alignment tags will cause the first line indent to be
 switched off for that paragraph.
 The following text will always be aligned against the left margin:
 .. code-block:: 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
 .. _a_fmt_break:
 Vertical Space and Page Breaks
 ==============================
 You can apply page breaks to partition, chapter and scene headings for novel documents from the
 **Manuscript Build** tool. If you need to add a page break or additional vertical spacing in other
 places, there are special codes available for this purpose.
 Adding more than one line break between paragraphs will **not** increase the space between those
 paragraphs when building the project. To add additional space between paragraphs, add the text
 ``[vspace]`` on a line of its own, and the build tool will insert a blank paragraph in its place.
 If you need multiple blank paragraphs just add a colon and a number to the above code. For
 instance, writing ``[vspace:3]`` will insert three blank paragraphs.
 If you need to add a page break somewhere, put the text ``[new page]`` on a line by itself before
 the text you wish to start on a new page.
 .. note::
   The page break code is applied to the text that follows it. It adds a "page break before" mark
   to the text when exporting to HTML or Open Document. This means that a ``[new page]`` which has
   no text following it, it will not result in a page break.
 **Example:**
 .. code-block:: 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 has pages.
 .. _a_fmt_stats:
 Inserting Word Counts in the Text
 =================================
 The cover page of a manuscript normally has the word count stated on it. Any statistics value
 collected by novelWriter can be inserted into any document. You can generate the code for this from
 the **Insert** menu under **Word/Character Count**.
 The value inserted is the actual count for your entire manuscript, so it is not populated until you
 run the **Manuscript Build** tool. Until then they will show up as "0" in the viewer panel.