Merge pull request #202 from vkbo/docs

Updated documentation
2020-05-09 16:25:24 +02:00
parent e774a3546f 1a348b347a
commit 8c8000b8f9
13 changed files with 120 additions and 53 deletions
@@ -167,4 +167,8 @@ They broadly follow Python PEP8, but there are a few modifications.

 ## Screenshot

-![Screenshot 1](docs/source/images/screenshot.png)
+**novelWriter with default system theme:**
+![Screenshot 1](docs/source/images/screenshot_default.png)
+
+**novelWriter with dark theme:**
+![Screenshot 1](docs/source/images/screenshot_dark.png)
@@ -11,8 +11,9 @@ This will open the document editor, which uses a simplified markdown format, des
 The document currently being edited can also be viewed in parallel in a right hand side view pane.
 To view a document, simply press :kbd:`Ctrl-R`, or select a file and go to :menuselection:`Document --> View Document` in the menu.
 The document viewed does not need to be the same document currently being edited.
+If you are viewing the same document as the one you're editing, pressing :kbd:`Ctrl-R` again will update the document with your last changes.

-References to tags can also be opened in the view pane from the document editor by moving the cursor to a reference to a tag and hitting :kbd:`Ctrl-Enter`.
+References to tags can be opened in the view pane from the document editor by moving the cursor to a reference to a tag and hitting :kbd:`Ctrl-Enter`.
 In the view panel, the references become clickable links, and the "Referenced By" panel at the bottom will show links to all documents referring back to it.

 .. note::
@@ -50,10 +51,42 @@ A non-breaking space is inserted with :kbd:`Shift-Space`.

 Both hard line breaks and non-breaking spaces are highlighted by the syntax highlighter as an alternate coloured background, depending on the selected theme.

+Project Outline View
+====================
+
+The Project Outline View is available as the second tab on the right hand side of the main window marked "Outline".
+The Outline View provides an overview of the novel structure, displaying a tree hierarchy of the elements of the novel, that is, the level 1 to 4 headings.
+
+Various meta data and information extracted from tags can be displayed in columns in the Outline View.
+To turn on or off specific columns, right click the header and select the columns you want to show.
+The order of the columns can be rearranged by dragging them to a different position.
+
+.. note::
+   The "Title" columns cannot be disabled or moved.
+
+The information viewed in teh Outline View is based on the Project Index.
+While novelWriter does its best to keep the index up-to-date when content changes, you can always rebuild it manually by pressing :kbd:`F9`.
+
+The Outline View itself can be regenerated by pressing :kbd:`F10`.
+You can also enable automatic updating in the :menuselection:`Tools` menu, which will trigger an update whenever the index is updated.
+You may want to disable this feature if your project is very large,
+
+Synopsis Feature
+================
+
+The "Synopsis" column of the Outline View takes its information from a specially formatted comment.
+In order to flag a comment as a Synopsis, add the word "Synopsis:" as the first word of the comment.
+The ";" is required, and "synopsis" is not case sensitive.
+If it is correctly formatted, the syntax highlighter will indicate this by altering the colour of the word.
+
+.. note::
+   Only one comment can be flagged as a synopsis comment for each heading.
+   If multiple comments are flagged as a synopsis, the last one will be used.
+
 Keyboard Shortcuts
 ==================

-All features are available as keyboard shortcuts.
+Most features are available as keyboard shortcuts.
 These are as following:

 .. csv-table:: Keyboard Shortcuts
@@ -92,6 +125,7 @@ These are as following:
   ":kbd:`Ctrl-Y`",          "Redo latest undo."
   ":kbd:`Ctrl-Z`",          "Undo latest changes."
   ":kbd:`Ctrl-F7`",         "Toggle spell checking."
+   ":kbd:`Ctrl-F10`",        "Toggle automatic updating of project outline."
   ":kbd:`Ctrl-Del`",        "If in tree view, move a document to trash, or delete a folder."
   ":kbd:`Ctrl-Enter`",      "Open the tag or reference under the cursor in the view panel."
   ":kbd:`Ctrl-Shift-,`",    "Change project settings."
@@ -115,6 +149,7 @@ These are as following:
   ":kbd:`F7`",              "Re-run spell checker."
   ":kbd:`F8`",              "Activate Zen Mode, hiding project tree and view panel."
   ":kbd:`F9`",              "Re-build project indices."
+   ":kbd:`F10`",             "Re-build project outline."
   ":kbd:`F11`",             "Activate full screen mode."
   ":kbd:`Shift-Enter`",     "Insert a hard line break at the cursor position."
   ":kbd:`Shift-F3`",        "Find previous occurrence of word in current document. (Same as :kbd:`Ctrl-Shift-G`"
@@ -13,7 +13,7 @@ The user interface is intended to be as minimalistic as practically possible, wh

 .. note::
   novelWriter is not intended to be a full office type word processor.
-   It doesn't support images, links, tables, and its formatting is limited to headers, and bold, italics and underlined text.
+   It doesn't support images, links, tables, and its formatting is limited to headers, and bold, italicised and underlined text.

 Most features are accessible through the menu and through keyboard shortcuts.
 The colour scheme of the user interface can be modified with various themes, and new themes are fairly straight forward to add.
@@ -42,8 +42,15 @@ Additional export options are available through `Pandoc <https://pandoc.org/>`_.
 Currently, novelWriter will assist in converting the project to Open Office documents, Word documents, and epub.
 However, to be able to fully take advantage of the many features of Pandoc, you may want to run it yourself and use the novelWriter html or markdown export as input.

-screenshot
+Screenshot
 ----------

-.. image:: images/screenshot.png
+**novelWriter with default system theme:**
+
+.. image:: images/screenshot_default.png
+   :width: 800
+
+**novelWriter with dark theme:**
+
+.. image:: images/screenshot_dark.png
   :width: 800
@@ -4,16 +4,16 @@ Supporting Files (Notes)

 Supporting files, or notes, are any files stored in root folders that are not the Novel root folder.
 These files are intended for summaries and outlines of the various plot elements, characters, locations, and so on, of the novel.
-These are not required, but making at least minimal files for each such element, and add a tag to them, makes it possible to use the timeline view feature to see how each element intersects with each section of the novel itself.
+These are not required, but making at least minimal files for each such element, and add a tag to them, makes it possible to use the Outline View feature to see how each element intersects with each section of the novel itself, and add clickable cross-references between document in the editor and viewer.

 File Tags
 =========

 Each note file 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 files and will then show up as dots in the timeline view.
+Tags can then be referenced in the novel files and will show up in the Outline View.

-The syntax highlighter will alert the user that the keyword is correctly used and that the tag is allowed.
+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 to date.

 The tag is the only part of these files that the application uses.
@@ -6,7 +6,7 @@ A novelWriter project requires a dedicated folder for storing its files on the l
 See the Technical Information section for further details.

 A new project can be created from the Project menu by selecting :menuselection:`Project --> New Project`.
-A list of recently opened projects is also maintained and can be selected from the menu.
+A list of recently opened projects is maintained, and displayed in the "Open Project" dialog.

 The project specific settings are available in :menuselection:`Project --> Project Settings`.
 See further details below.
@@ -23,28 +23,42 @@ Using these is of course entirely optional.
 A new project will not have all of the root folders present, but you can add the ones you want from :menuselection:`Project --> Create Root Folder`.

 The root folders are intended for the following use, but aside from the Novel folder, no restrictions apply.
+You can use them however you want.
+The root folders correspond to the categories of tags that can be used.
+See the "Project Structure" section for further details.

 * **Novel:** The root folder of all text that goes into the final novel.
  This class of files have other rules and features than other files in the project.
  See the Novel Structure section for more details.
 * **Plot:** This is the root folder where main plots can be outlined.
-  It is optional, but adding at least dummy files can be useful in order to generate the timeline view.
+  It is optional, but adding at least dummy files can be useful in order to tag plot elements for the Outline View.
 * **Characters:** Character files go in this root folder.
-  These are especially important if one wants to use the timeline view to see which character appears where and which part of the story is told from a specific character's point-of-view.
-* **Locations:** Location is for various scene locations that one wants to track in the timeline view if that applies to the story.
+  These are especially important if one wants to use the Outline View to see which character appears where, and which part of the story is told from a specific character's point-of-view.
+* **Locations:** Location is for various scene locations that one wants to track.
 * **Timeline:** If the story jumps in time within the same plot, this class of files can be used to track this.
 * **Objects:** Important objects in the story can be tracked here.
 * **Entities:** Entities, like organisations or companies, that are part of the plot, can be organised here.
 * **Custom:** The custom root folder can be used for tracking anything else not covered by the above options.

 Deleted files will be moved into a special "Trash" root folder.
-Currently, these files cannot be permanently deleted from the project.
+Files in the Trash folder can be deleted permanently.

 Orphaned Documents
 ------------------

 In the event the editor crashes or otherwise exits without saving the project state, files that have been added to the project tree and are saved to disk will appear in a special "Orphaned Items" root folder next time the application is started.
-These orphaned files will not have any meta data associated with them, so the label and other information will have to be set again, and the files moved back to the correct location in the project.
+These orphaned files will not have any meta data associated with them, although novelWriter will try to restore the file label it had in the project tree. Other information will have to be set again, and the files moved back to the correct location in the project.
+
+Project Lockfile
+----------------
+
+To prevent orphaned files caused by file conflicts when novelWriter projects are synced with file synchronisation tools, a project lockfile is written to the project folder.
+If you try to open a project which has such a file, you will be presented with a warning, and some information about where the project is potentially open.
+You will be give the option to ignore this warning, and continue opening the project.
+However, if multiple instances are in fact editing the same project, you are likely to cause inconsistencies and create diverging project files.
+
+.. note::
+   If, for some reason, novelWriter crashes, the lock file may remain. If so, it is safe to ignore the lock file warning when re-opening the project.

 Using Folders in the Project Tree
 ---------------------------------
@@ -121,10 +135,11 @@ Backup
 An automatic backup system is built into novelWriter.
 In order to use it, a backup path to where the backups are to be stored needs to be provided in :menuselection:`Tools --> Preferences`.
 Backups can be run automatically when a project is closed, which also implies it is run when the application is closed.
-Backups are date stamped zip files of the entire project folder.
+Backups are date stamped zip files of the entire project folder, and are stored in a subfolder of the backup path with the same name as the project working title set in Project Settings.

-The backup feature, when configured, can also be run manually from the Tools menu.
+The backup feature, when configured, can also be run manually from the :menuselection:`Tools` menu.
+It is also possible to dissable automated backup for a given project in Project Settings.

-For the backup to be able to run, the Working Title must be set in Project Settings.
-This value is used to generate the file name.
-It is also possible to dissable automated backup for a given project in its project settings.
+.. note::
+   For the backup to be able to run, the Working Title must be set in Project Settings.
+   This value is used to generate the folder name for the zip files.
@@ -34,7 +34,6 @@ The following Python packages are required to run novelWriter:
 The following are optional, but recommended:

 * ``pyenchant`` for spell checking
-* ``pycountry`` for translating language codes to language names
 * ``latexcodec`` for escaping unicode characters in LaTeX export
 * ``pypandoc`` for additional exports to Word, Open Office, eBooks, etc.

@@ -42,11 +41,13 @@ The following are optional, but recommended:
 Running novelWriter
 ===================

-If all the required dependencies are met, you can run novelWriter from the command line:
+If all the required dependencies are met, you can run novelWriter from the command line in one of the following ways:

 .. code-block:: console

   python novelWriter.py
+   python3 novelWriter.py
+   ./novelWriter.py

 A few switches are supported from the command line, mostly to assist in debugging if an error is encountered.
 To list all options, run:
@@ -16,57 +16,49 @@ The structure is instead dictated by the heading level.
 Four levels of headings are supported, signified by the number of hashes preceding the title.
 See the Markdown section.

-The header levels are not only important when generating the exported novel file, but is also used by the indexer and timeline view.
-Each heading starts a new region where new references to tags can be set, and will show up as a new row in the timeline view.
+The header levels are not only important when generating the exported novel file, but they are also used by the indexer and Outline View.
+Each heading starts a new region where new references to tags can be set.

 The different header levels are interpreted as specific section types of the novel.

 * ``# Header1``: Header level 1 signifies that the text refers to either the novel title or the name of a top level partition.
 * ``## Header2``: Header level 2 signifies a chapter level partition.
 * ``### Header3``: Header level 3 signifies a scene level partition.
-* ``#### Header4``: Header level 4 signifies a sub-scene level partition.
+* ``#### Header4``: Header level 4 signifies a sub-scene level partition (section).

 Tag References
 ==============

-Each section, indicated by a heading, can contain references to tags set in the supporting files of the project.
-See the File Tags section.
+Each partition, indicated by a heading, can contain references to tags set in the supporting files of the project.

-The references are gathered by the indexer and used to generate the timeline view of how the different parts of the novel are connected.
+The references are gathered by the indexer and used to generate the Outline View of how the different parts of the novel are connected.
 References and tags are also clickable in the view panel, and makes it easy to navigate reference notes while writing.
+For setting the targets of references, see the "Supporting Files" section.

 References are set as keyword and a list of corresponding tags.
 The valid keywords are listed below. The format of such a line is ``@keyword: value1, [value2] ... [valueN]``.
-Note that not all keywords allow multiple values.
+All keywords allow multiple values.

 * ``@pov``: The point-of-view character for the current section.
  The target must be a note tag in the character root folder.
-  Only one value is accepted. further values are ignored.
 * ``@char``: Other characters in the current section.
  The target must be a note tag in the character root folder.
-  Multiple values are allowed.
  This should not include the point-of-view character.
 * ``@plot``: The plot timelines touched by the current section.
  The target must be a note tag in the plot root folder.
-  Multiple values are allowed.
 * ``@time``: The timelines touched by the current section.
  The target must be a note tag in the timeline root folder.
-  Multiple values are allowed.
 * ``@location``: The location the current section takes place in.
  The target must be a note tag in the locations root folder.
-  Multiple values are allowed.
 * ``@object``: Objects present in the current section.
  The target must be a note tag in the object root folder.
-  Multiple values are allowed.
 * ``@entity``: Entities present in the current section.
  The target must be a note tag in the entities root folder.
-  Multiple values are allowed.
 * ``@custom``: Custom references in the current section.
  The target must be a note tag in the custom root folder.
-  Multiple values are allowed.

 The syntax highlighter will alert the user that only the correct keywords are used, and that the tags referenced exist.
-If the index of defined tags is out of date, press :kbd:`F9` to regenerate it, or select :menuselection:`Tools --> Rebuild Indices` from the menu.
+If the index of defined tags is out of date, press :kbd:`F9` to regenerate it, or select :menuselection:`Tools --> Rebuild Index` from the menu.
 In general, the index for a file is regenerated when a file is saved, so this shouldn't normally be necessary.

 Novel File Layout
@@ -96,6 +88,7 @@ the layout selected also shows up as flags in the tree view, making it easier to
  These will not impact the overall structure, but will allow for setting new characters and plot references in parts of a scene if such granularity is needed.
 * **Note**: A generic file that is optionally ignored when the novel is exported.

-The layout granularity is entirely optional.
-In principle, you can write the entire novel in a single file with layout "Book".
-You can also have a single file per chapter.
+.. note::
+   The layout granularity is entirely optional.
+   In principle, you can write the entire novel in a single file with layout "Book".
+   You can also have a single file per chapter.
@@ -15,13 +15,15 @@ Main Project File

 The project itself requires a dedicated folder for storing its files.
 The main project file is stored as an XML file with the name ``nwProject.nwx``.
-This file contains all the meta data unique for the project.
-That includes project settings.
+This file contains all the meta data required for the project.
+That includes project-specific settings.

 If this file is lost or corrupted, the structure of the project is lost.
-It is important to keep this file backed up.
-The last 10 versions of the file are kept in backup in the project's ``cache`` folder.
-These files are replaced on a rotation from 0 to 9.
+It is important to keep this file backed up, either through the built-in backup tool, or your own backup solution.
+
+.. note::
+   The novelWriter project folder is structured so that it can easily be added to a version control system like git.
+   If so, you may want to add a `.gitignore` file to exclude files with the extensions `.bak` and `.json`.

 The project XML file is suitable for diff tools and version control, although a timesetamp is set in the meta section on line 2 each time the file is saved.

@@ -34,8 +36,20 @@ The documents are saved with a folder and filename derived from this hash.
 If you wish to find the physical location of a file in the project, you can either look it up in the project XML file, or select :menuselection:`Document --> Show File Details` in the menu when having the document open.

 The reason for this cryptic file naming is to avoid issues with file naming conventions and restrictions on different operating systems, and also to have a file name that does not depend on what the user names the files, or changes it to.
-The file name set in the tree view is only saved in the project XML file.
+The file meta data in the tree view, except the file label, is only saved in the project XML file.

 Each document file contains a plain text version of the text from the editor.
 The file can in principle be edited in any text editor, and is suitable for diffing and version control if so desired.
 Just make sure the file remains in utf-8 encoding, otherwise unicode chatracters may become mangled.
+
+The first line contains some meta data starting with the characters "%%~".
+This line is mainly there to restore some information if it is lost from the project file, and the information may be helpful if you do open the file in an external editor as it contains the file label as the last entry.
+The line can be deleted without any consequences to the rest of the content of the file.
+
+The File Saving Process
+-----------------------
+
+When saving the project file, or any of the documents, the data is first saved to a temporary file.
+If successful, the old data file is renamed with a `.bak` extension, and the temporary file becomes the new file.
+This ensures that the previously saved data is only replaced when the new data has been successfully saved.
+The `.bak` file will always contain the previous version of the file, although when auto-save is enabled, they may have the same content.
@@ -17,6 +17,4 @@ The folders in the tree view have no structural meaning other than they’re a w

 You can link files and notes together by assigning tags to them, and then reference them from other files. The file class of a file determines which reference keywords apply to each file. For instance a file in the Characters root folder can be referenced using either the @char keyword or the @pov keyword.

-If you want to see the content of the file the reference points to, you can click Ctrl+Enter with the cursor on top of the reference, and the view pane will show you the file. In the view pane, all references are clickable, so you can navigate further. At the bottom of the view pane, a list of files referencing the one your viewing will appear. This panel updates when you navigate, unless you make it sticky by clicking the sticky checkbox.
-
-
+If you want to see the content of the file the reference points to, you can click Ctrl+Enter with the cursor on top of the reference, and the view pane will show you the file. In the view pane, all references are clickable, so you can navigate further. At the bottom of the view pane, a list of files referencing the one your viewing will appear. This panel updates when you navigate, unless you make it sticky by clicking the sticky checkbox.
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='utf-8'?>
-<novelWriterXML appVersion="0.4.5" fileVersion="1.0" saveCount="122" autoCount="15" timeStamp="2020-05-08 22:47:59">
+<novelWriterXML appVersion="0.4.5" fileVersion="1.0" saveCount="127" autoCount="17" timeStamp="2020-05-09 16:03:23">
  <project>
    <name>Sample Project</name>
    <title>Sample Project</title>
@@ -10,7 +10,7 @@
  <settings>
    <spellCheck>True</spellCheck>
    <autoOutline>True</autoOutline>
-    <lastEdited>636b6aa9b697b</lastEdited>
+    <lastEdited>96b68994dfa3d</lastEdited>
    <lastViewed>b3e74dbc1f584</lastViewed>
    <lastWordCount>875</lastWordCount>
    <autoReplace>
@@ -119,7 +119,7 @@
      <charCount>1692</charCount>
      <wordCount>313</wordCount>
      <paraCount>6</paraCount>
-      <cursorPos>530</cursorPos>
+      <cursorPos>1721</cursorPos>
    </item>
    <item handle="88706ddc78b1b" order="5" parent="e7ded148d6e4a">
      <name>Chapter Two</name>