Update project documentation
This commit is contained in:
Veronica Berglyd Olsen
Binary file not shown.
|
Before Width: | Height: | Size: 70 KiB After Width: | Height: | Size: 72 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 128 KiB After Width: | Height: | Size: 103 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 151 KiB |
@@ -4,9 +4,11 @@
|
||||
Building the Manuscript
|
||||
***********************
|
||||
|
||||
.. _Pandoc: https://pandoc.org/
|
||||
|
||||
You can at any time build a manuscript, an outline of your notes, or any other type of document
|
||||
from the text in your project. All of this is handled by the :guilabel:`Manuscript Build` tool.
|
||||
You can activate it from the sidebar, the :guilabel:`Tools` menu, or by pressing :kbd:`F5`.
|
||||
from the text in your project. All of this is handled by the **Manuscript Build** tool. You can
|
||||
activate it from the sidebar, the **Tools** menu, or by pressing :kbd:`F5`.
|
||||
|
||||
.. versionadded:: 2.1
|
||||
This tool is new for version 2.1. A simpler tool was used for earlier versions. The simpler tool
|
||||
@@ -20,40 +22,60 @@ The Manuscript Build Tool
|
||||
=========================
|
||||
|
||||
.. figure:: images/fig_manuscript_build.png
|
||||
:width: 80%
|
||||
|
||||
The :guilabel:`Manuscript Build` tool main window.
|
||||
The **Manuscript Build** tool main window.
|
||||
|
||||
The main window of the :guilabel:`Manuscript Build` tool contains a list of all the builds you have
|
||||
The main window of the **Manuscript Build** tool contains a list of all the builds you have
|
||||
defined, a selection of settings, and a few buttons to generate preview, open the print dialog, or
|
||||
run the build to create a manuscript document.
|
||||
|
||||
|
||||
Outline and Word Counts
|
||||
-----------------------
|
||||
|
||||
.. figure:: images/fig_manuscript_build_outline.png
|
||||
:width: 80%
|
||||
|
||||
The **Manuscript Build** tool main window with the **Outline** visible.
|
||||
|
||||
The **Outline** tab on the left lets you navigate the headings in the preview document. It will
|
||||
show up to scene level headings for novel documents, and level 2 headings for notes.
|
||||
|
||||
A collapsible panel of word and character counts are also available below the preview document.
|
||||
These are calculated from the text you have included in the document, and are more accurate counts
|
||||
than what's available in the project tree since they are counted *after formatting*.
|
||||
|
||||
For a detailed description on how they are counted, see :ref:`a_counting`.
|
||||
|
||||
|
||||
.. _a_manuscript_settings:
|
||||
|
||||
Build Settings
|
||||
==============
|
||||
|
||||
Each build definition can be edited by opening it in the :guilabel:`Manuscript Build Settings`
|
||||
dialog, either by double-clicking or by selecting it and pressing the edit button in the toolbar.
|
||||
Each build definition can be edited by opening it in the **Manuscript Build Settings** dialog,
|
||||
either by double-clicking or by selecting it and pressing the edit button in the toolbar.
|
||||
|
||||
.. tip::
|
||||
You can keep the :guilabel:`Manuscript Build Settings` dialog open while testing the different
|
||||
options, and just hit the :guilabel:`Apply` button. You can test the result of your settings
|
||||
by pressing the :guilabel:`Preview` button in the main :guilabel:`Manuscript Build` window.
|
||||
When you're happy with the result, you can close the settings.
|
||||
You can keep the **Manuscript Build Settings** dialog open while testing the different options,
|
||||
and just hit the :guilabel:`Apply` button. You can test the result of your settings by pressing
|
||||
the :guilabel:`Preview` button in the main **Manuscript Build** window. When you're happy with
|
||||
the result, you can close the settings.
|
||||
|
||||
|
||||
Document Selection
|
||||
------------------
|
||||
|
||||
.. figure:: images/fig_build_settings_selections.png
|
||||
:width: 80%
|
||||
|
||||
The :guilabel:`Selections` page of the :guilabel:`Manuscript Build Settings` dialog.
|
||||
The **Selections** page of the **Manuscript Build Settings** dialog.
|
||||
|
||||
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
|
||||
type, and a set of switches for which root folders to include.
|
||||
The **Selections** page of the **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 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
|
||||
explicitly include or exclude them by using the buttons below the tree view. The last button can be
|
||||
@@ -69,13 +91,14 @@ Formatting Headings
|
||||
-------------------
|
||||
|
||||
.. figure:: images/fig_build_settings_headings.png
|
||||
:width: 80%
|
||||
|
||||
The :guilabel:`Headings` page of the :guilabel:`Manuscript Build Settings` dialog.
|
||||
The **Headings** page of the **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` 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, or insert character names, like shown in the figure above.
|
||||
The **Headings** page of the **Manuscript Build Settings** dialog allows you to set 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, or insert character names, like shown in the figure above.
|
||||
|
||||
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
|
||||
@@ -86,7 +109,7 @@ Any text you add that isn't highlighted in colours will remain in your formatted
|
||||
``{Title}`` will always be replaced by the text in the heading from your documents.
|
||||
|
||||
You can preview the result of these format strings by clicking :guilabel:`Apply`, and then clicking
|
||||
:guilabel:`Preview` in the :guilabel:`Manuscript Build` tool main window.
|
||||
:guilabel:`Preview` in the **Manuscript Build** tool main window.
|
||||
|
||||
|
||||
Scene Separators
|
||||
@@ -107,10 +130,9 @@ be treated as a separator.
|
||||
Hard and Soft Scenes
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you wish to distinguish between so-called soft and hard scene breaks, where a hard scene break
|
||||
is understood as a scene break that changes point-of-view character, you can use the modified scene
|
||||
heading format in your text. You can then give these headings a different formatting in the
|
||||
:guilabel:`Headings` settings.
|
||||
If you wish to distinguish between so-called soft and hard scene breaks, you can use the
|
||||
alternative scene heading format in your text. You can then give these headings a different
|
||||
formatting in the **Headings** settings.
|
||||
|
||||
See :ref:`a_fmt_head` for more info on how to format headings in your text.
|
||||
|
||||
@@ -118,10 +140,9 @@ See :ref:`a_fmt_head` for more info on how to format headings in your text.
|
||||
Output Settings
|
||||
---------------
|
||||
|
||||
The :guilabel:`Content`, :guilabel:`Format` and :guilabel:`Output` pages of the
|
||||
:guilabel:`Manuscript Build Settings` dialog control a number of other settings for the output.
|
||||
Some of these only apply to specific output formats, which is indicated by the section headings on
|
||||
the settings pages.
|
||||
The **Content**, **Format** and **Output** pages of the **Manuscript Build Settings** dialog
|
||||
control a number of other settings for the output. Some of these only apply to specific output
|
||||
formats, which is indicated by the section headings on the settings pages.
|
||||
|
||||
|
||||
.. _a_manuscript_build:
|
||||
@@ -130,12 +151,13 @@ Building Manuscript Documents
|
||||
=============================
|
||||
|
||||
.. figure:: images/fig_build_build.png
|
||||
:width: 80%
|
||||
|
||||
The :guilabel:`Manuscript Build` dialog used for writing the actual manuscript documents.
|
||||
The **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.
|
||||
When you press the :guilabel:`Build` button on the **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 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
|
||||
@@ -157,7 +179,7 @@ Open Document Format
|
||||
|
||||
novelWriter HTML
|
||||
The HTML format writes a single ``.htm`` file with minimal style formatting. The HTML document
|
||||
is suitable for further processing by document conversion tools like Pandoc, for importing in
|
||||
is suitable for further processing by document conversion tools like Pandoc_, for importing in
|
||||
word processors, or for printing from browser.
|
||||
|
||||
novelWriter Markup
|
||||
@@ -198,4 +220,4 @@ on the print dialog.
|
||||
|
||||
.. note::
|
||||
The paper format should in all cases default to whatever your system default is. If you want to
|
||||
change it, you have to select it from the :guilabel:`Print Preview` dialog.
|
||||
change it, you have to select it from the **Print Preview** dialog.
|
||||
|
||||
+122
-113
@@ -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**.
|
||||
|
||||
@@ -16,9 +16,9 @@ this chapter hopes to explain in more detail how to use this tags and references
|
||||
|
||||
.. tip::
|
||||
If you find the Tags and Reference system difficult to follow just from reading this chapter,
|
||||
you can create a new project in the :guilabel:`Welcome` dialog's New project form and select
|
||||
"Create an example project" from the "Pre-fill project" option. The example project contains
|
||||
several examples of tags and references.
|
||||
you can create a new project in the **Welcome** dialog's New project form and select "Create an
|
||||
example project" from the "Pre-fill project" option. The example project contains several
|
||||
examples of tags and references.
|
||||
|
||||
|
||||
.. _a_references_metadata:
|
||||
@@ -68,7 +68,7 @@ You can only set **one** tag per heading, and the tag has to be unique across **
|
||||
the project.
|
||||
|
||||
After a tag has been defined, it can be referenced in novel documents, or cross-referenced in other
|
||||
notes. Tags will also show up in the :guilabel:`Outline View` and in the references panel under the
|
||||
notes. Tags will also show up in the **Outline View** and in the references panel under the
|
||||
document viewer when a document is open in the viewer.
|
||||
|
||||
The syntax highlighter will indicate to you that the keyword is correctly used and that the tag is
|
||||
@@ -79,7 +79,7 @@ that valid tags do.
|
||||
The tag is the only part of these notes that novelWriter uses. The rest of the document content is
|
||||
there for you to use in whatever way you 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.
|
||||
notes, you can do this from the **Manuscript Build** tool.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
Tags are no longer case sensitive. The tags are by default displayed with the capitalisation you
|
||||
@@ -117,8 +117,8 @@ How to Use References
|
||||
=====================
|
||||
|
||||
Each heading of any level in your project can contain references to tags set in project notes. The
|
||||
references are gathered by the indexer and used to generate the :guilabel:`Outline View`, among
|
||||
other things.
|
||||
references are gathered by the indexer and used to generate the **Outline View**, among 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
|
||||
@@ -126,70 +126,69 @@ reference keywords allow multiple values.
|
||||
|
||||
``@pov``
|
||||
The point-of-view character for the current section. The target must be a note tag in a
|
||||
:guilabel:`Character` type root folder.
|
||||
**Character** type root folder.
|
||||
|
||||
``@focus``
|
||||
The character that has the focus for the current section. This can be used in cases where the
|
||||
focus is not a point-of-view character. The target must be a note tag in a :guilabel:`Character`
|
||||
type root folder.
|
||||
focus is not a point-of-view character. The target must be a note tag in a **Character** type
|
||||
root folder.
|
||||
|
||||
``@char``
|
||||
Other characters in the current section. The target must be a note tag in a
|
||||
:guilabel:`Character` type root folder. This should not include the point-of-view or focus
|
||||
character if those references are used.
|
||||
Other characters in the current section. The target must be a note tag in a **Character** type
|
||||
root folder. This should not include the point-of-view or focus character if those references
|
||||
are used.
|
||||
|
||||
``@plot``
|
||||
The plot or subplot advanced in the current section. The target must be a note tag in a
|
||||
:guilabel:`Plot` type root folder.
|
||||
The plot or subplot advanced in the current section. The target must be a note tag in a **Plot**
|
||||
type root folder.
|
||||
|
||||
``@time``
|
||||
The timelines touched by the current section. The target must be a note tag in a
|
||||
:guilabel:`Timeline` type root folder.
|
||||
The timelines touched by the current section. The target must be a note tag in a **Timeline**
|
||||
type root folder.
|
||||
|
||||
``@location``
|
||||
The location the current section takes place in. The target must be a note tag in a
|
||||
:guilabel:`Locations` type root folder.
|
||||
**Locations** type root folder.
|
||||
|
||||
``@object``
|
||||
Objects present in the current section. The target must be a note tag in a :guilabel:`Object`
|
||||
type root folder.
|
||||
Objects present in the current section. The target must be a note tag in a **Object** type root
|
||||
folder.
|
||||
|
||||
``@entity``
|
||||
Entities present in the current section. The target must be a note tag in a
|
||||
:guilabel:`Entities` type root folder.
|
||||
Entities present in the current section. The target must be a note tag in an **Entities** type
|
||||
root folder.
|
||||
|
||||
``@custom``
|
||||
Custom references in the current section. The target must be a note tag in a :guilabel:`Custom`
|
||||
type root folder. The custom folder are for any other category of notes you may want to use.
|
||||
Custom references in the current section. The target must be a note tag in a **Custom** type
|
||||
root folder. The custom folder are for any other category of notes you may want to use.
|
||||
|
||||
The syntax highlighter will alert the user that the tags and references are used correctly, and
|
||||
that the tags referenced exist.
|
||||
|
||||
.. 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.
|
||||
:kbd:`F9` to regenerate it, or select **Rebuild Index** from the **Tools** menu. In general, the
|
||||
index for a document is regenerated when it is saved, so this shouldn't normally be necessary.
|
||||
|
||||
.. tip::
|
||||
If you add a reference in the editor to a tag that doesn't yet exist, you can right-click it and
|
||||
select :guilabel:`Create Note for Tag`. This will generate a new project note automatically with
|
||||
the new tag defined. In order for this to be possible, a root folder for that category of
|
||||
references must already exist.
|
||||
select **Create Note for Tag**. This will generate a new project note automatically with the new
|
||||
tag defined. In order for this to be possible, a root folder for that category of references
|
||||
must already exist.
|
||||
|
||||
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
|
||||
connections in the plot. You can follow links in the document editor by clicking them with the
|
||||
mouse while holding down the :kbd:`Ctrl` key. Clicked links are always opened in the view panel.
|
||||
|
||||
Project notes don't show up in the :guilabel:`Outline View`, so referencing between notes is only
|
||||
Project notes don't show up in the **Outline View**, so referencing between notes is only
|
||||
meaningful if you want to be able to click-navigate between them, or of course if you just want to
|
||||
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 as well.
|
||||
**Manuscript Build** tool, the cross-references become clickable links in the exported HTML
|
||||
document as well.
|
||||
|
||||
Example of a novel document with references to characters and plots:
|
||||
|
||||
@@ -217,7 +216,7 @@ character ``@`` on a new line. It will first suggest tag or reference keywords f
|
||||
after the ``:`` has been added, suggest references from the list of tags you have already defined.
|
||||
|
||||
You can use the auto-completer to add multiple references with a ``,`` between them, and even type
|
||||
new ones. New references can be created by right-clicking on them and selecting
|
||||
:guilabel:`Create Note for Tag` from the menu.
|
||||
new ones. New references can be created by right-clicking on them and selecting **Create Note for
|
||||
Tag** from the menu.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
|
||||
@@ -6,14 +6,13 @@ Novel Structure
|
||||
|
||||
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`. Active 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, where they
|
||||
become inactive.
|
||||
There are two different types of documents in a project, **Novel Documents** and **Project Notes**.
|
||||
Active novel documents can only live in a **Novel** type root folder. You can also move them to
|
||||
**Archive** and **Trash** of course, where they become inactive.
|
||||
|
||||
The :guilabel:`Project Tree` can distinguish between the different heading levels of the novel
|
||||
documents using coloured icons, and optionally add emphasis on the label, set in
|
||||
:guilabel:`Preferences`.
|
||||
The project tree can distinguish between the different heading levels of the novel documents using
|
||||
coloured icons, and optionally add emphasis on the label, set in **Preferences** for easier
|
||||
identification.
|
||||
|
||||
|
||||
.. _a_struct_heads:
|
||||
@@ -29,40 +28,41 @@ title. See also the :ref:`a_fmt` section for more details about the markup synta
|
||||
|
||||
.. note::
|
||||
The heading 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` for more details.
|
||||
the indexer when building the outline tree in the **Outline View** as well as in the **Novel
|
||||
Tree**. Each heading also starts a new region where new Tags and References can be defined. See
|
||||
:ref:`a_references` for more details.
|
||||
|
||||
The syntax for the four basic heading types, and the two special types, is listed in section
|
||||
The syntax for the four basic heading types, and the three special types, is listed in section
|
||||
:ref:`a_fmt_head`. The meaning of the four levels for the structure of your novel is as follows:
|
||||
|
||||
**Heading Level 1: Partition**
|
||||
This heading level signifies that the text refers to a top level partition. This is useful when
|
||||
This heading level signifies that the text refers to a top level heading. This is useful when
|
||||
you want to split the manuscript up into books, parts, or acts. These headings are not required.
|
||||
The novel title itself should use the special heading level ``#!`` covered in :ref:`a_fmt_head`.
|
||||
|
||||
**Heading Level 2: Chapter**
|
||||
This heading level signifies a chapter level partition. Each time you want to start a new
|
||||
chapter, you must add such a heading. If you choose to split your manuscript up into one
|
||||
document per scene, you need a single chapter document with just the heading. You can of course
|
||||
also add a synopsis and reference keywords to the chapter document. If you want to open the
|
||||
chapter with a quote or other introductory text that isn't part of a scene, this is also where
|
||||
you'd put that text.
|
||||
This heading level signifies a chapter. Each time you want to start a new chapter, you must add
|
||||
such a heading. If you choose to split your manuscript up into one document per scene, you need
|
||||
a single chapter document with just the heading. You can of course also add a synopsis and
|
||||
reference keywords to the chapter document. If you want to open the chapter with a quote or
|
||||
other introductory text that isn't part of a scene, this is also where you'd put that text.
|
||||
|
||||
**Heading Level 3: Scene**
|
||||
This heading level signifies a scene level partition. You must provide a title text, but the
|
||||
title text can be replaced with a scene separator or just skipped entirely when you build your
|
||||
manuscript.
|
||||
This heading level signifies a scene. You must provide a title text, but the title text can be
|
||||
replaced with a scene separator or just skipped entirely when you build your manuscript. If you
|
||||
need to distinguish between hard and soft scene breaks, there is an alternative format for
|
||||
scenes you can use for this distinction. The formatting is covered in :ref:`a_fmt_head`. See
|
||||
also :ref:`a_struct_heads_scenes`.
|
||||
|
||||
**Heading Level 4: Section**
|
||||
This heading level signifies a sub-scene level partition, usually called a "section" in the
|
||||
This heading level can be used to split up a scene, usually called a "section" in the
|
||||
documentation and the user interface. These can be useful if you want to change references
|
||||
mid-scene, like if you change the point-of-view character. You are free to use sections as you
|
||||
wish, and you can filter them out of the final manuscript just like with scene titles.
|
||||
wish, and you can filter them out of the final manuscript.
|
||||
|
||||
Page breaks are automatically added before partition and chapter headings when you build your
|
||||
project to a format that supports page breaks. If you want page breaks in other places, you have to
|
||||
specify them manually. See :ref:`a_fmt_break`.
|
||||
Page breaks can be automatically added before partition, chapter and scene headings from the
|
||||
**Manuscript Build** tool when you build your project to a format that supports page breaks. If you
|
||||
want page breaks in other places, you have to specify them manually. See :ref:`a_fmt_break`.
|
||||
|
||||
.. tip::
|
||||
There are multiple options of how to process novel headings when building the manuscript. For
|
||||
@@ -76,9 +76,9 @@ specify them manually. See :ref:`a_fmt_break`.
|
||||
Novel Title and Front Matter
|
||||
----------------------------
|
||||
|
||||
It is recommended that you add a document at the very top of each Novel root folder with the novel
|
||||
title as the first line. You should modify the level 1 heading format code with an ``!`` in order
|
||||
to render it as a document title that is excluded from any automatic Table of Content in a
|
||||
It is recommended that you add a document at the very top of each **Novel** root folder with the
|
||||
novel title as the first line. You should modify the level 1 heading format code with an ``!`` in
|
||||
order to render it as a document title that is excluded from any automatic Table of Content in a
|
||||
manuscript build document, like so:
|
||||
|
||||
.. code-block:: md
|
||||
@@ -102,7 +102,7 @@ Unnumbered Chapter Headings
|
||||
|
||||
If you use the automatic numbering feature for your chapters, but you want to keep some special
|
||||
chapters separate from this, you can add an ``!`` to the level 2 heading formatting code to tell
|
||||
the build tool to skip these chapters.
|
||||
the build tool to skip these chapters when adding numbers.
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
@@ -110,18 +110,31 @@ the build tool to skip these chapters.
|
||||
|
||||
Chapter Text
|
||||
|
||||
There is a separate formatting feature for such chapter titles in the :guilabel:`Manuscript Build`
|
||||
tool as well. See the :ref:`a_manuscript` page for more details. When building a document of a
|
||||
format that supports page breaks, also unnumbered chapters will have a page break added just like
|
||||
for normal chapters.
|
||||
There is a separate formatting feature for such chapter titles in the **Manuscript Build** tool as
|
||||
well. See the :ref:`a_manuscript` page for more details. When building a document of a format that
|
||||
supports page breaks, also unnumbered chapters can have a page break added just like for normal
|
||||
chapters.
|
||||
|
||||
.. Note::
|
||||
Previously, you could also disable the automatic numbering of a chapter by adding an ``*`` as
|
||||
the first character of the chapter title itself. This feature has been dropped in favour of the
|
||||
current format in order to keep level 1 and 2 headers consistent. Please update your chapter
|
||||
headings if you've used this syntax.
|
||||
|
||||
.. _a_struct_heads_scenes:
|
||||
|
||||
Hard and Soft Scene Breaks
|
||||
--------------------------
|
||||
|
||||
If you need two different ways to style scenes in your manuscript, like if you want to insert
|
||||
different scene separators for soft and hard scene breaks, there is an alternative scene format
|
||||
available for scene headings with a ``!`` added to the formatting code.
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
### Soft Scene Transition
|
||||
|
||||
A soft scene break.
|
||||
|
||||
###! Hard Scene Transition
|
||||
|
||||
A hard scene break.
|
||||
|
||||
There is a separate formatting feature for these titles in the **Manuscript Build** tool.
|
||||
|
||||
.. versionadded:: 2.4
|
||||
|
||||
@@ -142,6 +142,8 @@ A global search tool is available from the side bar. It allows you to search thr
|
||||
project. The tool does not provide a replace feature. There is a search and replace tool available
|
||||
in the document editor that acts on the open document.
|
||||
|
||||
.. versionadded:: 2.4
|
||||
|
||||
|
||||
.. _a_breakdown_project:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user