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

Update project documentation

Browse Source
This commit is contained in:
Veronica Berglyd Olsen
2024-04-13 18:18:06 +02:00
parent cae0977a01
commit a3ebe24eb7
8 changed files with 267 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/project_overview.rst
+122 -113
View File
@@ -4,25 +4,27 @@
Novel Projects
**************
New projects can be created from the :guilabel:`Project` menu by selecting
:guilabel:`Create or Open Project`. This will open the :guilabel:`Welcome` dialog, where you can
select the :guilabel:`New` button that will assist you in creating a new project.
New projects can be created from the **Project** menu by selecting **Create or Open Project**. This
will open the **Welcome** dialog, where you can select the :guilabel:`New` button that will assist
you in creating a new project. This dialog is also displayed when you start novelWriter.
A novelWriter project requires a dedicated folder for storing its files on the local file system.
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:`Welcome`
dialog. A project can be removed from this list by selecting it and pressing the :kbd:`Del` key or
by right-clicking it and selecting the :guilabel:`Remove Project` option.
A list of recently opened projects is maintained, and displayed in the **Welcome** dialog. A
project can be removed from this list by selecting it and pressing the :kbd:`Del` key or by
right-clicking it and selecting the **Remove Project** option.
.. figure:: images/fig_welcome.jpg
The project list (left) and new project form (right) of the :guilabel:`Welcome` dialog.
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's
novel text, including word counts, and a table of contents with word and page counts, is available
through the :guilabel:`Novel Details` dialog.
Project-specific settings are available in **Project Settings** in the **Project** menu. See
further details below in the :ref:`a_proj_settings` section.
Details about the project's novel text, including word counts, and a table of contents with word
and page counts, is available through the **Novel Details** dialog. Statistics about the project
is also available in the **Manuscript Build** tool.
.. _a_proj_roots:
@@ -33,64 +35,70 @@ Project Roots
Projects are structured into a set of top level folders called "Root Folders". They are visible in
the project tree at the left side of the main window.
The :term:`novel documents` go into a root folder of type :guilabel:`Novel`. :term:`Project notes`
go into the other root folders. These other root folder types are intended for your notes on the
various elements of your story. Using them is of course entirely optional.
The :term:`novel documents` go into a root folder of type **Novel**. :term:`Project notes` go into
the other root folders. These other root folder types are intended for your notes on the 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 :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
listed below. However, aside from the **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 closely connected to how the Tags and References system works. For more
details, see the :ref:`a_references` chapter.
:guilabel:`Novel`
Root Folder Types
-----------------
**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
details.
:guilabel:`Plot`
**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 :guilabel:`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 **Outline View**. Tags in
this folder can be references using the ``@plot`` keyword.
:guilabel:`Characters`
**Characters**
Character notes go in this root folder type. These are especially important if you want to use
the :guilabel:`Outline View` to see which character appears where, which part of the story is
told from a specific character's point-of-view, or focusing on a particular character's
storyline. The character names can also be inserted into for instance chapter titles when you
create your manuscript. 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
the **Outline View** to see which character appears where, which part of the story is told from
a specific character's point-of-view, or focusing on a particular character's storyline.
The character names can also be inserted into for instance chapter titles when you create your
manuscript. 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 present.
:guilabel:`Locations`
**Locations**
The locations folder type is for various scene locations that you want to track. Tags in this
folder can be references using the ``@location`` keyword.
:guilabel:`Timeline`
**Timeline**
If the story has multiple plot timelines or jumps in time within the same plot, this folder type
can be used to track this. Tags in this type of folder can be references using the ``@time``
keyword.
:guilabel:`Objects`
Important objects in the story, for instance objects that change hands often, can be tracked
here. Tags in this type of folder can be references using the ``@object`` keyword.
**Objects**
Important objects in the story, for instance physical objects that change hands often, can be
tracked here. Tags in this type of folder can be references using the ``@object`` keyword.
:guilabel:`Entities`
**Entities**
Does your plot have many powerful organisations or companies? Or other entities that are part of
the plot? They can be organised here. Tags in this type of folder can be references using the
``@entity`` keyword.
:guilabel:`Custom`
**Custom**
The custom root folder type can be used for tracking anything else not covered by the above
options. Tags in this folder type can be references using the ``@custom`` keyword.
The root folders correspond to the categories of tags that can be used to reference them. For more
information about the tags listed, see :ref:`a_references_references`.
The root folders are closely tied to the tags and reference system. Each folder type corresponds to
the categories of tags that can be used to reference them. For more information about the tags
listed, see :ref:`a_references_references`.
.. note::
You can rename root folders to whatever you want. However, this doesn't change the reference
@@ -105,12 +113,11 @@ information about the tags listed, see :ref:`a_references_references`.
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 :term:`project index` and cannot be
referenced.
Deleted documents are moved into a special **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 :term:`project index` and cannot be referenced.
A document or a folder can be moved to trash from the :guilabel:`Project` menu, or by pressing
A document or a folder can be moved to trash from the **Project** menu, or by pressing
:kbd:`Ctrl+Shift+Del`. Root folders can only be removed when they are empty.
@@ -119,13 +126,34 @@ A document or a folder can be moved to trash from the :guilabel:`Project` menu,
Archived Documents
------------------
If you don't want to delete a document, or put it in the :guilabel:`Trash` folder where it may be
deleted accidentally, but still want it out of your main project tree, you can create an
:guilabel:`Archive` root folder and move it there.
If you don't want to delete a document, or put it in the **Trash** folder where it may be deleted
accidentally, but still want it out of your main project tree, you can create an **Archive** root
folder instead and move it there. It has the same effect as moving it to **Trash**, but it is safe
from deletion.
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
:term:`project index`, so the tags and references defined in it will not show up anywhere else.
excluded from the **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_dirs:
Using Folders in the Project Tree
---------------------------------
Regular folders, those that are not root folders, have no structural significance to the project.
When novelWriter 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
to be able to collapse and hide them in the project tree when you're not working on those
documents.
.. versionadded:: 2.0
As of version 2.0 it is possible to add child documents to other documents. This is particularly
useful when you create chapters and scenes. If you add separate scene documents, you should also
add separate chapter documents, even if they only contain a chapter heading. You can then add
scene documents as child items to the chapters.
.. _a_proj_roots_orphaned:
@@ -143,8 +171,8 @@ previously have been located in the project. The project loading routine will tr
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 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.
document will be added to the **Novel** root folder. Finally, if a **Novel** does not exist, one
will be created.
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
@@ -157,15 +185,16 @@ Project Lockfile
----------------
To prevent lost documents caused by file conflicts when novelWriter projects are synchronised via
file synchronisation tools, a project lockfile is written to the project storage folder. If you try
to open a project which has such a file present, you will be presented with a warning, and some
information about where else novelWriter thinks the project is also open. You will be given the
option to ignore this warning, and continue opening the project at your own risk.
file synchronisation tools, a project lockfile is written to the project storage folder when a
project is open. If you try to open a project which already has such a file present, you will be
presented with a warning, and some information about where else novelWriter thinks the project is
also open. You will be given the option to ignore this warning, and continue opening the project at
your own risk.
.. note::
If, for some reason, novelWriter crashes, the lock file may remain even if there are no other
instances keeping the project open. In such a case it is safe to ignore the lock file warning
when re-opening the project.
If, for some reason, novelWriter or your computer crashes, the lock file may remain even if
there are no other instances keeping the project open. In such a case it is safe to ignore the
lock file warning when re-opening the project.
.. warning::
If you choose to ignore the warning and continue opening the project, and multiple instances of
@@ -175,52 +204,31 @@ option to ignore this warning, and continue opening the project at your own risk
novelWriter will try to resolve project inconsistencies the next time you open the project.
.. _a_proj_roots_dirs:
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 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
to be able to collapse and hide them in the project tree when you're not working on those
documents.
.. versionadded:: 2.0
As of version 2.0 it is possible to add child documents to other documents. This is particularly
useful when you create chapters and scenes. If you add separate scene documents, you should also
add separate chapter documents, even if they only contain a chapter heading. You can then add
scene documents as child items to the chapters.
.. _a_proj_files:
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.
New documents can be created from the toolbar in the 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`.
You can always rename an item by selecting **Rename Item** from the **Project** menu, or by
pressing :kbd:`F2` when a document or folder is selected.
Other settings for project items are available from the context menu that you can activate by
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.
Other settings for project documents and folders are available from the context menu that you can
activate by right-clicking on an it in the tree. The **Transform** submenu includes options for
converting, splitting, or merging documents. See :ref:`a_ui_tree_split_merge` for more details on
the latter two.
Document Templates
------------------
If you wish to create template documents to be used when creating new project documents, like for
instance a character note template, you can add a :guilabel:`Templates` root folder to your
project. Any document added to this root folder will show up in the :guilabel:`Add Item` menu in
the project tree toolbar. When selected, a new document is created with its content copied from the
chosen template.
instance a character note template, you can add a **Templates** root folder to your project. Any
document added to this root folder will show up in the **Add Item** menu in the project tree
toolbar. When selected, a new document is created with its content copied from the chosen template.
.. versionadded:: 2.3
@@ -233,8 +241,8 @@ Word Counts
A character, word and paragraph count is maintained for each document, as well as for each section
of a document following a :term:`heading<headings>`. 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 :guilabel:`Project Tree` for any document selected in the
project or novel trees.
shown in the details panel below the project tree for any document selected in the project or novel
trees.
The word counts are not updated in real time, but run in the background every few seconds for as
long as the document is being actively edited.
@@ -242,7 +250,7 @@ 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 :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`.
Either from the **Tools** menu, or by pressing :kbd:`F9`.
The rules for how the counts are made is covered in more detail in :ref:`a_counting`.
@@ -252,33 +260,35 @@ The rules for how the counts are made is covered in more detail in :ref:`a_count
Project Settings
================
The :guilabel:`Project Settings` can be accessed from the :guilabel:`Project` menu, or by pressing
The **Project Settings** can be accessed from the **Project** menu, or by pressing
:kbd:`Ctrl+Shift+,`. This will open a dialog box, with a set of tabs.
Settings Tab
------------
The :guilabel:`Settings` tab holds the project name, title, and author settings.
The **Settings** tab holds the project name, author, and language settings.
The :guilabel:`Project Name` can be edited here. It is used for the GUI (main window title) and for
generating backup files. So keep in mind that if you do change this setting, the backup file names
will change too.
The **Project Name** can be edited here. It is used for the main window title and for generating
backup files. So keep in mind that if you do change this setting, the backup file names will change
too.
You can also change the :guilabel:`Authors` and :guilabel:`Project Language` setting. These are
only used when building the manuscript, for some formats.
You can also change the **Authors** and **Project Language** setting. These are only used when
building the manuscript, for some formats. The language setting is also used when inserting text
into documents in the viewer, like for instance labels for keywords and special comments.
If your project is in a different language than your main spell checking language is set to, you
can override the default setting here. The project language can also be changed from the
:guilabel:`Tools` menu. You can also override the automatic backup setting if you wish.
can override the default setting here. The project language can also be changed from the **Tools**
menu.
You can also override the automatic backup setting for the project if you wish.
Status and Importance Tabs
--------------------------
Each document or folder of type :guilabel:`Novel` can be given a "Status" label accompanied by a
coloured icon, and each document or folder of the remaining types can be given an "Importance"
label.
Each document or folder of type **Novel** can be given a "Status" label accompanied by a coloured
icon, and each document or folder of the remaining types can be given an "Importance" label.
These labels are there purely for your convenience, and you are not required to use them for any
other features to work. No other part of novelWriter accesses this information. The intention is to
@@ -316,22 +326,22 @@ Backup
======
An automatic backup system is built into novelWriter. In order to use it, a backup path to where
the backup files are to be stored must be provided in :guilabel:`Preferences`.
the backup files are to be stored must be provided in **Preferences**. The path defaults to a
folder named "Backups" in your home directory.
Backups can be run automatically when a project is closed, which also implies it is run when the
application itself is closed. Backups are date stamped zip files of the project files in the
project folder (files not strictly a part of the project are ignored). The zip archives are stored
in a subfolder of the backup path. The subfolder will have the same name as the
:guilabel:`Project Name` as defined in :ref:`a_proj_settings`.
in a subfolder of the backup path. The subfolder will have the same name as the **Project Name** as
defined in :ref:`a_proj_settings`.
The backup feature, when configured, can also be run manually from the :guilabel:`Tools` menu.
It is also possible to disable automated backups for a given project in
:guilabel:`Project Settings`.
The backup feature, when configured, can also be run manually from the **Tools** menu. It is also
possible to disable automated backups for a given project in **Project Settings**.
.. note::
For the backup to be able to run, the :guilabel:`Project Name` must be set in
:guilabel:`Project Settings`. This value is used to generate the name and path of the backups.
Without it, the backup will not run at all, but it will produce a warning message.
For the backup to be able to run, the **Project Name** must be set in **Project Settings**. This
value is used to generate the name and path of the backups. Without it, the backup will not run
at all, but it will produce a warning message.
.. _a_proj_stats:
@@ -344,9 +354,8 @@ total word counts of your novel documents and notes at the end of the session, p
session lasted either more than 5 minutes, or that the total word count changed. For more details
about the log file, see :ref:`a_storage`.
A tool to view the content of the log file is available in the :guilabel:`Tools` menu under
:guilabel:`Writing Statistics`. You can also launch it by pressing :kbd:`F6`, or find it on the
sidebar.
A tool to view the content of the log file is available in the **Tools** menu under **Writing
Statistics**. You can also launch it by pressing :kbd:`F6`, or find it on the sidebar.
The tool will show a list of all your sessions, and a set of filters to apply to the data. You can
also export the filtered data to a JSON file or to a CSV file that can be opened by a spreadsheet
@@ -356,4 +365,4 @@ application like for instance Libre Office Calc or Excel.
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, or 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`.
in **Preferences**.