Create story structure docs (#2295)

docs/source/index.rst

@@ -75,6 +75,13 @@ See :ref:`a_started` for more details.
    project_references
    project_manuscript
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Writing Aids
+   :hidden:
+
+   writing_story
+
 .. toctree::
    :maxdepth: 1
    :caption: Additional Details

docs/source/int_overview.rst

@@ -26,27 +26,27 @@ In order to use novelWriter effectively, you need to know the basics of how it w
 chapters will explain the main principles. They start with the basics, and get more detailed as you
 read on.
 
-:ref:`a_breakdown` – Essential Information
+:ref:`a_breakdown` -- Essential Information
    This chapter explains the basics of how the application works and what it can and cannot do.
 
-:ref:`a_ui_project` – Recommended Reading
+:ref:`a_ui_project` -- Recommended Reading
    This chapter will give you a more detailed explanation of how you can use the user interface
    components to organise and view your project work.
 
-:ref:`a_ui_writing` – Recommended Reading
+:ref:`a_ui_writing` -- Recommended Reading
    This chapter will give you a more detailed explanation of how the text editor and viewer work.
 
-:ref:`a_fmt` – Essential Information
+:ref:`a_fmt` -- Essential Information
    This chapter covers how you should format your text. The editor is plain text, so text
    formatting requires some basic markup. The structure of your novel is also inferred from how you
    use headings. Tags and references are implemented by special keywords.
 
-:ref:`a_kb` – Optional / Lookup
+:ref:`a_kb` -- Optional / Lookup
    This chapter lists all the keyboard shortcuts in novelWriter and what they do. Most of the
    shortcuts are also listed next to their menu entries inside the app, or in tool tips. This
    chapter is mostly for reference.
 
-:ref:`a_typ` – Optional
+:ref:`a_typ` -- Optional
    This chapter gives you an overview of the special typographical symbols available in
    novelWriter. The auto-replace feature can handle the insertion of standard quote symbols for
    your language, and other special characters. If you use any symbols aside from these, their
@@ -61,25 +61,37 @@ structure of your novel and show you additional information about its flow and c
 to take advantage of these features, you must structure your text in a specific way and add some
 meta data for it to extract.
 
-:ref:`a_proj` – Essential Information
+:ref:`a_proj` -- Essential Information
    This chapter explains how you organise the content of your project, and how to set up automated
    backups of your work.
 
-:ref:`a_struct` – Essential Information
+:ref:`a_struct` -- Essential Information
    This chapter covers the way your novel's structure is encoded into the text documents. It
    explains how the different levels of headings are used, and some special formatting for
    different kinds of headings.
 
-:ref:`a_references` - Recommended Reading
+:ref:`a_references` -- Recommended Reading
    This chapter explains how you organise your notes, and how the Tags and References system works.
    This system lets you cross-link your documents in your project, and display these references in
    the application interface.
 
-:ref:`a_manuscript` - Recommended Reading
+:ref:`a_manuscript` -- Recommended Reading
    This chapter explains how the **Manuscript Build** tool works, how you can control the way
    chapter titles are formatted, and how scene and section breaks are handled.
 
 
+Writing Aids
+============
+
+We are in the process of adding tools to novelWriter that can be used to track more information
+about your project to assist in your writing. These tools are entirely optional and will not be in
+your way if you choose to not use them.
+
+:ref:`a_story_structure` -- Writing Tools
+   Story structure comments are a way to add meta data that can be used to analyse the structure of
+   your writing. These comments can be exported to spreadsheets for analysis.
+
+
 Additional Details & Technical Topics
 =====================================
 

docs/source/writing_story.rst

@@ -0,0 +1,69 @@
+.. _a_story_structure:
+
+************************
+Story Structure 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
+
+.. versionadded:: 2.7
+
+
+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.
+
+There are probably as many ways to examine story structure as there are authors and editors
+combined. For this reason the story tag is flexible. You can use any terms you want and track any
+aspect of the story that serves your purposes.
+
+An example method has been advanced by Shawn Coyne in *The Story Grid*. This method asserts that a
+story is composed of "beats", and that each beat has an inciting incident, a complication, a
+crisis, and a resolution. One might capture these elements of a beat where a character overcomes
+their fear of giving a speech as:
+
+.. code-block:: md
+
+   ### Scene
+
+   %Synopsis: Carol overcomes her fear of giving a speech.
+
+   %Story.incite: Carol is pleased to be invited to a conference to see her boss deliver a keynote.
+   %Story.complication: Carol's boss calls in sick and asks her to deliver a big speech.
+   %Story.crisis: Carol has a fear of appearing on stage.
+   %Story.resolution: Carol engages the help of a coach who helps her overcome her fears and delivers a great speech.
+
+Other analytical models propose tracking a scene's pace, how it affects the mood of the story, or
+which element(s) of the story's genre are being satisfied. An author can use this mechanism to
+track any element of a scene. Some examples include time of day, how much time passes in the scene,
+or even the physical form of a shape-shifting character. If a story involves magic, one could track
+which wand a main character has in hand. It's up to tha author.
+
+When the story and other scene metadata is extracted into a tabular form, it is possible to get a
+comprehensive overview of the story and to identify possible issues. For example, so many
+fast-paced scenes without a break that readers might become fatigued or over-stimulated.
+
+
+Output
+======
+
+The story structure comments can be included in the manuscript, and are formatted similarly to
+the synopsis comments:
+
+.. figure:: images/fig_story_structure_manuscript.png
+
+   A set of story structure comments as shown in the Manuscript tool.
+
+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.