Renamed document files to .rst for easier preview and highlight
This commit is contained in:
Veronica K. B. Olsen
@@ -0,0 +1,85 @@
|
||||
##################
|
||||
Exporting Projects
|
||||
##################
|
||||
|
||||
The novelWriter project can be exported in various formats using the build tool available from :menuselection:`Project --> Build Project` or by pressing :kbd:`F5`.
|
||||
|
||||
*****************
|
||||
Header Formatting
|
||||
*****************
|
||||
|
||||
The titles for the four levels of story structure can be formatted collectively in the export tool.
|
||||
This is done through a series of keyword-replace steps.
|
||||
|
||||
The keyword ``%title%`` will always be replaced by the text you put after the ``#`` characters in your document.
|
||||
|
||||
The keywords ``%ch%`` and ``%chw%`` is replaced by a number, or a number word, respectively.
|
||||
The number is incremented by one each time the build tool sees a new heading of level two in a file with layout "Chapter".
|
||||
If the file has layout "Unnumbered", the counter is not incremented.
|
||||
the latter is useful for for instance Prologue and Epilogue chapters.
|
||||
|
||||
Likewise, the keywords ``%sc%`` and ``%sca%`` are number counters for scene files.
|
||||
These are incremented each time a heading of level three is encountered.
|
||||
The former keyword is reset to one for each new chapter, while the latter is not reset but counts from first scene encountered.
|
||||
|
||||
If you want to insert a line break in you=r title format, add two backslashes ``\\``.
|
||||
|
||||
.. note::
|
||||
Header formatting only applies to novel files.
|
||||
Headings in note files will will be left as-is, but heading levels 1 through 4 are converted to the correct heading level in the respective output formats.
|
||||
|
||||
****************
|
||||
Scene Separators
|
||||
****************
|
||||
|
||||
If you don't want any titles for your scenes (and for your sections if you have them), you can leave the boxes empty, and an empty paragraph will be inserted between the scenes or sections instead.
|
||||
Alternatively, if you want a separator between them, like the common "\*\*\*", you can also enter that in the box.
|
||||
In fact, if the format is a piece of static text, it will always be treated as a separator.
|
||||
|
||||
**************
|
||||
File Selection
|
||||
**************
|
||||
|
||||
Which files are selected for export can be controlled from the options on the left side of the dialog window.
|
||||
The switch for "Include novel files" will select any file that isn't classified as a note.
|
||||
The switch for "Include note files" will select any file that is a note.
|
||||
This is allows for exporting just the novel, just your notes, or both, as you see fit.
|
||||
|
||||
In addition, you can select to export the synopsis comments, regular comments, keywords, and even exclude the body text itself.
|
||||
If you for instance want to export a document with an outline of the novel, you can enable keywords and synopsis export and disable body text, thus getting a document with each heading followed by the tags and references and the synopsis.
|
||||
|
||||
**************
|
||||
Export Formats
|
||||
**************
|
||||
|
||||
Currently, five formats are supported for exporting.
|
||||
|
||||
OpenDocument Format
|
||||
===================
|
||||
|
||||
This is produces an open document odt file.
|
||||
The document produced has very little formatting, and may require further editing afterwards.
|
||||
For a better formatted office document, you may get a better result with exporting to HTML and the import that HTML document in your office word processor.
|
||||
|
||||
PDF Format
|
||||
==========
|
||||
|
||||
The PDF export is just a shortcut for print to file.
|
||||
|
||||
novelWriter HTML
|
||||
================
|
||||
|
||||
The HTML export format writes a single ``.htm`` file with minimal style formatting.
|
||||
The exported HTML file is suitable for further processing by document conversion tools like Pandoc, for importing in word processors, or for printing from browser.
|
||||
|
||||
novelWriter Markdown
|
||||
====================
|
||||
|
||||
This is simply a concatenation of the files selected by the filters.
|
||||
The files in the project are stacked together in the order they appear in the tree view, with comments, tags, etc. included if they are selected.
|
||||
This is a useful format for exporting the project for later import back into novelWriter.
|
||||
|
||||
Plain Text
|
||||
==========
|
||||
|
||||
The plain text export format writes a simple ``.txt`` file without any formatting at all.
|
||||
@@ -0,0 +1,25 @@
|
||||
####################################
|
||||
Welcome to novelWriter Documentation
|
||||
####################################
|
||||
|
||||
This is the documentation for novelWriter |version|.
|
||||
|
||||
**Contents**
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
introduction
|
||||
started
|
||||
interface
|
||||
projects
|
||||
structure
|
||||
notes
|
||||
export
|
||||
technical
|
||||
|
||||
**Indices and Tables**
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
@@ -0,0 +1,160 @@
|
||||
***************
|
||||
User Interface
|
||||
***************
|
||||
|
||||
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 a file is selected.
|
||||
This will open the document editor, which uses a simplified markdown format, described in the section below.
|
||||
|
||||
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 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.
|
||||
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, 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"
|
||||
:widths: 15, 50
|
||||
|
||||
"``# 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 rendered as bold text."
|
||||
"``_text_``", "The text is rendered as italicized text."
|
||||
"``__text__``", "The text is rendered 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."
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
==================
|
||||
|
||||
Most features are available as keyboard shortcuts.
|
||||
These are as following:
|
||||
|
||||
.. csv-table:: Keyboard Shortcuts
|
||||
:header: "Shortcut", "Description"
|
||||
:widths: 15, 50
|
||||
|
||||
":kbd:`Alt-1`", "Switch focus to tree view pane."
|
||||
":kbd:`Alt-2`", "Switch focus to document editor pane."
|
||||
":kbd:`Alt-3`", "Switch focus to document viewer pane."
|
||||
":kbd:`Ctrl-.`", "Correct word under cursor."
|
||||
":kbd:`Ctrl-/`", "Change block format to comment."
|
||||
":kbd:`Ctrl-0`", "Remove block formatting for block under cursor."
|
||||
":kbd:`Ctrl-1`", "Change block format to header level 1."
|
||||
":kbd:`Ctrl-2`", "Change block format to header level 2."
|
||||
":kbd:`Ctrl-3`", "Change block format to header level 3."
|
||||
":kbd:`Ctrl-4`", "Change block format to header level 4."
|
||||
":kbd:`Ctrl-A`", "Select all text in document."
|
||||
":kbd:`Ctrl-B`", "Format selected text, or word under cursor, as bold."
|
||||
":kbd:`Ctrl-C`", "Copy selected text to clipboard."
|
||||
":kbd:`Ctrl-D`", "Wrap selected text, or word under cursor, in double quotes."
|
||||
":kbd:`Ctrl-E`", "If in tree view, edit a document or folder settings. (Same as :kbd:`F2`)"
|
||||
":kbd:`Ctrl-F`", "Open the search bar and search for selected word, if any is selected."
|
||||
":kbd:`Ctrl-G`", "Find next occurrence of word in current document. (Same as :kbd:`F3`)"
|
||||
":kbd:`Ctrl-H`", "Open the search and replace bar and search for selected word, if any is selected. (On Mac, this is :kbd:`Cmd+=`)"
|
||||
":kbd:`Ctrl-I`", "Format selected text, or word under cursor, as italic."
|
||||
":kbd:`Ctrl-N`", "Create new document."
|
||||
":kbd:`Ctrl-O`", "Open selected document."
|
||||
":kbd:`Ctrl-Q`", "Exit novelWriter."
|
||||
":kbd:`Ctrl-R`", "If in tree view, open a document for viewing. If in editor pane, open current document for viewing."
|
||||
":kbd:`Ctrl-S`", "Save the current document in the editor."
|
||||
":kbd:`Ctrl-T`", "Show project timeline."
|
||||
":kbd:`Ctrl-U`", "Format selected text, or word under cursor, as underline."
|
||||
":kbd:`Ctrl-V`", "Paste text from clipboard to cursor position."
|
||||
":kbd:`Ctrl-W`", "Close the current document in the editor."
|
||||
":kbd:`Ctrl-X`", "Cut selected text to clipboard."
|
||||
":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."
|
||||
":kbd:`Ctrl-Shift-/`", "Remove block formatting for block under cursor."
|
||||
":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."
|
||||
":kbd:`Ctrl-Shift-D`", "Wrap selected text, or word under cursor, in single quotes."
|
||||
":kbd:`Ctrl-Shift+G`", "Find previous occurrence of word in current document. (Same as :kbd:`Shift-F3`"
|
||||
":kbd:`Ctrl-Shift-I`", "Import text to the current document from a text file."
|
||||
":kbd:`Ctrl-Shift-N`", "Create new folder."
|
||||
":kbd:`Ctrl-Shift-O`", "Open a project."
|
||||
":kbd:`Ctrl-Shift-R`", "Close the document view pane."
|
||||
":kbd:`Ctrl-Shift-S`", "Save the current project."
|
||||
":kbd:`Ctrl-Shift-W`", "Close the current project."
|
||||
":kbd:`Ctrl-Shift-Up`", "Move item one step up in the tree view."
|
||||
":kbd:`Ctrl-Shift-Down`", "Move item one step down in the tree view."
|
||||
":kbd:`F1`", "Open documentation."
|
||||
":kbd:`F2`", "If in tree view, edit a document or folder settings. (Same as :kbd:`Ctrl-E`)"
|
||||
":kbd:`F3`", "Find next occurrence of word in current document. (Same as :kbd:`Ctrl-G`)"
|
||||
":kbd:`F5`", "Export project dialog."
|
||||
":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`"
|
||||
":kbd:`Shift-Space`", "Insert a non-breaking space at the cursor position."
|
||||
":kbd:`Enter`", "If in tree view, open a document for editing."
|
||||
|
||||
.. note::
|
||||
On macOS, replace :kbd:`Ctrl` with :kbd:`Cmd`.
|
||||
@@ -0,0 +1,56 @@
|
||||
************
|
||||
Introduction
|
||||
************
|
||||
|
||||
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.
|
||||
|
||||
Design Philosophy
|
||||
-----------------
|
||||
|
||||
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, 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.
|
||||
|
||||
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
|
||||
----------
|
||||
|
||||
**novelWriter with default system theme:**
|
||||
|
||||
.. image:: images/screenshot_default.png
|
||||
:width: 800
|
||||
|
||||
**novelWriter with dark theme:**
|
||||
|
||||
.. image:: images/screenshot_dark.png
|
||||
:width: 800
|
||||
@@ -0,0 +1,23 @@
|
||||
************************
|
||||
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 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 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, 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.
|
||||
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.
|
||||
@@ -0,0 +1,145 @@
|
||||
**************
|
||||
Novel Projects
|
||||
**************
|
||||
|
||||
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`.
|
||||
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.
|
||||
|
||||
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", "Entities" or "Custom".
|
||||
These other root folder types are intended for your notes on the various elements of your story.
|
||||
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 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 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.
|
||||
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, 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
|
||||
---------------------------------
|
||||
|
||||
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, 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 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.
|
||||
|
||||
Status Tab
|
||||
----------
|
||||
|
||||
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::
|
||||
The status levels currently in use by a file cannot be deleted.
|
||||
|
||||
Importance Tab
|
||||
--------------
|
||||
|
||||
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::
|
||||
The importance levels currently in use by a file cannot be deleted.
|
||||
|
||||
Auto-Replace Tab
|
||||
----------------
|
||||
|
||||
A set of automatically replaced keywords can be added in this tab.
|
||||
The keywords in the left column wile be replaced by the text in the right column when documents are opened in the viewer.
|
||||
This will also be applied to exports when the feature is added.
|
||||
|
||||
Note that a keyword cannot contain any spaces.
|
||||
The angle brackets are added by default, and when used in the text are a part of the keyword to be replaced.
|
||||
This is to ensure that parts of the text isn't unintentionally replaced by the content of the list.
|
||||
|
||||
Writing Files
|
||||
=============
|
||||
|
||||
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 :kbd:`Ctrl-E` or :kbd:`F2` with the item selected.
|
||||
|
||||
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
|
||||
======
|
||||
|
||||
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, 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 :menuselection:`Tools` menu.
|
||||
It is also possible to dissable automated backup for a given project in 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.
|
||||
@@ -0,0 +1,91 @@
|
||||
***************
|
||||
Getting Started
|
||||
***************
|
||||
|
||||
You can download novelWriter from https://github.com/vkbo/novelWriter/releases
|
||||
|
||||
Latest version is |version|:
|
||||
|
||||
* ZIP file: https://github.com/vkbo/novelWriter/archive/v0.6.1.zip
|
||||
* TAR file: https://github.com/vkbo/novelWriter/archive/v0.6.1.tar.gz
|
||||
|
||||
Extract the archive to a location of your choice.
|
||||
|
||||
Installing Dependencies
|
||||
=======================
|
||||
|
||||
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
|
||||
|
||||
python -m pip install -r requirements.txt
|
||||
|
||||
On some operating systems you need to use ``python3`` instead of ``python``.
|
||||
|
||||
The following Python packages are required to run novelWriter:
|
||||
|
||||
* ``pyqt5`` for the GUI
|
||||
* ``lxml`` for writing project files
|
||||
|
||||
.. note::
|
||||
Sometimes the SVG graphics package for pyqt5 must be installed separately.
|
||||
|
||||
The following are optional, but recommended:
|
||||
|
||||
* ``pyenchant`` for spell checking
|
||||
|
||||
PyQt/Qt should be at least 5.2.1, but ideally 5.10 or higher for nearly all features to work.
|
||||
Exporting to markdown requires PyQt/Qt 5.14.
|
||||
There are no known minimum for lxml, but the code was originally written with 4.2.
|
||||
The optional spell check library must be at least 3.0.0 to work with Windows.
|
||||
On Linux, 2.0.0 also works fine.
|
||||
|
||||
Running novelWriter
|
||||
===================
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
python novelWriter.py --help
|
||||
|
||||
|
||||
Building a Standalone Executable
|
||||
================================
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
python install.py
|
||||
|
||||
If successful, the executable will be in the "dist" folder.
|
||||
|
||||
|
||||
Additional Instructions for Windows
|
||||
-----------------------------------
|
||||
|
||||
If you don't have Python installed, you can download it from the python.org website.
|
||||
The installers for Windows are available at https://www.python.org/downloads/windows/
|
||||
|
||||
novelWriter should work with Python 3.5 or higher, and the executable installer is the easiest to install.
|
||||
Please note that the `pyenchant` package for spell checking does not currently work with the x86-64 version, so if you want spell checking, you must install the x86 version.
|
||||
|
||||
Also, make sure you select the "Add Python to PATH" option.
|
||||
|
||||
.. image:: images/python_win_install.png
|
||||
: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.
|
||||
@@ -0,0 +1,94 @@
|
||||
*****************
|
||||
Project Structure
|
||||
*****************
|
||||
|
||||
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
|
||||
======================
|
||||
|
||||
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 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 (section).
|
||||
|
||||
Tag References
|
||||
==============
|
||||
|
||||
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 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]``.
|
||||
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.
|
||||
* ``@char``: Other characters in the current section.
|
||||
The target must be a note tag in the character root folder.
|
||||
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.
|
||||
* ``@time``: The timelines touched by the current section.
|
||||
The target must be a note tag in the timeline root folder.
|
||||
* ``@location``: The location the current section takes place in.
|
||||
The target must be a note tag in the locations root folder.
|
||||
* ``@object``: Objects present in the current section.
|
||||
The target must be a note tag in the object root folder.
|
||||
* ``@entity``: Entities present in the current section.
|
||||
The target must be a note tag in the entities root folder.
|
||||
* ``@custom``: Custom references in the current section.
|
||||
The target must be a note tag in the custom root folder.
|
||||
|
||||
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 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
|
||||
=================
|
||||
|
||||
Files that exist under the Novel type root folder can have a number of layouts set.
|
||||
See overview below.
|
||||
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.
|
||||
* **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 optionally ignored when the novel is exported.
|
||||
|
||||
.. 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.
|
||||
@@ -0,0 +1,55 @@
|
||||
*********************
|
||||
Technical Information
|
||||
*********************
|
||||
|
||||
This section contains details of how novelWriter stores and handles the project data.
|
||||
|
||||
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
|
||||
-----------------
|
||||
|
||||
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 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, 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.
|
||||
|
||||
Project Documents
|
||||
-----------------
|
||||
|
||||
The project documents are saved in folders starting with ``data_``.
|
||||
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 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 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.
|
||||
Reference in New Issue
Block a user