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

Merge branch 'main' into dev

Browse Source
This commit is contained in:
Veronica K. B. Olsen
2021-03-13 17:00:07 +01:00
parent 2f790140e0 47ece1f285
commit de57d0b027
16 changed files with 248 additions and 162 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+26 -19
View File
@@ -38,7 +38,7 @@ unit tests are run on the latest versions of Ubuntu Linux, Windows Server and ma
Contributions to this project are welcome. However, please read the
[Contributing Guide](https://github.com/vkbo/novelWriter/blob/main/CONTRIBUTING.md) before
submitting larger additions ot changes to this project.
submitting larger additions or changes to this project.
# Key Features
@@ -48,7 +48,7 @@ Some features of novelWriter are listed below. Consult the
### Markdown Flavour
novelWriter is _not_ a full-feature Markdown editor. It is a plain text editor that uses
Markdown-like syntax for adding a minimal set of formatting that is useful for the specific task
Markdown-like syntax to allow for a minimal set of formatting that is useful for the specific task
of writing novels. The formatting is currently limited to:
* Headings levels 1 to 4 using the `#` syntax only.
@@ -61,9 +61,10 @@ That is it. Features not supported in the editor are also not exported when usin
In addition, novelWriter adds the following, which is otherwise not supported by Markdown:
* A line starting with `%` is treated as a comment and not rendered on exports unless requested.
Comments do not count towards the word count. If the first word of the comment is `synopsis:`,
the comment is indexed and treated as the synopsis for the section of text under the same header.
These synopsis comments can be used to build an outline and exported to external documents.
Comments do not count towards the word count.
* If the first word of the comment is `synopsis:`, the comment is indexed and treated as the
synopsis for the section of text under the same header. These synopsis comments can be used to
build an outline and exported to external documents.
* A set of meta data keyword/values starting with the character `@`. This is used for tagging
and inter-linking documents, and can also be included when generate a project outline.
* A variety of thin and non-breaking spaces are supported. Some of them depend on the system
@@ -71,22 +72,22 @@ In addition, novelWriter adds the following, which is otherwise not supported by
* Tabs can be used in the text, and should be properly aligned in both editor and viewer. This can
be used to make simple tables and lists. Full Markdown tables and lists are not supported. Note
that for HTML exports, most browsers will treat a tab as a space, so it may not show up like
expected. If you import the HTML file to Libre Office, for instance, they should appear as
expected.
expected. Open Document exports should produce the expected result.
The core export format of novelWriter is HTML5. You can also export the entire project as a single
novelWriter Markdown-flavour document. These can later be imported again into novelWriter. In
addition, export to Open Document, PDF, and plain text is offered through the Qt library, although
with limitations to formatting.
The core export formats of novelWriter are Open Document and HTML5. Open Document is an open
standard for office type documents that is supported by most office applications. See
[Open Document > Application Support](https://en.wikipedia.org/wiki/OpenDocument#Application_support)
for more details.
The HTML format is well suited for file conversion tools and import into other text editors.
You can also export the entire project as a single novelWriter Markdown-flavour document. These can
later be imported again into novelWriter. In addition, printing and export to PDF is offered
through the Qt library, although with limitations to formatting.
### Colour Themes
The editor has syntax highlighting for the features it supports, and includes a set of different
syntax highlighting themes. Optional GUI themes are also available, including dark themes.
### Easy Organising of Project Files
The structure of the project is shown on the left hand side of the main window. Project files are
@@ -110,7 +111,6 @@ impact on the format of the exported document. See the
Supporting note files can be added for the story plot, characters, locations, story timeline, etc.
These have their separate root folders. These are optional files.
### Visualisation of Story Elements
The different notes can be assigned tags, which other files can refer back to using the `@` meta
@@ -121,7 +121,8 @@ to quickly navigate between the documents while editing.
# Installing and Running
For install instructions, please check the [Getting Started](https://novelwriter.readthedocs.io/en/latest/int_started.html) section in
For install instructions, please check the
[Getting Started](https://novelwriter.readthedocs.io/en/latest/int_started.html) section in
the [documentation](https://novelwriter.readthedocs.io/).
## TLDR Instructions
@@ -164,6 +165,10 @@ python setup.py xdg-install
This should make novelWriter available as a regular application on your system, with a launceher
icon, and file association with novelWriter project files.
**Note:** If you don't want to install the dependencies from pip and instead use your distro's own
packages, you must manually install `python3-pyqt5`, `python3-lxml` and `python3-enchant`
(Debian/Ubuntu), or the corresponding packages for your distro.
### Setup on macOS
If you're installing from source, the following commands will set up novelWriter on macOS:
@@ -180,15 +185,17 @@ line with:
novelWriter
```
If you want to help improve the setup process on macOS, it would be much appreciated.
### Setup on Windows
For Windows, first ensure that you have Python installed. If not, get it from
[python.org/downloads](https://www.python.org/downloads/). Remember to select "Add Python to PATH"
during the installation, otherwise novelWriter cannot find it.
during the installation, otherwise novelWriter will not start.
Then, download the `novelWriter-x.y.z-minimal.zip` file, where `x.y.z` is the version number, from
the [releases](https://github.com/vkbo/novelWriter/releases) page. You can extract it to wherever
you want to keep novelWriter on your PC, and run the `setup_windows.bat` file in it
Then, download the `novelWriter-x.y.z-minimal-win.zip` file, where `x.y.z` is the version number,
from the [releases](https://github.com/vkbo/novelWriter/releases) page. You can extract it to
wherever you want to keep novelWriter on your PC, and run the `setup_windows.bat` file in it
(double-clicking it should work). This will install the necessary dependencies from
[pypi.org](https://pypi.org/) and create desktop and start menu icons.
docs/source/index.rst
+2 -2
View File
@@ -41,8 +41,8 @@ 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
novelWriter. It runs fine on Linux, Windows and macOS, and users have tested it on other platforms
too. novelWriter can be run directly from the Python source, or installed from the pip tool or via
the provided setup script. A setup.exe is provided for Windows. See :ref:`a_started` for further
details.
the provided setup script. See :ref:`a_started`, or one or the setup instructions for your
operating system for further details.
**Useful Links**
docs/source/int_introduction.rst
+23 -16
View File
@@ -11,10 +11,10 @@ projects are structured is covered in :ref:`a_struct`.
In addition, the project can contain notes on the various plot elements, characters, locations,
etc, that make up the story. These notes are organised in a set of category-specific top-level
folders (root folders), and each entry can be tagged and cross-referenced from within the novel
documents and notes. These tags make it possible to inter-link documents, and generate an overview
of the entire novel project and how the various documents and plot elements are interconnected.
This is covered in :ref:`a_proj` and :ref:`a_notes`.
folders referred to as "root" folders, and each entry can be tagged and cross-referenced from
within the novel documents and notes. These tags make it possible to inter-link documents, and
generate an overview of the entire novel project and how the various documents and plot elements
are interconnected. The tag and reference syntax is covered in :ref:`a_proj` and :ref:`a_notes`.
These additional features are not standard in markdown, but are available through special meta
keywords described in :ref:`a_struct_tags`. Syntax highlighting is provided to make it easier to
@@ -36,31 +36,37 @@ at the same time provide a complete set of features needed for writing a novel.
links, tables, and other complex structures and objects often needed for such documents.
Formatting is limited to headers, and bold, italicised and strikethrough text.
.. tip::
If you do need to align information in rows and columns in your notes, you can achieve this with
tabs and hard line breaks. The tab stop width can be specified in :guilabel:`Preferences` and
hard line breaks can be inserted by adding to spaces at the end of the line.
The main window does not have a toolbar like many other applications do. This reduces clutter, and
since the documents are formatted with markdown tags, is more or less redundant. However, all
formatting features supported are available through convenient keyboard shortcuts. They are also
available in the main menu. A full list of shortcuts can be found in the :ref:`a_ui_shortcuts`
section.
available in the main menu so you don't have to look up the syntax every time until you've
memorised it. A full list of shortcuts can be found in the :ref:`a_ui_shortcuts` section.
In addition, novelWriter offers a :guilabel:`Focus Mode` where all the user interface elements
other than the document editor itself are hidden away.
In addition, novelWriter has a :guilabel:`Focus Mode` where all the user interface 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,
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 icon themes in colour and greyscale are also offered. The icons are based on the Typicons_ icon
set designed by Stephen Hutchings.
other light and dark themes are 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 icon themes in colour and greyscale are also offered. The icons
are based on the Typicons_ icon set designed by Stephen Hutchings.
The main window is split in two, or optionally three, panels. The left-most panel contains the
project tree and all the documents in your project. The second panel is the document editor, and
the optional third panel is a document viewer which can view any document in your project
independently of the document editor.
independently of the document editor. It is not intended as a preview window, although you can use
it for this, but for viewing your notes next to your editor while you're writing.
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
you structure your novel documents, this outline can be quite different from your project tree.
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.
itself in terms of partitions, chapters and scenes as it appears in the text of the documents.
.. _Typicons: https://github.com/stephenhutchings/typicons.font
@@ -96,8 +102,9 @@ The project can at any time be exported to a range of different formats through
:guilabel:`Build Novel Project` tool. Natively, novelWriter supports export to Open Document,
HTML5, and various flavours of Markdown.
The HTML5 export format is suitable for convertion by a number of other tools like Pandoc, or for
importing into word processors. In addition, printing and printing to PDF is also possible.
The HTML5 export format is suitable for conversion by a number of other tools like Pandoc, or for
importing into word processors if the Open Document format isn't suitable. In addition, printing
and printing to PDF is also possible.
It is also possible to export the content of the project to a JSON file. This is useful if you want
to write your own processing script in for instance Python as the entire novel can be read into a
docs/source/int_started.rst
+15 -16
View File
@@ -10,8 +10,8 @@ Getting Started
This section contains brief guides to how you can get novelWriter running on your computer. These
are the methods currently supported by the developer. Packages may also be available in other
package managers, but those are not managed by the developer. A Windows installer file is also
provided on the GitHub_ releases page and linked from the `main website`_.
package managers, but those are not managed by the developer. No installers are provided at this
time, but it is fairly straightforward to set up novelWriter with the provided install scripts.
As novelWriter matures, more options for how to install it and get it running will be added. For
non-Windows users the install process is at the present time best suited for people used to working
@@ -22,10 +22,10 @@ run on. The instructions below are supplementary information, instructions for a
and additional build options.
.. 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. Likewise,
``pip`` may need to be replaced with ``pip3``.
The text below assumes the command ``python`` corresponds to a Python 3 executable. Python 2 is
now deprecated, but many systems still have both Python 2 and 3. For such systems, the command
``python3`` may be needed instead. On Linux, the scripts can also be made executable and run
without the ``python`` command. Likewise, ``pip`` may need to be replaced with ``pip3``.
.. _a_started_depend:
@@ -43,17 +43,16 @@ The following Python packages are needed to run novelWriter:
* ``lxml`` – needed for full XML support.
* ``pyenchant`` – needed for efficient spell checking (optional).
PyQt/Qt should be at least 5.2.1, but ideally 5.10 or higher for nearly all features to work.
Searching using regular expressions requires 5.3, and for full Unicode support, 5.13. There is no
PyQt/Qt should be at least 5.3, but ideally 5.10 or higher for nearly all features to work. For
instance, searching using regular expressions with full Unicode support requires 5.13. There is no
known minimum version requirement for package ``lxml``, but the code was originally written with
4.2, which is therefore set as the minimum. It may work on lower versions. You have to test it.
Optionally, a package can be installed to interface with the Enchant spell checking libaries, but
this isn't strictly required. If no external spell checking library is available, novelWriter falls
back to using the internal ``difflib`` of Python to check spelling. This is a much slower approach,
and it is less sophisticated than full spell checking libaries, but if you only work with small
files, the performance loss is not noticeable. The spell check library must be at least 3.0 to work
with Windows. On Linux, 2.0 also works fine.
back to using the internal ``difflib`` of Python to check spelling. This is a slower and less
sophisticated spell checker than the full spell checking libaries. The spell check library must be
at least 3.0 to work with Windows. On Linux, 2.0 also works fine.
If you install from PyPi, these dependencies should be installed automatically. If you install from
source, dependencies can still be installed from PyPi with:
@@ -77,7 +76,7 @@ and Python 3. It is regularly tested on Linux, Windows and macOS. The latest ver
is |release|.
To install from PyPi you must first have the ``python`` and ``pip`` commands available on your
system. If you don't, see specific instructions for your operating system later in this document.
system. If you don't, see specific instructions for your operating system in this documentation.
To install novelWriter from PyPi, use the following command:
.. code-block:: console
@@ -105,9 +104,9 @@ default.
Building the Documentation
==========================
If you installed novelWriter from a package, the documentation should be included. If you're
running novelWriter from the source code, a local copy of this documentation can be generated. It
requires the following Python packages on Debian and Ubuntu.
If you installed novelWriter from a package, the documentation should be bre-built and included. If
you're running novelWriter from the source code, a local copy of this documentation can be
generated. It requires the following Python packages on Debian and Ubuntu.
* ``python3-sphinx``
* ``python3-sphinxcontrib.qthelp``
docs/source/setup_linux.rst
+7 -7
View File
@@ -8,8 +8,9 @@ Setup on Linux
.. _main website: https://novelwriter.io
This is a brief guide to how you can get novelWriter running on a Linux computer. There are
currently no packaged version of novelWriter for Linux, so it is recommended that you just extract
the source to a practical location on your system and run the ``setup.py`` script.
currently no install package of novelWriter for Linux, so it is recommended that you download
either the full source or minimal package and extract it to a practical location on your system and
run the ``setup.py`` script.
Running from Source
@@ -52,17 +53,16 @@ system where Python packages are usually kept. This is not really the best suite
GUI application like novelWriter, so you may instead copy the entire source to a suiteable location
yourself.
By default, this command installs novelWriter for the current user only. To install for all users,
run the script with the ``sudo`` command.
This should install novelWriter to either ``~/.local/bin/novelWriter`` if installed for local user
only, or to ``/usr/local/bin/novelWriter`` if installed for all users.
only, or to ``/usr/local/bin/novelWriter`` if installed for all users (with the ``sudo`` command).
Step 3: Create Launcher Icons
-----------------------------
To set up the novelWriter desktop launcher, the icons, and the project file association, run:
Regardless of where you extract or install the source files, you can easily set up a standard icon
and launcher. To set up this desktop launcher, the needed icons, and the project file association,
run:
.. code-block:: console
docs/source/setup_mac.rst
+3 -2
View File
@@ -9,8 +9,9 @@ Setup on macOS
.. _brew docs: https://docs.brew.sh/Homebrew-and-Python
This is a brief guide to how you can get novelWriter running on macOS. There are currently no
packaged version of novelWriter for macOS, so it is recommended that you just extract the source to a
practical location on your system and run it.
install package of novelWriter for macOS, so it is recommended that you download either the full
source or minimal package and extract it to a practical location on your system and
run it.
Running from Source
docs/source/setup_windows.rst
-1
View File
@@ -28,7 +28,6 @@ You can still create the installer yourself if you want to. It can be generated
Please use the "Running from Source" option below instead. It has been improved and a script has
been added that does nearly the same thing.
.. _installer issue: https://github.com/vkbo/novelWriter/issues/640
docs/source/tech_technical.rst
+15 -13
View File
@@ -43,21 +43,20 @@ file is saved, and various meta data entries are incremented on each save.
Project Documents
-----------------
The project documents are saved in a folder in the main project folder named ``content``. Each
All 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
when the document was first created. The documents are saved with a filename assembled from this
hash and the file extension ``.nwd``.
If you wish to find the physical location of a document in the project, you can either look it up
in the project XML file, select :guilabel:`Show File Details` from the :guilabel:`Document` menu
If you wish to find the file system location of a document in the project, you can either look it
up in the project XML file, select :guilabel:`Show File Details` from the :guilabel:`Document` menu
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 documents in the project and where they are saved.
The ``ToC.txt`` file has a list of all documents in the project, referenced by their label, and
where they are saved.
The reason for this cryptic file naming is to avoid issues with file naming conventions and
restrictions on different operating systems, and also to have a file name that does not depend on
what the user names the document within the project, or changes it to. The file meta data in the
project tree is mainly saved in the project XML file, although some basic meta data is added to the
header of each document file.
what the user names the document within the project, or changes it to.
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
@@ -89,12 +88,13 @@ file instead.
Project Meta Data
=================
The project folder contains a subfolder named ``meta``, containing a number of files. The meta
The project folder contains a subfolder named ``meta``, containing a number of files. The meta
folder contains semi-important files. That is, they can be lost with only minor impact to the
project.
If you use version control software on your project, you can exclude this folder, although you may
want to track the session log file. The JSON files within this folder can safely be ignored.
want to track the session log file. The JSON files within this folder can safely be ignored as they
will be automatically regenerated if lost.
The Project Index
@@ -108,10 +108,11 @@ The index is maintained and updated whenever a document or note is saved in the
all references and tags in documents and notes, as well as the location of all headers in the
project, and the word counts within each header section.
While the integrity of the index is checked when the file is loaded, the check is not very deep and
it is possible to corrupt the index if the file is manually edited and manipulated. If so,
novelWriter may crash during launch. If this happens, you must delete the index file and rebuild
the index.
The integrity of the index is checked when the file is loaded. It is possible to corrupt the index
if the file is manually edited and manipulated, so the check is important to avoid sudden crashes
of novelWriter. if the file contains errors, novelWriter will automatically build it anew. If the
check somehow fails and novelWriter keeps crashing, you can delete the file manually and rebuild
the index. If this too fails, you have likely encountered a bug.
Cached GUI Options
@@ -124,6 +125,7 @@ to the project. Global GUI settings are stored in the main config file.
The file is not critical, but if it is lost, all such GUI options will revert back to their default
settings.
Session Stats
-------------
docs/source/usage_export.rst
+2 -2
View File
@@ -119,8 +119,8 @@ Export Formats
Currently, six formats are supported for exporting.
OpenDocument Format
The Build tool can produce either an ``.odt`` file, of a ``.fodt`` file. The latter is just a
Open Document Format
The Build tool can produce either an ``.odt`` file, or an ``.fodt`` file. The latter is just a
flat version of the document format as a single XML file.
novelWriter HTML
docs/source/usage_interface.rst
+80 -31
View File
@@ -7,6 +7,7 @@ User Interface
The user interface is kept as simple as possible to avoid distractions when writing. This page
lists all the main GUI elements, and explains what they do.
.. _a_ui_tree:
The Project Tree
@@ -47,25 +48,59 @@ currently selected item. This panel also includes the latest paragraph and chara
addition to the word count.
.. _a_ui_tree_novel:
The Novel Tree
--------------
An alternative way to view the project structure is the novel tree. You can switch to this view by
selecting the :guilabel:`Novel` tab under the project tree. This view is a simplified version of
the view in the :guilabel:`Outline`. It is convenient when you want to browse the structure of the
story itself rather than the document files.
.. note::
You cannot reorganise the entries in the novel tree as that would imply restructuring the
content of the document files.
.. _a_ui_tree_status:
Document Importance and Status
------------------------------
Each document or folder in your project can have either a "Status" or "Importance" flag set. These
are flags that you control and define in their respective tabs in :guilabel:`Project Settings`. The
"Status" flag is intended to tag a Novel document as for instance a draft or as completed, and the
"Importance" flag is intended to tag character notes, or other notes, as for instance a main, major
or minor character.
Whether a document uses a "Status" or "Importance" flag depends on which root folder it lives in.
If it's in the :guilabel:`Novel` folder, it uses the "Status" flag, otherwise it uses an
"Importance" flag. Some folders, like :guilabel:`Trash` and :guilabel:`Outtakes` allow both.
.. _a_ui_tree_dnd:
Project Tree Drag and Drop
--------------------------
Project Tree Drag & Drop
------------------------
The project tree allows drag and drop to a certain extent. This feature is primarily intended for
The project tree allows drag & drop to a certain extent. This feature is primarily intended for
rearranging the order of your documents within each root folder, and has only limited support for
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. If you make a mistake, the last move
action can be undone by pressing :kbd:`Ctrl`:kbd:`Shift`:kbd:`Z`.
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
:guilabel:`Outtakes` folders. Notes can be moved freely between all root folders.
:guilabel:`Outtakes` folders. Notes can be moved freely between all root folders, but keep in mind
that if you move a note into a :guilabel:`Novel`, its "Importance" setting will be reset to the
default "Status" setting. See :ref:`a_ui_tree_status`.
Folders cannot be moved at all outside their root tree. Neither can a folder containing documents
be deleted. You must first delete the containing documents.
Root folders in the project tree cannot be dragged and dropped at all. If you want to reorder them,
you can move them up or down with respect to eachother from the :guilabel:`Tools` menu, the
you can move them up or down with respect to eachother from the :guilabel:`Project` menu, the
right-click context menu, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down`
key.
@@ -78,8 +113,8 @@ Editing and Viewing Documents
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 document in the document editor. The editor uses a
simplified markdown format. The format is described in the :ref:`a_ui_md` section below. The editor
has a maximise button (toggles the :guilabel:`Distraction Free Mode`) and a close button in the
top-right corner.
has a maximise button (toggles the :guilabel:`Focus 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. To view a document, press :kbd:`Ctrl`:kbd:`R`, or select :guilabel:`View Document` in the
@@ -91,23 +126,24 @@ 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
the edit or view panel. Optionally, the full project path to the document can be shown. This can be
set in the :guilabel:`Preferences` dialog from the :guilabel:`Tools` menu. Clicking on the document
title bar will select and reveal its location in the project tree, making it easier to locate in a
large project.
set in :guilabel:`Preferences` from the :guilabel:`Tools` menu. Clicking on the document title bar
will select and reveal its location in the project tree, making it easier to locate in a large
project.
Any tag reference in the editor can be opened in the viewer by moving the cursor to the label and
pressing :kbd:`Ctrl`:kbd:`Return`. You can also control-click them with your mouse. 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 points to. The document viewer keeps a history of viewed
documents, which you can navigate with the arrow buttons in the top-left corner of the viewer. If
your mouse has back and forward navigation buttons, these can be used as well.
your mouse has back and forward navigation buttons, these can be used as well. They work just like
the backward and forward features in a browser.
At the bottom of the view panel there is a :guilabel:`References` panel. (If it is hidden, click
the icon to reveal it.) This panel will show links to all documents referring back to it, if any
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
through all documents in the list in the :guilabel:`References` panel without losing the list in
the process.
the icon to reveal it.) This panel will show links to all documents referring back to the one
you're currently viewing, if any 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 through all documents in the list in the
:guilabel:`References` panel without losing the list in the process.
.. note::
The :guilabel:`References` panel relies on an up-to-date index of the project. The index is
@@ -122,11 +158,15 @@ Auto-Replace as You Type
========================
A few auto-replace features are supported by the editor. You can control every aspect of the
auto-replace feature from :guilabel:`Preferences`. You can also disable it entirely.
auto-replace feature from :guilabel:`Preferences`. You can also disable this feature entirely if
you wish.
.. tip::
If you don't like auto-replacement, all symbols inserted by this feature are also available in
the :guilabel:`Insert` menu, and via convenient :ref:`a_ui_shortcuts_ins`.
the :guilabel:`Insert` menu, and via convenient :ref:`a_ui_shortcuts_ins`. You may also be using
a `Compose Key`_ setup, which means you may not need the auto-replace feature.
.. _Compose Key: https://en.wikipedia.org/wiki/Compose_key
The editor is able to replace two and three hyphens with short and long dashes, triple points with
ellipsis, and replace straight single and double quotes with user-defined quote symbols. It will
@@ -173,17 +213,22 @@ level of the novel. See :ref:`a_struct_heads` for more details.
``### Title``
Heading level three. If the document is a novel file, the header level indicates the start of a
new scene. Scene numbers or scene separators can be inserted automatically when exporting the
manuscript, so you can use the title field as a working title for your scenes.
manuscript, so you can use the title field as a working title for your scenes if you wish.
``#### Title``
Heading level four. If the document is a novel file, the header level indicates the start of a
new section. Scene titles can be replaced by separators or removed when exporting the
manuscript, so you can use the title field as a working title for your sections.
new section. Section titles can be replaced by separators or removed when exporting the
manuscript, so you can use the title field as a working title for your sections if you wish.
.. note::
The space after the ``#`` characters is mandatory. The syntax highlighter will change colour and
font size when the heading is correctly formatted.
.. tip::
If you do use the automatic numbering feature for exports, you can tell the export tool to skip
assigning a number to a specific chapter by adding a ``*`` as the first character of the title
itself. See :ref:`a_struct_heads_unnum` for more details.
.. _a_ui_md_emph:
@@ -229,14 +274,14 @@ In addition to these standard markdown features, novelWriter also allows for com
The text of a comment is ignored by the word counter. The text can also be filtered out when
exporting or viewing the document.
If the first word of a comment is ``Synopsis:`` (with the colon), the comment 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.
If the first word of a comment is ``Synopsis:`` (with the colon included), the comment 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...``
This is a comment. The text is not exported by default (this can be overridden), seen in the
Viewer, or counted towards word counts.
document viewer, or counted towards word counts.
``% Synopsis: text...``
This is a synopsis comment. It is generally treated in the same way as a regular comment, except
@@ -270,13 +315,13 @@ also be inserted at the cursor position in the editor via the :guilabel:`Insert`
Additional Markdown and Non-Standard Features
---------------------------------------------
The editor and viewer also support markdown standard hard line breaks, and preserves non-breaking
The editor and viewer also support markdown standard hard line breaks, and preserve non-breaking
spaces if running with Qt 5.9 or higher. For older versions, the non-breaking spaces are lost when
the document is saved. This is unfortunately hard-coded in the Qt text editor.
the document is saved. This is unfortunately hard-coded into the Qt text editor.
* A hard line break can be achieved by leaving two or more spaces at the end of the line. This is
standard markdown syntax. Alternatively, the user can press :kbd:`Ctrl`:kbd:`K`, :kbd:`Return` to
insert this type of space.
insert this type of line break.
* A non-breaking space can be 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`.
@@ -288,6 +333,10 @@ in :ref:`a_ui_shortcuts_ins`.
Both hard line breaks and non-breaking spaces are highlighted by the syntax highlighter as an
alternate coloured background, depending on the selected theme.
.. tip::
Non-breaking spaces are the correct type of space to separate a number from its unit. Generally,
it prevents the line wrapping algorithms from adding line breaks where it shouldn't.
.. _a_ui_outline:
@@ -317,7 +366,7 @@ rearranged by dragging them to a different position.
The :guilabel:`Title` column cannot be disabled or moved.
The information viewed in the outline is based on the project's main index. While novelWriter does
its best to keep the index up to date when content changes, you can always rebuild it manually by
its best to keep the index up to date when contents change, you can always rebuild it manually by
pressing :kbd:`F9` if something isn't right.
The outline view itself can be regenerated by pressing :kbd:`F10`. You can also enable automatic
docs/source/usage_notes.rst
+5 -3
View File
@@ -6,9 +6,11 @@ Project Notes
novelWriter doesn't have a database and complicated forms for filling in details about plot
elements, characters, and all sorts of additional information that isn't a part of the novel text
itself. Instead, all such information is saved in notes. The relation between all these additional
elements is extracted from the documents and notes by the project indexer, based on the tags and
references you set within them.
itself. Instead, all such information is saved in notes that are written and maintained just like
all other text in your project.
The relation between all these additional elements is extracted from the documents and notes by the
project indexer, based on the tags and references you set within them.
Using notes is not required, but making at least minimal notes for each plot element, and adding a
tag to them, makes it possible to use the :guilabel:`Outline` feature to see how each element
docs/source/usage_projects.rst
+18 -11
View File
@@ -4,15 +4,15 @@
Novel Projects
**************
A novelWriter project requires a dedicated folder for storing its files on the local file system.
See :ref:`a_tech` for further details on how files are organised.
A new project can be created from the :guilabel:`Project` menu by selecting
:guilabel:`New Project`. This will open the :guilabel:`New Project Wizard` that will assist you in
creating a barebone project suited to your needs.
creating a barebone project suited to your needs. A novelWriter project requires a dedicated folder
for storing its files on the local file system. See :ref:`a_tech` for further details on how files
are organised.
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.
dialog. A project can be removed from this list by selecting it and pressing the :kbd:`Del` key or
by clicking the :guilabel:`Remove` button.
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. Details about the project,
@@ -98,7 +98,7 @@ referenced.
Folders and root folders can only be deleted when they are empty. Recursive deletion is not
supported. A document or a folder can be deleted from the :guilabel:`Project` menu, or by pressing
:kbd:`Ctrl`:kbd:`Del`.
:kbd:`Ctrl`:kbd:`Shift`:kbd:`Del`.
.. _a_proj_roots_out:
@@ -108,9 +108,9 @@ Archived Documents (Outtakes)
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`
root folder from the :guilabel:`Project` menu. You are not allowed to move folders to this root
folder, only documents. If you need folders in it to organise your documents, you can of course
create new ones there.
root folder from the :guilabel:`Project` menu. You are not allowed to move entire folders to this
root folder, only documents. If you need folders in it to organise your documents, you can of
course create new ones there.
You can drag any document to this folder and preserve its settings. The document will always be
excluded from the :guilabel:`Build Novel Project` builds. It is also removed from the project
@@ -180,7 +180,7 @@ documents.
.. tip::
You can use folders to sort your scene documents into chapters. You will still need to add a
chapter document as the first item of your chapter folder, and the scene documents as the
following items.
following items. Another way to use folders is to make a folder for each act.
.. _a_proj_files:
@@ -212,7 +212,7 @@ Word Counts
A character, word and paragraph count is maintained for each document, as well as for each section
of a document following a header. The word count, and change of words in the current session, is
displayed in the footer of any document open in the editor, and all stats are shown in the details
panel below the project tree for any document selected in the project tree.
panel below the project tree for any document selected in the project or novel tree.
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.
@@ -265,6 +265,8 @@ use these to indicate at what stage of completion each novel document is, or how
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.
See also :ref:`a_ui_tree_status`.
.. note::
The status or importance level currently in use by one or more documents cannot be deleted, but
they can be edited.
@@ -326,3 +328,8 @@ A tool to view the content of this file is available in the :guilabel:`Tools` me
The tool will show a list of all your sessions, and a set of filters to apply to it. You can also
export the filtered data to a JSON file or to a CSV file that can be opened by a spreadsheet
application like for instance Libre Office Calc.
As of version 1.2, the log file also stores how much of the session time was spent idle. The
definition of idle here is that the novelWriter main window loses focus, and the user hasn't made
any changes to the currently open document in five minutes. The number of minutes can be altered in
:guilabel:`Preferences`.
docs/source/usage_structure.rst
+25 -9
View File
@@ -23,8 +23,9 @@ title. See also the :ref:`a_ui_md` section for more details about the markdown s
.. note::
The header levels are not only important when generating the exported novel file, they are also
used by the indexer when building the outline tree in the :guilabel:`Outline` tab. Each heading
also starts a new region where new references and tags can be set.
used by the indexer when building the outline tree in the :guilabel:`Outline` tab as well as the
:guilabel:`Novel` tab of the project tree. Each heading also starts a new region where new
references and tags can be defined.
The different header levels are interpreted as specific section types of the novel in the following
way:
@@ -51,7 +52,7 @@ way:
Header level four signifies a sub-scene level partition, usually called a "section" in the
documentation and the 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
wish, and can filter the titles out of the final manuscript just like with scene titles.
wish, and can filter them out of the final manuscript just like with scene titles.
.. tip::
There are multiple options of how to process novel titles when exporting the manuscript. For
@@ -73,8 +74,8 @@ an asterisk (``*``). Like so:
``## *Unnumbered Chapter Title``
The leading asterisk is only considered by the :guilabel:`Build Novel Project` tool, and will be
removed before inserted at the location of the ``%title%`` label. See the :ref:`a_export` page for
more details.
removed before the title is inserted at the location of the ``%title%`` label. See the
:ref:`a_export` page for more details.
.. note::
If you need the first character of the title to be an actual asterisk, you must escape it:
@@ -191,7 +192,7 @@ Below is an overview of all available layout formats.
produce the same result as a collection of :guilabel:`Partition`, :guilabel:`Chapter` and
:guilabel:`Scene` layout documents. However, it does not provide the functionality of the
:guilabel:`Unnumbered` layout format by default, but this can still be achieved by prefixing the
chapter title with an asterisk (``*``).
chapter title with an asterisk (``*``). See :ref:`a_struct_heads_unnum` for more details.
:guilabel:`Partition`
A partition can be used to split the novel into parts. Partition titles are indicated with a
@@ -208,7 +209,7 @@ Below is an overview of all available layout formats.
:guilabel:`Unnumbered`
Same as :guilabel:`Chapter`, but when exporting the project, and automatic chapter numbering is
enabled, documents with this layout will not increment the chapter number. It also has a
enabled, documents with this layout will not increment and apply a chapter number. It also has a
separate title formatting setting. This makes the layout suitable for Prologue and Epilogue type
chapters.
@@ -226,9 +227,24 @@ Below is an overview of all available layout formats.
The layout granularity is entirely optional. In principle, you can write the entire novel in a
single document with layout :guilabel:`Book`. You can also have a single document per chapter if
that suits you better. The :guilabel:`Outline` will show your structure of chapters and scenes
regardless of how your documents are organised.
regardless of how your documents are organised. So will the novel tree.
.. tip::
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 documents into separate chapter and scene
documents.
documents. The split tool will try to select the correct layout for each of the new documents.
.. _a_struct_layout_auto:
Novel Layout Automation
-----------------------
When a document is saved from the document editor, novelWriter will check if the level of the first
header of the document matches the selected document layout. If the header level is inconsistent
with the layout, the layout will automatically be corrected if it can be unambiguously determined.
This means that for instance saving a document with header level three, when the layout is set to
:guilabel:`Chapter`, the layout will automatically be changed to :guilabel:`Scene`. If, however,
the layout was set to :guilabel:`Book`, no change will be made because the :guilabel:`Book` layout
is not associated with a specific header level.
docs/source/usage_typography.rst
+12 -12
View File
@@ -17,7 +17,7 @@ This chapter provides some additional information on how novelWriter handles the
Special Notes on Symbols
========================
Some additional notes on these symbols.
Some additional notes on the available symbols.
Dashes and Ellipsis
@@ -28,9 +28,9 @@ automatically to short and long dashes, and three dots to ellipsis. The last aut
always be reverted with the undo command :kbd:`Ctrl`:kbd:`Z`, reverting the text to what you typed
before the automatic replacement occurred.
The symbols are available in the :guilabel:`Insert` menu. In addition, "Figure Dash" is also
available. The Figure Dash is a dash that has the same width as the numbers of the same font, which
tend to be the same width so that numbers align nicely in columns.
In addition, "Figure Dash" is available. The Figure Dash is a dash that has the same width as the
numbers of the same font, for most fonts. It helps to align numbers align nicely in columns when
you need to use a dash in them.
Single and Double Quotes
@@ -44,9 +44,9 @@ Ordinarily, text wrapped in quotes are highlighted by the editor. This is meant
for highlighting dialogue between characters. This feature can be disabled in
:guilabel:`Preferences` if this feature isn't wanted.
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. Two convenience functions in the :guilabel:`Format` menu can be used to
The editor distinguishes between text wrapped in regular 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. Two convenience functions in the :guilabel:`Format` menu can be used to
re-format a selected section of text with the correct quote symbols.
.. _Quotation Mark: https://en.wikipedia.org/wiki/Quotation_mark
@@ -58,9 +58,9 @@ Single and Double Prime
Both single and double prime symbols are available in the :guilabel:`Insert` menu. These symbols
are the correct symbols to use for unit symbols for feet, inches, minutes and seconds. The usage of
these is described in more detail on the Wikipedia Prime_ page. They look very similar to single
and double straight quotes, but may be renderred similarly by the font, but they have different
and double straight quotes, and may be renderred similarly by the font, but they have different
codes. Using these correctly will also prevent the auto-replace and dialogue highlighting features
to understand their meaning in the text.
misunderstanding their meaning in the text.
.. _Prime: https://en.wikipedia.org/wiki/Prime_(symbol)
@@ -69,8 +69,8 @@ Modifier Letter Apostrophe
--------------------------
The auto-replace feature will consider any right-facing single straight quote as a quote symbol,
even if it's intended as an apostrophe. This also includes the syntax highlighter, which may assume
the first following apostrophe is the closing symbol of a single quoted region of text.
even if it is intended as an apostrophe. This also includes the syntax highlighter, which may
assume the first following apostrophe is the closing symbol of a single quoted region of text.
To get around this, an alternative apostrophe is available. It is a special Unicode character that
is not categorised as punctuation, but as a modifier. It is usually renderred the same way as the
@@ -99,6 +99,6 @@ All non-breaking spaces are highlighted with a differently coloured background t
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
format. For plain text, they are exported as regular spaces.
format.
.. _thin space: https://en.wikipedia.org/wiki/Thin_space
nw/gui/projtree.py
+15 -17
View File
@@ -456,14 +456,14 @@ class GuiProjectTree(QTreeWidget):
for tHandle in self.getTreeFromHandle(trashHandle):
if tHandle == trashHandle:
continue
self.deleteItem(tHandle, alreadyAsked=True)
self.deleteItem(tHandle, alreadyAsked=True, bulkAction=True)
if nTrash > 0:
self._setTreeChanged(True)
return True
def deleteItem(self, tHandle=None, alreadyAsked=False, askForTrash=False):
def deleteItem(self, tHandle=None, alreadyAsked=False, bulkAction=False):
"""Delete an item from the project tree. As a first step, files are
moved to the Trash folder. Permanent deletion is a second step. This
second step also deletes the item from the project object as well as
@@ -474,24 +474,27 @@ class GuiProjectTree(QTreeWidget):
logger.error("No project open")
return False
if not self.hasFocus():
if not self.hasFocus() and not bulkAction:
logger.info("Delete action blocked due to no widget focus")
return False
if tHandle is None:
tHandle = self.getSelectedHandle()
if tHandle is None:
logger.error("There is no item to delete")
return False
trItemS = self._getTreeItem(tHandle)
nwItemS = self.theProject.projTree[tHandle]
if trItemS is None or nwItemS is None:
logger.error("Could not find tree item for deletion")
return False
wCount = int(trItemS.data(self.C_COUNT, Qt.UserRole))
if nwItemS.itemType == nwItemType.FILE:
logger.debug("User requested file %s moved to trash" % tHandle)
logger.debug("User requested file %s deleted" % tHandle)
trItemP = trItemS.parent()
trItemT = self._addTrashRoot()
if trItemP is None or trItemT is None:
@@ -532,21 +535,16 @@ class GuiProjectTree(QTreeWidget):
else:
# The file is not already in the trash folder, so we
# move it there.
doTrash = False
if askForTrash:
msgYes = self.askQuestion(
self.tr("Delete File"),
self.tr("Move file '{0}' to Trash?").format(nwItemS.itemName),
)
if msgYes:
doTrash = True
else:
doTrash = True
if doTrash:
msgYes = self.askQuestion(
self.tr("Delete File"),
self.tr("Move file '{0}' to Trash?").format(nwItemS.itemName),
)
if msgYes:
if pHandle is None:
logger.warning("File has no parent item")
logger.debug("Moving file %s to trash" % tHandle)
self.propagateCount(tHandle, 0)
tIndex = trItemP.indexOfChild(trItemS)
trItemC = trItemP.takeChild(tIndex)
@@ -1214,7 +1212,7 @@ class GuiProjectTreeMenu(QMenu):
"""Forward the delete item call to the project tree.
"""
if self.theItem is not None:
self.theTree.deleteItem(askForTrash=True)
self.theTree.deleteItem()
return
def _doEmptyTrash(self):
tests/test_gui/test_gui_projtree.py
-1
View File
@@ -42,7 +42,6 @@ def testGuiProjTree_TreeItems(qtbot, caplog, monkeypatch, nwGUI, nwMinimal):
monkeypatch.setattr(QMessageBox, "warning", lambda *args: QMessageBox.Yes)
monkeypatch.setattr(QMessageBox, "information", lambda *args: QMessageBox.Yes)
monkeypatch.setattr(GuiMain, "editItem", lambda *args: None)
monkeypatch.setattr(GuiProjectTree, "hasFocus", lambda *args: True)
nwGUI.theProject.projTree.setSeed(42)
nwTree = nwGUI.treeView