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

Make a second apss through the entire documentation to fix issues

Browse Source
This commit is contained in:
Veronica Berglyd Olsen
2023-10-15 20:11:29 +02:00
parent cceb31aac7
commit ccffa91c49
21 changed files with 278 additions and 269 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/index.rst
+3 -3
View File
@@ -18,13 +18,13 @@ storage for robustness.
The project storage is suitable for version control software, and also well suited for file
synchronisation tools. All text is saved as plain text files with a meta data header. The core
project structure is stored in a single project XML file. Other meta data is primarily saved as
JSON files. See the :ref:`a_breakdown_storage` section for more details.
project structure is stored in a single project XML file. Other meta data is saved as JSON files.
See the :ref:`a_breakdown_storage` section for more details.
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
as well. novelWriter can also be run directly from the Python source, or installed from packages or
from pip. See :ref:`a_started` for more details.
with pip. See :ref:`a_started` for more details.
**Useful Links**
docs/source/int_customise.rst
+8 -11
View File
@@ -17,7 +17,7 @@ Spell Check Dictionaries
========================
novelWriter uses Enchant_ as the spell checking tool. Depending on your operating system, it may or
may not load installed spell check dictionaries automatically.
may not load all installed spell check dictionaries automatically.
Linux and MacOS
---------------
@@ -40,7 +40,6 @@ This assumes your user profile is stored at ``C:\Users\<USER>``. The last one or
not exist, so you may need to create them.
.. note::
The Free Desktop link points to a repository, and what may look like file links inside the
dictionary folder are actually links to web pages. If you right-click and download those, you
get HTML files, not dictionaries!
@@ -54,9 +53,9 @@ not exist, so you may need to create them.
Syntax and GUI Themes
=====================
Adding your own GUI and syntax themes is relatively easy altough requires that you manually edit
config files with colour values. The themes are defined by simple plain text config files with meta
data and colour settings.
Adding your own GUI and syntax themes is relatively easy, altough it requires that you manually
edit config files with colour values. The themes are defined by simple plain text config files with
meta data and colour settings.
In order to make your own versions, first copy one of the existing files to your local computer and
modify it as you like.
@@ -81,15 +80,14 @@ set as ``name`` inside the file.
.. versionadded:: 2.0
The ``icontheme`` value was added to GUI themes. Make sure you set this value in existing custom
themes. Otherwise it defaults to ``typicons_light``, which may not match your theme colour
scheme. Otherwise, novelWriter will try to guess your icon theme, and may not pick the most
themes. Otherwise, novelWriter will try to guess your icon theme, and may not pick the most
suitable one.
Gustom GUI and Icons Theme
--------------------------
A GUI theme conf file consists of the follwing settings:
A GUI theme ``.conf`` file consists of the follwing settings:
.. code-block:: cfg
@@ -138,7 +136,7 @@ Omitted values are not loaded and will use default values.
Custom Syntax Theme
-------------------
A syntax theme conf file consists of the follwing settings:
A syntax theme ``.conf`` file consists of the follwing settings:
.. code-block:: cfg
@@ -168,7 +166,6 @@ A syntax theme conf file consists of the follwing settings:
replacetag = 0, 0, 0
modifier = 0, 0, 0
In the Main section, you must define at least the ``name`` setting. The Syntax colour values are
RGB numbers on the format ``r, g, b`` where each is an integer from to 255. Omitted values are set
RGB numbers on the format ``r, g, b`` where each is an integer from to 255. Omitted values default
to black, except ``background`` which defaults to white,
docs/source/int_howto.rst
+2 -2
View File
@@ -25,7 +25,7 @@ Managing the Project
:guilabel:`Merge Documents in Folder`.
In the dialog that pops up, the documents will be in the same order as in the folder, but you
can also rearrange them here of you wish.
can also rearrange them here of you wish. See :ref:`a_ui_tree_split_merge` for more details.
Layout Tricks
@@ -68,7 +68,7 @@ Organising Your Text
for soft scene breaks. the :guilabel:`Build Manuscript` tool will let you add separate
formatting for the two when you generate your manuscript. You can for instance add the common
"``* * *``" for hard breaks and select to hide section breaks, which will just insert an empty
paragraph in their place.
paragraph in their place. See :ref:`a_manuscript_settings` for more details.
Other Tools
docs/source/int_introduction.rst
+16 -16
View File
@@ -7,10 +7,10 @@ Key Features
.. _Snowflake: https://www.advancedfictionwriting.com/articles/snowflake-method/
.. _Markdown: https://en.wikipedia.org/wiki/Markdown
At the core, novelWriter is a multi-document plain text editor. It uses a markup syntax inspired by
At its core, novelWriter is a multi-document plain text editor. It uses a markup syntax inspired by
Markdown_ to apply simple formatting to the text. It is designed for writing fiction, so the
formatting features are limited to those relevant for this purpose. It is not suitable for
technical writing, and it is *not* a full feature Markdown editor.
formatting features available are limited to those relevant for this purpose. It is *not* suitable
for technical writing, and it is *not* a full-feature Markdown editor.
Your novel project is organised as a collection of separate plain text documents instead of a
single, large document. The idea here is to make it easier to reorganise your project structure
@@ -22,8 +22,8 @@ your notes about your characters, your world building, and so on.
You can at any point split the individual documents by their headers up into multiple documents, or
merge multiple documents into single documents. This makes it easier to use variations of the
popular Snowflake_ method for writing. You can focus on writing larger structure-focused documents,
like one per act for instance, and later effortlessly split these up into scenes by their headers.
Snowflake_ method for writing. You can focus on writing larger structure-focused documents, like
one per act for instance, and later effortlessly split these up into scenes by their headers.
Below are some key features of novelWriter.
@@ -42,11 +42,11 @@ Below are some key features of novelWriter.
**Organise your documents how you like**
You can split your novel project up into as many individual documents as you want to. When you
build the project, they are all glued together in the top-to-bottom order in which they appear
in the project tree. You can use as few text documents as you like, but splitting the project up
into chapters and scenes means you can easily reorder them using the drag and drop feature. You
can start out with a few documents and then later split them into multiple documents based on
their headers.
build the project into a manuscript, they are all glued together in the top-to-bottom order in
which they appear in the project tree. You can use as few text documents as you like, but
splitting the project up into chapters and scenes means you can easily reorder them using the
drag-and-drop feature. You can also start out with a few documents and then later split them
into multiple documents based on their headers.
**Multi-novel project support**
As of novelWriter 2.0, you can have multiple Novel type root folders in a project. This allows
@@ -56,22 +56,22 @@ Below are some key features of novelWriter.
**Keep track of your plot elements**
All notes in your project can be assigned a :term:`tag` that you can :term:`reference` from any
other document or note. In fact, you can add a new tag under each heading of a note if you need
to be able to reference specific sections.
to be able to reference specific sections of ot.
**Get an overview of your plot elements**
In the :guilabel:`Outline View` on the main window you can see an outline of all the chapters,
scenes, and sections of your project. If they have any references in them, these are listed in
additional columns. You can also add a synopsis to each document, which can be listed here as
well. You have the option to add or remove columns of information from this outline. A subset of
the outline information is also available in the :guilabel:`Novel View` as an alternative view
to the project tree.
additional columns. You can also add a synopsis to each chapter or scene, which can be listed
here as well. You have the option to add or remove columns of information from this outline. A
subset of the outline information is also available in the :guilabel:`Novel View` as an
alternative view to the project tree.
**Building your manuscript**
Whether you want to assemble a manuscript, or export all your notes, or generate an outline of
your chapters and scenes with a synopsis, you can use the :guilabel:`Build Manuscript` tool to
do so. The tool lets you select what information you want to include in the generated document,
and how it is formatted. You can send the result to a printer, a PDF, or to an Open Document
file that can be opened by most office type word processors. You can also generate the result
file that can be opened by most office type word processors. You can also generate the result
as HTML, or Markdown, both suitable for further conversion to other formats.
docs/source/int_overview.rst
+22 -21
View File
@@ -14,12 +14,13 @@ novelWriter is built as a cross-platform application using `Python 3 <https://ww
the programming language, and `Qt 5 <https://www.qt.io/>`_ for the user interface.
novelWriter is built for Linux first, and this is where it works best. However, it also runs fine
on Windows and MacOS due to being built with cross-platform tools. The author of the application
doesn't own a Mac, so on-going Mac support is dependant on user feedback and user contributions.
on Windows and MacOS due to the cross-platform framework it's build on. The author of the
application doesn't own a Mac, so on-going Mac support is dependant on user feedback and user
contributions.
Spell checking in novelWriter is provided by a third party library called
`Enchant <https://abiword.github.io/enchant/>`_. Please see the section on :ref:`a_custom_dict` for
how to handle spell checking in different languages.
how to install spell checking languages.
For install instructions, see :ref:`a_started`.
@@ -28,40 +29,40 @@ Using novelWriter
=================
In order to use novelWriter effectively, you need to know the basics of how it works. The following
sections will explain the main principles. It starts with the basics, and gets more detailed as you
chapters will explain the main principles. It starts with the basics, and gets more detailed as you
read on.
:ref:`a_breakdown` – Essential Information
This section explains the basics of how the application works and what it can and cannot do.
This chapter explains the basics of how the application works and what it can and cannot do.
:ref:`a_ui_project` – Recommended Reading
This section will give you a more detailed explanation of how you the user interface components
This chapter will give you a more detailed explanation of how you the user interface components
to organise and view your project work.
:ref:`a_ui_writing` – Recommended Reading
This section will give you a more detailed explanation of how the text editor and viewer work.
This chapter will give you a more detailed explanation of how the text editor and viewer work.
:ref:`a_fmt` – Essential Information
This section covers how you should format your text. The editor is plain text, so text
This chapter covers how you should format your text. The editor is plain text, so text
formatting requires some basic markup. The structure of your novel is also inferred by how you
use headings. Tags and references are implemented by special keywords.
:ref:`a_kb` – Optional / Lookup
This section lists all the keyboard shortcuts in novelWriter and what they do. Most of the
shortcuts are also listed next to the menu items inside the app, or in tool tips, so this
section is mostly for reference.
This chapter lists all the keyboard shortcuts in novelWriter and what they do. Most of the
shortcuts are also listed next to their menu entries inside the app, or in tool tips. This
chapter is mostly for reference.
:ref:`a_typ` – Optional
This section gives you an overview of the special typographical symbols available in
This chapter gives you an overview of the special typographical symbols available in
novelWriter. The auto-replace feature can handle the insertion of standard quote symbols for
your language, and other special characters. If you use any symbols aside from these. their
intended use is explained here.
:ref:`a_prjfmt` – Optional
This section is more technical and has an overview of changes made to the way your project data
This chapter is more technical and has an overview of changes made to the way your project data
is stored. The format has changed a bit from time to time, and sometimes the changes require
that you make small modifications to your project. Everything you need to know is listed in this
section.
chapter.
Organising Your Projects
@@ -73,19 +74,19 @@ to take advantage of these features, you must structure your text in a specific
meta data for it to extract.
:ref:`a_proj` – Essential Information
This section explains how you organise the content of your project, and how to set up automated
This chapter explains how you organise the content of your project, and how to set up automated
backups of your work.
:ref:`a_struct` – Essential Information
This section covers the way your novel's structure is encoded into the text documents. It
explains how the different levels of headings are used, and how you can include information
about characters, plot elements, and other meta data in your text.
This chapter covers the way your novel's structure is encoded into the text documents. It
explains how the different levels of headings are used, and some special formatting for
different kinds of headings.
:ref:`a_references` - Recommended Reading
This section explains how you organise your notes, and how the Tags and References system works.
This chapter explains how you organise your notes, and how the Tags and References system works.
This system lets you cross-link your documents in your project, and display these references in
the application interface.
:ref:`a_manuscript` - Recommended Reading
This section explains in more detail how the Manuscript Build tool works, how you can control
the way chapter titles are formatted, and how scene and section breaks are handled.
This chapter explains how the :guilabel:`Manuscript Build` tool works, how you can control the
way chapter titles are formatted, and how scene and section breaks are handled.
docs/source/int_started.rst
+6 -6
View File
@@ -14,8 +14,8 @@ Getting Started
.. _Releases: https://github.com/vkbo/novelWriter/releases
.. _AppImage: https://appimage.org/
Package installers are available for all major platforms, including Linux, Windows and MacOS. See
below for install instructions for each platform.
Package installers for novelWriter are available for all major platforms, including Linux, Windows
and MacOS. See below for install instructions for each platform.
You can also install novelWriter from the Python Package Index (PyPi). See :ref:`a_started_pip`.
Installing from PyPi does not set up icon launchers, so you will either have to do this yourself,
@@ -37,7 +37,7 @@ Installing it should be straightforward.
If you have any issues, try uninstalling the previous version and making a fresh install. If you
already had a version installed via a different method, you should uninstall that first as having
multiple installations has been known to cause issues.
multiple installations has been known to cause problems.
.. note::
The novelWriter installer is not signed because Microsoft doesn't currently provide a way for
@@ -112,9 +112,9 @@ completely standalone images for the app that include the necessary environment
They can of course be run on any Linux distro, if you prefer this to native packages.
.. note::
novelWriter generally stops supporting Python versions that have reached end of life. If your
Linux distro still uses older Python versions, you may want to try the AppImage instead.
novelWriter generally don't support Python versions that have reached end of life. If your Linux
distro still uses older Python versions and novelWriter won't run, you may want to try the
AppImage instead.
.. _a_started_macos:
docs/source/project_manuscript.rst
+21 -21
View File
@@ -10,7 +10,7 @@ You can activate it from the sidebar, the :guilabel:`Tools` menu, or by pressing
.. versionadded:: 2.1
This tool is new for version 2.1. A simpler tool was used for earlier versions. The simpler tool
only allows you to define a single set of options for one build, but otherwise has much the same
only allows you to define a single set of options for the build, but otherwise has much the same
functionality.
@@ -52,7 +52,7 @@ Document Selection
The :guilabel:`Selections` page of the :guilabel:`Manuscript Build Settings` dialog allows you to
fine tune which documents are included in the build. They are indicated by a green arrow icon in
the last column. On the right, you have some filter options for selecting content of a specific
the last column. On the right you have some filter options for selecting content of a specific
type, and a set of switches for which root folders to include.
You can override the result of these filters by marking one or more documents and selecting to
@@ -71,14 +71,14 @@ Formatting Headings
The :guilabel:`Headings` page of the :guilabel:`Manuscript Build Settings` dialog.
The :guilabel:`Headings` page of the :guilabel:`Manuscript Build Settings` dialog allows you to set
how the headings in your :term:`Novel Documents` as formatted. By default, the title is just copied
as-is, indicated by the ``{Title}`` format. You can change this to for instance add chapter
how the headings in your :term:`Novel Documents` are formatted. By default, the title is just
copied as-is, indicated by the ``{Title}`` format. You can change this to for instance add chapter
numbers and scene numbers like shown int he figure above.
Clicking the edit button will copy the formatting string into the edit box, where a syntax
highlighter will help indicate which parts are automatically generated by the build tool. The
:guilabel:`Insert` button is a dropdown list of these formats, and selecting one will insert it at
the position of the cursor.
Clicking the edit button next to a format will copy the formatting string into the edit box where
it can be modified, and where a syntax highlighter will help indicate which parts are automatically
generated by the build tool. The :guilabel:`Insert` button is a dropdown list of these formats, and
selecting one will insert it at the position of the cursor.
Any text you add that isn't highlighted in colours will remain in your formatted titles.
``{Title}`` will always be replaced by the text in the heading from your documents.
@@ -92,11 +92,11 @@ Scene Separators
If you don't want any titles for your scenes (or for your sections if you have them), you can leave
the formatting boxes empty. If so, an empty paragraph will be inserted between the scenes or
sections instead, resulting in a gap in the text. You can also switch on the :guilabel:`Hide`
setting, which will ignore them completely. That is, there won't even be an extra gap insetred.
setting, which will ignore them completely. That is, there won't even be an extra gap inserted.
Alternatively, if you want a separator text between them, like the common ``* * *``, you can enter
the desired separator text in the formatting box. In fact, if the format is any piece of static
text, it will always be treated as a separator.
the desired separator text as the format. If the format is any piece of static text, it will always
be treated as a separator.
Output Settings
@@ -115,15 +115,15 @@ Building Manuscript Documents
.. figure:: images/fig_build_build.png
The :guilabel:`Manuscript Build` dialog sued for writing the actual manuscript documents.
The :guilabel:`Manuscript Build` dialog used for writing the actual manuscript documents.
When you press the :guilabel:`Build` button on the :guilabel:`Build Manuscript` tool main window, a
special file dialog opens up. This is where you pick your desired output format and where to write
the file.
On the left is a list of all the available file formats, and on the right, a list of what documents
are included based on the build definition you selected. You can choose an output path, and set a
base file name as well. The file extension will be added automatically.
On the left side of the dialog is a list of all the available file formats, and on the right, a
list of the documents which are included based on the build definition you selected. You can choose
an output path, and set a base file name as well. The file extension will be added automatically.
To generate the manuscript document, press the :guilabel:`Build` button. A small progress bar will
show the build progress, but for small projects it may pass very fast.
@@ -137,7 +137,7 @@ Currently, four document formats are supported.
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. Most rich text editors support the
former, and a few the latter.
former, and only a few the latter.
novelWriter HTML
The HTML format writes a single ``.htm`` file with minimal style formatting. The HTML document
@@ -145,10 +145,10 @@ novelWriter HTML
word processors, or for printing from browser.
novelWriter Markup
This is simply a concatenation of the project documents selected by the filters. The documents
are stacked together in the order they appear in the project tree, with comments, tags, etc.
included if they are selected. This is a useful format for exporting the project for later
import back into novelWriter.
This is simply a concatenation of the project documents selected by the filters into a ``.txt``
file. The documents are stacked together in the order they appear in the project tree, with
comments, tags, etc. included if they are selected. This is a useful format for exporting the
project for later import back into novelWriter.
Standard/Extended Markdown
The Markdown format comes in both Standard and Extended flavour. The *only* difference in terms
@@ -161,7 +161,7 @@ Additional Formats
In addition to the above document formats, the novelWriter HTML and Markup formats can also be
wrapped in a JSON file. These files will have a meta data entry and a body entry. For HTML, also
the accompanying css styles are included.
the accompanying CSS styles used by the preview are included.
The text body is saved in a two-level list. The outer list contains one entry per document, in the
order they appear in the project tree. Each document is then split up into a list as well, with one
docs/source/project_overview.rst
+38 -37
View File
@@ -9,7 +9,7 @@ This will open the :guilabel:`New Project Wizard` that will assist you in creati
project suited to your needs.
A novelWriter project requires a dedicated folder for storing its files on the local file system.
See :ref:`a_storage` for further details on how files are organised.
If you're interested in the details, you can have a look at the chapter :ref:`a_storage`.
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 or
@@ -36,17 +36,14 @@ various elements of your story. Using them is of course entirely optional.
A new project may not have all of the root folders present, but you can add the ones you want from
the project tree tool bar.
Each root folder has one or more reference keyword associated with it that is used to reference
them from other documents and notes. The intended usage of each type of root folder is listed
below. However, aside from the :guilabel:`Novel` folder, no restrictions are applied by the
Each root folder has one or more :term:`reference` :term:`keyword` associated with it that is used
to reference them from other documents and notes. The intended usage of each type of root folder is
listed below. However, aside from the :guilabel:`Novel` folder, no restrictions are applied by the
application on what you put in them. You can use them however you want.
The root folder system is closesly connected to how the Tags and References system works. For more
details, see the :ref:`a_references` chapter.
.. tip::
You can make multiple root folders of each kind if you wish to split up your notes.
:guilabel:`Novel`
This is the root folder type for text that goes into the final novel or novels. This class of
documents have other rules and features than the project notes. See :ref:`a_struct` for more
@@ -54,8 +51,8 @@ details, see the :ref:`a_references` chapter.
:guilabel:`Plot`
This is the root folder type where main plots can be outlined. It is optional, but adding at
least brief notes can be useful in order to tag plot elements for the Outline View. Tags in this
folder can be references using the ``@plot`` keyword.
least brief notes can be useful in order to tag plot elements for the :guilabel:`Outline View`.
Tags in this folder can be references using the ``@plot`` keyword.
:guilabel:`Characters`
Character notes go in this root folder type. These are especially important if you want to use
@@ -63,7 +60,7 @@ details, see the :ref:`a_references` chapter.
told from a specific character's point-of-view, or focusing on a particular character's
storyline. Tags in this type of folder can be referenced using the ``@pov`` keyword for
point-of-view characters, ``@focus`` for a focus character, or the ``@char`` keyword for any
other character.
other character present.
:guilabel:`Locations`
The locations folder type is for various scene locations that you want to track. Tags in this
@@ -94,6 +91,9 @@ information about the tags listed, see :ref:`a_references_references`.
You can rename root folders to whatever you want. However, this doesn't change the reference
keyword or what they do.
.. versionadded:: 2.0
As of version 2.0, you can make multiple root folders of each kind to split up your project.
.. _a_proj_roots_del:
@@ -102,7 +102,7 @@ Deleted Documents
Deleted documents will be moved into a special :guilabel:`Trash` root folder. Documents in the
trash folder can then be deleted permanently, either individually, or by emptying the trash from
the menu. Documents in the trash folder are removed from the project index and cannot be
the menu. Documents in the trash folder are removed from the :term:`project index` and cannot be
referenced.
A document or a folder can be deleted from the :guilabel:`Project` menu, or by pressing
@@ -115,12 +115,12 @@ Archived Documents
------------------
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:`Archive`
root folder and move it there.
deleted accidentally, but still want it out of your main project tree, you can create an
:guilabel:`Archive` root folder and move it there.
You can drag any document to this folder and preserve its settings. The document will always be
excluded from the :guilabel:`Build Manuscript` tool. It is also removed from the project index, so
the tags and references defined in it will not show up anywhere else.
excluded from the :guilabel:`Build Manuscript` tool. It is also removed from the
:term:`project index`, so the tags and references defined in it will not show up anywhere else.
.. _a_proj_roots_orphaned:
@@ -131,19 +131,19 @@ Recovered Documents
If novelWriter crashes or otherwise exits without saving the project state, or if you're using a
file synchronisation tool that runs out of sync, there may be files in the project folder that
aren't tracked in the core project file. These files, when discovered, are recovered and added back
into the project, if possible.
into the project.
The discovered files are scanned for meta information that give clues as to where the document may
previously have been located in the project. The project loading routines will try to put them back
The discovered files are scanned for metadata that give clues as to where the document may
previously have been located in the project. The project loading routine will try to put them back
as close as possible to this location, if it still exists. Generally, it will be appended to the
end of the folder where it previously was located. If that folder doesn't exist, it will try to add
it to the correct root folder. If it cannot figure out which root folder is correct, the document
will be added to the :guilabel:`Novel` root folder. Finally, if the :guilabel:`Novel` folder is
missing, one will be created.
it to the correct root folder type. If it cannot figure out which root folder is correct, the
document will be added to the :guilabel:`Novel` root folder. Finally, if the :guilabel:`Novel`
folder is missing, one will be created.
If the title of the document can be recovered, the word "Recovered:" will be added as a prefix. If
the title cannot be determined, the document will be named after its internal key, which is a
string of characters and numbers.
If the title of the document can be recovered, the word "Recovered:" will be added as a prefix to
indicate that it may need further attention. If the title cannot be determined, the document will
be named after its internal key, which is a string of characters and numbers.
.. _a_proj_roots_lock:
@@ -176,7 +176,7 @@ Using Folders in the Project Tree
---------------------------------
Folders, aside from root folders, have no structural significance to the project. When novelWriter
is processing the documents in the novel, like for instance when you create a manuscript from it,
is processing the documents in a project, like for instance when you create a manuscript from it,
these folders are ignored. Only the order of the documents themselves matter.
The folders are there purely as a way for you to organise the documents in meaningful sections and
@@ -197,14 +197,15 @@ Project Documents
New documents can be created from the toolbar in the :guilabel:`Project Tree`, or by pressing
:kbd:`Ctrl+N`. This will open the create new item menu and let you choose between a number of
pre-defined documents and folders. You will be prompted for a label for the new item. You can
always rename an item by selecting :guilabel:`Rename Item` from the :guilabel:`Project` menu, or by
pressing :kbd:`F2`.
pre-defined documents and folders. You will be prompted for a label for the new item.
You can always rename an item by selecting :guilabel:`Rename Item` from the :guilabel:`Project`
menu, or by pressing :kbd:`F2`.
Other settings for project items are available from the context menu that you can activate by
right-clicking on an item in the :guilabel:`Project Tree`. The :guilabel:`Transform` submenu
includes options for converting, splitting, or merging items. See :ref:`a_ui_tree_split_merge` for
more details on the latter two.
right-clicking on an item in the tree. The :guilabel:`Transform` submenu includes options for
converting, splitting, or merging items. See :ref:`a_ui_tree_split_merge` for more details on the
latter two.
.. _a_proj_files_counts:
@@ -222,9 +223,9 @@ The word counts are not updated in real time, but run in the background every fe
long as the document is being actively edited.
A total project word count is displayed in the status bar. The total count depends on the sum of
the values in the project tree, which again depend on an up to date index. If the counts seem
wrong, a full project word recount can be initiated by rebuilding the project's index. Either from
the :guilabel:`Tools` menu, or by pressing :kbd:`F9`.
the values in the project tree, which again depend on an up to date :term:`project index`. If the
counts seem wrong, a full project word recount can be initiated by rebuilding the project's index.
Either from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`.
.. _a_proj_settings:
@@ -250,9 +251,9 @@ backup files may change too.
The :guilabel:`Novel Title` and :guilabel:`Authors` settings are used when building the manuscript,
for some formats.
If your project is in a different language than your main spell checking is set to, you can
override the default spell checking language here. You can also override the automatic backup
setting. The project language can also be changed from the :guilabel:`Tools` menu.
If your project is in a different language than your main spell checking language is set to, you
can override the default setting here. You can also override the automatic backup setting. The
project language can also be changed from the :guilabel:`Tools` menu.
Status and Importance Tabs
docs/source/project_references.rst
+27 -24
View File
@@ -5,14 +5,14 @@ Tags and References
*******************
In novelWriter there are no forms or tables to fill in to define the characters, locations and
other elements of your story. Instead, you can mark your :term:`Project Notes` as representing
these story elements by creating a :term:`tag`. Whenever you want to link a piece of yur story to
other elements of your story. Instead, you can mark your :term:`project notes` as representing
these story elements by creating a :term:`tag`. Whenever you want to link a piece of your story to
a note defining a story element, like a character, you create a :term:`reference` back to that tag.
You can also cross-link your Project Notes in the same way.
You can also cross-link your project notes in the same way.
This is perhaps one of the features that makes novelWriter quite different than other, similar
This is perhaps one of the features that makes novelWriter different from other, similar
applications. It is therefore not always obvious to new users how this is supposed to work, so
this chapter hopes to explains in more detail how these tags and references system works.
this chapter hopes to explains in more detail how to use the tags and references system.
.. tip::
If you find the Tags and Reference system difficult to follow just from reading this chapter,
@@ -30,11 +30,11 @@ The structure of your novelWriter project is inferred from the :term:`headings`
documents, not the documents themselves. See :ref:`a_struct_heads` for more details. Therefore,
metadata is also associated with headings, and not documents.
If you split your project into separate documents for each scene, this may not matter. However,
there are several benefits to using documents at a larger structural scale when starting your
project. For instance, it may make more sense to define all your scenes, and even chapters, in a
single document at first, or perhaps a document per act. You can later split these documents up
using the split feature. See :ref:`a_ui_tree_split_merge` for more details on this feature.
If you split your project into separate documents for each scene, this distinction may not matter.
However, there are several benefits to using documents at a larger structural scale when starting
your project. For instance, it may make more sense to define all your scenes, and even chapters, in
a single document at first, or perhaps a document per act. You can later split these documents up
using the document split feature. See :ref:`a_ui_tree_split_merge` for more details.
The implication here is that you can treat each heading as an independent element of your notes
that can be referenced somewhere else. In order to make it possible to reference a header section,
@@ -53,23 +53,23 @@ has to be unique across all documents in the project.
.. note::
In version 2.2, tags will be made case insensitive, but as of novelWriter 2.1 they are not. You
should avoid using tags that are only distinquished by case.
should however avoid using tags that are only distinguished by case.
Tags can then be referenced in the novel documents, or cross-referenced in other notes, and will
show up in the :guilabel:`Outline View` and in the back-reference panel when a document is opened
in the viewer.
After the tags have been defined, they can then be referenced in the novel documents, or
cross-referenced in other notes. they will also show up in the :guilabel:`Outline View` and in the
back-reference panel when a document is opened in the viewer.
The syntax highlighter will alert you that the keyword is correctly used and that the tag is
The syntax highlighter will indicate to you that the keyword is correctly used and that the tag is
allowed, that is, the tag is unique. Duplicate tags should be detected as long as the index is up
to date. An invalid tag should have a green wiggly line under it, and will not receive the syntax
colour that valid tags do.
The tag is the only part of these notes that the application uses. The rest of the document content
The tag is the only part of these notes that the novelWriter uses. The rest of the document content
is there for the writer to use in whatever way they wish. Of course, the content of the documents
can be added to the manuscript, or an outline document. If you want to compile a single document of
all your notes, you can do this from the :guilabel:`Manuscript Build` tool.
Example:
Example of a heading with a tag for a character of the story:
.. code-block:: none
@@ -81,10 +81,11 @@ Example:
When this is done in a document in a :term:`Root Folder` of type "Characters", the tag is
automatically treated as an available character in your project, and you will be able to reference
it in any of your other documents.
it in any of your other documents using the reference keywords for characters.
It is the root folder type that defines what category of story elements the tag is indexed under.
See the :ref:`a_proj_roots` section for an overview of availabe root folder types.
See the :ref:`a_proj_roots` section for an overview of availabe root folder types. They are also
covered in the next section.
.. _a_references_references:
@@ -98,7 +99,7 @@ other things.
References are set as a :term:`keyword` and a list of corresponding tags. The valid keywords are
listed below. The format of a reference line is ``@keyword: value1, [value2] ... [valueN]``. All
keywords allow multiple values.
reference keywords allow multiple values.
``@pov``
The point-of-view character for the current section. The target must be a note tag in a
@@ -141,9 +142,11 @@ keywords allow multiple values.
The syntax highlighter will alert the user that the tags and references are used correctly, and
that the tags referenced exist.
The highlighter may be mistaken if the index of defined tags is out of date. If so, press :kbd:`F9`
to regenerate it, or select :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu. In general,
the index for a document is regenerated when it is saved, so this shouldn't normally be necessary.
.. note::
The highlighter may be mistaken if the index of defined tags is out of date. If so, press
:kbd:`F9` to regenerate it, or select :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu.
In general, the index for a document is regenerated when it is saved, so this shouldn't normally
be necessary.
One note can also reference another note in the same way novel documents do. When the note is
opened in the document viewer, the references become clickable links, making it easier to follow
@@ -157,7 +160,7 @@ highlight that two notes are related.
.. tip::
If you cross-reference between notes and export your project as an HTML document using the
:guilabel:`Manuscript Build` tool, the cross-references become clickable links in the exported
HTML document.
HTML document as well.
Example of a novel document with references to characters and plots:
docs/source/project_structure.rst
+4 -5
View File
@@ -8,8 +8,7 @@ This chapter covers the structure of a novel project.
There are two different types of documents in a project, :guilabel:`Novel Documents` and
:guilabel:`Project Notes`. Novel documents can only live in a :guilabel:`Novel` type root folder.
You can also move them to :guilabel:`Archive` and :guilabel:`Trash` of course. This chapter covers
the former type.
You can also move them to :guilabel:`Archive` and :guilabel:`Trash` of course.
The :guilabel:`Project Tree` can distinguish between the different header levels of the novel
documents using coloured icons, and optionally add emphasis on the label, set in
@@ -22,16 +21,16 @@ Importance of Headings
======================
Subfolders under root folders have no impact on the structure of the novel itself. The structure is
instead dictated by the heading level of the headers within the documents.
instead dictated by the heading level of the headings within the documents.
Four levels of headings are supported, signified by the number of hashes (``#``) preceding the
title. See also the :ref:`a_fmt` section for more details about the markdown syntax.
title. See also the :ref:`a_fmt` section for more details about the markup syntax.
.. note::
The header levels are not only important when generating the manuscript, they are also used by
the indexer when building the outline tree in the :guilabel:`Outline View` as well as in the
:guilabel:`Novel Tree`. Each heading also starts a new region where new Tags and References
can be defined. See :ref:`a_references`.
can be defined. See :ref:`a_references` for more details.
The syntax for the four basic header types, and the two special header types, is listed in section
:ref:`a_fmt_head`. The meaning of the four levels for the structure of your novel is as follows:
docs/source/tech_locations.rst
+9 -7
View File
@@ -7,7 +7,7 @@ File Locations
.. _QStandardPaths: https://doc.qt.io/qt-5/qstandardpaths.html
novelWriter will create a few files on your system outside of the application folder itself. These
file locations are described in this document.
file locations are described in this chapter.
.. _a_locations_conf:
@@ -17,15 +17,16 @@ Configuration
The general configuration of novelWriter, including everything that is in :guilabel:`Preferences`,
is saved in one central configuration file. The location of this file depends on your operating
system. The system paths are provided by the Qt QStandardPaths_ class and its ConfigLocation value.
system. The system paths are provided by the Qt QStandardPaths_ class and its ``ConfigLocation``
value.
The standard paths are:
* Linux: ``~/.config/novelwriter/novelwriter.conf``
* macOS: ``~/Library/Preferences/novelwriter/novelwriter.conf``
* MacOS: ``~/Library/Preferences/novelwriter/novelwriter.conf``
* Windows: ``C:\Users\<USER>\AppData\Local\novelwriter\novelwriter.conf``
Here, ``~`` corresponds to the user's home directory on Linux and macOS, and ``<USER>`` is the
Here, ``~`` corresponds to the user's home directory on Linux and MacOS, and ``<USER>`` is the
user's username on Windows.
.. note::
@@ -40,15 +41,16 @@ Application Data
novelWriter also stores a bit of data that is generated by the user's actions. This includes the
list of recent projects form the :guilabel:`Open Project` dialog. Custom themes should also be
saved here. The system paths are provided by the Qt QStandardPaths_ class and its AppDataLocation.
saved here. The system paths are provided by the Qt QStandardPaths_ class and its
``AppDataLocation`` value.
The standard paths are:
* Linux: ``~/.local/share/novelwriter/``
* macOS: ``~/Library/Application Support/novelwriter/``
* MacOS: ``~/Library/Application Support/novelwriter/``
* Windows: ``C:\Users\<USER>\AppData\Roaming\novelwriter\``
Here, ``~`` corresponds to the user's home directory on Linux and macOS, and ``<USER>`` is the
Here, ``~`` corresponds to the user's home directory on Linux and MacOS, and ``<USER>`` is the
user's username on Windows.
.. note::
docs/source/tech_source.rst
+13 -13
View File
@@ -8,7 +8,7 @@ Running from Source
.. _PyPi: https://pypi.org/project/novelWriter/
.. _Sphinx Docs: https://www.sphinx-doc.org/
This section describes various ways of running novelWriter directly from the source code, and how
This chapter describes various ways of running novelWriter directly from the source code, and how
to build the various components like the translation files and documentation.
.. note::
@@ -30,11 +30,11 @@ by running:
Dependencies
============
novelWriter has been designed to rely on as few dependencies as possible. Aside from the packages
needed to communicate with the Qt GUI libraries, only one package is required for handling the XML
format of the main project file. Everything else is handled with standard Python libraries.
novelWriter has been designed to rely on as few dependencies as possible. Only the Python wrapper
for the Qt GUI libraries is required. The package for spell checking is optional, but recommended.
Everything else is handled with standard Python libraries.
The following Python packages are needed to run novelWriter:
The following Python packages are needed to run all features of novelWriter:
* ``PyQt5`` – needed for connecting with the Qt5 libraries.
* ``PyEnchant`` – needed for spell checking (optional).
@@ -53,7 +53,6 @@ source, dependencies can still be installed from PyPi with:
pip install -r requirements.txt
.. note::
On Linux distros, the Qt library is usually split up into multiple packages. In some cases,
secondary dependencies may not be installed automatically. For novelWriter, the library files
for renderring the SVG icons may be left out and needs to be installed manually. This is the
@@ -70,7 +69,7 @@ build the package using the Python Packaging Authority's build tool. It can be i
.. code-block:: bash
pip install --upgrade build
pip install build
On Debian-based systems the tool can also be installed with:
@@ -82,11 +81,11 @@ With the tool installed, run the following command from the root of the novelWri
.. code-block:: bash
python -m build
python -m build --wheel
This should generate two files in the ``dist/`` folder at your current location. One with file
extension ``.tar.gz`` and one with extension ``.whl``. The latter is the package you want to
install, here with example version number 2.0.7, but yours may be different:
This should generate a ``.whl`` file in the ``dist/`` folder at your current location. The wheel
file can then be installed on your system. Here with example version number 2.0.7, but yours may be
different:
.. code-block:: bash
@@ -124,7 +123,8 @@ Building the Example Project
============================
In order to be able to create new projects from example files, you need a ``sample.zip`` file in
the ``assets`` folder of the source. This file can be built from setup script by running:
the ``assets`` folder of the source. This file can be built from the ``pkgutils.py`` script by
running:
.. code-block:: bash
@@ -152,7 +152,7 @@ The documentation can then be built from the root folder in the source code by r
If successful, the documentation should be available in the ``docs/build/html`` folder and you can
open the ``index.html`` file in your browser.
You can also build a PDF manual from the documentation using the setup script:
You can also build a PDF manual from the documentation using the ``pkgutils.py`` script:
.. code-block:: bash
docs/source/tech_storage.rst
+9 -9
View File
@@ -6,27 +6,27 @@ How Data is Stored
.. _documentation: https://docs.novelwriter.io/
This section contains details of how novelWriter stores and handles the project data.
This chapter contains details of how novelWriter stores and handles the project data.
Project Structure
=================
All novelWriter files are written with utf-8 encoding. Since Python automatically converts Unix
line endings to Windows line endings on Windows systems, and vice versa, novelWriter does not make
any adaptations to the formatting on Windows systems. This is handled entirely by the Python
standard library. Python also handles this when working on the same files on both Windows and
Unix-based operating systems.
line endings to Windows line endings on Windows systems, novelWriter does not make any adaptations
to the formatting on Windows systems. This is handled entirely by the Python standard library.
Python also handles this when working on the same files on both Windows and Unix-based operating
systems.
Main Project File
-----------------
The project itself requires a dedicated folder for storing its files, where novelWriter will create
its own "file system" where the folder and file hierarchy is described in a project XML file. This
is the main project file in the project's root folder with the name ``nwProject.nwx``. This file
also contains all the meta data required for the project (except the index data), and a number of
related project settings.
its own "file system" where the project's folder and file hierarchy is described in a project XML
file. This is the main project file in the project's root folder with the name ``nwProject.nwx``.
This file also contains all the meta data required for the project (except the index data), and a
number of related project settings.
If this file is lost or corrupted, the structure of the project is lost, although not the text
itself. It is important to keep this file backed up, either through the built-in backup tool, or
docs/source/tech_tests.rst
+6 -7
View File
@@ -34,12 +34,11 @@ Since several of the tests involve opening up the novelWriter GUI, you may want
for the duration of the test run. Moving your mouse while the tests are running may otherwise
interfere with the execution of some tests.
You can disable the renderring of the GUI by setting the flag ``export QT_QPA_PLATFORM=offscreen``,
or alternatively run the tests with the ``xvfb`` package, like so:
You can disable the renderring of the GUI by setting the flag ``QT_QPA_PLATFORM=offscreen``:
.. code-block:: bash
xvfb-run pytest
export QT_QPA_PLATFORM=offscreen pytest
Advanced Options
@@ -51,7 +50,7 @@ You can also add coverage report generation. For instance to HTML:
.. code-block:: bash
xvfb-run pytest -v --cov=novelwriter --cov-report=html
export QT_QPA_PLATFORM=offscreen pytest -v --cov=novelwriter --cov-report=html
Other useful report formats are ``xml``, and ``term`` for terminal output.
@@ -60,7 +59,7 @@ subpackage groups are ``base``, ``core``, and ``gui``. Consider for instance:
.. code-block:: bash
xvfb-run pytest -v --cov=novelwriter --cov-report=html -m core
export QT_QPA_PLATFORM=offscreen pytest -v --cov=novelwriter --cov-report=html -m core
This will only run the tests of the "core" package, that is, all the classes that deal with the
project data of a novelWriter project. The "gui" tests, likewise, will run the tests for the GUI
@@ -71,7 +70,7 @@ You can also filter the tests with the ``-k`` switch. The following will do the
.. code-block:: bash
xvfb-run pytest -v --cov=novelwriter --cov-report=html -k testCore
export QT_QPA_PLATFORM=offscreen pytest -v --cov=novelwriter --cov-report=html -k testCore
All tests are named in such a way that you can filter them by adding more bits of the test names.
They all start with the word "test". Then comes the group: "Core", "Base", "Dlg", "Tool", or "Gui".
@@ -80,6 +79,6 @@ file. For instance, running the following will run all tests for the document ed
.. code-block:: bash
xvfb-run pytest -v --cov=novelwriter --cov-report=html -k testGuiEditor
export QT_QPA_PLATFORM=offscreen pytest -v --cov=novelwriter --cov-report=html -k testGuiEditor
To run a single test, simply add the full test name to the ``-k`` switch.
docs/source/usage_breakdown.rst
+45 -37
View File
@@ -8,9 +8,9 @@ How it Works
.. _Pandoc: https://pandoc.org/
.. _Open Document: https://en.wikipedia.org/wiki/OpenDocument
The main features of novelWriter are listed in the :ref:`a_intro` section. Here, we go into some
more details on how they are implemented. This is intended as an overview. Later on in this
documentation, these features will be covered in more detail.
The main features of novelWriter are listed in the :ref:`a_intro` chapter. In this chapter, we go
into some more details on how they are implemented. This is intended as an overview. Later on in
this documentation, these features will be covered in more detail.
.. _a_breakdown_design:
@@ -19,20 +19,20 @@ GUI Layout and Design
=====================
The user interface of novelWriter is intended to be as minimalistic as practically possible, while
at the same time provide a complete set of features needed for writing a novel.
at the same time provide useful features needed for writing a novel.
The main window does not have an editor toolbar like many other applications do. This reduces
clutter, and since the documents are formatted with style tags, it is more or less redundant.
Most formatting features supported are available through convenient keyboard shortcuts. They are
also available in the main menu, so you don't have to look up formatting codes every time you need
them. For reference, a list of all shortcuts can be found in the :ref:`a_kb` section.
them. For reference, a list of all shortcuts can be found in the :ref:`a_kb` chapter.
.. note::
novelWriter is not intended to be a full office type word processor. It doesn't support images,
links, tables, and other complex structures and objects often needed for such documents.
Formatting is limited to headers, emphasis, text alignment, and a few other simple features.
On the left edge of the main window, you will find a sidebar. This bar has buttons for the standard
On the left side of the main window, you will find a sidebar. This bar has buttons for the standard
views you can switch between, a quick link to the :guilabel:`Build Manuscript` tool, and a set of
project-related tools and quick access to settings at the bottom.
@@ -46,11 +46,13 @@ Project Tree View
When in :guilabel:`Project Tree View` mode, the main work area of 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. An optional third panel on the right
contains a document viewer which can view any document in your project independently of what is
open in the document editor. This panel is not intended as a preview window, although you can use
it for this purpose if you wish as it will apply the formatting tags you have specified. The main
purpose of the viewer is for viewing your notes next to your editor while you're writing.
your project. The second panel is the document editor.
An optional third panel on the right contains a document viewer which can view any document in your
project independently of what is open in the document editor. This panel is not intended as a
preview window, although you can use it for this purpose if you wish as it will apply the
formatting tags you have specified. The main purpose of the viewer is for viewing your notes next
to your editor while you're writing.
The editor also has a :guilabel:`Focus Mode` you can toggle either from the menu, from the icon in
the editor's header, or by pressing :kbd:`F8`. When :guilabel:`Focus Mode` is enabled, all the user
@@ -79,15 +81,15 @@ the novel icon button next to it.
Generally, the novel view should update when you make changes to the novel structure, including
edits of the current document in the editor. The information is only updated when the automatic
save of the document is triggered, or you manually press :kbd:`Ctrl+S` to save changes. You can
adjust the auto-save interval in :guilabel:`Preferences`. You can also regenerate the whole novel
save of the document is triggered, or you manually press :kbd:`Ctrl+S` to save changes. (You can
adjust the auto-save interval in :guilabel:`Preferences`.) You can also regenerate the whole novel
view by pressing the refresh button at the top of the side panel.
It is possible to show an optional third column in the novel view, The settings are available from
the menu button ath the top.
the menu button in the toolbar.
If you click the arrow icon to the right of each item, a tooltip will pop up showing you all the
meta data collected for that heading entry.
If you click the arrow icon to the right of each item, a tooltip will pop out showing you all the
meta data collected for that heading.
Novel Outline View
@@ -111,8 +113,8 @@ Colour Themes
By default, novelWriter will use the colour theme provided by the Qt library, which is determined
by the Fusion_ style setting. You can also choose between a standard dark and light theme that have
neutral colours from :guilabel:`Preferences`. Other colour themes are also available, and more can
be contributed by users to the project.
neutral colours from :guilabel:`Preferences`. Other colour themes are also available. More themes
can be contributed to novelWriter on GitHub.
Switching the GUI colour theme does not affect the colours of the editor and viewer. They have
separate colour themes called :guilabel:`Editor Themes`. They are separated because there are a lot
@@ -143,9 +145,9 @@ within those documents.
The four heading levels (**H1** to **H4**) are treated as follows:
* **H1** is used for the book title, and for partitions.
* **H1** is used for the novel title, and for partitions.
* **H2** is used for chapter tiles.
* **H3** is used for scene titles – optionally replaced by separators.
* **H3** is used for scene titles -- optionally replaced by separators.
* **H4** is for section titles within scenes, if such granularity is needed.
The project tree will select an icon for the document based on the first heading in it.
@@ -157,7 +159,8 @@ whatever they want. See :ref:`a_struct` and :ref:`a_references` for more details
.. versionadded:: 2.0
You can add documents as child items of other documents. This is often more useful than adding
folders, since you anyway may want to have the chapter heading in a separate document from your
individual scene documents so that you can rearrange scene documents freely.
individual scene documents so that you can rearrange scene documents freely without affecting
chapter placement.
.. _a_breakdown_export:
@@ -177,7 +180,8 @@ In addition, you can export the content of the project to a JSON file. This is u
to write your own custom processing script in for instance Python, as the entire novel can be read
into a Python dictionary with a couple of lines of code. The JSON file can be populated with either
HTML formatted text, or with the raw text as typed into the novel documents.
See :ref:`a_manuscript_build` for more details.
See :ref:`a_manuscript` for more details.
.. versionadded:: 2.1
You can now define multiple build definitions in the :guilabel:`Build Manuscript` tool. This
@@ -192,31 +196,35 @@ Project Storage
The files of a novelWriter project are stored in a dedicated project folder. The project structure
is kept in a file at the root of this folder called ``nwProject.nwx``. All the document files and
associated meta data is stored in the other folders below the project folder. For more technical
associated meta data is stored in other folders below the project folder. For more technical
details about what all the files mean and how they're organised, see the :ref:`a_storage` section.
This way of storing data was chosen for several reasons. Firstly, all the text you add to your
project is saved directly to your project folder in separate files. Only the project structure and
the text you are currently editing is stored in memory at any given time. Secondly, having multiple
small files means it is very easy to synchronise them between computers with standard file
synchronisation tools. Thirdly, if you use version control software to track the changes to your
project, the file formats used for the files are well suited. Also the JSON documents have line
breaks and indents, which makes it easier to track them with version control software.
This way of storing data was chosen for several reasons.
Firstly, all the text you add to your project is saved directly to your project folder in separate
files. Only the project structure and the text you are currently editing is stored in memory at any
given time, which means there is a smaller risk of losing data if the application or your computer
crashes.
Secondly, having multiple small files means it is very easy to synchronise them between computers
with standard file synchronisation tools.
Thirdly, if you use version control software to track the changes to your project, the file formats
used for the files are well suited. Also the JSON documents have line breaks and indents, which
makes it easier to track them with version control software.
.. note::
Since novelWriter has to keep track of a bunch of files and folders when a project is open, it
may not run well on some virtual file systems. A file or folder must be accessible with exactly
the path it was saved or created with. An example where this is not the case is the way Google
Drive is mapped on Linux Gnome desktops using gvfs/gio.
.. caution::
You should not add additional files to the project folder yourself. Nor should you,a s a rule,
manually edit files within it. If you really must manually edit the text files, e.g. with some
automated task you want to perform, you need to rebuild the :term:`Project Index` when you open
the project again.
You should not add additional files to the project folder yourself. Nor should you manually edit
files within it as a general rule. If you really must manually edit the text files, e.g. with
some automated task you want to perform, you need to rebuild the :term:`Project Index` when you
open the project again.
Editing text files in the ``content`` folder is less risky as they are just plain text. Editing
Editing text files in the ``content`` folder is less risky as these are just plain text. Editing
the main project XML file, however, may make the project file unreadable and you may crash
novelWriter and lose project structure information and project settings.
docs/source/usage_format.rst
+9 -10
View File
@@ -11,7 +11,7 @@ values and allowing for some text formatting. The syntax is based on Markdown, b
In addition to formatting codes, novelWriter allows for comments, a synopsis tag, and a set of
keyword and value sets used for :term:`tags<tag>` and :term:`references<reference>`. There are also
some codes that apply to whole paragraphs. See :ref:`a_fmt_text` below for more details.
some codes that apply to whole paragraphs. See :ref:`a_fmt_text` for more details.
.. _a_fmt_hlight:
@@ -65,7 +65,7 @@ correctly to produce the intended result. See :ref:`a_struct_heads` for more det
``#### Title Text``
Heading level four. For novel documents, the header level indicates the start of a new section.
Section titles can be replaced by separators or removed completely when building the manuscript.
Section titles can be replaced by separators or ignored completely when building the manuscript.
For headers level one and two, adding a ``!`` modifies the behaviour of the heading:
@@ -165,9 +165,9 @@ The text of a comment is ignored by the word counter. The text can also be filte
building the manuscript or viewing the document.
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.
in a special manner 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 renderred by default (this can be overridden), seen in the
@@ -204,8 +204,8 @@ References are on the form:
``@keyword: value``
A reference keyword followed by a value, or a comma separated list of values.
The available reference keywords are listed in the :ref:`a_references_references` section. They can
also be inserted at the cursor position in the editor via the :guilabel:`Insert` menu.
Tags andreferences are covered in detail in the :ref:`a_references` chapter. The keywords can be
inserted at the cursor position in the editor via the :guilabel:`Insert` menu.
.. _a_fmt_align:
@@ -214,7 +214,7 @@ Paragraph Alignment and Indentation
===================================
All documents have the text by default aligned to the left or justified, depending on your
Preferences.
settings in :guilabel:`Preferences`.
You can override the default text alignment on individual paragraphs by specifying alignment tags.
These tags are double angle brackets. Either ``>>`` or ``<<``. You put them either before or after
@@ -262,8 +262,7 @@ headers of level two for novel documents, i.e. chapters, but not for project not
If you need to add a page break somewhere else, put the text ``[NEW PAGE]`` on a line by itself
before the text you wish to start on a new page.
Page breaks are automatically added to partition, chapter and unnumbered chapter headers of novel
documents. If you want such breaks for scenes and sections, you must add them manually.
If you want page breaks for scenes and sections, you must add them manually.
.. note::
The page break code is applied to the text that follows it. It adds a "page break before" mark
docs/source/usage_project.rst
+15 -14
View File
@@ -4,7 +4,7 @@
Project Views
*************
This sections covers in more detail the different project views available in novelWriter.
This chapter covers in more detail the different project views available in novelWriter.
.. figure:: images/fig_project_tree_detailed.png
@@ -81,14 +81,14 @@ Splitting Documents
The :guilabel:`Split Document` dialog.
The :guilabel:`Split Document by Header` option will open a dialog that allows you to split the
selected document into multiple new documents based on the headers it contains. You can select at
which header level the split is to be performed from the dropdown box. The list box will preview
which headers will be split into new documents.
selected document into multiple new documents based on the headings it contains. You can select at
which heading level the split is to be performed from the dropdown box. The list box will preview
which headings will be split into new documents.
You are given the option to create a folder for these new documents, and whether or not to create a
hierarchy of documents. That is, put sections under scenes, and scenes under chapters.
The source document **is not** deleted in the process, but you have the option to let the tool move
The source document *is not* deleted in the process, but you have the option to let the tool move
the source document to the :guilabel:`Trash` folder.
Merging Documents
@@ -119,9 +119,9 @@ Each document or folder in your project can have either a "Status" or "Importanc
are flags that you control and define yourself. novelWriter doesn't do anything with them at all.
To modify the labels, go to their respective tabs in :guilabel:`Project Settings`.
The "Status" flag is intended to tag a :term:`Novel document<novel documents>` as for instance a
The "Status" flag is intended to tag a :term:`novel document<novel documents>` as for instance a
draft or as completed, and the "Importance" flag is intended to tag character notes, or other
:term:`project notes`, as for instance a main, major or minor character.
:term:`project notes`, as for instance a main, major, or minor character or story element.
Whether a document uses a "Status" or "Importance" flag depends on which :term:`root folder` it
lives in. If it's in a :guilabel:`Novel` folder, it uses the "Status" flag, otherwise it uses an
@@ -139,10 +139,11 @@ your manuscript in the :guilabel:`Manuscript Build` tool.
Drag & drop has only limited support for moving documents. In general, bulk actions are not
allowed. This is deliberate to avoid accidentally messing up your project. If you make a mistake,
the last move action can be undone by pressing :kbd:`Ctrl+Shift+Z`.
the last move action can be undone by pressing :kbd:`Ctrl+Shift+Z` or from the menu icon in the
project tree's toolbar.
Documents and their folders can be rearranged freely within their root folders. If you move a Novel
documents out of a Novel folder, it will be converted to a project note. Notes can be moved freely
document out of a Novel folder, it will be converted to a project note. Notes can be moved freely
between all root folders, but keep in mind that if you move a note into a :guilabel:`Novel` root
folder, its "Importance" setting will be switched with a "Status" setting. See
:ref:`a_ui_tree_status`. The old value will not be overwritten though, and should be restored if
@@ -171,7 +172,7 @@ of the story itself rather than the document files.
You cannot reorganise the entries in the novel tree, or add any new documents, as that would
imply restructuring the content of the document files themselves. Any such editing must be done
in the project tree. However, you can add new headings to existing documents, or change
references, which will be updated in this view.
references, which will be updated in this view when the document is saved.
.. _a_ui_outline:
@@ -189,16 +190,16 @@ the novel, that is, the level 1 to 4 headings representing partitions, chapters,
sections.
The document containing the heading can also be displayed as a separate column, as well as the line
number where it occurs. Double-clicking an entry will open the corresponding document in the
editor.
number where the heading is defined. Double-clicking an entry will open the corresponding document
in the editor and switch to :guilabel:`Project Tree View` mode.
You can select which novel folder to display from the dropdown menu. You can optionally also choose
to show a combination of all novel folders.
.. note::
Since the internal structure of the novel does not depend directly on the folder and document
structure of the project tree, these will not necessarily look the same, depending on how you
choose to organise your documents. See the :ref:`a_struct` page for more details.
structure of the project tree, this view will not necessarily look the same, depending on how
you choose to organise your documents. See the :ref:`a_struct` page for more details.
Various meta data and information extracted from :term:`tags<tag>` can be displayed in columns in
the outline. A default set of such columns is visible, but you can turn on or off more columns from
docs/source/usage_projectformat.rst
+4 -5
View File
@@ -11,15 +11,14 @@ Most of the changes to the file formats over the history of novelWriter have no
user side of things. The project files are generally updated automatically. However, some of the
changes require minor actions from the user.
The key changes in the formats are listed below, as well as the user actions required, where
applicable.
The key changes in the formats are listed in this chapter, as well as the user actions required,
where applicable.
.. only:: not html
A full project file format specification is available in the online documentation_.
.. caution::
When you update a project from one format version to the next, the project can no longer be
opened by a version of novelWriter prior to the version where the new file format was
introduced. You will get a notification about any updates to your project file format and will
@@ -71,7 +70,7 @@ Format 1.3 Changes
This project format was introduced in novelWriter version 1.5.
With this format, the number of document layouts was reduced from 8 to 2. The conversion of
With this format, the number of document layouts was reduced from eight to two. The conversion of
document layouts is performed automatically when the project is opened.
Due to the reduction of layouts, some features that were previously controlled by these layouts
@@ -85,7 +84,7 @@ should be used only a few places in any given project. These are as follows:
* The formatting of the level one title on the title page must be changed from ``# Title Text`` to
``#! Title Text`` in order to retain the previous functionality. See :ref:`a_fmt_head`.
* Any text that was previously centred on the page must be manually centred using the new text
* Any text that was previously centred on the page must be manually centred using the text
alignment feature. See :ref:`a_fmt_align`.
**Unnumbered Chapters**
docs/source/usage_shortcuts.rst
+2 -2
View File
@@ -5,10 +5,10 @@ Keyboard Shortcuts
******************
Most features in novelWriter are available as keyboard shortcuts. This is a reference list if these
shortcuts. Most of them are also listed in the application.
shortcuts. Most of them are also listed in the application's user interface.
.. note::
On macOS, replace :kbd:`Ctrl` with :kbd:`Cmd`.
On MacOS, replace :kbd:`Ctrl` with :kbd:`Cmd`.
.. _a_kb_main:
docs/source/usage_typography.rst
+3 -3
View File
@@ -59,8 +59,8 @@ 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
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, 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
misunderstanding their meaning in the text.
@@ -81,7 +81,7 @@ right single quotation marks, depending on the font. There is a Wikipedia articl
.. note::
On export with the :guilabel:`Build Manuscript` tool, these apostrophes will be replaced
automatically with the corresponding right hand single quote symbol as is generally recommended.
Therefore it doesn't really matter if you only use them to correct highlighting.
Therefore it doesn't really matter if you only use them to correct syntax highlighting.
Special Space Symbols
docs/source/usage_writing.rst
+16 -16
View File
@@ -6,7 +6,7 @@ The Editor and Viewer
.. _Compose Key: https://en.wikipedia.org/wiki/Compose_key
This sections covers in more detail how the document editor and viewer panels work.
This chapter covers in more detail how the document editor and viewer panels work.
.. _a_ui_edit:
@@ -21,7 +21,7 @@ Editing a Document
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
Markdown-like syntax for some features, and a novelWriter-specific syntax for others. The syntax
format is described in the :ref:`a_fmt` section.
format is described in the :ref:`a_fmt` chapter.
The editor has a maximise button (toggles the :guilabel:`Focus Mode`) and a close button in the
top--right corner. On the top--left side you will find an edit button that opens the
@@ -33,8 +33,8 @@ header at the top of the edit or view panel. Optionally, the full project path t
be shown. This can be set in :guilabel:`Preferences`.
.. tip::
Clicking on the document title bar will select the document in the project tree and reveal its
location, making it easier to locate in a large project.
Clicking on the document title bar will select the document in the project tree and thus reveal
its location there, making it easier to find in a large project.
Any :term:`references<reference>` in the editor can be opened in the viewer by moving the cursor to
the label and pressing :kbd:`Ctrl+Return`. You can also control-click them with your mouse.
@@ -54,10 +54,10 @@ viewer. To view a document, press :kbd:`Ctrl+R`, or select :guilabel:`View Docum
context menu. If you have a middle mouse button, middle-clicking on the document will also open it
in the viewer.
The document viewed does not have to be the same document as currently being edited. However, If
you *are* viewing the same document, pressing :kbd:`Ctrl+R` again will update the document with
your latest changes. You can also press the reload button in the top--right corner of the view
panel, next to the close button, to achieve the same thing.
The document viewed does not have to be the same document as the one currently being edited.
However, If you *are* viewing the same document, pressing :kbd:`Ctrl+R` again will update the
document with your latest changes. You can also press the reload button in the top--right corner of
the viewer panel, next to the close button, to achieve the same thing.
In the viewer :term:`references<reference>` become clickable links. Clicking them will replace the
content of the viewer with the content of the document the reference points to.
@@ -75,10 +75,10 @@ This is convenient if you want to quickly look through all documents in the list
: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
maintained automatically. However, if anything is missing, or seems wrong, the index can always
be rebuilt by selecting :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu, or by
pressing :kbd:`F9`.
The :guilabel:`References` panel relies on an up-to-date :term:`index<project index>` of the
project. The index is maintained automatically. However, if anything is missing, or seems wrong,
the index can always be rebuilt by selecting :guilabel:`Rebuild Index` from the
:guilabel:`Tools` menu, or by pressing :kbd:`F9`.
.. _a_ui_edit_search:
@@ -124,8 +124,8 @@ 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_kb_ins`. You may also be using a
`Compose Key`_ setup, which means you may not need the auto-replace feature.
the :guilabel:`Insert` menu, and via :ref:`a_kb_ins`. You may also be using a `Compose Key`_
setup, which means you may not need the auto-replace feature at all.
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
@@ -135,5 +135,5 @@ tricky for languages that use the same symbol for these, like English does.
.. tip::
If the auto-replace feature changes a symbol when you did not want it to change, pressing
:kbd:`Ctrl+Z` immediately after the auto-replacement will undo it without undoing the character
you typed.
:kbd:`Ctrl+Z` once after the auto-replacement will undo it without undoing the character
you typed before it.