diff --git a/README.md b/README.md index a884f462..ca06da60 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/source/index.rst b/docs/source/index.rst index d5e1bc77..d110f746 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -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** diff --git a/docs/source/int_introduction.rst b/docs/source/int_introduction.rst index 8bc8b3ad..900c3921 100644 --- a/docs/source/int_introduction.rst +++ b/docs/source/int_introduction.rst @@ -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 diff --git a/docs/source/int_started.rst b/docs/source/int_started.rst index 6c2b596c..385f99fc 100644 --- a/docs/source/int_started.rst +++ b/docs/source/int_started.rst @@ -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`` diff --git a/docs/source/setup_linux.rst b/docs/source/setup_linux.rst index 37267d45..4a34cc45 100644 --- a/docs/source/setup_linux.rst +++ b/docs/source/setup_linux.rst @@ -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 diff --git a/docs/source/setup_mac.rst b/docs/source/setup_mac.rst index e338f02a..5b738865 100644 --- a/docs/source/setup_mac.rst +++ b/docs/source/setup_mac.rst @@ -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 diff --git a/docs/source/setup_windows.rst b/docs/source/setup_windows.rst index b34046d8..a6130854 100644 --- a/docs/source/setup_windows.rst +++ b/docs/source/setup_windows.rst @@ -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 diff --git a/docs/source/tech_technical.rst b/docs/source/tech_technical.rst index f28874a9..7b74def1 100644 --- a/docs/source/tech_technical.rst +++ b/docs/source/tech_technical.rst @@ -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 ------------- diff --git a/docs/source/usage_export.rst b/docs/source/usage_export.rst index b9968e6b..e1a50691 100644 --- a/docs/source/usage_export.rst +++ b/docs/source/usage_export.rst @@ -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 diff --git a/docs/source/usage_interface.rst b/docs/source/usage_interface.rst index e9d9c4ae..7947747d 100644 --- a/docs/source/usage_interface.rst +++ b/docs/source/usage_interface.rst @@ -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 diff --git a/docs/source/usage_notes.rst b/docs/source/usage_notes.rst index b0b46143..09064530 100644 --- a/docs/source/usage_notes.rst +++ b/docs/source/usage_notes.rst @@ -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 diff --git a/docs/source/usage_projects.rst b/docs/source/usage_projects.rst index 60266f16..1f101848 100644 --- a/docs/source/usage_projects.rst +++ b/docs/source/usage_projects.rst @@ -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`. diff --git a/docs/source/usage_structure.rst b/docs/source/usage_structure.rst index 5a903efb..9163e8eb 100644 --- a/docs/source/usage_structure.rst +++ b/docs/source/usage_structure.rst @@ -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. diff --git a/docs/source/usage_typography.rst b/docs/source/usage_typography.rst index dc91d616..03a7ada4 100644 --- a/docs/source/usage_typography.rst +++ b/docs/source/usage_typography.rst @@ -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 diff --git a/nw/gui/projtree.py b/nw/gui/projtree.py index 1e557ba8..54a4acfb 100644 --- a/nw/gui/projtree.py +++ b/nw/gui/projtree.py @@ -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): diff --git a/tests/test_gui/test_gui_projtree.py b/tests/test_gui/test_gui_projtree.py index b0fdaa89..07fbc312 100644 --- a/tests/test_gui/test_gui_projtree.py +++ b/tests/test_gui/test_gui_projtree.py @@ -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