Improve documentation for dialogue highlighting and story comments

docs/source/features/dialogue.rst

@@ -0,0 +1,91 @@
+.. _docs_features_dialogue:
+
+*********************
+Dialogue Highlighting
+*********************
+
+Character dialogue can be automatically highlighted in your text both while you're writing and in
+generated manuscript documents.
+
+The default language settings in novelWriter are for English. That includes the dialogue
+highlighting settings. However, many dialogue styles are supported. You can modify this by changing
+the settings under "Text Highlighting" in **Preferences**.
+
+.. figure:: images/fig_dialogue_highlighting.png
+
+   The **Text Highlighting** section of **Preferences**.
+
+
+Quoted Dialogue
+===============
+
+By default, dialogue highlighting is enabled for double quotes as defined in the **Quotation
+Style** section of **Preferences**.
+
+.. figure:: images/fig_dialogue_quote_styles.png
+
+   The **Quotation Style** section of **Preferences**.
+
+You can change which quote symbols are highlighted by selecting one of the options of "None",
+"Single", "Double", or "Both" from the "Highlight dialogue" setting under **Text Highlighting**.
+
+You can also enable or disable the "Allow open-ended dialogue" setting to allow the style where
+multi-paragraph dialogue is not closed until the last paragraph.
+
+.. admonition:: Limitations
+
+   Dialogue highlighting for single quotes is difficult to process when the same single quote
+   symbol is also used for apostrophes. There isn't a good solution to this. Your best option in
+   those cases is to insert an alternative apostrophe symbol in cases where the highlighter guesses
+   wrongly. See :ref:`docs_more_typographical_symbols_apostrophe` for more details.
+
+
+Alternative Dialogue
+====================
+
+There is also an "Alternative dialogue symbols" setting you can use to add your own symbols. These
+are highlighted in a different colour than regular dialogue, so you can use both at the same time.
+The intended use case here is if you use an alternative style to distinguish a different style of
+communication.
+
+The feature idea came from a science fiction series where mind-to-mind communication used a
+different quotation style.
+
+
+Dialogue Line Symbols
+=====================
+
+In some languages, a single symbol at the start of a paragraph can indicate that the whole
+paragraph is dialogue. Often this is a short dash (en dash), but not always.
+
+.. figure:: images/fig_dialogue_line.png
+
+   An example of dialogue starting with a short dash.
+
+You can enable this feature by adding the symbols to the "Dialogue line symbols" setting. Multiple
+symbols are allowed.
+
+
+Dialogue with Narrator Break
+============================
+
+The dialogue symbol setting will not detect when the narrator breaks in. In some styles there is no
+way to actually detect this; in others there are. These are usually dashes. You can select one of
+the supported dash symbols for narrator breaks.
+
+.. figure:: images/fig_dialogue_narrator_break.png
+
+   An example of dialogue starting with a short dash and a long dash narrator break.
+
+
+Alternating Dialogue and Narration
+==================================
+
+The alternating dialogue and narration style is supported with the "Alternating dialogue/narration
+symbol" setting. It can be set to one of the supported dashes. This style will switch into dialogue
+mode when it encounters the selected dash in a paragraph, and switch back out when it sees the next
+one, and so forth.
+
+.. figure:: images/fig_dialogue_alternating.png
+
+   An example of alternating dialogue and narration using a long dash.

docs/source/features/shortcuts.rst

@@ -8,6 +8,7 @@ Most features in novelWriter are available as keyboard shortcuts. This is a refe
 shortcuts. Most of them are also listed in the application's user interface.
 
 .. note::
+
    On MacOS, replace :kbd:`Ctrl` with :kbd:`Cmd`.
 
 

docs/source/features/story_comments.rst

@@ -1,25 +1,26 @@
 .. _docs_features_story:
 
-************************
-Story Structure Comments
-************************
+**************
+Story Comments
+**************
 
-
-As of version 2.7, story structure annotations using the ``%story`` style of comment is supported.
-To use the feature, make the first word of a comment ``story``, followed by a period, a structure
-term, a colon, a space and the text for that term.
-
-Here's an example:
-
-.. code-block:: md
-
-   %story.term: text
+A special set of comment styles allow for annotating your text with structure information. There
+are two styles of comments available. They are an extension to regular comments as described in
+:ref:`docs_usage_comments`.
 
 .. versionadded:: 2.7
 
 
+Story Structure Comments
+========================
+
+You can annotate story structure by using the ``%Story`` style of comment. To use the feature,
+make the first word of a comment ``Story``, followed by a period, a structure term, a colon, a
+space and the text for that term.
+
+
 Usage
-=====
+-----
 
 The story term can be anything that you want to track in the manuscript. This construct is intended
 to make it easier to extract metadata from a work to perform a structural analysis of the story.
@@ -33,6 +34,8 @@ story is composed of "beats", and that each beat has an inciting incident, a com
 crisis, and a resolution. One might capture these elements of a beat where a character overcomes
 their fear of giving a speech as:
 
+:bdg-info:`Example`
+
 .. code-block:: md
 
    ### Scene
@@ -56,7 +59,7 @@ fast-paced scenes without a break that readers might become fatigued or over-sti
 
 
 Output
-======
+------
 
 The story structure comments can be included in the manuscript, and are formatted similarly to
 the synopsis comments:
@@ -67,3 +70,41 @@ the synopsis comments:
 
 When you export your project data from the Outline View, all story structure terms are added as
 columns to the exported file, which can then be opened in the spread sheet software of your choice.
+
+
+Story Notes
+===========
+
+Story notes are similar to story structure comments, but have no predefined meaning. Essentially
+they are a generalisation of the story structure comment, and the only point of having this
+additional format is to allow you do filter them in and out of your manuscript independently.
+
+You can annotate story notes by using the ``%Note`` style of comment. To use the feature,
+make the first word of a comment ``Note``, followed by a period, a term, a colon, a space and the
+text for the note.
+
+
+Usage
+-----
+
+These notes are free form, but one intended use case is to add consistency annotations to your text
+to remind yourself where you have described something that must be checked against other parts of
+your text later on.
+
+:bdg-info:`Example`
+
+.. code-block:: md
+
+   ### Scene
+
+   %Synopsis: Carol overcomes her fear of giving a speech.
+
+   %Note.consistency: This is the first time in the story Carol gives a speech.
+
+
+Output
+------
+
+Story notes are included in the manuscript in exactly the same way story structure comments are,
+but has a separate inclusion setting in the build settings. They are also included in CSV exports
+from the **Outline View**.

docs/source/index.rst

@@ -65,9 +65,10 @@ storage for robustness.
    :caption: Additional Features
    :hidden:
 
-   features/shortcuts
+   features/dialogue
    features/breaks_and_spaces
-   features/story_structure
+   features/story_comments
+   features/shortcuts
 
 .. toctree::
    :maxdepth: 1

docs/source/more/counting.rst

@@ -7,7 +7,7 @@ Word and Text Counts
 This is an overview of how words and other counts of your text are performed. The counting rules
 should be relatively standard, and are compared to Libre Office Writer rules.
 
-The counts provided in the app on the raw text is meant to be approximate. For more accurate
+The counts provided in the app on the raw text are meant to be approximate. For more accurate
 counts, you need to build your manuscript in the **Manuscript Tool** and check the counts on the
 generated preview.
 

docs/source/more/typography.rst

@@ -17,7 +17,7 @@ keyboard shortcuts. See :ref:`docs_features_shortcuts_insert`.
 This chapter provides some additional information on how novelWriter handles these symbols.
 
 
-.. _a_typ_notes:
+.. _docs_more_typographical_symbols:
 
 Special Notes on Symbols
 ========================
@@ -66,6 +66,8 @@ codes. Using these correctly will also prevent the auto-replace and dialogue hig
 misunderstanding their meaning in the text.
 
 
+.. _docs_more_typographical_symbols_apostrophe:
+
 Modifier Letter Apostrophe
 --------------------------
 

docs/source/user_interface/editor_viewer.rst

@@ -182,18 +182,3 @@ tricky for languages that use the same symbol for these, like English does.
    If the auto-replace feature changes a symbol when you did not want it to change, pressing
    :kbd:`Ctrl+Z` once after the auto-replacement will undo it without undoing the character
    you typed before it.
-
-
-.. _docs_ui_edit_view_dialogue:
-
-Dialogue Highlighting
-=====================
-
-The editor and viewer can optionally highlight character dialogue in your novel documents. By
-default, this feature is set to display text in double quotes as dialogue. In **Preferences**, you
-can change this to support various other dialogue markers that instead uses dashes to indicate
-dialogue, like those used in Spanish, Portuguese, Polish, etc.
-
-Various styles are supported by changing the settings under "Text Highlighting" in **Preferences**.
-
-It is also possible to include the dialogue highlighting in your manuscripts.