Reproog/novelWriter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Copied the rest of the documentation from the html version to the read .rst files

Browse Source
This commit is contained in:
Veronica K. B. Olsen
2019-10-24 18:44:04 +02:00
parent 15b94da2e6
commit 3ae87b6cf4
6 changed files with 254 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/index.rst
+13 -24
View File
@@ -1,34 +1,23 @@
novelWriter Documentation
=========================
Welcome to novelWriter Documentation
====================================
This is the documentation for novelWriter |version|.
Contents
^^^^^^^^
.. toctree::
:maxdepth: 2
introduction
interface
projects
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.
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.
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.
structure
notes
technical
Indices and Tables
==================
^^^^^^^^^^^^^^^^^^
* :ref:`genindex`
* :ref:`modindex`
docs/source/interface.rst
+77
View File
@@ -0,0 +1,77 @@
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.
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.
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 viewed does not need to be the same document currently being edited.
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.
* ``# Title``: Heading level one. The space after the # is mandatory.
* ``## Title``: Heading level two. The space after the # is mandatory.
* ``### Title``: Heading level three. The space after the # is mandatory.
* ``#### Title``: Heading level four. The space after the # is mandatory.
* ``**text**``: The text is renderred as bold text.
* ``_text_``:The text is renderred as italics text.
* ``__text__``: The text is renderred as underlined text.
* ``% 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.
Keyboard Shortcuts
^^^^^^^^^^^^^^^^^^
All features are available as keyboard shortcuts.
These are as following:
* ``Ctrl+Shift+O``: Open a project.
* ``Ctrl+Shift+S``: Save the current project.
* ``Ctrl+Shift+W``: Close the current project.
* ``Ctrl+Shift+,``: Change project settings.
* ``Ctrl+Shift+N``: Create new folder.
* ``Ctrl+E, F2``: If in tree view, edit a document or folder settings.
* ``Ctrl+Del``: If in tree view, move a document to trash, or delete a folder.
* ``Ctrl+Q``: Exit novelWriter.
* ``Ctrl+N``: Create new document.
* ``Ctrl+O``: Open selected document.
* ``Return``: If in tree view, open a document for editing.
* ``Ctrl+S``: Save the current document in the editor.
* ``Ctrl+W``: Close the current document in the editor.
* ``Ctrl+R``: If in tree view, open a document for viewing. If in editor pane, open current document for viewing.
* ``Ctrl+Shift+R``: Close the document view pane.
* ``Ctrl+Z``: Undo latest changes.
* ``Ctrl+Y``: Redo latest undo.
* ``Ctrl+C``: Copy selected text to clipboard.
* ``Ctrl+X``: Cut selected text to clipboard.
* ``Ctrl+V``: Paste text from clipboard to cursor position.
* ``Ctrl+A``: Select all text in document.
* ``Ctrl+Shift+A``: Select all text in current paragraph.
* ``Ctrl+1``: Switch focus to tree view pane.
* ``Ctrl+2``: Switch focus to document editor pane.
* ``Ctrl+3``: Switch focus to document viewer pane.
* ``Ctrl+T``: Show project timeline.
* ``Ctrl+B``: Format selected text, or word under cursor, as bold.
* ``Ctrl+I``: Format selected text, or word under cursor, as italic.
* ``Ctrl+U``: Format selected text, or word under cursor, as underline.
* ``Ctrl+D``: Wrap selected text, or word under cursor, in double quotes.
* ``Ctrl+Shift+D``: Wrap selected text, or word under cursor, in single quotes.
* ``Ctrl+Shift+Up``: Move item one step up in the tree view.
* ``Ctrl+Shift+Down``: Move item one step down in the tree view.
* ``Ctrl+F7``: Toggle spell checking.
* ``F7``: Re-run spell checker.
* ``Ctrl+.``: Correct word under cursor.
* ``F9``: Re-build project indices.
* ``F1``: Open documentation.
docs/source/introduction.rst
+21
View File
@@ -0,0 +1,21 @@
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.
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.
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.
docs/source/notes.rst
+19
View File
@@ -0,0 +1,19 @@
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.
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.
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 rest of the file is there for the writer to use in whatever way they wish.
docs/source/structure.rst
+90
View File
@@ -0,0 +1,90 @@
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.
Importance of Headings
^^^^^^^^^^^^^^^^^^^^^^
Subfolders under root folders have no impact on the structure of the novel itself.
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 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.
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.
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 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.
* ``@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.
* ``@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.
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.
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.
* **Title Page**: The title page layout.
The title should be formatted as a heading level one.
* **Book**: In principle, the entire novel can be contained in a single file.
In that case, use the Book layout on this file.
The internal structure is then controlled by the heading levels.
* **Plain Page**: A plain page is just that,
It is not included into content and the heading levels are ignored.
* **Partition**: A partition can be used to split a the novel into parts.
Use a level one heading for this.
* **Chapter**: Signifies the start of a new chapter.
If the text itself is contained in scene files, these files should only contain the title and tag references for characters, plot, etc.
The heading for chapters should be level two.
* **Unnumbered**: Same as Chapter, but when exporting the files and automatic chapter numbering is enabled, this file will not receive a number.
* **Scene**: A scene file.
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.
docs/source/technical.rst
+34
View File
@@ -0,0 +1,34 @@
Technical Information
=====================
This section contains details of how novelWriter stores and handles the project data.
How Data is Stored
^^^^^^^^^^^^^^^^^^
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.
If this file is lost or corrupted, the structure of the project is lost.
It is important to keep this file backed up.
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.
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.
The documents are saved with a folder and filename derived from this hash.
The reason for this is to avoid issues with file naming conventions and restrictions.
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.