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

Merge branch 'dev' into novel_tab

Browse Source
This commit is contained in:
Veronica K. B. Olsen
2021-01-02 13:18:08 +01:00
parent 3d5a5e4d86 a84fc734ff
commit ad5f3f2450
10 changed files with 496 additions and 422 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/index.rst
+10 -8
View File
@@ -30,18 +30,19 @@ novelWriter |release|
novelWriter is a markdown-like text editor designed for writing novels and larger projects of many novelWriter is a markdown-like text editor designed for writing novels and larger projects of many
smaller plain text documents. It uses its own flavour of markdown that supports a meta data syntax smaller plain text documents. It uses its own flavour of markdown that supports a meta data syntax
for comments, synopsis and cross-referencing between files. The idea is to have a simple text editor for comments, synopsis and cross-referencing between documents. The idea is to have a simple text
which allows for easy organisation of text files and notes, built on a plain text file project editor which allows for easy organisation of text documents and notes, built on a plain text file
repository for robustness. project repository for robustness.
The plain text storage is suitable for version control software, and also well suited for file The plain text storage is suitable for version control software, and also well suited for file
synchronisation tools. The core project structure is stored in a project XML file. Other meta data synchronisation tools. The core project structure is stored in a single project XML file. Other
is primarily saved as JSON files. meta data is primarily saved as JSON files.
Any operating system that can run Python 3 and has the Qt 5 libraries should be able to run Any operating system that can run Python 3 and has the Qt 5 libraries should be able to run
novelWriter. It runs fine on Linux, Windows and macOS already, and users have tested it on other novelWriter. It runs fine on Linux, Windows and macOS, and users have tested it on other platforms
platforms too. Since novelWriter is still under development, it is easier to run it if you are too. novelWriter can be run directly from the Python source, or installed from the pip tool or via
already familiar with how to run Python applications on your platform. the provided setup script. A setup.exe is provided for Windows. See :ref:`a_started` for further
details.
**Useful Links** **Useful Links**
@@ -50,6 +51,7 @@ already familiar with how to run Python applications on your platform.
* Source Code: https://github.com/vkbo/novelWriter * Source Code: https://github.com/vkbo/novelWriter
* Source Releases: https://github.com/vkbo/novelWriter/releases * Source Releases: https://github.com/vkbo/novelWriter/releases
* Issue Tracker: https://github.com/vkbo/novelWriter/issues * Issue Tracker: https://github.com/vkbo/novelWriter/issues
* Feature Discussions: https://github.com/vkbo/novelWriter/discussions
* PyPi Project: https://pypi.org/project/novelWriter * PyPi Project: https://pypi.org/project/novelWriter
docs/source/int_interface.rst
+106 -100
View File
@@ -4,65 +4,70 @@
User Interface User Interface
************** **************
The user interface is kept as simple as possible to avoid distractions when writing. This page lists The user interface is kept as simple as possible to avoid distractions when writing. This page
all the main GUI elements, and explains what they do. lists all the main GUI elements, and explains what they do.
.. _a_ui_tree: .. _a_ui_tree:
The Project Tree The Project Tree
================ ================
The main window contains a project tree in the left-most panel. It shows the entire structure of the The main window contains a project tree in the left-most panel. It shows the entire structure of
project. It has four columns: the project. It has four columns:
:guilabel:`Label` :guilabel:`Label`
The first column shows the item icon and its label. The labels can be edited from the menu, or by The first column shows the item icon and its label. The labels can be edited from the
pressing :kbd:`F2` or :kbd:`Ctrl`:kbd:`E`. The label is not the same as the title you set inside :guilabel:`Project` menu, or by pressing :kbd:`F2` or :kbd:`Ctrl`:kbd:`E`. The label is not the
the document, but it will appear in the header above the document text itself. same as the title you set inside the document, but it will appear in the header above the
document text itself.
:guilabel:`Words` :guilabel:`Words`
The second column shows the word count of the file, or the sum of words in the child items if it The second column shows the word count of the document, or the sum of words in the child items
is a folder. If the counts seem incorrect, they can be updated by rebuilding the project index if it is a folder. If the counts seem incorrect, they can be updated by rebuilding the project
from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`. index from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`.
:guilabel:`Inc` :guilabel:`Inc`
The third column indicates whether the file is included in the final project build or not. You The third column indicates whether the document is included in the final project build or not.
may want to filter out files that you no longer want to keep in the final manuscript, but want to You may want to filter out documents that you no longer want to keep in the final manuscript,
keep in the project for reference. but want to keep in the project for reference.
:guilabel:`Flags` :guilabel:`Flags`
The fourth column shows various meta data flags for the item. The first is an icon indicating the The fourth column shows various meta data flags for the item. The first is an icon indicating
importance or status of the file. These are colour coded status levels that you control and the importance or status of the document. These are colour coded status levels that you control
define yourself. They can be changed in :guilabel:`Project Settings` from the :guilabel:`Project` and define yourself. They can be changed in :guilabel:`Project Settings` from the
menu. The first character after the icon indicates the class of the item, that is ``N`` for :guilabel:`Project` menu. The first character after the icon indicates the class of the item,
**Novel**, ``C`` for **Character**, etc (see :ref:`a_struct_tags`. The second character indicates that is ``N`` for **Novel**, ``C`` for **Character**, etc (see :ref:`a_struct_tags`). The second
the file layout type (see :ref:`a_proj_roots`). character indicates the document layout type (see :ref:`a_proj_roots`).
Below the project tree you will find a small details panel showing the full information of the Below the project tree you will find a small details panel showing the full information of the
currently selected item. This panel also includes the latest paragraph and character counts in currently selected item. This panel also includes the latest paragraph and character counts in
addition to the word count. addition to the word count.
Right-clicking an item in the project tree will open a context menu under the cursor, displaying
a selection of actions that can be performed on the selected item.
.. _a_ui_tree_dnd: .. _a_ui_tree_dnd:
Project Tree Drag and Drop Project Tree Drag and Drop
-------------------------- --------------------------
The project tree allows dragging and drop to a certain extent. This feature is primarily intended The project tree allows drag and drop to a certain extent. This feature is primarily intended for
for rearranging the order of your files within each root folder, and has only limited support for rearranging the order of your documents within each root folder, and has only limited support for
moving files elsewhere in the project tree. In general, bulk actions are not allowed. This is moving documents elsewhere in the project tree. In general, bulk actions are not allowed. This is
deliberate to avoid accidentally messing up your project. The project tree has no undo function. deliberate to avoid accidentally messing up your project. The project tree has no undo function.
Document files and their folders can be rearranged freely within their root folders. Novel files Documents and their folders can be rearranged freely within their root folders. Novel documents
cannot be moved out of the :guilabel:`Novel` folder, except to :guilabel:`Trash` and the cannot be moved out of the :guilabel:`Novel` folder, except to :guilabel:`Trash` and the
:guilabel:`Outtakes` folder. Note files can be moved freely anywhere. :guilabel:`Outtakes` folder. Notes can be moved freely between root folders.
Folders cannot be moved at all outside their root tree. Neither can a folder containing files be Folders cannot be moved at all outside their root tree. Neither can a folder containing documents
deleted. You must first delete the files. be deleted. You must first delete the containing documents.
Root folders in the project tree cannot be dragged and dropped at all. However, if you want to Root folders in the project tree cannot be dragged and dropped at all. If you want to reorder them,
reorder them, you can move them up or down with respect to eachother from the :guilabel:`Tools` you can move them up or down with respect to eachother from the :guilabel:`Tools` menu or the
menu, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down` key. right-click context menu, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down`
key.
.. _a_ui_edit: .. _a_ui_edit:
@@ -70,32 +75,36 @@ menu, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down` ke
Editing and Viewing Documents Editing and Viewing Documents
============================= =============================
To edit a document, double-click the file in the project tree, or press the :kbd:`Return` key while To edit a document, double-click it in the project tree, or press the :kbd:`Return` key while
having it selected. This will open the file in the document editor. The editor uses a simplified having it selected. This will open the document in the document editor. The editor uses a
markdown format. The format is described in the :ref:`a_ui_md` section below. The editor has a simplified markdown format. The format is described in the :ref:`a_ui_md` section below. The editor
maximise button (activates :guilabel:`Focus Mode`) and a close button in the top-right corner. has a maximise button (activates :guilabel:`Distraction Free Mode`) and a close button in the
top-right corner.
Any document in the project tree can also be viewed in parallel in a right hand side document viewer Any document in the project tree can also be viewed in parallel in a right hand side document
To view a document, press :kbd:`Ctrl`:kbd:`R`, or select :guilabel:`View Document` in the menu. The viewer. To view a document, press :kbd:`Ctrl`:kbd:`R`, or select :guilabel:`View Document` in the
document viewed does not have to be the same document currently being edited. However, If you *are* menu. If you have a middle mouse button, middle-clicking on the document will also open it in the
viewing the same document, pressing :kbd:`Ctrl`:kbd:`R` again will update the document with your viewer. The document viewed does not have to be the same document currently being edited. However,
latest changes. You can also press the little reload button in the top-right corner of the view If you *are* viewing the same document, pressing :kbd:`Ctrl`:kbd:`R` again will update the document
with your latest changes. You can also press the reload button in the top-right corner of the view
panel next to the close button to achieve the same thing. panel next to the close button to achieve the same thing.
Both the document editor and viewer will show the label of the document in the header at the top of Both the document editor and viewer will show the label of the document in the header at the top of
the edit or view panel. Optionally, the full project path to the file can be shown. This can be set the edit or view panel. Optionally, the full project path to the document can be shown. This can be
in the :guilabel:`Preferences` dialog from the :guilabel:`Tools` menu. Clicking on the document set in the :guilabel:`Preferences` dialog from the :guilabel:`Tools` menu. Clicking on the document
title bar will select and reveal the file in the project tree, making it easier to find the project title bar will select and reveal its location in the project tree, making it easier to find in a
location of the file in a large project. large project.
Any reference to a tag in the editor can be opened in the viewer by moving the cursor to the label Any reference to a tag in the editor can be opened in the viewer by moving the cursor to the label
and pressing :kbd:`Ctrl`:kbd:`Return`. In the viewer, the references become clickable links. and pressing :kbd:`Ctrl`:kbd:`Return`. In the viewer, the references become clickable links.
Clicking them will replace the content of the viewer with the content of the document the reference Clicking them will replace the content of the viewer with the content of the document the reference
points to. points to. The document viewer keeps a history of viewed documents that you can navigate with the
arrow buttons in the top-left corner of the viewer. If your mouse has navigation buttons, these can
be used as well.
At the bottom of the view panel there is a :guilabel:`References` panel. (If it is hidden, click the At the bottom of the view panel there is a :guilabel:`References` panel. (If it is hidden, click
icon to reveal it.) This panel will show links to all documents referring back to it, if any has the icon to reveal it.) This panel will show links to all documents referring back to it, if any
been defined. The :guilabel:`Sticky` button will freeze the content of the panel to the current has been defined. The :guilabel:`Sticky` button will freeze the content of the panel to the current
document, even if you navigate to another document. This is convenient if you want to quickly look document, even if you navigate to another document. This is convenient if you want to quickly look
through all documents in the list in the :guilabel:`References` panel. through all documents in the list in the :guilabel:`References` panel.
@@ -145,28 +154,28 @@ a synopsis tag, and a set of keyword and value sets used for tags and references
Headings Headings
-------- --------
Four levels of headings are allowed. For files of type "Note", they are free to be used as you see Four levels of headings are allowed. For documents of layout "Note", they are free to be used as
fit, but for all other file layouts used for the novel text itself, they indicate the structural you see fit, but for all other layouts used for the novel text itself, they indicate the structural
level of the novel. See :ref:`a_struct_heads` for more details. level of the novel. See :ref:`a_struct_heads` for more details.
``# Title`` ``# Title``
Heading level one. If the file is a novel file, the header level indicates the start of a new Heading level one. If the document is a novel file, the header level indicates the start of a
partition. This heading level can also be used for the title page novel title. new partition. This heading level can also be used for the title page novel title.
``## Title`` ``## Title``
Heading level two. If the file is a novel file, the header level indicates the start of a new Heading level two. If the document is a novel file, the header level indicates the start of a
chapter. new chapter.
``### Title`` ``### Title``
Heading level three. If the file is a novel file, the header level indicates the start of a new Heading level three. If the document is a novel file, the header level indicates the start of a
scene. new scene.
``#### Title`` ``#### Title``
Heading level four. If the file is a novel file, the header level indicates the start of a new Heading level four. If the document is a novel file, the header level indicates the start of a
section. new section.
.. note:: .. note::
The space after the ``#`` characters is mandatory. The syntaxhighlighter will change colour and The space after the ``#`` characters is mandatory. The syntax highlighter will change colour and
font size when the heading is correctly formatted. font size when the heading is correctly formatted.
@@ -187,12 +196,12 @@ A minimal set of text emphasis styles are supported.
Strikethrough text. Strikethrough text.
In markdown guides it is often recommended to differentiate between strong importance and emphasis In markdown guides it is often recommended to differentiate between strong importance and emphasis
by using ``**`` for strong and ``_`` for emphasis, although markdown generally supports also ``__`` by using ``**`` for strong and ``_`` for emphasis, although markdown generally also supports ``__``
for strong and ``*`` fdr emphasis. However, since the differentiation makes the highlighting and for strong and ``*`` for emphasis. However, since the differentiation makes the highlighting and
conversion significantly simpler and faster, in novelWriter this is a rule, not just a conversion significantly simpler and faster, in novelWriter this is a rule, not just a
recommendation. The following is therefore the only supported formatting syntax: recommendation.
There are also some additional rules: In addition, the following rules apply:
1. The emphasis and strikethrough formatting tags do not allow spaces between the words and the tag 1. The emphasis and strikethrough formatting tags do not allow spaces between the words and the tag
itself. That is, ``**text**`` is valid, ``**text **`` is not. itself. That is, ``**text**`` is valid, ``**text **`` is not.
@@ -201,6 +210,8 @@ There are also some additional rules:
3. If using both ``**`` and ``_`` to wrap the same text, the underscore must be the inner wrapper. 3. If using both ``**`` and ``_`` to wrap the same text, the underscore must be the inner wrapper.
This is due to the underscore also being a valid word character, so if they are on the outside, This is due to the underscore also being a valid word character, so if they are on the outside,
they violate rule 2. they violate rule 2.
4. Text emphasis does not span past line breaks. If you need to add emphasis to multiple lines or
paragraphs, you must apply it to each of them in turn.
.. _a_ui_md_comm: .. _a_ui_md_comm:
@@ -208,20 +219,26 @@ There are also some additional rules:
Comments and Synopsis Comments and Synopsis
--------------------- ---------------------
In addition to these standard markdown features, novelWriter also allows for comments in the text In addition to these standard markdown features, novelWriter also allows for comments in document.
files. The text of the comment is ignored by the word counter and not exported or, optionally, The text of the comment is ignored by the word counter and not exported or, optionally, hidden when
hidden when viewing the document. If the first word of a comment is ``Synopsis:`` (with the colon), viewing the document. If the first word of a comment is ``Synopsis:`` (with the colon), the comment
the comment is treated specially, and will show up in the :ref:`a_ui_outline` in a dedicated column. is treated specially and will show up in the :ref:`a_ui_outline` in a dedicated column. The word
``synopsis`` is not case sensitive. If it is correctly formatted, the syntax highlighter will
indicate this by altering the colour of the word.
``% text...`` ``% text...``
A comment. The text is not exported by default (this can be overridden), seen in the Viewer, or A comment. The text is not exported by default (this can be overridden), seen in the Viewer, or
counted towards word counts. counted towards word counts.
``% Synopsis: text...`` ``% Synopsis: text...``
A synopsis comment. It is generally treated in the same way as regular comments, except that it A synopsis comment. It is generally treated in the same way as a regular comment, except that it
is captured by the indexing algorithm and displayed in the :ref:`a_ui_outline`. It can also be is also captured by the indexing algorithm and displayed in the :ref:`a_ui_outline`. It can also
filtered separately when exporting the project to for instance generate an outline document of be filtered separately when exporting the project to for instance generate an outline document
the whole project. of the whole project.
.. note::
Only one comment can be flagged as a synopsis comment for each heading. If multiple comments are
flagged as synopsis comments, the last one will be used.
.. _a_ui_md_tags: .. _a_ui_md_tags:
@@ -230,13 +247,14 @@ Tags and References
------------------- -------------------
The document editor supports a minimal set of keywords used for setting tags, and making references The document editor supports a minimal set of keywords used for setting tags, and making references
between files. The tags and references can be set once per section defined by a heading. Using them between documents. The tags and references can be set once per section defined by a heading. Using
multiple times under the same heading will just override the previous setting. them multiple times under the same heading will just override the previous setting.
``@keyword: value`` ``@keyword: value``
A keyword argument followed by a value, or a comma separated list of values. A keyword argument followed by a value, or a comma separated list of values.
The available tag and reference keywords are listed in the :ref:`a_struct_tags` section. The available tag and reference keywords are listed in the :ref:`a_struct_tags` section. They can
also be inserted at the cursor position in the editor via the :guilabel:`Insert` menu.
.. _a_ui_md_add: .. _a_ui_md_add:
@@ -246,12 +264,13 @@ Additional Markdown and Non-Standard Features
The editor and viewer also supports markdown standard hard line breaks, and preserves non-breaking The editor and viewer also supports markdown standard hard line breaks, and preserves non-breaking
spaces if running with Qt 5.9 or higher. For older versions, the non-breaking spaces are lost when spaces if running with Qt 5.9 or higher. For older versions, the non-breaking spaces are lost when
the file is saved. This is unfortunately hard-coded in the Qt text editor. the document is saved. This is unfortunately hard-coded in the Qt text editor.
* A hard line break is achieved by leaving two or more spaces at the end of the line. Alternatively, * A hard line break is achieved by leaving two or more spaces at the end of the line.
the user can press :kbd:`Ctrl`:kbd:`K`, :kbd:`Return` to insert this. Alternatively, the user can press :kbd:`Ctrl`:kbd:`K`, :kbd:`Return` to insert this.
* A non-breaking space is inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Space`. * A non-breaking space is inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Space`.
* Thin spaces are also supported, and can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Shift`:kbd:`Space`. * Thin spaces are also supported, and can be inserted with :kbd:`Ctrl`:kbd:`K`,
:kbd:`Shift`:kbd:`Space`.
* Non-breaking thin space can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`Space`. * Non-breaking thin space can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`Space`.
These are all insert features, and the :guilabel:`Insert` menu has more. They are also listed These are all insert features, and the :guilabel:`Insert` menu has more. They are also listed
@@ -268,16 +287,16 @@ Project Outline View
The project's Outline view is available as the second tab on the right hand side of the main window The project's Outline view is available as the second tab on the right hand side of the main window
labelled :guilabel:`Outline`. The outline provides an overview of the novel structure, displaying a labelled :guilabel:`Outline`. The outline 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, not the files. tree hierarchy of the elements of the novel, that is, the level 1 to 4 headings.
The document file containing the heading can also be displayed as a separate column, as well as the The document containing the heading can also be displayed as a separate column, as well as the line
line number where it occurs. Double-clicking an entry will open the corresponding file in the number where it occurs. Double-clicking an entry will open the corresponding document in the
editor. editor.
.. note:: .. note::
Since the internal structure of the novel does not depend on the file structure of the project Since the internal structure of the novel does not depend directly on the folder and document
tree, these will not necessarily look the same, depending how you chose to organise your files. structure of the project tree, these will not necessarily look the same, depending how you
See the :ref:`a_struct` page for more details. choose to organise your documents. See the :ref:`a_struct` page for more details.
Various meta data and information extracted from tags can be displayed in columns in the outline. Various meta data and information extracted from tags can be displayed in columns in the outline.
A default set of such columns is visible, but you can turn on or off more columns by right clicking A default set of such columns is visible, but you can turn on or off more columns by right clicking
@@ -296,21 +315,8 @@ updating in the :guilabel:`Tools` menu, which will trigger an update whenever th
and the :guilabel:`Outline` tab is active. You may want to disable this feature if your project is and the :guilabel:`Outline` tab is active. You may want to disable this feature if your project is
very large, very large,
The :guilabel:`Synopsis` column of the outline view takes its information from a specially
.. _a_ui_outline_synopsis: formatted comment. See :ref:`a_ui_md_comm`.
Synopsis Column
---------------
The :guilabel:`Synopsis` column of the outline view takes its information from a specially formatted
comment. See :ref:`a_ui_md_comm`. In order to flag a comment as a synopsis, add the word
``Synopsis:`` as the first word of the comment. The ``:`` is required, and the word ``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 comment, the last one will be used.
.. _a_ui_shortcuts: .. _a_ui_shortcuts:
@@ -401,9 +407,9 @@ Most features are available as keyboard shortcuts. These are as follows:
Insert Shortcuts Insert Shortcuts
---------------- ----------------
A set of insert features are also available through shortcuts, but they require a double combination A set of insert features are also available through shortcuts, but they require a double
of key sequences. The insert feature is activated with :kbd:`Ctrl-K`, followed by a key or combination of key sequences. The insert feature is activated with :kbd:`Ctrl`:kbd:`K`, followed by
combination for the inserted character or punctuation. a key or combination for the inserted character or punctuation.
.. csv-table:: Keyboard Shortcuts .. csv-table:: Keyboard Shortcuts
:header: "Shortcut", "Description" :header: "Shortcut", "Description"
docs/source/int_introduction.rst
+38 -34
View File
@@ -5,20 +5,22 @@ Introduction
************ ************
novelWriter is a simple, multi-document plain text editor using a modified markdown syntax to apply novelWriter is a simple, multi-document plain text editor using a modified markdown syntax to apply
simple formatting. It is designed for writing novels, and allows for the component documents to be simple formatting to the text. It is designed for writing novels, and allows for the component
ordered freely to create the desired structure of the novel. More details about how projects are documents to be ordered freely to create the desired structure of the novel. More details about how
structured is covered on the :ref:`a_struct` page. projects are structured is covered on the :ref:`a_struct` page.
In addition, the project can contain notes on the various plot elements, characters, locations, etc, In addition, the project can contain notes on the various plot elements, characters, locations,
that make up the story. These notes are organised in a set of category-specific top-level folders, etc, that make up the story. These notes are organised in a set of category-specific top-level
and each entry can be tagged and cross-referenced from within the novel files and other notes. These folders (root folders), and each entry can be tagged and cross-referenced from within the novel
tags make it possible to inter-link documents, and generate an overview of the entire novel project documents and notes. These tags make it possible to inter-link documents, and generate an overview
and how the various files and plot elements are interconnected. This is covered on the :ref:`a_proj` of the entire novel project and how the various documents and plot elements are interconnected.
and :ref:`a_notes` pages. This is covered on the :ref:`a_proj` and :ref:`a_notes` pages.
These additional features are not standard in markdown, but are available through special meta These additional features are not standard in markdown, but are available through special meta
keywords. Syntax highlighting is provided to make it easier to verify that the markdown tags are keywords described in :ref:`a_struct_tags`. Syntax highlighting is provided to make it easier to
used correctly. The syntax is covered on the :ref:`a_ui` page. verify that the markdown tags are used correctly.
An overview of the supported markdown syntax is covered on the :ref:`a_ui` page.
.. _a_intro_design: .. _a_intro_design:
@@ -31,8 +33,8 @@ at the same time provide a complete set of features needed for writing a novel.
.. note:: .. note::
novelWriter is not intended to be a full office type word processor. It doesn't support images, novelWriter is not intended to be a full office type word processor. It doesn't support images,
links, tables, and other complex structure and objects often needed for such document. Formatting links, tables, and other complex structures and objects often needed for such documents.
is limited to headers, and bold, italicised and strikethrough text. Formatting is limited to headers, and bold, italicised and strikethrough text.
The main window does not have a toolbar like most other applications do. This reduces clutter, and The main window does not have a toolbar like most other applications do. This reduces clutter, and
since the documents are formatted with markdown tags, is more or less redundant. However, all since the documents are formatted with markdown tags, is more or less redundant. However, all
@@ -40,23 +42,24 @@ formatting features supported are available through convenient keyboard shortcut
available in the main menu. A full list of shortcuts can be found in the :ref:`a_ui_shortcuts` available in the main menu. A full list of shortcuts can be found in the :ref:`a_ui_shortcuts`
section. section.
In addition, novelWriter offers a :guilabel:`Focus Mode` where all the user interface elements other In addition, novelWriter offers a :guilabel:`Distraction Free Mode` where all the user interface
than the document editor itself are hidden away. elements other than the document editor itself are hidden away.
The colour scheme of the user interface defaults to that of the host operating system. In addition, The colour scheme of the user interface defaults to that of the host operating system. In addition,
a dark theme is provided, and can be enabled in :guilabel:`Preferences` from the :guilabel:`Tools` a dark theme is provided, and can be enabled in :guilabel:`Preferences` from the :guilabel:`Tools`
menu. A number of syntax highlighting themes are also available in :guilabel:`Preferences`. A set of menu. A number of syntax highlighting themes are also available in :guilabel:`Preferences`. A set
icon themes in colour and greyscale are also offered. The icons are based on the Typicons_ icon set of icon themes in colour and greyscale are also offered. The icons are based on the Typicons_ icon
designed by Stephen Hutchings. set designed by Stephen Hutchings.
The main window is split in two, or optionally three, panels. The left-most contains the project The main window is split in two, or optionally three, panels. The left-most contains the project
tree and all the files in your project. The second panel is the document editor, and the optional tree and all the documents in your project. The second panel is the document editor, and the
third panel is a document viewer which can view any document in your project. optional third panel is a document viewer which can view any document in your project.
A second tab is also available on the main window. This is the :guilabel:`Outline` tab where the A second tab is also available on the main window. This is the :guilabel:`Outline` tab where the
entire novel structure can be displayed, with all the tags and references listed. Depending on how entire novel structure can be displayed, with all the tags and references listed. Depending on how
you structure your novel project files, this outline can be quite different than your project tree. you structure your novel documents, this outline can be quite different from your project tree.
Your project tree lists files, your Outline tree lists the structure of the novel itself. Your project tree lists individual documents, your Outline tree lists the structure of the novel
itself as it appears in the text of the documents.
.. _Typicons: https://github.com/stephenhutchings/typicons.font .. _Typicons: https://github.com/stephenhutchings/typicons.font
@@ -66,10 +69,10 @@ Your project tree lists files, your Outline tree lists the structure of the nove
Project Layout Project Layout
============== ==============
You are free to structure your project files as you wish in subfolders, and split the text between You are free to structure your project documents as you wish in subfolders, and split the text
files in whatever way suits you. All that matters to novelWriter is the linear order the files between documents in whatever way suits you. All that matters to novelWriter is the linear order
appear at in the project tree (top to bottom). The chapters, scenes and sections of the novel are the documents appear at in the project tree (top to bottom). The chapters, scenes and sections of
determined by the headings within those files. the novel are determined by the headings within those documents.
The four heading levels (**H1** to **H4**) are treated as follows: The four heading levels (**H1** to **H4**) are treated as follows:
@@ -78,9 +81,9 @@ The four heading levels (**H1** to **H4**) are treated as follows:
* **H3** is used for scene titles – optionally replaced by separators. * **H3** is used for scene titles – optionally replaced by separators.
* **H4** is for section titles within scenes, if such granularity is needed. * **H4** is for section titles within scenes, if such granularity is needed.
This header level structure is only taken into account for novel files. For the files designated as This header level structure is only taken into account for novel documents. For the project notes,
project notes, the header levels imply no structural meaning, and the user is free to do whatever the header levels have no structural meaning, and the user is free to do whatever they want. See
they want. See the :ref:`a_struct` page for more details. the :ref:`a_struct` and :ref:`a_notes` pages for more details.
.. _a_intro_export: .. _a_intro_export:
@@ -88,9 +91,10 @@ they want. See the :ref:`a_struct` page for more details.
Project Export Project Export
============== ==============
The project can at any time be exported to a range of different formats. Natively, novelWriter The project can at any time be exported to a range of different formats through the
supports export to plain text file, HTML document, novelWriter flavoured markdown, standard :guilabel:`Build Novel Project` tool. Natively, novelWriter supports export to plain text file,
markdown (requires Qt 5.14), and to a basic Open Document. HTML document, novelWriter flavoured markdown, standard markdown (requires Qt 5.14), and to a basic
Open Document format.
In addition, printing and printing to PDF is also possible. The best supported export format is In addition, printing and printing to PDF is also possible. The best supported export format is
HTML, which can be imported or converted by a number of other tools like Pandoc, or simply imported HTML, which can be imported or converted by a number of other tools like Pandoc, or simply imported
@@ -108,8 +112,8 @@ formats.
.. _a_intro_screenshots: .. _a_intro_screenshots:
Screenshot Screenshots
========== ===========
**novelWriter with default system theme:** **novelWriter with default system theme:**
docs/source/int_started.rst
+69 -35
View File
@@ -4,13 +4,19 @@
Getting Started Getting Started
*************** ***************
This is a brief guide to how you can get novelWriter running on your computer. These are the methods This is a brief guide to how you can get novelWriter running on your computer. These are the
currently supported by the developer. Packages may also be available in other package managers, but methods currently supported by the developer. Packages may also be available in other package
those are not managed by me. managers, but those are not managed by the developer. A Windows installer file is also provided on
the GitHub page and main website.
As novelWriter matures, more options for how to install it and get it running will be added. At the As novelWriter matures, more options for how to install it and get it running will be added. For
present time, the process is best suited for people used to work with Python projects from command non-Windows users the install process is at the present time best suited for people used to working
line. with the command line.
.. note::
The text below assumes the command ``python`` corresponds to a Python 3 executable. For
operating systems with both Python 2 and 3, the command ``python3`` may be needed instead. On
Linux, the scripts can also be made executable and run without the ``python`` command.
.. _a_started_install: .. _a_started_install:
@@ -28,6 +34,41 @@ Latest version of novelWriter is |release|.
.. _PyPi: https://pypi.org/project/novelWriter/ .. _PyPi: https://pypi.org/project/novelWriter/
.. _a_started_install_win:
Windows Installer
-----------------
You can run novelWriter directly from source on Windows, but a Windows installer is also provided
for 64-bit Windows on the `main website`_ and GitHub_ page. This installer bundles all that is
needed for novelWriter to run, including Python and the xml and Qt libraries.
.. _main website: https://novelwriter.io
.. _a_started_install_source:
Install from Source on Linux
----------------------------
For Linux systems, novelWriter can be installed from source with the provided ``setup.py`` script.
To install novelWriter into the system's default Python install locations, run:
.. code-block:: console
python setup.py install
To set up the novelWriter desktop launcher, the icons and the project file association, run:
.. code-block:: console
python setup.py xdg-install
By default, these commands installs novelWriter and its icons for the current user only. To install
for all users, run the script with the ``sudo`` command. Other options are also available. Run
``python setup.py help`` for a full list of install options.
.. _a_started_depend: .. _a_started_depend:
Dependencies Dependencies
@@ -68,17 +109,15 @@ You can of course also install these packages from your operating system's packa
PyQt/Qt should be at least 5.2.1, but ideally 5.10 or higher for nearly all features to work. PyQt/Qt should be at least 5.2.1, but ideally 5.10 or higher for nearly all features to work.
Exporting to standard Markdown, for instance, requires PyQt/Qt 5.14. Searching using regular Exporting to standard Markdown, for instance, requires PyQt/Qt 5.14. Searching using regular
expressions requires 5.3, and for full Unicode support, 5.13. expressions requires 5.3, and for full Unicode support, 5.13. There is no known minimum version
requirement for package ``lxml``, but the code was originally written with 4.2, which is therefore
There are no known minimum version requirement for package ``lxml``, but the code was originally set as the minimum. It may work on lower versions. You have to test it.
written with 4.2, which is therefore set as the minimum. It may work on lower versions. You have to
test it.
The spell checking extension is optional, but recommended: The spell checking extension is optional, but recommended:
* ``pyenchant``, needed for efficient spell checking. * ``pyenchant``, needed for efficient spell checking.
The optional spell check library must be at least 3.0.0 to work with Windows. On Linux, 2.0.0 also The optional spell check library must be at least 3.0 to work with Windows. On Linux, 2.0 also
works fine. works fine.
@@ -87,9 +126,9 @@ works fine.
Building the Documentation Building the Documentation
-------------------------- --------------------------
If you installed novelWriter from a package, the documentation should be included. If you're running If you installed novelWriter from a package, the documentation should be included. If you're
novelWriter from the source code, a local copy of this documentation can be generated. It requires running novelWriter from the source code, a local copy of this documentation can be generated. It
the following Python packages on Debian and Ubuntu. requires the following Python packages on Debian and Ubuntu.
* ``python3-sphinx`` * ``python3-sphinx``
* ``python3-sphinxcontrib.qthelp`` * ``python3-sphinxcontrib.qthelp``
@@ -100,13 +139,20 @@ Or from PyPi:
pip install sphinx sphinxcontrib-qthelp pip install sphinx sphinxcontrib-qthelp
To build the help packages from the documentation source, run The documentation can then be built from the ``docs`` folder in the source code by running:
.. code-block:: console .. code-block:: console
./setup.py qthelp make html
from the root source folder. If successful, the documentation should then be available in the ``docs/build/html`` folder.
The documentation can also be built for the Qt Assistant. To build the help packages from the
documentation source, run the following from the root source folder:
.. code-block:: console
python setup.py qthelp
The setup script will copy the generated files into the ``nw/assets/help`` folder, and novelWriter The setup script will copy the generated files into the ``nw/assets/help`` folder, and novelWriter
will detect the presence of the files and redirect the menu help entry to open help locally instead will detect the presence of the files and redirect the menu help entry to open help locally instead
@@ -121,17 +167,14 @@ locally first, then send you to the website as a fallback.
.. _a_started_running: .. _a_started_running:
Running novelWriter Running from Source
=================== ===================
If all the required dependencies are met, you can run novelWriter from the command line in one of If all the required dependencies are met, you can run novelWriter from the command line:
the following ways:
.. code-block:: console .. code-block:: console
python novelWriter.py 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 A few switches are supported from the command line, mostly to assist in debugging if an error is
encountered. To list all options, run: encountered. To list all options, run:
@@ -140,10 +183,6 @@ encountered. To list all options, run:
python novelWriter.py --help python novelWriter.py --help
There are also a couple of install scripts in the setup folder which will assist in setting up a
launch icon and the novelWriter project file mimetype for Gnome desktops on Linux. Currently,
there's one script for Debian and one for Ubuntu.
.. _a_started_standalone: .. _a_started_standalone:
@@ -151,15 +190,10 @@ Building a Standalone Executable
================================ ================================
A standalone executable can be built with ``pyinstaller``, using the provided python script 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 ``make.py`` in the source folder. This script can install dependencies, build a standalone
and build the standalone executable of novelWriter. You can run the script by typing the following executable of novelWriter, or build a ``setup.exe`` file with Inno Setup.
into your command prompt:
.. code-block:: console For a full list of the script's options, run ``python make.py help``.
python install.py
If successful, the executable will be in the "dist" folder.
.. _a_started_standalone_win: .. _a_started_standalone_win:
docs/source/int_typography.rst
+15 -15
View File
@@ -4,10 +4,10 @@
Typographical Notes Typographical Notes
******************* *******************
novelWriter has some support for typographical symbols that are not usually easily available in many novelWriter has some support for typographical symbols that are not usually easily available in
text editors. This includes for instance the proper unicode quotation marks, dashes, ellipsis, thin many text editors. This includes for instance the proper unicode quotation marks, dashes, ellipsis,
spaces, etc. All these symbols are available from the :guilabel:`Insert` menu, and via keyboard thin spaces, etc. All these symbols are available from the :guilabel:`Insert` menu, and via
shortcuts. See :ref:`a_ui_shortcuts_ins`. keyboard shortcuts. See :ref:`a_ui_shortcuts_ins`.
This chapter provides some additional information on how novelWriter handles these symbols. This chapter provides some additional information on how novelWriter handles these symbols.
@@ -24,9 +24,9 @@ Dashes and Ellipsis
------------------- -------------------
With the auto-replace feature enabled (see :ref:`a_ui_edit_auto`), multiple hyphens are converted With the auto-replace feature enabled (see :ref:`a_ui_edit_auto`), multiple hyphens are converted
automatically to short and long dashes, and three dots to ellipsis. The last auto-replace can always automatically to short and long dashes, and three dots to ellipsis. The last auto-replace can
be reverted with the undo command :kbd:`Ctrl`:kbd:`Z`, reverting the text to what you typed before always be reverted with the undo command :kbd:`Ctrl`:kbd:`Z`, reverting the text to what you typed
the automatic replacement occurred. before the automatic replacement occurred.
Single and Double Quotes Single and Double Quotes
@@ -36,14 +36,14 @@ All the different quotation marks listed on the `Quotation Mark`_ Wikipedia page
can be selected as auto-replaced symbols for straight single and double quote key strokes. The can be selected as auto-replaced symbols for straight single and double quote key strokes. The
settings can be found in the :guilabel:`Preferences`. settings can be found in the :guilabel:`Preferences`.
Ordinarily, text wrapped in quotes are highlighted by the editor. This is meant as a convenience for Ordinarily, text wrapped in quotes are highlighted by the editor. This is meant as a convenience
highlighting dialogue between characters. This feature can be disabled in the for highlighting dialogue between characters. This feature can be disabled in the
:guilabel:`Preferences` if this feature isn't wanted. :guilabel:`Preferences` if this feature isn't wanted.
The editor distinguishes between text wrapped in straight quotes and with the user-selected double The editor distinguishes between text wrapped in straight quotes and with the user-selected double
quote symbols. This is to help the writer recognise which parts of the text are not using the chosen quote symbols. This is to help the writer recognise which parts of the text are not using the
quote symbols. Two convenience functions in the :guilabel:`Format` menu can be used to re-format a chosen quote symbols. Two convenience functions in the :guilabel:`Format` menu can be used to
selected section of text with the correct quote symbols. re-format a selected section of text with the correct quote symbols.
.. _Quotation Mark: https://en.wikipedia.org/wiki/Quotation_mark .. _Quotation Mark: https://en.wikipedia.org/wiki/Quotation_mark
@@ -76,10 +76,10 @@ separate a number from its unit is with a `thin space`_. It is usually 2/3 the w
space. For numbers and units, this should in addition be a non-breaking space, that is, the text space. For numbers and units, this should in addition be a non-breaking space, that is, the text
wrapping should not add a line break on this particular space. wrapping should not add a line break on this particular space.
A regular space can also be made into a non-breaking space. A regular space can also be made into a non-breaking space if needed.
All non-breaking spaces are highlighted with a differently coloured packground. The colour will All non-breaking spaces are highlighted with a differently coloured background to make it easier to
depend on the selected colour theme. spot them in the text. The colour will depend on the selected colour theme.
The thin and non-breaking spaces are converted to their corresponding HTML codes on export to HTML The thin and non-breaking spaces are converted to their corresponding HTML codes on export to HTML
format. For plain text, they are exported as regular spaces. format. For plain text, they are exported as regular spaces.
docs/source/tech_technical.rst
+26 -23
View File
@@ -10,11 +10,11 @@ This section contains details of how novelWriter stores and handles the project
How Data is Stored How Data is Stored
================== ==================
All novelWriter files are written with utf-8 encoding. Since Python automatically converts Unix line All novelWriter files are written with utf-8 encoding. Since Python automatically converts Unix
endings to Windows line endings on Windows systems, novelWriter does not make any adaptations to the line endings to Windows line endings on Windows systems, novelWriter does not make any adaptations
formatting on Windows systems. This is handled entirely by the Python standard library. Python also to the formatting on Windows systems. This is handled entirely by the Python standard library.
handles this fairly well when working on the same files on both Windows and Unix-based operating Python also handles this fairly well when working on the same files on both Windows and Unix-based
systems. operating systems.
Main Project File Main Project File
@@ -44,29 +44,31 @@ Project Documents
The project documents are saved in a folder in the main project folder named ``content``. Each The project documents are saved in a folder in the main project folder named ``content``. Each
document has a file handle taken from the first 13 characters of a SHA256 hash of the system time 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 filename assembled from this hash when the document was first created. The documents are saved with a filename assembled from this
and the file extension ``.nwd``. hash and the file extension ``.nwd``.
If you wish to find the physical location of a file in the project, you can either look it up in the If you wish to find the physical location of a document in the project, you can either look it up
project XML file, select :guilabel:`Show File Details` from the :guilabel:`Document` menu when in the project XML file, select :guilabel:`Show File Details` from the :guilabel:`Document` menu
having the document open, or look in the ``ToC.txt`` file in the root of the project folder. when having the document open, or look in the ``ToC.txt`` file in the root of the project folder.
The ``ToC.txt`` file has a list of all document files in the project and where they are saved. The ``ToC.txt`` file has a list of all document files in the project and where they are saved.
The reason for this cryptic file naming is to avoid issues with file naming conventions and 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 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 what the user names the document within the project, or changes it to. The file meta data in the
file label, is only saved in the project XML file. project tree is mainly saved in the project XML file, although some basic meta data is added to the
header of each document file.
Each document file contains a plain text version of the text from the editor. The file can in 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 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 desired. Just make sure the file remains in utf-8 encoding, otherwise unicode chatracters may
mangled when the file is opened in novelWriter again. become mangled when the file is opened in novelWriter again.
The first line of the file contains some meta data starting with the characters ``%%~``. This line The first lines of the file may contain some meta data starting with the characters ``%%~``. These
is mainly there to restore some information if it is lost from the project file, and the information lines are mainly there to restore some information if it is lost from the project file, and the
may be helpful if you do open the file in an external editor as it contains the file label as the information may be helpful if you do open the file in an external editor as it contains the
last entry. The line can be deleted without any consequences to the rest of the content of the file, document label and the document class and layout. The lines can be deleted without any consequences
and will be added back the next time the file is saved in novelWriter. to the rest of the content of the file, and will be added back the next time the document is saved
in novelWriter.
The File Saving Process The File Saving Process
@@ -75,8 +77,9 @@ The File Saving Process
When saving the project file, or any of the documents, the data is first saved to a temporary file. 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 removed, and the temporary file becomes the new file. This If successful, the old data file is removed, 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 ensures that the previously saved data is only replaced when the new data has been successfully
saved. saved to the storage medium.
For the project XML file, a ``.bak`` file is kept which will always contain the previous version of For the project XML file, a ``.bak`` file is in addition kept, which will always contain the
the file, although when auto-save is enabled, they may have the same content. If the opening of a previous version of the file, although when auto-save is enabled, they may have the same content.
project file fails, novelWriter will automatically try to open the ``.bak`` file instead. If the opening of a project file fails, novelWriter will automatically try to open the ``.bak``
file instead.
docs/source/write_export.rst
+30 -27
View File
@@ -23,12 +23,13 @@ a series of keyword–replace steps. They are all on the format ``%keyword%``.
``%ch%`` ``%ch%``
This is replaced by a chapter number. The number is incremented by one each time the build tool This is replaced by a chapter number. The number is incremented by one each time the build tool
sees a new heading of level two in a file with layout :guilabel:`Chapter`. If the file has layout sees a new heading of level two in a document with layout :guilabel:`Chapter`. If the document
:guilabel:`Unnumbered`, the counter is *not* incremented. The latter is useful for for instance has layout :guilabel:`Unnumbered`, the counter is *not* incremented. The latter is useful for
Prologue and Epilogue chapters. for instance Prologue and Epilogue chapters.
``%chw%`` ``%chw%``
This is like ``%ch%``, but the number is expressed as a word like for instance "One", "Two", etc. This is like ``%ch%``, but the number is expressed as a word like for instance "One", "Two",
etc.
``%chi%`` ``%chi%``
This is also like ``%ch%``, but the number is represented as a lower case Roman number. This is also like ``%ch%``, but the number is represented as a lower case Roman number.
@@ -49,13 +50,13 @@ a series of keyword–replace steps. They are all on the format ``%keyword%``.
This inserts a line break within the title. This inserts a line break within the title.
.. note:: .. note::
Header formatting only applies to novel files. Headings in note files will will be left as-is on Header formatting only applies to novel documents. Headings in notes will be left as-is on
export. However, heading levels 1 through 4 are converted to the correct heading level in the export. However, heading levels 1 through 4 are converted to the correct heading level in the
respective output formats. respective output formats.
**Example** **Example**
* The format ``%title%`` just reproduces the title you set in the document file. * The format ``%title%`` just reproduces the title you set in the document.
* The format ``Chapter %ch%: %title%`` produces something like "Chapter 1: My Chapter Title". * The format ``Chapter %ch%: %title%`` produces something like "Chapter 1: My Chapter Title".
* The format ``Scene %ch%.%sc%`` produces something like "Scene 1.2" for scene 2 in chapter 1. * The format ``Scene %ch%.%sc%`` produces something like "Scene 1.2" for scene 2 in chapter 1.
@@ -65,8 +66,8 @@ a series of keyword–replace steps. They are all on the format ``%keyword%``.
Scene Separators Scene Separators
================ ================
If you don't want any titles for your scenes (and for your sections if you have them), you can leave If you don't want any titles for your scenes (or 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. the boxes empty. If so, 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 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 that in the box. In fact, if the format is a piece of static text, it will always be treated as a
@@ -78,10 +79,11 @@ separator.
File Selection File Selection
============== ==============
Which files are selected for export can also be controlled from the options on the left side of the Which documents and notes are selected for export can be controlled from the options on the left
dialog window. The switch for :guilabel:`Include novel files` will select any file that isn't side of the dialog window. The switch for :guilabel:`Include novel files` will select any document
classified as a note. The switch for :guilabel:`Include note files` will select any file that *is* that isn't classified as a note. The switch for :guilabel:`Include note files` will select any
a note. This is allows for exporting just the novel, just your notes, or both, as you see fit. document 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 In addition, you can select to export the synopsis comments, regular comments, keywords, and even
exclude the body text itself. exclude the body text itself.
@@ -91,11 +93,12 @@ exclude the body text itself.
keywords and synopsis export and disable body text, thus getting a document with each heading keywords and synopsis export and disable body text, thus getting a document with each heading
followed by the tags and references and the synopsis. followed by the tags and references and the synopsis.
If you need to exclude specific files from your exports, like draft files or files you want to take If you need to exclude specific documents from your exports, like draft documents or documents you
out of your manuscript, but don't want to delete, you can un-check the :guilabel:`Include when want to take out of your manuscript, but don't want to delete, you can un-check the
building project` option for each file in the project tree. An included file has a checkmark after :guilabel:`Include when building project` option for each document in the project tree. An included
the status icon in the :guilabel:`Flags` column. The :guilabel:`Build Novel Project` tool has a document has a checkmark after the status icon in the :guilabel:`Flags` column. The
switch to ignore this flag if you need to collectively override these settings. :guilabel:`Build Novel Project` tool has a switch to ignore this flag if you need to collectively
override these settings.
.. _a_export_formats: .. _a_export_formats:
@@ -107,26 +110,26 @@ Currently, six formats are supported for exporting.
OpenDocument Format OpenDocument Format
This produces an open document ``.odt`` file. The document produced has very little formatting, This 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 and may require further editing afterwards. For a better formatted office document, you may get
better result with exporting to HTML and the import that HTML document into your office word a better result with exporting to HTML and then import that HTML document into your office word
processor. They are generally very good at importing HTML files. processor. They are generally very good at importing HTML documents.
PDF Format PDF Format
The PDF export is just a shortcut for print to file. For a better PDF result, you may instead The PDF export is just a shortcut for print to file. For a better PDF result, you may instead
want to export HTML, and use a word processor to convert the HTML document to PDF. want to export to HTML, and use a word processor to convert the HTML document to PDF.
novelWriter HTML novelWriter HTML
The HTML export format writes a single ``.htm`` file with minimal style formatting. The exported 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 HTML document is suitable for further processing by document conversion tools like Pandoc, for
importing in word processors, or for printing from browser. It is generally the best formatted importing in word processors, or for printing from browser. It is generally the best formatted
export option and supports all features of novelWriter since it is entirely geenrated by the export option and supports all features of novelWriter since it is entirely geenrated by the
application and doesn't depend on Qt library features. application and doesn't depend on Qt library features.
novelWriter Markdown novelWriter Markdown
This is simply a concatenation of the files selected by the filters. The files in the project are This is simply a concatenation of the project documents selected by the filters. The documents
stacked together in the order they appear in the tree view, with comments, tags, etc. included if are stacked together in the order they appear in the project tree, with comments, tags, etc.
they are selected. This is a useful format for exporting the project for later import back into included if they are selected. This is a useful format for exporting the project for later
novelWriter. import back into novelWriter.
Standard Markdown Standard Markdown
If you have Qt 5.14 or higher, the option to export to plain markdown is available. This feature If you have Qt 5.14 or higher, the option to export to plain markdown is available. This feature
@@ -142,7 +145,7 @@ Additional Export Options
========================= =========================
In addition to the above document formats, the novelWriter HTML and Markdown formats can also be In addition to the above document formats, the novelWriter HTML and Markdown formats can also be
wrapped in a JSON file. The files will have a meta data entry and a body entry. For HTML, also the wrapped in a JSON file. These files will have a meta data entry and a body entry. For HTML, also
accompanying css styles are exported. accompanying css styles are exported.
The text body is saved in a two-level list. The outer list contains one entry per exported file, in The text body is saved in a two-level list. The outer list contains one entry per exported file, in
docs/source/write_notes.rst
+24 -21
View File
@@ -1,18 +1,19 @@
.. _a_notes: .. _a_notes:
************************ *************
Supporting Files (Notes) Project Notes
************************ *************
novelWriter doesn't have a database and compicated forms to fill in all details about plot elements, novelWriter doesn't have a database and complicated forms to fill in all details about plot
characters, and all sorts of additional information that isn't a part of the novel text itself. elements, characters, and all sorts of additional information that isn't a part of the novel text
Instead, all such information is saved in notes. The relation between all these additional elements itself. Instead, all such information is saved in notes. The relation between all these additional
is extracted from these files by the project indexer based on the tags and references you set. elements is extracted from these documents by the project indexer based on the tags and references
you set.
These files are not required, but making at least minimal files for each such plot element, and add These notes are not required, but making at least minimal files for each such plot element, and
a tag to them, makes it possible to use the :guilabel:`Outline` feature to see how each element adding a tag to them, makes it possible to use the :guilabel:`Outline` feature to see how each
intersects with each section of the novel itself, and add clickable cross-references between element intersects with each section of the novel itself, and adds clickable cross-references
documents in the editor and viewer. between documents in the editor and viewer.
.. _a_notes_tags: .. _a_notes_tags:
@@ -20,9 +21,9 @@ documents in the editor and viewer.
Tags in Notes Tags in Notes
============= =============
Each new heading in a note file can have a tag associated with it. The format of a tag is Each new heading in a note can have a tag associated with it. The format of a tag is
``@tag: tagname``, where tagname is a unique identifier. Tags can then be referenced in the novel ``@tag: tagname``, where tagname is a unique identifier. Tags can then be referenced in the novel
files, or cross-referenced in other note files, and will show up in the outline view and in the documents, or cross-referenced in other notes, and will show up in the outline view and in the
back-reference panel when a document is being viewed. back-reference panel when a document is being viewed.
The syntax highlighter will alert the user that the keyword is correctly used and that the tag is The syntax highlighter will alert the user that the keyword is correctly used and that the tag is
@@ -30,15 +31,17 @@ allowed, that is, the tag is unique. Duplicate tags should be detected as long a
to date. An invalid tag should have a green wiggly line under it, and will not receive the syntax to date. An invalid tag should have a green wiggly line under it, and will not receive the syntax
colour that valid tags do. colour that valid tags do.
The tag is the only part of these files that the application uses. The rest of the file content is The tag is the only part of these notes that the application uses. The rest of the document content
there for the writer to use in whatever way they wish. Of course, the content of the files can be is there for the writer to use in whatever way they wish. Of course, the content of the documents
exported if you want to compile a single document of all your notes, or include them in an outline. can be exported if you want to compile a single document of all your notes, or include them in an
outline.
A note file can also reference other note files in the same way novel files do. When the note file A note can also reference other notes in the same way novel documents do. When the note is opened
is opened in the view panel, these become clickable links, making it easier to follow connections in in the view panel, the references become clickable links, making it easier to follow connections in
the plot. Note files don't show up in the outline view though, so referencing between notes is only the plot. Notes don't show up in the outline view though, so referencing between notes is only
meaningful if you want to be able to click-navigate between them. meaningful if you want to be able to click-navigate between them.
.. tip:: .. tip::
If you cross-reference between notes as well, and export your project as an HTML file using the If you cross-reference between notes and export your project as an HTML document using the
export tool, the cross-references become clickable in the exported document. :guilabel:`Build Novel Project` tool, the cross-references become clickable in the exported
HTML document as well.
docs/source/write_projects.rst
+92 -81
View File
@@ -8,9 +8,11 @@ A novelWriter project requires a dedicated folder for storing its files on the l
See the :ref:`a_tech` page for further details on how files are organised. See the :ref:`a_tech` page for further details on how files are organised.
A new project can be created from the :guilabel:`Project` menu by selecting A new project can be created from the :guilabel:`Project` menu by selecting
:guilabel:`New Project`. A list of recently opened projects is maintained, and displayed in the :guilabel:`New Project`. This will open the :guilabel:`New Project Wizard` that will assist you in
:guilabel:`Open Project` dialog. A project can be removed from this list by selecting it and creating a barebone project suited to your needs.
pressing the :kbd:`Del` key.
A list of recently opened projects is maintained, and displayed in the :guilabel:`Open Project`
dialog. A project can be removed from this list by selecting it and pressing the :kbd:`Del` key.
The project specific settings are available in :guilabel:`Project Settings` in the The project specific settings are available in :guilabel:`Project Settings` in the
:guilabel:`Project` menu. See further details below in the :ref:`a_proj_settings` section. :guilabel:`Project` menu. See further details below in the :ref:`a_proj_settings` section.
@@ -24,28 +26,28 @@ Project Roots
Projects are structured into a set of top level folders called *root folders*. They are visible in Projects are structured into a set of top level folders called *root folders*. They are visible in
the project tree at the left side of the main window. the project tree at the left side of the main window.
The core novel files go into a root folder of type :guilabel:`Novel`. Other supporting files go The core novel documents go into a root folder of type :guilabel:`Novel`. Other supporting
into the other root folders. These other root folder types are intended for your notes on the documents go into the other root folders. These other root folder types are intended for your notes
various elements of your story. Using these is of course entirely optional. 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 A new project may not have all of the root folders present, but you can add the ones you want from
:guilabel:`Create Root Folder` in the :guilabel:`Project` menu. :guilabel:`Create Root Folder` in the :guilabel:`Project` menu.
The root folders are intended for the following use, but aside from the :guilabel:`Novel` folder, The root folders are intended for the following use, but aside from the :guilabel:`Novel` folder,
no restrictions are enforced by the application. You can use them however you want. no restrictions are enforced by the application. You can use them however you want.
:guilabel:`Novel` :guilabel:`Novel`
This is the root folder of all text that goes into the final novel. This class of files have This is the root folder of all text that goes into the final novel. This class of documents have
other rules and features than other files in the project. See the :ref:`a_struct` page for more other rules and features than other documents in the project. See the :ref:`a_struct` page for
details. more details.
:guilabel:`Plot` :guilabel:`Plot`
This is the root folder where main plots can be outlined. It is optional, but adding at least 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. Tags in this dummy notes can be useful in order to tag plot elements for the Outline view. Tags in this
folder can be references using the ``@plot`` keyword. folder can be references using the ``@plot`` keyword.
:guilabel:`Characters` :guilabel:`Characters`
Character files go in this root folder. These are especially important if one wants to use the Character notes go in this root folder. These are especially important if one wants to use the
Outline view to see which character appears where, and which part of the story is told from a Outline view to see which character appears where, and which part of the story is told from a
specific character's point-of-view. Tags in this folder can be references using the ``@pov`` specific character's point-of-view. Tags in this folder can be references using the ``@pov``
keyword for point-of-view characters, or the ``@char`` keyword for other characters. keyword for point-of-view characters, or the ``@char`` keyword for other characters.
@@ -56,7 +58,7 @@ no restrictions are enforced by the application. You can use them however you wa
:guilabel:`Timeline` :guilabel:`Timeline`
If the story has multiple plot timelines or jumps in time within the same plot, this class of If the story has multiple plot timelines or jumps in time within the same plot, this class of
files can be used to track this. Tags in this folder can be references using the ``@time`` notes can be used to track this. Tags in this folder can be references using the ``@time``
keyword. keyword.
:guilabel:`Objects` :guilabel:`Objects`
@@ -65,8 +67,8 @@ no restrictions are enforced by the application. You can use them however you wa
:guilabel:`Entities` :guilabel:`Entities`
Does your plot have many powerful organisations or companies? Or other entities that are part of Does your plot have many powerful organisations or companies? Or other entities that are part of
the plot? They can be organised here. Tags in this folder can be references using the ``@entity`` the plot? They can be organised here. Tags in this folder can be references using the
keyword. ``@entity`` keyword.
:guilabel:`Custom` :guilabel:`Custom`
The custom root folder can be used for tracking anything else not covered by the above options. The custom root folder can be used for tracking anything else not covered by the above options.
@@ -86,13 +88,14 @@ information about the tags listed, see :ref:`a_struct_tags`.
Deleted Documents Deleted Documents
----------------- -----------------
Deleted document files will be moved into a special :guilabel:`Trash` root folder. Files in the Deleted documents will be moved into a special :guilabel:`Trash` root folder. Documents in the
trash folder can then be deleted permanently, either individually, or by emptying the trash from trash folder can then be deleted permanently, either individually, or by emptying the trash from
the menu. Files in this folder are removed from the project index and cannot be referenced. the menu. Documents in the trash folder are removed from the project index and cannot be
referenced.
Folders and root folders can only be deleted when they are empty. Recursive deletion is not Folders and root folders can only be deleted when they are empty. Recursive deletion is not
supported. A document file or a folder can be deleted from the :guilabel:`project` menu, or by supported. A document or a folder can be deleted from the :guilabel:`Project` menu, or by pressing
pressing :kbd:`Ctrl`:kbd:`Del`. :kbd:`Ctrl`:kbd:`Del`.
.. _a_proj_roots_out: .. _a_proj_roots_out:
@@ -100,15 +103,15 @@ pressing :kbd:`Ctrl`:kbd:`Del`.
Archived Documents (Outtakes) Archived Documents (Outtakes)
----------------------------- -----------------------------
If you don't want to delete a file, or put it in the :guilabel:`Trash` folder where it may be If you don't want to delete a document, or put it in the :guilabel:`Trash` folder where it may be
deleted, but still want it out of your main project tree, you can create an :guilabel:`Outtakes` deleted, but still want it out of your main project tree, you can create an :guilabel:`Outtakes`
root folder from the :guilabel:`Project` menu. You are not allowed to move folders to this root root folder from the :guilabel:`Project` menu. You are not allowed to move folders to this root
folder, only files. If you need folders in it to organise your files, you can of course create new folder, only documents. If you need folders in it to organise your documents, you can of course
ones there. create new ones there.
You can drag any file to this folder and preserve its settings. The file will always be excluded You can drag any document to this folder and preserve its settings. The document will always be
from the :guilabel:`Build Novel Project` builds. The file is also removed from the project index, excluded from the :guilabel:`Build Novel Project` builds. It is also removed from the project
so the tags and references defined in it will not show up anywhere else. index, so the tags and references defined in it will not show up anywhere else.
.. _a_proj_roots_orph: .. _a_proj_roots_orph:
@@ -121,16 +124,17 @@ file synchronisation tool that runs out of sync, there may be files in the proje
aren't tracked in the core project file. These files, when discovered, are recovered and added back aren't tracked in the core project file. These files, when discovered, are recovered and added back
into the project if possible. into the project if possible.
The discovered files are scanned for meta information that gives clues as to where the file may The discovered files are scanned for meta information that gives clues as to where the document may
previously have been located in the project. The project loading routines will try to put them back previously have been located in the project. The project loading routines will try to put them back
as close as possible to this location if it still exists. Generally, it will be appended to the end as close as possible to this location, if it still exists. Generally, it will be appended to the
of the folder where it previously was located. If that folder doesn't exist, it will try to add it end of the folder where it previously was located. If that folder doesn't exist, it will try to add
to the correct root folder. If it cannot figure out which root folder is correct, the file will be it to the correct root folder. If it cannot figure out which root folder is correct, the document
added to the :guilabel:`Novel` root folder. will be added to the :guilabel:`Novel` root folder. Only if the :guilabel:`Novel` folder is
missing will it give up.
If the title of the file can be recovered, the word "Recovered:" will be added as a prefix. If the If the title of the document can be recovered, the word "Recovered:" will be added as a prefix. If
title cannot be determined, the file will be named "Recovered File N" where N is a sequential the title cannot be determined, the document will be named "Recovered File N" where N is a
number. sequential number.
.. _a_proj_roots_lock: .. _a_proj_roots_lock:
@@ -138,11 +142,11 @@ number.
Project Lockfile Project Lockfile
---------------- ----------------
To prevent orphaned files caused by file conflicts when novelWriter projects are synced with file To prevent lost documents 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 synchronisation tools, a project lockfile is written to the project folder. If you try to open a
project which has such a file present, you will be presented with a warning, and some information project which has such a file present, you will be presented with a warning, and some information
about where else novelWriter thinks the project is also open. You will be give the option to ignore about where else novelWriter thinks the project is also open. You will be give the option to ignore
this warning, and continue opening the project. this warning, and continue opening the project at your own risk.
.. note:: .. note::
If, for some reason, novelWriter crashes, the lock file may remain even if there are no other If, for some reason, novelWriter crashes, the lock file may remain even if there are no other
@@ -152,7 +156,8 @@ this warning, and continue opening the project.
.. warning:: .. warning::
If you choose to ignore the warning and continue opening the project, and multiple instances of If you choose to ignore the warning and continue opening the project, and multiple instances of
the project are in fact open, you are likely to cause inconsistencies and create diverging the project are in fact open, you are likely to cause inconsistencies and create diverging
project files, potentially resulting in loss of data and orphaned files. project files, potentially resulting in loss of data and orphaned files. You are not likely to
lose any actual text unless both instances have the same document open in the editor,
.. _a_proj_roots_dirs: .. _a_proj_roots_dirs:
@@ -161,35 +166,38 @@ Using Folders in the Project Tree
--------------------------------- ---------------------------------
Folders, aside from root folders, have no structural significance to the project. When novelWriter Folders, aside from root folders, have no structural significance to the project. When novelWriter
is processing the files in the novel, like for instance during export, these folders are ignored. is processing the documents in the novel, like for instance during export, these folders are
Only the order of the document files themselves matter. ignored. Only the order of the documents themselves matter.
The folders are there purely as a way for the user to organise the files in meaningful sections and The folders are there purely as a way for the user to organise the documents in meaningful sections
to be able to collapse and hide them in the project tree when you're not working on those files. and to be able to collapse and hide them in the project tree when you're not working on those
documents.
.. tip:: .. tip::
You can use folders to sort your scene files into chapters. You will then need to add a chapter You can use folders to sort your scene documents into chapters. You will then need to add a
file as the first file of your folder, and the scene files as the following files. chapter documents as the first item of your folder, and the scene documents as the following
items.
.. _a_proj_files: .. _a_proj_files:
Project Files Project Documents
============= =================
New document files can be created from the :guilabel:`Document` menu, or by pressing New documents can be created from the :guilabel:`Document` menu, or by pressing :kbd:`Ctrl`:kbd:`N`
:kbd:`Ctrl`:kbd:`N` while in the Project Tree. This will create a new, empty file, and open the while in the project tree. This will create a new, empty document, and open the :guilabel:`Item
:guilabel:`:Item Settings` dialog where the filename and various other settings can be changed. Settings` dialog where the document label and various other settings can be changed. This dialog
This dialog can also be opened again later from either the :guilabel:`Project` menu, selecting can also be opened again later from either the :guilabel:`Project` menu, selecting :guilabel:`Edit
:guilabel:`Edit Item`, or by pressing :kbd:`Ctrl`:kbd:`E` or :kbd:`F2` with the item selected. Project Item`, or by pressing :kbd:`Ctrl`:kbd:`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 The layout of the document is also defined here. For Novel documents, the full list of layout
available. For non-Novel files, only "Note" is available. See :ref:`a_struct_layout` for more options are available. For non-Novel documents, only :guilabel:`Note` is available. See
details. :ref:`a_struct_layout` for more details.
You can also select whether the file is by default included when building the project. This setting You can also select whether the document is by default included when building the project. This
can be overridden in the :guilabel:`Build Novel Project` tool if you wish to include them anyway. setting can be overridden in the :guilabel:`Build Novel Project` tool if you wish to include them
This is covered in the :ref:`a_export_files` section. anyway. This is covered in the :ref:`a_export_files` section. You can also toggle the included
state of a document from the right-click context menu.
.. _a_proj_files_counts: .. _a_proj_files_counts:
@@ -197,12 +205,12 @@ This is covered in the :ref:`a_export_files` section.
Word Counts Word Counts
----------- -----------
A character, word and paragraph count is maintained for each file, as well as dor each section of a A character, word and paragraph count is maintained for each document, as well as for each section
file defined by a header. The word count, and change of words in the current session, is displayed of a document following a header. The word count, and change of words in the current session, is
in the footer of any document open in the editor, and all stats are shown in the details panel displayed in the footer of any document open in the editor, and all stats are shown in the details
below the project tree for any file selected. panel below the project tree for any document selected in the project tree.
The word counts are not updated in real time, but runs in the background every five seconds for as The word counts are not updated in real time, but run in the background every five seconds for as
long as the document is being actively edited. long as the document is being actively edited.
A total project word count is displayed in the status bar. The total count depends on the sum of A total project word count is displayed in the status bar. The total count depends on the sum of
@@ -228,39 +236,38 @@ The :guilabel:`Settings` tab holds the project title and author settings.
The :guilabel:`Working Title` can be set to a different title than the :guilabel:`Book Title`. The The :guilabel:`Working Title` can be set to a different title than the :guilabel:`Book Title`. The
difference between them is simply that the :guilabel:`Working Title` is used for the GUI (main difference between them is simply that the :guilabel:`Working Title` is used for the GUI (main
window title) and for generating the backup files. The intention is that the :guilabel:`Working window title) and for generating the backup files. The intention is that the :guilabel:`Working
Title` should remain unchanged throughput the project, otherwise the name of exported files and Title` should remain unchanged throughout the project, otherwise the name of exported files and
backup files may change too. backup files may change too.
The :guilabel:`Book Title` and :guilabel:`Book Authors` settings are currently not used for The :guilabel:`Book Title` and :guilabel:`Book Authors` settings are currently not used for
anything, so setting then is just for the benefit of the author. Future, planned features will be anything, so setting then is just for the benefit of the author. Future features may be using them,
using them, and they are exported on some export formats in the :guilabel:`Build Novel Project` and they are exported on some export formats in the :guilabel:`Build Novel Project` tool.
tool.
Details Tab Details Tab
----------- -----------
This tab presents an overview of meta data for the project. It states where on your file system the This tab presents an overview of meta data for the project. It states where on your file system the
project is saved, how may times it has been saved, how many folders and files it contains, and how project is saved, how may times it has been saved, how many folders and documents it contains, and
many words exist in the entire project. how many words exist in the entire project.
Status and Importance Tabs Status and Importance Tabs
-------------------------- --------------------------
Each file of type "Novel" can be given a status level, signified by a coloured icon and each file Each document or folder of type :guilabel:`Novel` can be given a status level, signified by a
of the remaining types can be given an importance level. These are colour coded icons and labels coloured icon, and each document or folder of the remaining types can be given an importance level.
that can be applied to each file. These are colour coded icons and labels that can be applied to each document or folder.
These are purely there for the user's convenience, and you are not required to use them for any These are purely there for the user's convenience, and you are not required to use them for any
other feature to work. No other part of novelWriter accesses this information. The intention is to other features to work. No other part of novelWriter accesses this information. The intention is to
use these to indicate at what stage of completeion each novel file is, or how important the content use these to indicate at what stage of completion each novel document is, or how important the
of a note file is to the plot. You don't have to use them this way, that's just what they were content of a note is to the plot. You don't have to use them this way, that's just what they were
intended for, but you can make them whatever you want. intended for, but you can make them whatever you want.
.. note:: .. note::
The status or importance level currently in use by one or more files cannot be deleted, but they The status or importance level currently in use by one or more documents cannot be deleted, but
can be edited. they can be edited.
Auto-Replace Tab Auto-Replace Tab
@@ -270,10 +277,13 @@ A set of automatically replaced keywords can be added in this tab. The keywords
will be replaced by the text in the right column when documents are opened in the viewer. They will will be replaced by the text in the right column when documents are opened in the viewer. They will
also be applied to exports. also be applied to exports.
The auto-replace feature will replace text in angle brackets that are also in this list. The syntax
highlighter will add an alternate colour to text marching the syntax.
.. note:: .. note::
A keyword cannot contain any spaces. The angle brackets are added by default, and when used in 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 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. aren't unintentionally replaced by the content of the list.
.. _a_proj_backup: .. _a_proj_backup:
@@ -282,7 +292,7 @@ Backup
====== ======
An automatic backup system is built into novelWriter. In order to use it, a backup path to where An automatic backup system is built into novelWriter. In order to use it, a backup path to where
the backup files are to be stored must to be provided in :guilabel:`Preferences`. the backup files are to be stored must be provided in :guilabel:`Preferences`.
Backups can be run automatically when a project is closed, which also implies it is run when the 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 application is closed. Backups are date stamped zip files of the entire project folder, and are
@@ -290,7 +300,7 @@ stored in a subfolder of the backup path with the same name as the project :guil
Title` set in :ref:`a_proj_settings`. Title` set in :ref:`a_proj_settings`.
The backup feature, when configured, can also be run manually from the :guilabel:`Tools` menu. The backup feature, when configured, can also be run manually from the :guilabel:`Tools` menu.
It is also possible to dissable automated backup for a given project in :guilabel:`Project It is also possible to disable automated backup for a given project in :guilabel:`Project
Settings`. Settings`.
.. note:: .. note::
@@ -298,17 +308,18 @@ Settings`.
:guilabel:`Project Settings`. This value is used to generate the folder name for the zip files. :guilabel:`Project Settings`. This value is used to generate the folder name for the zip files.
Without it, the backup will not run at all, but produce a warning message. Without it, the backup will not run at all, but produce a warning message.
.. _a_proj_stats: .. _a_proj_stats:
Writing Statistics Writing Statistics
================== ==================
When you work on your project, a log file records when you opened it, when you closed it, and how When you work on a project, a log file records when you opened it, when you closed it, and the
many words you added to your novel and note files during the session. You can view this file in the total word counts of your novel documents and notes at the end of the session. You can view this
``meta`` folder in the directory where you saved your project. The file is named file in the ``meta`` folder in the directory where you saved your project. The file is named
``sessionStats.log``. ``sessionStats.log``.
A small tool to view the content of this file is available in the :guilabel:`Tools` menu under A tool to view the content of this file is available in the :guilabel:`Tools` menu under
:guilabel:`Writing Statistics`. You can also launch it by pressing :kbd:`F6`. :guilabel:`Writing Statistics`. You can also launch it by pressing :kbd:`F6`.
The tool will show a list of all your sessions, and a set of filters to apply to it. You can also The tool will show a list of all your sessions, and a set of filters to apply to it. You can also
docs/source/write_structure.rst
+85 -77
View File
@@ -6,8 +6,8 @@ Novel Structure
This section covers the structure of a novel project. This section covers the structure of a novel project.
This section concerns files under the Novel type root folder only. There are some restrictions It concerns documents under the :guilabel:`Novel` type root folder only. There are some
and features that only applies to these type of files. restrictions and features that only apply to these types of documents.
.. _a_struct_heads: .. _a_struct_heads:
@@ -16,7 +16,7 @@ Importance of Headings
====================== ======================
Subfolders under root folders have no impact on the structure of the novel itself. The structure is Subfolders under root folders have no impact on the structure of the novel itself. The structure is
instead dictated by the heading level of the headers within the document files. instead dictated by the heading level of the headers within the documents.
Four levels of headings are supported, signified by the number of hashes preceding the title. See Four levels of headings are supported, signified by the number of hashes preceding the title. See
also the :ref:`a_ui_md` section for more details about the markdown syntax. also the :ref:`a_ui_md` section for more details about the markdown syntax.
@@ -31,29 +31,31 @@ way:
``# Header1`` ``# Header1``
Header level one signifies that the text refers to either the novel title or the name of a top Header level one signifies that the text refers to either the novel title or the name of a top
level partition when you want to split the manuscript up into books, parts, or acts. level partition useful when you want to split the manuscript up into books, parts, or acts.
``## Header2`` ``## Header2``
Header level two signifies a chapter level partition. Each time you want to start a new chapter, Header level two signifies a chapter level partition. Each time you want to start a new chapter,
you must add such a heading. If you choose to split your manuscript up into one file per scene, you must add such a heading. If you choose to split your manuscript up into one document per
you need a single chapeter file with just the heading. You can of course also add a synopsis and scene, you need a single chapter document with just the heading. You can of course also add a
reference keywords to the chapter file. If you want to open the chaper with a quote, this is synopsis and reference keywords to the chapter document. If you want to open the chapter with a
also where you'd put the text for that. quote or other introductory text that isn't part of a scene, this is also where you'd put that
text.
``### Header3`` ``### Header3``
Header level three signifies a scene level partition. The title itself can be replaced with a Header level three signifies a scene level partition. You must provide a title text, but the
scene separator or just skipped entirely when you export your manuscript. title text can be replaced with a scene separator or just skipped entirely when you export your
manuscript.
``#### Header4`` ``#### Header4``
Header level four signifies a sub-scene level partition, usually called just a section in the Header level four signifies a sub-scene level partition, usually called just a section in the
documentation und user interface. These can be useful if you want to change tag references documentation and user interface. These can be useful if you want to change tag references
mid-scene, like if you change the point-of-view character. You are free to use sections as you mid-scene, like if you change the point-of-view character. You are free to use sections as you
wish also in novel files, and can filter the titles out of the final manuscript just like with wish, and can filter the titles out of the final manuscript just like with scene titles.
scene titles.
There are multiple options of how to process novel titles when exporting the manuscript. For .. tip::
instance, chapter numbers can be applied automatically, and so can scene numbers if you want them in There are multiple options of how to process novel titles when exporting the manuscript. For
a draft manuscript. See the :ref:`a_export` page for more details. instance, chapter numbers can be applied automatically, and so can scene numbers if you want
them in a draft manuscript. See the :ref:`a_export` page for more details.
.. _a_struct_heads_unnum: .. _a_struct_heads_unnum:
@@ -61,11 +63,11 @@ a draft manuscript. See the :ref:`a_export` page for more details.
Unnumbered Chapter Headings Unnumbered Chapter Headings
--------------------------- ---------------------------
If you use file layout types for your files, the automatic numbering feature for your chapters is If you use layout types for your documents, the automatic numbering feature for your chapters is
controlled by whether you use the :guilabel:`Chapter` or :guilabel:`Unnumbered` layout type for your controlled by whether you use the :guilabel:`Chapter` or :guilabel:`Unnumbered` layout type for
file. However, if you have a different file layout where this isn't practical, you can also switch your document. However, if you have a different document layout where this isn't practical, you can
off chapter numbering for a chapter by making the first charcater of the chapter title an ``*``. also switch off chapter numbering for a chapter by making the first character of the chapter title
Like so: an ``*``. Like so:
``## *Unnumbered Chapter Title`` ``## *Unnumbered Chapter Title``
@@ -74,7 +76,8 @@ removed before inserted at the location of the ``%title%`` label. See the :ref:`
more details. more details.
.. note:: .. note::
If you need the first character of the title to be an actual asterisk, you must escape it: ``\*``. If you need the first character of the title to be an actual asterisk, you must escape it:
``\*``.
.. _a_struct_tags: .. _a_struct_tags:
@@ -82,12 +85,13 @@ more details.
Tag References Tag References
============== ==============
Each text section indicated by a heading of any level, can contain references to tags set in the Each text partition indicated by a heading of any level, 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 supporting notes of the project. The references are gathered by the indexer and used to generate
outline view on the :guilabel:`Outline` tab of how the different parts of the novel are connected. the outline view on the :guilabel:`Outline` tab of how the different parts of the novel are
connected.
References and tags are also clickable in the document editor and viewer, making it easy to navigate References and tags are also clickable in the document editor and viewer, making it easy to
between reference notes while writing. Clicked links are always opened in the view panel. navigate between reference notes while writing. Clicked links are always opened in the view panel.
References are set as a keyword and a list of corresponding tags. The valid keywords are listed References are set as a keyword and a list of corresponding tags. The valid keywords are listed
below. The format of a reference line is ``@keyword: value1, [value2] ... [valueN]``. All keywords below. The format of a reference line is ``@keyword: value1, [value2] ... [valueN]``. All keywords
@@ -98,8 +102,8 @@ allow multiple values.
:guilabel:`Character` type root folder. :guilabel:`Character` type root folder.
``@char`` ``@char``
Other characters in the current section. The target must be a note tag in a :guilabel:`Character` Other characters in the current section. The target must be a note tag in a
type root folder. This should not include the point-of-view character(s). :guilabel:`Character` type root folder. This should not include the point-of-view character(s).
``@plot`` ``@plot``
The plot or subplot advanced in the current section. The target must be a note tag in a The plot or subplot advanced in the current section. The target must be a note tag in a
@@ -118,50 +122,50 @@ allow multiple values.
type root folder. type root folder.
``@entity`` ``@entity``
Entities present in the current section. The target must be a note tag in an :guilabel:`Entities` Entities present in the current section. The target must be a note tag in an
type root folder. :guilabel:`Entities` type root folder.
``@custom`` ``@custom``
Custom references in the current section. The target must be a note tag in a :guilabel:`Custom` Custom references in the current section. The target must be a note tag in a :guilabel:`Custom`
type root folder. type root folder.
The syntax highlighter will alert the user that the tags and references are used correctly, and that The syntax highlighter will alert the user that the tags and references are used correctly, and
the tags referenced exist. that the tags referenced exist.
The highlighter may be mistaken if the index of defined tags is out of date. If so, press :kbd:`F9` The highlighter may be mistaken if the index of defined tags is out of date. If so, press :kbd:`F9`
to regenerate it, or select :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu. In general, to regenerate it, or select :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu. In general,
the index for a file is regenerated when a file is saved, so this shouldn't normally be necessary. the index for a document is regenerated when it is saved, so this shouldn't normally be necessary.
.. _a_struct_layout: .. _a_struct_layout:
Novel File Layout Novel Document Layout
================= =====================
All files in a novelWriter project can have a layout format set. These layouts are important when All documents in a novelWriter project can have a layout format set. These layouts are important
the project is exported as they indicate how to treat the content in terms of formatting, headings, when the project is exported as they indicate how to treat the content in terms of formatting,
and page breaks. The layout for each file is indicated as the last set of characters in the headings, and page breaks. The layout for each document is indicated as the last set of characters
:guilabel:`Flags` column of the project tree. in the :guilabel:`Flags` column of the project tree.
Not all layout types are actually treated differently, but they also help to indicate what each file Not all layout types are actually treated differently, they also help to indicate what each
is for in your project. The :guilabel:`Book` layout is a generic novel file layout that is formatted document is for in your project. The :guilabel:`Book` layout is a generic novel document layout
identically to :guilabel:`Chapter` and :guilabel:`Scene` layout files, but may help to indicate what that is formatted identically to :guilabel:`Chapter` and :guilabel:`Scene` layout documents, but
files do in your project. may help to indicate what each document does in your project.
You can for instance lay out your project using :guilabel:`Book` files for each act, and then later You can for instance lay out your project using :guilabel:`Book` documents for each act, and then
split those into chapter or scene files by using the :guilabel:`Split Document` tool. Scenes can later split those into chapter or scene documents by using the :guilabel:`Split Document` tool.
also be contained within :guilabel:`Chapter` type files, but you lose the drag and drop feature that Scenes can also be contained within :guilabel:`Chapter` type documents, but you lose the drag and
comes with having them in separate files if you organise them this way. drop feature that comes with having them in separate documents if you organise them this way.
Some layouts *do* have implications on how the project is exported. Files with layout Some layouts *do* have implications on how the project is exported. Documents with layout
:guilabel:`Title Page` and :guilabel:`Partition` have all headings and text centred, while the :guilabel:`Title Page` and :guilabel:`Partition` have all headings and text centred, while the
:guilabel:`Unnumbered` layout disables the automatic chapter numbering feature for everything :guilabel:`Unnumbered` layout disables the automatic chapter numbering feature for everything
contained within it. The latter is convenient for Prologue and Epilogue type chapters. contained within it. The latter is convenient for Prologue and Epilogue type chapters.
All of the above layout formats are only usable in the Novel root folder. Files that are not a part The above layout formats are only usable in the Novel root folder. Documents that are not a part of
of the novel itself should have the Note layout. These files are not getting any special formatting, the novel itself should have the Note layout. These documents are not getting any special
and it is possible to collectively filter them out during export. Note files can be used anywhere formatting, and it is possible to collectively filter them out during export. Notes can be used
in the project, also in the Novel root folder. anywhere in the project, also in the Novel root folder.
Below is an overview of all available layout formats. Below is an overview of all available layout formats.
@@ -175,45 +179,49 @@ Below is an overview of all available layout formats.
exported with a page break before it. exported with a page break before it.
:guilabel:`Book` :guilabel:`Book`
This is the generic novel file format that in principle can be used for all novel files. Since This is the generic novel format that in principle can be used for all novel documents. Since
the internal structure of the novel is controlled by the heading levels, this file will produce the internal structure of the novel is controlled by the heading levels, this layout will
the same result as a collection of :guilabel:`Partition`, :guilabel:`Chapter` and produce the same result as a collection of :guilabel:`Partition`, :guilabel:`Chapter` and
:guilabel:`Scene` type files. However, it does not provide the functionality of the :guilabel:`Scene` layout documents. However, it does not provide the functionality of the
:guilabel:`Unnumbered` layout format. :guilabel:`Unnumbered` layout format by default, but this can still be achieved by prefixing the
chapter title with a ``*``.
:guilabel:`Partition` :guilabel:`Partition`
A partition can be used to split the novel into parts. Partition titles are indicated with a A partition can be used to split the novel into parts. Partition titles are indicated with a
level one heading. You can also add text and meta data to the page. The :guilabel:`Partition` level one heading. You can also add text and meta data to the page. The :guilabel:`Partition`
file layout will in addition force a page break before the heading, and centre all content on the layout will in addition force a page break before the heading, and centre all content on the
page. page.
:guilabel:`Chapter` :guilabel:`Chapter`
Signifies the start of a new chapter. If the text itself is contained in scene files, these files Signifies the start of a new chapter. If the text itself is contained in scene documents, these
should only contain the title, comments, synopsis, and tag references for characters, plot, etc. documents should only contain the title, comments, synopsis, and tag references for characters,
The heading for chapters should be level two. If you need an opening text, like a quote or other plot, etc. The heading for chapters should be level two. If you need an opening text, like a
leading text before the first scene, this is also where you'd want to add this text. quote or other leading text before the first scene, this is also where you'd want to add this
text.
:guilabel:`Unnumbered` :guilabel:`Unnumbered`
Same as :guilabel:`Chapter`, but when exporting the files and automatic chapter numbering is Same as :guilabel:`Chapter`, but when exporting the documents and automatic chapter numbering is
enabled, this file will not increment the chapeter number. It also has a separate title enabled, documents with this layout will not increment the chapter number. It also has a
formatting setting. This makes the layout suitable for Prologue and Epilogue type chapters. separate title formatting setting. This makes the layout suitable for Prologue and Epilogue type
chapters.
:guilabel:`Scene` :guilabel:`Scene`
A scene file. This file should have a header of level three. Further sections can have headers Used for scenes. This document should have a header of level three. Further sections can have
of level four, but there are no file layout specifically for sections. headers of level four, but there are no layout specifically for sections.
:guilabel:`Note` :guilabel:`Note`
A generic file that is optionally ignored when the novel is exported. Use these files for A generic document that is optionally ignored when the novel is exported. Use this layout for
descriptions of content in the supporting root folders. Note files can also be added to the Novel descriptions of content in the supporting root folders. Notes can also be added to the
root folder if you need to insert notes there. Note file headers receive no special formatting :guilabel:`Novel` root folder if you need to insert notes there. Note headers receive no special
when building the project. They are always exported as-is. formatting when building the project. They are always exported as-is.
.. note:: .. note::
The layout granularity is entirely optional. In principle, you can write the entire novel in a The layout granularity is entirely optional. In principle, you can write the entire novel in a
single file with layout :guilabel:`Book`. You can also have a single file per chapter if that single document with layout :guilabel:`Book`. You can also have a single document per chapter if
suits you better. The :guilabel:`Outline` will show your structure of chapters and scenes that suits you better. The :guilabel:`Outline` will show your structure of chapters and scenes
regardless of how your files are organised. regardless of how your documents are organised.
.. tip:: .. tip::
You can always start writing with a coarse file layout with one or a few files, and then later You can always start writing with a coarse layout with one or a few documents, and then later
use the split tool to automatically split the files into chapter and scene files. use the split tool to automatically split the documents into separate chapter and scene
documents.