Merge branch 'master' into release_0.4

docs/source/interface.txt

@@ -2,24 +2,32 @@
 User Interface
 ***************
 
-The user interface is kept as simple as possible to avoid distractions.
-The main window contains a tree vew pane with the entire structure of the project, and a small details panel below it to display additional information.
+The user interface is kept as simple as possible to avoid distractions when writing.
+The main window contains a tree view pane with the entire structure of the project, and a small details panel below it to display additional information about the currently selected item.
 
-Editing a document can be done by either double-clicking on it, or hitting the return key when the item is selected.
-This will open the source editor which uses a simplified markdown format described in the section below.
+Editing a document can be done by either double-clicking on it, or hitting the return key when a file is selected.
+This will open the document editor, which uses a simplified markdown format, described in the section below.
 
-The document can also be viewed as html with all the comments and commands stripped out. To view a document, simply press Ctrl+R or select a file and go to :menuselection:`Document --> View Document` in the menu.
+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.
 
+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`.
+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::
+   The "Referenced By" panel relies on an up-to-date index of the project.
+   If anything is missing, or seems wrong, the index can always be rebuilt from :menuselection:`Tools --> Rebuild Index` or by pressing :kbd:`F9`.
+
 Markdown Format
 ===============
 
-the document editor uses a simplified markdown format.
+The document editor uses a simplified markdown format.
 That is, it supports basic formatting like bold, italics and underline, as well as four levels of headings.
 The formats are listed below.
 
-In addition to these standard markdown features, the editor also allows for comments, that is text that is ignored by the word counter and not exported or seen in the document viewer.
-The editor also has a minimal set of commands used for setting tags and references between files.
+In addition to these standard markdown features, the editor also allows for comments, that is text that is ignored by the word counter and not exported or, optionally, hidden in the document viewer.
+The editor also has a minimal set of keywords used for setting tags and references between files.
 
 .. csv-table:: Formatting Syntax
    :header: "Format", "Description"
@@ -35,6 +43,13 @@ The editor also has a minimal set of commands used for setting tags and referenc
    "``% text...``",       "A comment. The text is not exported, seen in viewer, or counted towards word counts."
    "``@keyword: value``", "A keyword argument followed by a value, or a comma separated list of values."
 
+The editor and viewer also supports markdown standard hard line breaks, and preserves non-breaking spaces.
+A hard line break is achieved by leaving two or more spaces at the end of the line.
+Alternatively, the user can press :kbd:`Shift-Enter` to insert this.
+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.
+
 Keyboard Shortcuts
 ==================
 
@@ -71,6 +86,7 @@ These are as following:
    ":kbd:`Ctrl-Z`",          "Undo latest changes."
    ":kbd:`Ctrl-F7`",         "Toggle spell checking."
    ":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."
    ":kbd:`Ctrl-Shift-1`",    "Replace occurrence of word in current document, and search for next occurrence."
    ":kbd:`Ctrl-Shift-A`",    "Select all text in current paragraph."
@@ -89,5 +105,7 @@ These are as following:
    ":kbd:`F5`",              "Export project dialog."
    ":kbd:`F7`",              "Re-run spell checker."
    ":kbd:`F9`",              "Re-build project indices."
+   ":kbd:`Shift-Enter`",     "Insert a hard line break at the cursor position."
    ":kbd:`Shift-F3`",        "Find previous occurrence of word in current document."
-   ":kbd:`Return`",          "If in tree view, open a document for editing."
+   ":kbd:`Shift-Space`",     "Insert a non-breaking space at the cursor position."
+   ":kbd:`Enter`",           "If in tree view, open a document for editing."

docs/source/introduction.txt

@@ -2,20 +2,48 @@
 Introduction
 ************
 
-novelWriter is a simple multi-document plain text editor using a modified
-markdown syntax to apply simple formatting. Additional features are available
-through special meta data commands. These make it possible to generate an
-overview of the entire novel project and how the various files are
-interconnected.
+novelWriter is a simple, multi-document plain text editor using a modified markdown syntax to apply simple formatting.
+Additional features that are not standard markdown are available through special meta data keywords.
+These keywords make it possible to inter-link documents, and generate an overview of the entire novel project and how the various files are interconnected.
 
-The user interface is intended to be as minimalistic as practically possible,
-and 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. They are separated
-into gui and syntax themes, and can be found in the themes folder in the source
-code.
+Design Philosophy
+-----------------
 
-The tree view has various sections for the various types of supporting files
-that the User may want to add to the project. The novel itself lives under its
-own root folder, and export features are in the process of being added. These
-will include HTML, open document and PDF via LaTeX.
+The user interface is intended to be as minimalistic as practically possible, while at the same time provide a complete set of features needed for writing a novel.
+
+.. 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.
+
+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.
+
+The project itself is laid out in a tree view on the left hand side of the main window.
+It has various sections, called *root folders*, for the various types of supporting files that the user may want to add to the project.
+The novel itself lives under its own root folder.
+
+Project Layout
+--------------
+
+The layout of the novel itself is managed through the four supported heading levels, H1 through H4.
+H1 is used for the book title, and for partitions.
+H2 is used for chapter tiles.
+H3 is reserved for scene titles.
+H4 is for section titles within scenes, if such granularity is necessary.
+
+For the files designated as project notes, the usage of headers imply no structural meaning, and the user is free to do whatever they want.
+
+Project Export
+--------------
+
+The project can at any time be exported to a range of different formats.
+Natively, novelWriter supports export to plain text file, html5 document, LaTeX source file, novelWriter flavoured markdown, and standard markdown.
+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
+----------
+
+.. image:: images/screenshot.png
+   :width: 800

docs/source/notes.txt

@@ -4,7 +4,7 @@ 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 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 timeline view feature to see how each element intersects with each section of the novel itself.
 
 File Tags
 =========
@@ -16,5 +16,8 @@ Tags can then be referenced in the novel files and will then show up as dots in
 The syntax highlighter will alert the user that the keyword is correctly used and that the tag is allowed.
 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 used.
+The tag is the only part of these files that the application uses.
 The rest of the file is there for the writer to use in whatever way they wish.
+
+A note file can also reference other note files in the same way novel files do.
+When the note file is opened in the view pane, these become clickable links, making it easier to follow connections in the plot.

docs/source/projects.txt

@@ -2,7 +2,7 @@
 Novel Projects
 **************
 
-A novelWriter project requires a dedicated folder for storing its files.
+A novelWriter project requires a dedicated folder for storing its files on the local file system.
 See the Technical Information section for further details.
 
 A new project can be created from the Project menu by selecting :menuselection:`Project --> New Project`.
@@ -16,10 +16,13 @@ Project Structure
 
 Projects are structured into a set of root folders, visible in the left side tree view panel.
 
-The core novel files go into a root folder of type Novel.
-Other supporting files go into root folders of types Plot, Characters, Locations, Timeline, Objects or Custom.
+The core novel files go into a root folder of type "Novel".
+Other supporting files go into root folders of types "Plot", "Characters", "Locations", "Timeline", "Objects", "Entities" or "Custom".
 These other root folder types are intended for your notes on the various elements of your story.
-Using these are of course entirely optional.
+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 follwing use, but aside from the Novel folder, not restrictions apply.
 
 * **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.
@@ -30,7 +33,8 @@ Using these are of course entirely optional.
   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.
 * **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, and connected to the timeline as well.
+* **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.
@@ -40,46 +44,52 @@ 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 title and other information has to be set again, and the files moved back to the correct location in the project.
-Using Project Folders
+These orphaned files will not have any meta data associated with them, so the label and other information has to be set again, and the files moved back to the correct location in the project.
 
-Folders, aside from root folders, have no structural significance to the project. They are there purely as a way for the user to organise the files in meaningful sections and to be able to close them in the tree view. When processing the files in the novel, the folders are ignored.
+Using Folders in the Project Tree
+---------------------------------
+
+Folders, aside from root folders, have no structural significance to the project.
+They are there purely as a way for the user to organise the files in meaningful sections and to be able to close them in the tree view.
+When processing the files in the novel, like for instance during export, the folders are ignored.
 
 Project Settings
 ================
 
 The project settings can be accessed from the :menuselection:`Project --> Project Settings` menu entry.
-This will open a dialog box.
+This will open a dialog box, with a set of tabs.
 
 Settings Tab
 ------------
 
 The Settings tab holds the project title and author settings.
 Working Title can be set to a different title than the Book Title.
-The difference between them is simply that the Working Title is used for the GUI (main window title) and when the export features are added can optionally be printed to the cover sheet.
-The Book Title, on the other hand, will only be printed to the title page on export.
+The difference between them is simply that the Working Title is used for the GUI (main window title) and for generating the backup files.
+The intention is that the working title should remain unchanged, while changing the final title has no effect on features relying on the project name.
+The Book Title is currently not ues for anything, so setting it is just for the benefit of the author.
 
 The Book Authors text box takes one author per line.
-The line breaks matter in that this is converted to a list for later correct formatting.
 
 Status Tab
 ----------
 
-Each file of type NOVEL can be given a status level, signified by a coloured icon.
+Each file of type "Novel" can be given a status level, signified by a coloured icon.
 These are purely there for the user's convenience, and you are not required to use them for any other feature to work.
 The intention is to use this list to set what stage of writing you are on, although you can in principle make them whatever you want.
 
-Note that status levels currently in use by a file cannot be deleted.
+.. note::
+   The status levels currently in use by a file cannot be deleted.
 
 Importance Tab
 --------------
 
-Each file of types PLOT, CHARACTER, WORLD, TIMELINE, OBJECT or CUSTOM can be given an importance level, signified by a coloured icon like for status level.
+Each file of types "Plot", "Character", "World", "Timeline", "Object", "Entity", or "Custom", can be given an importance level, signified by a coloured icon like for status level.
 These are also purely there for the user's convenience, and you are not required to use them for any other feature to work.
 The intention is to use this list to set how important the character, plot element, or otherwise, is for the story.
 Again, these can in principle be used for whatever you want.
 
-Note that importance levels currently in use by a file cannot be deleted.
+.. note::
+   The importance levels currently in use by a file cannot be deleted.
 
 Auto-Replace Tab
 ----------------
@@ -95,11 +105,15 @@ This is to ensure that parts of the text isn't unintentionally replaced by the c
 Writing Files
 =============
 
-New document files can be created from the Document menu, or by pressing Ctrl+N while in the tree view pane.
+New document files can be created from the Document menu, or by pressing :kbd:`Ctrl-N` while in the tree view pane.
 This will create a new, empty file, and open the item settings dialog where the filename and various other settings can be set.
-This dialog can also be opened again later from either the menu, :menuselection:`Project -> Edit` item, or by pressing Ctrl+E or F2 with the item selected.
+This dialog can also be opened again later from either the menu, :menuselection:`Project -> Edit` item, or by pressing :kbd:`Ctrl-E` or :kbd:`F2` with the item selected.
 
-The different classes of documents have some restrictions.
+The layout of the file is also defined here.
+For Novel files, the full list of layout options are available.
+For non-Novel files, only "Note" is available.
+
+See the Project Structure section for more details.
 
 Backup
 ======

docs/source/started.txt

@@ -14,7 +14,8 @@ Extract the archive to a location of your choice.
 Installing Dependencies
 =======================
 
-If you already have Python installed, and don't mind starting novelWriter from command line, all you need to do is to open your command line tool, find the folder and run:
+If you already have Python installed, all you need to do is install the dependencies.
+To do this, your need to open your command line tool, find the folder where you extracted novelWriter, and run:
 
 .. code-block:: console
 
@@ -59,7 +60,7 @@ To list all options, run:
 Building a Standalone Executable
 ================================
 
-A standalone executable can be built with pyinstaller, using the python script named "install.py" in the source folder.
+A standalone executable can be built with pyinstaller, using the provided python script "install.py" in the source folder.
 This script will automatically try to install all dependencies and build the standalone executable of novelWriter.
 You can run the script by typing the following into your command prompt:
 
@@ -85,13 +86,3 @@ Also, make sure you select the "Add Python to PATH" option.
    :width: 600
 
 Once Python is set up and running, you can either run novelWriter from the folder where you extracted it, or you can build an executable and run that from a desktop icon instead.
-
-An install script is provided to automatically pull all dependencies and build a single executable.
-Open a command prompt in the folder where you extracted novelWriter, and run:
-
-.. code-block:: console
-
-   python install.py
-
-If everything went well, you should find a "novelWriter.exe" file in a folder named "dist".
-You can right-click it and create a desktop icon if you wish.

docs/source/structure.txt

@@ -2,8 +2,11 @@
 Project Structure
 *****************
 
-This section concerns files under the Novel type root folder.
-There are some restrictions and features that only applies to these type of files.
+This section covers the structure of a novel project.
+
+.. note::
+   This section concerns files under the Novel type root folder only.
+   There are some restrictions and features that only applies to these type of files.
 
 Importance of Headings
 ======================
@@ -30,6 +33,7 @@ Each section, indicated by a heading, can contain references to tags set in the
 See the File Tags section.
 
 The references are gathered by the indexer and used to generate the timeline 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.
 
 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]``.
@@ -54,20 +58,24 @@ Note that not all keywords allow multiple values.
 * ``@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 F9 to regenerate it, or select :menuselection:`Tools --> Rebuild Indices` from the menu.
+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.
 In general, the index for a file is regenerated when a file is saved, so this shouldn't normally be necessary.
 
 Novel File Layout
 =================
 
-Files that exist under the NOVEL type root folder can have a number of layouts set.
+Files that exist under the Novel type root folder can have a number of layouts set.
 See overview below.
-These layouts are currently not used for any internal feature, but when the export feature is added they will be important in determining how the different sections of the novel is formatted.
+These layouts are important when the project is exported, as they indicate how to treat the content in terms of formatting, headings and page breaks.
+the layout selected also shows up as flags in the tree view, making it easier to track what kind of files they are.
 
 * **Title Page**: The title page layout.
   The title should be formatted as a heading level one.
@@ -86,5 +94,8 @@ These layouts are currently not used for any internal feature, but when the expo
   This file should have a header of level three.
   Further sections can have headers of level four.
   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 ignored when the novel is exported.
-  These layout is allowed within the Novel root folder, and is the only layout allowed for a file outside the Novel root folder.
+* **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.

docs/source/technical.txt

@@ -7,6 +7,9 @@ This section contains details of how novelWriter stores and handles the project
 How Data is Stored
 ==================
 
+All novelWriter files are written with utf-8 encoding.
+Since Python automatically converts Unix line endings to Windows line endings on Windows systems, novelWriter does not make any adaptations to the formatting on Windows systems.
+
 Main Project File
 -----------------
 
@@ -17,6 +20,8 @@ That includes project 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.
 
 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.
 
@@ -24,11 +29,13 @@ Project Documents
 -----------------
 
 The project documents are saved in folders staring with ``data_``.
-Each document has a file handle taken from the first 13 characters of a SHA256 hash of the system time.
+Each document has a file handle taken from the first 13 characters of a SHA256 hash of the system time when the file was first created.
 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 is to avoid issues with file naming conventions and restrictions.
+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.
 
 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.