Update docs project section

docs/source/project_export.rst

@@ -1,11 +1,12 @@
 .. _a_export:
 
-******************
+***********************
-Exporting Projects
+Building the Manuscript
-******************
+***********************
 
-The novelWriter project can be exported in various formats using the build tool available from
+You can at any time build a manuscript, an outline of your notes, or any other type of document
-:guilabel:`Build Novel Project` in the :guilabel:`Tools` menu, or by pressing :kbd:`F5`.
+from the text in your project. All of this is handled by the :guilabel:`Build Novel Project` tool.
+You can activate it from the sidebar, the :guilabel:`Tools` menu, or by pressing :kbd:`F5`.
 
 
 .. _a_export_headers:
@@ -66,7 +67,7 @@ Scene Separators
 
 If you don't want any titles for your scenes (or for your sections if you have them), you can leave
 the formatting boxes empty. If so, an empty paragraph will be inserted between the scenes or
-sections instead resulting in a gap in the text.
+sections instead, resulting in a gap in the text.
 
 Alternatively, if you want a separator between them, like the common ``* * *``, you can enter the
 desired separator text in the formatting box. In fact, if the format is a piece of static text, it
@@ -78,13 +79,9 @@ will always be treated as a separator.
 File Selection
 ==============
 
-Which documents and notes are selected for export can be controlled from the options on the left
+Which documents and notes are selected for the build can be controlled from the options on the left
-side of the dialog window. The switch for :guilabel:`Include novel files` will enable or disable
+side of the dialog window. In addition, you can select to include the synopsis comments, regular
-inclusion of novel documents, and the switch for :guilabel:`Include note files` will do the same
+comments, keywords, and even exclude the body text itself if you just want an outline.
-for project notes. This allows for exporting just the novel, just your notes, or both, as you wish.
-
-In addition, you can select to export the synopsis comments, regular comments, keywords, and even
-exclude the body text itself.
 
 .. tip::
    If you for instance want to export a document with an outline of the novel, you can enable
@@ -92,11 +89,9 @@ exclude the body text itself.
    followed by the tags and references and the synopsis.
 
 If you need to exclude specific documents from your exports, like draft documents or documents you
-want to take out of your manuscript, but don't want to delete, you can un-check the
+want to take out of your manuscript, but don't want to delete, you can set the documents as
-:guilabel:`Include when building project` option for each such document in the project tree. An
+"inactive" in the project tree. :guilabel:`Build Novel Project` tool has a switch to collectively
-included document has a checkmark after in the third column of the project tree. The
+exclude inactive documents.
-:guilabel:`Build Novel Project` tool has a switch to ignore this flag if you need to collectively
-override these settings.
 
 
 .. _a_export_print:
@@ -108,13 +103,17 @@ The print button allows you to print the content in the preview window. You can
 of your system's printers, or print directly to a file as PDF. You can also print to file from the
 regular print dialog. The direct to file option is just a shortcut.
 
+.. note::
+   The paper format should in all cases default to whatever your system default is. Of you want to
+   change it, you have to select it from the :guilabel:`Print Preview`` dialog.
+
 
 .. _a_export_formats:
 
 Export Formats
 ==============
 
-Currently, six formats are supported for exporting.
+Currently, six formats are supported.
 
 Open Document Format
    The Build tool can produce either an ``.odt`` file, or an ``.fodt`` file. The latter is just a
@@ -122,9 +121,9 @@ Open Document Format
    former, and a few the latter.
 
 novelWriter HTML
-   The HTML export format writes a single ``.htm`` file with minimal style formatting. The exported
+   The HTML format writes a single ``.htm`` file with minimal style formatting. The HTML document
-   HTML document is suitable for further processing by document conversion tools like Pandoc, for
+   is suitable for further processing by document conversion tools like Pandoc, for importing in
-   importing in word processors, or for printing from browser.
+   word processors, or for printing from browser.
 
 novelWriter Markdown
    This is simply a concatenation of the project documents selected by the filters. The documents
@@ -133,23 +132,23 @@ novelWriter Markdown
    import back into novelWriter.
 
 Standard/GitHub Markdown
-   The Markdown export format comes in both Standard and GitHub flavour. The *only* difference in
+   The Markdown format comes in both Standard and GitHub flavour. The *only* difference in terms of
-   terms of novelWriter functionality is the support for strikethrough text, which is not supported
+   novelWriter functionality is the support for strikethrough text, which is not supported by the
-   by the Standard flavour, but *is* supported by the GitHub flavour.
+   Standard flavour, but *is* supported by the GitHub flavour.
 
 
 .. _a_export_options:
 
-Additional Export Options
+Additional Formats
-=========================
+==================
 
 In addition to the above document formats, the novelWriter HTML and Markdown formats can also be
 wrapped in a JSON file. These files will have a meta data entry and a body entry. For HTML, also
-the accompanying css styles are exported.
+the accompanying css styles are included.
 
-The text body is saved in a two-level list. The outer list contains one entry per exported
+The text body is saved in a two-level list. The outer list contains one entry per document, in the
-document, in the order they appear in the project tree. Each document is then split up into a list
+order they appear in the project tree. Each document is then split up into a list as well, with one
-as well, with one entry per paragraph it contains.
+entry per paragraph it contains.
 
 These files are mainly intended for scripted post-processing for those who want that option. A JSON
 file can be imported directly into a Python dict object or a PHP array, to mentions a few options.

docs/source/project_notes.rst

@@ -25,9 +25,9 @@ Tags in Notes
 
 Each new heading in a note can have a tag associated with it. The format of a tag is
 ``@tag: tagname``, where tagname is a unique identifier. Tags can then be referenced in the novel
-documents, or cross-referenced in other notes, and will show up in the outline view and in the
+documents, or cross-referenced in other notes, and will show up in the Outline View and in the
-back-reference panel when a document is being viewed. See :ref:`a_struct_tags` for how to reference
+back-reference panel when a document is opened in the viewer. See :ref:`a_struct_tags` for how to
-notes.
+reference notes.
 
 The syntax highlighter will alert the user that the keyword is correctly used and that the tag is
 allowed, that is, the tag is unique. Duplicate tags should be detected as long as the index is up
@@ -36,15 +36,37 @@ colour that valid tags do.
 
 The tag is the only part of these notes that the application uses. The rest of the document content
 is there for the writer to use in whatever way they wish. Of course, the content of the documents
-can be exported if you want to compile a single document of all your notes, or include them in an
+can be added to the manuscript, or an outline document. If you want to compile a single document of
-outline.
+all your notes, you can do this from the :guilabel:`Build Novel Project` tool.
 
 A note can also reference other notes in the same way novel documents do. When the note is opened
 in the view panel, the references become clickable links, making it easier to follow connections in
-the plot. Notes don't show up in the outline view though, so referencing between notes is only
+the plot. Notes don't show up in the Outline View though, so referencing between notes is only
-meaningful if you want to be able to click-navigate between them.
+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
    :guilabel:`Build Novel Project` tool, the cross-references become clickable links in the
    exported HTML document.
+
+Example of a project note with two headers, with separate tags, and with references to other notes:
+
+.. code-block:: none
+   :linenos:
+
+   # Main Characters
+
+   ## Jane Doe
+
+   @tag: Jane
+   @location: Earth
+
+   Something about Jane ...
+
+   ## John Doh
+
+   @tag: John
+   @location: Mars
+
+   Something about John ...

docs/source/project_overview.rst

@@ -33,12 +33,14 @@ other root folders. These other root folder types are intended for your notes on
 elements of your story. Using them is of course entirely optional.
 
 A new project may not have all of the root folders present, but you can add the ones you want from
-:guilabel:`Create Root Folder` in the :guilabel:`Project` menu.
+the project tree.
 
 Each root folder has one or more reference keyword associated with it that can be used to reference
-content in your notes from other documents and notes. The intended usage of each type of root
+tags in your notes from other documents and notes. The intended usage of each type of root folder
-folder is listed below. However, aside from the :guilabel:`Novel` folder, no restrictions are
+is listed below. However, aside from the :guilabel:`Novel` folder, no restrictions are applied by
-applied by the application. You can use them however you want.
+the application. You can use them however you want.
+
+You can make multiple root folders of each kind.
 
 :guilabel:`Novel`
    This is the root folder of all text that goes into the final novel. This class of documents have
@@ -51,9 +53,9 @@ applied by the application. You can use them however you want.
    folder can be references using the ``@plot`` keyword.
 
 :guilabel:`Characters`
-   Character notes go in this root folder. These are especially important if one wants to use the
+   Character notes go in this root folder. These are especially important if you want to use the
-   Outline view to see which character appears where, and which part of the story is told from a
+   Outline View to see which character appears where, and which part of the story is told from a
-   specific character's point-of-view or focusing on a particular character's storyline. Tags in
+   specific character's point-of-view, or focusing on a particular character's storyline. Tags in
    this folder can be referenced using the ``@pov`` keyword for point-of-view characters,
    ``@focus`` for a focus character, or the ``@char`` keyword for any other characters.
 
@@ -86,6 +88,28 @@ information about the tags listed, see :ref:`a_struct_tags`.
    You can rename root folders to whatever you want. However, this doesn't change the reference
    keyword.
 
+Example of a character note:
+
+.. code-block:: none
+   :linenos:
+
+   # Jane Doe
+
+   @tag: Jane
+
+   Some information about the character Jane Doe.
+
+Example of a novel scene referencing the above character:
+
+.. code-block:: none
+   :linenos:
+
+   ### Chapter 1, Scene 1
+
+   @pov: Jane
+
+   When Jane woke up that morning ...
+
 
 .. _a_proj_roots_del:
 
@@ -97,9 +121,8 @@ trash folder can then be deleted permanently, either individually, or by emptyin
 the menu. Documents in the trash folder are removed from the project index and cannot be
 referenced.
 
-Folders and root folders can only be deleted when they are empty. Recursive deletion is not
+A document or a folder can be deleted from the :guilabel:`Project` menu, or by pressing
-supported. A document or a folder can be deleted from the :guilabel:`Project` menu, or by pressing
+:kbd:`Ctrl`:kbd:`Shift`:kbd:`Del`. Root folders can only be deleted when they are empty.
-:kbd:`Ctrl`:kbd:`Shift`:kbd:`Del`.
 
 
 .. _a_proj_roots_out:
@@ -109,9 +132,7 @@ Archived Documents
 
 If you don't want to delete a document, or put it in the :guilabel:`Trash` folder where it may be
 deleted, but still want it out of your main project tree, you can create an :guilabel:`Archive`
-root folder from the :guilabel:`Project` menu. You are not allowed to move entire folders to this
+root folder.
-root folder, only documents. If you need folders in it to organise your documents, you can of
-course create new ones there.
 
 You can drag any document to this folder and preserve its settings. The document will always be
 excluded from the :guilabel:`Build Novel Project` builds. It is also removed from the project
@@ -179,9 +200,10 @@ and to be able to collapse and hide them in the project tree when you're not wor
 documents.
 
 .. tip::
-   You can use folders to sort your scene documents into chapters. You will still need to add a
+   You can add child documents to other documents. This is particularly useful when you create
-   chapter document as the first item of your chapter folder, and the scene documents as the
+   chapters and scenes. If you add separate scene documents, you should also add separate chapter
-   following items. Other ways to use folders is to make a folder for each act or part.
+   documents, even if they only contain a chapter heading. You can then add scene documents as
+   child items to the chapters.
 
 
 .. _a_proj_files:
@@ -189,21 +211,15 @@ documents.
 Project Documents
 =================
 
-New documents can be created from the :guilabel:`Document` menu, or by pressing :kbd:`Ctrl`:kbd:`N`
+New documents can be created from tool bar in the Project Tree, or by pressing :kbd:`Ctrl`:kbd:`N`.
-while in the project tree. This will create a new, empty document, and open the :guilabel:`Item
+This will open the create new item menu and let you choose between a number of pre-defined
-Settings` dialog where the document label and various other settings can be changed. This dialog
+documents and folders. You will be prompted for a label for the new item. You can always rename an
-can also be opened again later from either the :guilabel:`Project` menu, selecting :guilabel:`Edit
+item by selecting :guilabel:`Rename Item` from the :guilabel:`Project` menu, or by pressing
-Project Item`, or by pressing :kbd:`F2` with the item selected.
+:kbd:`F2`.
 
-The layout of the document is also defined here. The two options available are :guilabel:`Novel
+Other settings for project items are available from the context menu that you can activate by
-Document` and :guilabel:`Project Note`. These behave differently when the project is built. A
+right-clicking on them inb the Project Tree. The :guilabel:`Transform` submenu includes options for
-project note is never treated as part of the novel, no matter where in the project it is located.
+converting, splitting, or merging items.
-See :ref:`a_struct_layout` for more details.
-
-You can also select whether the document is by default included when building the project. This
-setting can be overridden in the :guilabel:`Build Novel Project` tool if you wish to include them
-anyway. This is covered in the :ref:`a_export_files` section. You can also toggle the included
-state of a document from the right-click context menu.
 
 
 .. _a_proj_files_counts:
@@ -237,17 +253,16 @@ The :guilabel:`Project Settings` can be accessed from the :guilabel:`Project` me
 Settings Tab
 ------------
 
-The :guilabel:`Settings` tab holds the project title and author settings.
+The :guilabel:`Settings` tab holds the project name, title, and author settings.
 
-The :guilabel:`Working Title` can be set to a different title than the :guilabel:`Book Title`. The
+The :guilabel:`Project Name` can be set to a different value than the :guilabel:`Novel Title`. The
-difference between them is simply that the :guilabel:`Working Title` is used for the GUI (main
+difference between them is simply that the :guilabel:`Project Name` is used for the GUI (main
-window title) and for generating the backup files. The intention is that the :guilabel:`Working
+window title) and for generating the backup files. The intention is that the :guilabel:`Project
-Title` should remain unchanged throughout the project, otherwise the name of exported files and
+Name` should remain unchanged throughout the project, otherwise the name of exported files and
 backup files may change too.
 
-The :guilabel:`Book Title` and :guilabel:`Book Authors` settings are currently not used for
+The :guilabel:`Novel Title` and :guilabel:`Authors` settings are used when building the manuscript,
-anything, so setting them is just for the benefit of the author. Future features may use them, and
+for some formats.
-they are exported on some export formats in the :guilabel:`Build Novel Project` tool.
 
 If your project is in a different language than your main spell checking is set to, you can
 override the default spell checking language here. You can also override the automatic backup
@@ -257,14 +272,14 @@ setting.
 Status and Importance Tabs
 --------------------------
 
-Each document or folder of type :guilabel:`Novel` can be given a status level, signified by a
+Each document or folder of type :guilabel:`Novel` can be given a _Status_ label accompanied by a
-coloured icon, and each document or folder of the remaining types can be given an importance level.
+coloured icon, and each document or folder of the remaining types can be given an _Importance_
-These are colour coded icons and labels that can be applied to each document or folder.
+label.
 
 These are purely there for the user's convenience, and you are not required to use them for any
 other features to work. No other part of novelWriter accesses this information. The intention is to
 use these to indicate at what stage of completion each novel document is, or how important the
-content of a note is to the plot. You don't have to use them this way, that's just what they were
+content of a note is to the story. You don't have to use them this way, that's just what they were
 intended for, but you can make them whatever you want.
 
 See also :ref:`a_ui_tree_status`.
@@ -279,7 +294,7 @@ Auto-Replace Tab
 
 A set of automatically replaced keywords can be added in this tab. The keywords in the left column
 will be replaced by the text in the right column when documents are opened in the viewer. They will
-also be applied to exports.
+also be applied to manuscript builds.
 
 The auto-replace feature will replace text in angle brackets that are in this list. The syntax
 highlighter will add an alternate colour to text marching the syntax, but it doesn't check if the
@@ -300,16 +315,17 @@ An automatic backup system is built into novelWriter. In order to use it, a back
 the backup files are to be stored must be provided in :guilabel:`Preferences`.
 
 Backups can be run automatically when a project is closed, which also implies it is run when the
-application itself is closed. Backups are date stamped zip files of the entire project folder, and
+application itself is closed. Backups are date stamped zip files of the project files in the
-are stored in a subfolder of the backup path. The subfolder will have the same name as the project
+project folder (files not strictly a part of the project are ignored). The zip archives are stored
-:guilabel:`Working Title` set in :ref:`a_proj_settings`.
+in a subfolder of the backup path. The subfolder will have the same name as the
+:guilabel:`Project Name` as defined in :ref:`a_proj_settings`.
 
 The backup feature, when configured, can also be run manually from the :guilabel:`Tools` menu.
-It is also possible to disable automated backups for a given project in :guilabel:`Project
+It is also possible to disable automated backups for a given project in
-Settings`.
+:guilabel:`Project Settings`.
 
 .. note::
-   For the backup to be able to run, the :guilabel:`Working Title` must be set in
+   For the backup to be able to run, the :guilabel:`Project Name` must be set in
    :guilabel:`Project Settings`. This value is used to generate the folder name for the zip files.
    Without it, the backup will not run at all, but it will produce a warning message.
 
@@ -320,7 +336,8 @@ Writing Statistics
 ==================
 
 When you work on a project, a log file records when you opened it, when you closed it, and the
-total word counts of your novel documents and notes at the end of the session. You can view this
+total word counts of your novel documents and notes at the end of the session provided that the
+session lasted either more than 5 minutes, or that the total word count changed. You can view this
 file in the ``meta`` folder in the directory where you saved your project. The file is named
 ``sessionStats.log``.
 

docs/source/project_structure.rst

@@ -22,10 +22,9 @@ Four levels of headings are supported, signified by the number of hashes (``#``)
 title. See also the :ref:`a_fmt` section for more details about the markdown syntax.
 
 .. note::
-   The header levels are not only important when generating the exported novel file, they are also
+   The header levels are not only important when generating the manuscript, they are also used by
-   used by the indexer when building the outline tree in the :guilabel:`Outline` tab as well as the
+   the indexer when building the outline tree in the Outline as well as the Novel Tree. Each
-   :guilabel:`Novel` tab of the project tree. Each heading also starts a new region where new
+   heading also starts a new region where new references and tags can be defined.
-   references and tags can be defined.
 
 The syntax for the four basic header types, and the two special header types, is listed in section
 :ref:`a_fmt_head`. The meaning of the four levels for the structure of your novel is as follows:
@@ -33,8 +32,7 @@ The syntax for the four basic header types, and the two special header types, is
 **Header Level 1: Partition**
    This header level signifies that the text refers to a top level partition. 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 header level one code explained in
+   The novel title itself should use the special header level explained in :ref:`a_fmt_head`.
-   :ref:`a_fmt_head`.
 
 **Header Level 2: Chapter**
    This header level signifies a chapter level partition. Each time you want to start a new
@@ -46,7 +44,7 @@ The syntax for the four basic header types, and the two special header types, is
 
 **Header Level 3: Scene**
    This header level signifies a scene level partition. You must provide a title text, but the
-   title text can be replaced with a scene separator or just skipped entirely when you export your
+   title text can be replaced with a scene separator or just skipped entirely when you build your
    manuscript.
 
 **Header Level 4: Section**
@@ -55,12 +53,12 @@ The syntax for the four basic header types, and the two special header types, is
    mid-scene, like if you change the point-of-view character. You are free to use sections as you
    wish, and can filter them out of the final manuscript just like with scene titles.
 
-Page breaks are automatically added before level 1 and 2 headers when you export your project to a
+Page breaks are automatically added before level 1 and 2 headers when you build your project to a
 format that supports page breaks, or when you print the document directly from the build tool. If
 you want page breaks in other places, you have to specify them manually. See :ref:`a_fmt_break`.
 
 .. tip::
-   There are multiple options of how to process novel titles when exporting the manuscript. For
+   There are multiple options of how to process novel titles 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. See the :ref:`a_export` page for more details.
 
@@ -70,19 +68,19 @@ you want page breaks in other places, you have to specify them manually. See :re
 Novel Title and Front Matter
 ----------------------------
 
-It is recommended that you add a document at the very top of your project with the novel title as
+It is recommended that you add a document at the very top of each Novel root folder with the novel
-the first line. You should modify the level 1 header format code with an ``!`` in order to render
+title as the first line. You should modify the level 1 header format code with an ``!`` in order to
-it as a document title that is excluded from any automatic Table of Content in an exported
+render it as a document title that is excluded from any automatic Table of Content in a manuscript
-document, like so:
+build document, like so:
 
 ``#! My Novel``
 
-The title is by default centred on the page when exported. You can add more text to the page as you
+The title is by default centred on the page. You can add more text to the page as you wish, like
-wish, like for instance the author's name and details.
+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
-when the project is exported.
+before the text.
 
 
 .. _a_struct_heads_unnum:
@@ -97,9 +95,9 @@ build tool to skip these chapters.
 ``##! Unnumbered Chapter Title``
 
 There is a separate formatting feature for such chapters in the :guilabel:`Build Novel Project`
-tool as well. See the :ref:`a_export` page for more details. When exporting to a format that
+tool as well. See the :ref:`a_export` page for more details. When building a document of a format
-supports page breaks, also unnumbered chapters will have a page break added just like for normal
+that supports page breaks, also unnumbered chapters will have a page break added just like for
-chapters.
+normal chapters.
 
 .. Note::
    Previously, you could also disable the automatic numbering of a chapter by adding an ``*`` as
@@ -110,14 +108,13 @@ chapters.
 
 .. _a_struct_tags:
 
-Tag References
+Note References
-==============
+===============
 
 Each text partition, indicated by a heading of any level, can contain references to tags set in the
-supporting notes of the project. The references are gathered by the indexer and used to generate an
+project notes of the project. The references are gathered by the indexer and used to generate the
-outline view on the :guilabel:`Outline` tab of how the different parts of the novel are connected.
+Outline View. This section covers how to make references to tags. See :ref:`a_notes_tags` for how
-This section covers how to set references to tags. See :ref:`a_notes_tags` for how to define tags
+to define tags the references can point to.
-the references can point to.
 
 References and tags are also clickable in the document editor and viewer, making it easy to
 navigate between reference notes while writing. Clicked links are always opened in the view panel.
@@ -171,6 +168,22 @@ The highlighter may be mistaken if the index of defined tags is out of date. If
 to regenerate it, or select :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu. In general,
 the index for a document is regenerated when it is saved, so this shouldn't normally be necessary.
 
+Example of a novel document with references to characters and plots:
+
+.. code-block:: none
+   :linenos:
+
+   ## Chapter 1
+
+   @pov: Jane
+
+   ### Scene 1
+
+   @char: John, Sam
+   @plot: Main
+
+   Once upon a time ...
+
 
 .. _a_struct_layout:
 
@@ -181,15 +194,13 @@ All documents in the project can have a layout format set. Previously, there wer
 available to change how the documents where formatted on export. These have now been reduced to
 just two layouts: :guilabel:`Novel Document` and :guilabel:`Project Note`.
 
-Novel documents can only live in the :guilabel:`Novel` root folder. You can also move them to
+Novel documents can only live in a :guilabel:`Novel` type root folder. You can also move them to
 :guilabel:`Archive` and :guilabel:`Trash` of course. Project notes can be added anywhere in the
 project.
 
-Depending on which icon theme you're using, the project tree can distinguish between the different
+The project tree can distinguish between the different layouts and header levels of the documents
-layouts and header levels of the documents to help indicate which are project notes and which are
+using coloured icons, and optionally add emphasis on the label (See the :guilabel:`Preferences`.)
-novel documents containing a partition, chapter, or scene. If the icon theme you've selected
+For novel documents, the heading level of the first heading is recorded, and indicated by the icon.
-doesn't show a difference, you can still see the layout description in the details panel below the
-project tree.
 
 .. tip::
    You can always start writing with a coarse setup with one or a few documents, and then later use