Move and expand text into usage section

docs/source/usage/advanced_formatting.rst

@@ -0,0 +1,5 @@
+.. _docs_usage_shortcodes:
+
+*******************
+Advanced Formatting
+*******************

docs/source/usage/basic_formatting.rst

@@ -3,3 +3,93 @@
 ****************
 Basic Formatting
 ****************
+
+.. _Markdown: https://en.wikipedia.org/wiki/Markdown
+
+The basic text formatting syntax of novelWriter is based on Markdown_. It is only a subset of the
+Markdown syntax though. Lists, images, and links are not supported.
+
+URLs in the text should automatically 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.
+
+
+.. _docs_usage_basics_paragraphs:
+
+Text Paragraphs
+===============
+
+A text paragraph is indicated by a blank line. That is, you need two line breaks to separate two
+fragments of text into two paragraphs. Single line breaks are treated as line breaks within a
+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
+being separated by blank lines.
+
+:bdg-success:`Correct`
+
+.. code-block:: md
+
+   ### Scene
+
+   This is a text paragraph.
+
+   This is another text paragraph.
+
+:bdg-danger:`Incorrect`
+
+.. code-block:: md
+
+   ### Scene
+
+   This is a text paragraph.
+       This is meant to be another text paragraph.
+
+If you do as shown in the "Incorrect" example, novelWriter will understand this as a single
+paragraph with two lines.
+
+
+.. _docs_usage_basics_emphasis:
+
+Text Emphasis with Markdown
+===========================
+
+A minimal set of Markdown text emphasis styles are supported for text paragraphs.
+
+``_text_``
+   The text is rendered as emphasised text (italicised).
+
+``**text**``
+   The text is rendered as strongly emphasised text (bold).
+
+``~~text~~``
+   Strike through text.
+
+In Markdown guides it is often recommended to differentiate between strong emphasis and emphasis
+by using ``**`` for strong and ``_`` for emphasis, although Markdown generally also supports ``__``
+for strong and ``*`` for emphasis. However, since the differentiation makes the highlighting and
+conversion significantly simpler and faster, in novelWriter this is a rule, not just a
+recommendation.
+
+In addition, the following rules apply:
+
+1. The emphasis and strike through formatting tags do not allow spaces between the words and the
+   tag itself. That is, ``**text**`` is valid, ``**text **`` is not.
+2. More generally, the delimiters must be on the outer edge of words. That is, ``some **text in
+   bold** here`` is valid, ``some** text in bold** here`` is not.
+3. If using both ``**`` and ``_`` to wrap the same text, the underscore must be the **inner**
+   wrapper. This is due to the underscore also being a valid word character, so if they are on the
+   outside, they violate rule 2.
+4. Text emphasis does not span past line breaks. If you need to add emphasis to multiple lines or
+   paragraphs, you must apply it to each of them in turn.
+5. Text emphasis can only be used in comments and paragraphs. Headings and meta data tags don't
+   allow for formatting, and any formatting markup will be rendered as-is.
+
+.. tip::
+
+   novelWriter supports standard escape syntax for the emphasis markup characters in case the
+   editor misunderstands your intended usage of them. That is, ``\*``, ``\_`` and ``\~`` will
+   generate a plain ``*``, ``_`` and ``~``, respectively, without interpreting them as part of the
+   markup.

docs/source/usage/chapters_and_scenes.rst

@@ -3,3 +3,82 @@
 *******************
 Chapters and Scenes
 *******************
+
+.. _Markdown: https://en.wikipedia.org/wiki/Markdown
+
+Since novelWriter uses a plain text format, the structure of your novel must follow a certain set
+of simple rules. For documents in a **Novel** type root folder, it is the heading that determines
+if it is a Chapter or a Scene document.
+
+The formatting of headings is based on Markdown_, and a heading is indicated by a line starting
+with the ``#`` character. It accepts from one two four of these. You can use multiple headings in
+the same document, but it is the first heading that determines which icon and information is
+displayed in the project tree.
+
+.. note::
+
+   You can use the same headings for your notes in the other root folders, but they aren't
+   treated as chapters or scenes, so you are free to use them as you want.
+
+
+.. _docs_usage_headers_levels:
+
+Heading Levels
+==============
+
+.. figure:: images/fig_heading_levels.png
+
+   An illustration of how heading levels correspond to the novel structure.
+
+Four levels of headings are understood for novel documents:
+
+``# Title Text``
+   This is a heading level one. This heading indicates the start of a new partition. Partitions are
+   for when you want to split your story into "Part 1", "Part 2", etc. You can also choose to use
+   them for splitting the text up into acts, and then hide these headings in your manuscript.
+
+``## 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.
+
+``### Scene Title``
+   This is a heading level three. This heading indicates the start of a new scene. Scene numbers or
+   scene separators can be inserted automatically when building the manuscript, so you can use the
+   title field as a working title for your scenes if you wish, but you must provide a minimal
+   title.
+
+``#### Section Title``
+   This is a heading level four. This heading indicates the start of a new section. Section titles
+   can be replaced by separators or ignored completely when building the manuscript. The meaning of
+   a section is really whatever you want it to be. You can use it to split your scenes up into
+   chunks, or into separate documents.
+
+For headings level one through three, adding a ``!`` modifies the meaning of the heading. The
+alternative meaning of the heading is only relevant to when you generate your manuscript, but you
+may want to keep the use cases in mind while writing.
+
+``#! Title Text``
+   This tells the **Manuscript Build** tool that the level one heading is intended to be used for
+   the novel or notes folder's main title, like for instance the novel title on the cover page.
+   When building the manuscript, this will use a different styling of the title, which you can
+   modify independently from how partition titles are styled.
+
+``##! Chapter Title``
+   This tells the **Manuscript Build** tool to not assign a chapter number to this chapter title if
+   automatic chapter numbers are enabled. Such titles are useful for prologues and epilogues for
+   instance.
+
+``###! 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
+   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.
+
+.. note::
+
+   The space after the ``#`` or ``!`` character is mandatory. The syntax highlighter will change
+   colour and font size when the heading is correctly formatted.

docs/source/usage/folders_and_documents.rst

@@ -1,5 +0,0 @@
-.. _docs_usage_dirs_docs:
-
-*********************
-Folders and Documents
-*********************

docs/source/usage/organising_project.rst

@@ -0,0 +1,118 @@
+.. _docs_usage_project:
+
+***********************
+Organising Your Project
+***********************
+
+Your project is organised into a set of top level folders called "Root Folders", which each have
+specific meaning in the project. Your project documents and notes are stored under these root
+folders. All the content of your project is available in the **Project Content** panel on the left
+side of the main window.
+
+.. figure:: images/fig_project_tree.png
+
+   The **Project Content** tree populated with example documents.
+
+Each line in the project tree shows the label of each item, its word count (or alternatively
+character count), an active/inactive icon (see :ref:`docs_features_active`), and a custom status
+icon (see :ref:`docs_features_status`).
+
+You can add, view and edit the documents in the project tree by right-clicking on them. Some
+features are also located in the buttons along the top next to the **Project Content** label.
+
+
+.. _docs_usage_project_roots:
+
+How Root Folders Work
+=====================
+
+Projects are structured into a set of top level folders called "Root Folders". They are visible in
+the project tree at the left side of the main window.
+
+The documents that make up your story go into a root folder of type **Novel**. Your notes go into
+the other root folders. These other root folder types are separated into types depending on what
+kind of notes go into them. This is not only for organisation. It also matters to how you can
+reference these notes later. We will come back to this in the :ref:`docs_usage_tags_refs` section.
+
+A new project may not have all of the root folders present, but you can add the ones you want from
+the project tree tool bar.
+
+The intended usage of each type of root folder is listed below. However, aside from the **Novel**
+folder, no restrictions are applied by the application on what you put in them. You can use them
+however you want.
+
+
+Root Folder Types
+-----------------
+
+**Novel**
+   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.
+
+   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**
+   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**
+   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**
+   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**
+   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**
+   Important objects in the story, for instance physical objects that change hands often, can be
+   tracked here.
+
+**Entities**
+   Does your plot have many powerful organisations or companies? Or other entities that are part of
+   the plot? They can be organised here.
+
+**Custom**
+   The custom root folder type can be used for tracking anything else not covered by the above
+   options.
+
+**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
+   of the document will be ignored by the scanner that looks for tags, and it will be ignored in
+   any outline view and in your manuscript.
+
+**Trash**
+   This folder behaves like you expect. Anything dropped in here can be deleted permanently from
+   the project, and the content doesn't show up anywhere else in novelWriter.
+
+The root folders are closely tied to the tags and reference system. Each folder type except
+**Archive** and **Trash** corresponds to one or more categories of tags that can be used to
+reference the content in them. See :ref:`docs_usage_tags_refs` for more details.
+
+.. tip::
+
+   The root folders have standard names, but you can rename them to whatever you want.
+
+
+.. _docs_usage_project_folders:
+
+Regular Folders
+===============
+
+Regular folders, those that are not root folders, have no structural significance to the project.
+When novelWriter is processing the documents in a project, like for instance when you create a
+manuscript from it, these folders are ignored. Only the order of the documents themselves matter.
+
+The folders are there purely as a way for you to organise the documents in meaningful sections and
+to be able to collapse and hide them in the project tree when you're not working on those
+documents.