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

Update the Project section of the docs

Browse Source
This commit is contained in:
Veronica Berglyd Olsen
2023-10-15 17:27:44 +02:00
parent 8e72432db8
commit 56b4cd3036
18 changed files with 539 additions and 467 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/images/fig_build_build.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 62 KiB

docs/source/images/fig_build_settings_headings.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 54 KiB

docs/source/images/fig_build_settings_selections.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 86 KiB

docs/source/images/fig_manuscript_build.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 99 KiB

docs/source/images/fig_project_merge_tool.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

docs/source/images/fig_project_split_tool.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

docs/source/index.rst
+2 -2
View File
@@ -75,8 +75,8 @@ from pip. See :ref:`a_started` for more details.
project_overview
project_structure
project_notes
project_export
project_references
project_manuscript
.. toctree::
:maxdepth: 1
docs/source/int_glossary.rst
+18 -3
View File
@@ -9,13 +9,19 @@ Glossary
Root Folder
A "Root Folder" is a top level folder of the project tree in novelWriter. Each type of root
folder has a specific icon to identify it. For an overview of available root folder types,
see :ref:``
see :ref:`a_proj_roots`.
Novel Documents
These are documents that are created under a "Novel" :term:`root folder`.
These are documents that are created under a "Novel" :term:`root folder`. They behave
differently than :term:`Project Notes`, and have some more restrictions. For instance, they
can not exist in folders intended only for project notes. See the :ref:`a_struct` chapter for
more details.
Project Notes
...
Project Notes are unrestricted documents that can be placed anywhere in your project. You
should not use these documents for story elements, only for notes. Project notes are the
source files used by the Tags and References system. See the :ref:`a_references` chapter for
more details on how to use them.
Tag
...
@@ -28,3 +34,12 @@ Glossary
Context Menu
...
Headings
Each level of headings in :term:`Novel Documents` have a specific meaning in terms of the
structure of the story. That is, they determine what novelWriter considers a partition, a
chapter, a scene or a text section. For :term:`Project Notes`, the header levels don't
matter. For more details on headings in novel documents, see :ref:`a_struct_heads`.
Keyword
...
docs/source/int_overview.rst
+7 -7
View File
@@ -81,11 +81,11 @@ meta data for it to extract.
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.
:ref:`a_notes` - Recommended Reading
This section briefly describes what novelWriter does with the note files you add to your
project. Generally, the application doesn't do much with them at all aside from looking through
them for tags you've set so that it knows which file to open when you click on a reference.
:ref:`a_references` - Recommended Reading
This section 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_export` - Recommended Reading
This section explains in more detail how the build tool works. In particular how you can
control the way chapter titles are formatted, and how scene and section breaks are handled.
: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.
docs/source/project_export.rst
-159
View File
@@ -1,159 +0,0 @@
.. _a_export:
***********************
Building the Manuscript
***********************
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:`Build Novel Project` tool.
You can activate it from the sidebar, the :guilabel:`Tools` menu, or by pressing :kbd:`F5`.
.. note::
This tool is scheduled to receive a full update in novelWriter 2.1, adding many new features
requested by users. See the `2.1 Milestone <https://github.com/vkbo/novelWriter/milestone/43>`_
for an overview.
.. _a_export_headers:
Header Formatting
=================
The titles for the five types of headings (the chapter headings come in a numbered and unnumbered
version) of story structure can be formatted collectively in the build tool. This is done through
a series of keyword–replace steps. They are all on the format ``%keyword%``.
``%title%``
This keyword will always be replaced with the title text you put after the ``#`` characters in
your document.
``%ch%``
This will be replaced by a chapter number. The number is incremented by one each time the build
tool sees a new heading of level two in a document, unless the heading formatting code has the
added ``!``. In the latter case, the counter is *not* incremented. This is useful for for
instance Prologue and Epilogue chapters.
``%chw%``
Behaves like ``%ch%``, but the number is represented as a number word. You can select between a
number of different languages.
``%chi%``
Begaves like ``%ch%``, but represented as a lower case Roman number from 1 to 4999.
``%chI%``
Behaves like ``%ch%``, but represented as an upper case Roman number from 1 to 4999.
``%sc%``
This is the number counter equivalent for scenes. These are incremented each time a heading of
level three is encountered, but reset to 1 each time a chapter is encountered. They can thus be
used for counting scenes within a chapter.
``%sca%``
Behaves like ``%sc%``, but the number is *not* reset to 1 for each chapter. Instead it runs from
1 from the beginning of the novel to produce an absolute scene count.
``\\``
This inserts a line break within the title.
.. note::
Header formatting only applies to novel documents. Headings in notes will be left as-is.
**Example**
* The format ``%title%`` just reproduces the title you set in the document.
* The format ``Chapter %ch%: %title%`` produces something like "Chapter 1: My Chapter Title".
* The format ``Scene %ch%.%sc%`` produces something like "Scene 1.2" for scene 2 in chapter 1.
.. _a_export_scenes:
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.
Alternatively, if you want a separator between them, like the common ``* * *``, you can enter the
desired separator text in the formatting box. In fact, if the format is a piece of static text, it
will always be treated as a separator.
.. _a_export_files:
File Selection
==============
Which documents and notes are selected for the build can be controlled from the options on the left
side of the dialog window. In addition, you can select to include the synopsis comments, regular
comments, keywords, and even exclude the body text itself if you just want an outline.
.. tip::
If you for instance want to export a document with an outline of the novel, you can enable
keywords and synopsis export and disable body text, thus getting a document with each heading
followed by the tags and references and the synopsis.
If you need to exclude specific documents from your exports, like draft documents or documents you
want to take out of your manuscript, but don't want to delete, you can set the documents as
"inactive" in the project tree. :guilabel:`Build Novel Project` tool has a switch to collectively
exclude inactive documents.
.. _a_export_print:
Printing
========
The print button allows you to print the content in the preview window. You can either print to one
of your system's printers, or print directly to a file as PDF. You can also print to file from the
regular print dialog. The direct to file option is just a shortcut.
.. note::
The paper format should in all cases default to whatever your system default is. Of you want to
change it, you have to select it from the :guilabel:`Print Preview`` dialog.
.. _a_export_formats:
Export Formats
==============
Currently, six 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.
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
word processors, or for printing from browser.
novelWriter Markdown
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.
Standard/GitHub Markdown
The Markdown format comes in both Standard and GitHub flavour. The *only* difference in terms of
novelWriter functionality is the support for strikethrough text, which is not supported by the
Standard flavour, but *is* supported by the GitHub flavour.
.. _a_export_options:
Additional Formats
==================
In addition to the above document formats, the novelWriter HTML and Markdown 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 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
entry per paragraph it contains.
These files are mainly intended for scripted post-processing for those who want that option. A JSON
file can be imported directly into a Python dict object or a PHP array, to mentions a few options.
docs/source/project_manuscript.rst
+185
View File
@@ -0,0 +1,185 @@
.. _a_manuscript:
***********************
Building the Manuscript
***********************
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`.
.. 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
functionality.
.. _a_manuscript_main:
The Manuscript Build Tool
=========================
.. figure:: images/fig_manuscript_build.png
The :guilabel:`Manuscript Build` tool main window.
The main window of the :guilabel:`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.
.. _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.
.. 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.
Document Selection
------------------
.. figure:: images/fig_build_settings_selections.png
The :guilabel:`Selections` page of the :guilabel:`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.
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
used to reset the override and return control to the filter settings.
In the figure, the green arrow icon and the blue pin icon indicates which documents are included,
and the red forbidden icon indicates that a document is explicitly excluded.
Formatting Headings
-------------------
.. figure:: images/fig_build_settings_headings.png
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
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.
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.
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.
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.
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.
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.
.. _a_manuscript_build:
Building Manuscript Documents
=============================
.. figure:: images/fig_build_build.png
The :guilabel:`Manuscript Build` dialog sued 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.
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.
File Formats
------------
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.
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
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.
Standard/Extended Markdown
The Markdown format comes in both Standard and Extended flavour. The *only* difference in terms
of novelWriter functionality is the support for strikethrough text, which is not supported by
the Standard flavour.
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 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
entry per paragraph it contains.
These files are mainly intended for scripted post-processing for those who want that option. A JSON
file can be imported directly into a Python dict object or a PHP array, to mentions a few options.
.. _a_manuscript_print:
Print and PDF
=============
The :guilabel:`Print` button allows you to print the content in the preview window. You can either
print to one of your system's printers, or select PDF as your output format from the printer icon
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.
docs/source/project_notes.rst
-72
View File
@@ -1,72 +0,0 @@
.. _a_notes:
*************
Project Notes
*************
novelWriter doesn't have a database and complicated forms for filling in details about plot
elements, characters, and all sorts of additional information that isn't a part of the novel text
itself. Instead, all such information is saved in notes that are written and maintained just like
all other text in your project.
The relation between all these additional elements is extracted from the documents and notes by the
project indexer, based on the tags and references you set within them.
Using notes is not required, but making at least minimal notes for each plot element, and adding a
tag to them, makes it possible to use the Outline View to see how each element intersects with each
section of the novel itself, and adds clickable cross-references between documents in the editor
and viewer.
.. _a_notes_tags:
Tags in Notes
=============
Each new heading in a note can have a tag associated with it. The format of a tag is
``@tag: tagname``, where tagname is a unique identifier of your choosing. Tags can then be
referenced in the novel documents, or cross-referenced in other notes, and will show up in the
Outline View and in the back-reference panel when a document is opened in the viewer. See
:ref:`a_struct_tags` for how to reference notes.
The syntax highlighter will alert the user 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
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:`Build Novel Project` tool.
One note can also reference another note in the same way novel documents do. When the note is
opened in the view panel, the references become clickable links, making it easier to follow
connections in the plot. Notes don't show up in the Outline View though, 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:`Build Novel Project` tool, the cross-references become clickable links in the
exported HTML document.
Example of a project note with two headers, with separate tags, and with references to other notes:
.. code-block:: none
:linenos:
# Main Characters
## Jane Doe
@tag: Jane
@location: Earth
Something about Jane ...
## John Doh
@tag: John
@location: Mars
Something about John ...
docs/source/project_overview.rst
+79 -99
View File
@@ -29,9 +29,9 @@ 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 novel documents go into a root folder of type :guilabel:`Novel`. 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 :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.
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.
@@ -41,80 +41,58 @@ them from other documents and notes. The intended usage of each type of root fol
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.
.. note::
It is not the notes themselves that are referenced by the listed reference keywords, but tags
set within the notes. See the examples below and in :ref:`a_struct_tags`.
:guilabel:`Novel`
This is the root folder of all text that goes into the final novel or novels. This class of
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`
This is the root folder 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
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.
:guilabel:`Characters`
Character notes go in this root folder. These are especially important if you want to use the
Outline View to see which character appears where, and which part of the story is told from a
specific character's point-of-view, or focusing on a particular character's storyline. Tags in
this 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 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. 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.
:guilabel:`Locations`
The locations folder is for various scene locations that you want to track. Tags in this folder
can be references using the ``@location`` keyword.
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`
If the story has multiple plot timelines or jumps in time within the same plot, this class of
notes can be used to track this. Tags in this folder can be references using the ``@time``
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 important objects that change hands often, can be
tracked here. Tags in this folder can be references using the ``@object`` keyword.
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.
:guilabel:`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 folder can be references using the
the plot? They can be organised here. Tags in this type of folder can be references using the
``@entity`` keyword.
:guilabel:`Custom`
The custom root folder can be used for tracking anything else not covered by the above options.
Tags in this folder can be references using the ``@custom`` keyword.
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_struct_tags`.
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
keyword.
Example of a character note:
.. code-block:: none
:linenos:
# Jane Doe
@tag: Jane
Some information about the character Jane Doe.
Example of a novel scene referencing the above character:
.. code-block:: none
:linenos:
### Chapter 1, Scene 1
@pov: Jane
When Jane woke up that morning ...
keyword or what they do.
.. _a_proj_roots_del:
@@ -128,7 +106,7 @@ the menu. Documents in the trash folder are removed from the project index and c
referenced.
A document or a folder can be deleted from the :guilabel:`Project` menu, or by pressing
:kbd:`Ctrl`:kbd:`Shift`:kbd:`Del`. Root folders can only be deleted when they are empty.
:kbd:`Ctrl+Shift+Del`. Root folders can only be deleted when they are empty.
.. _a_proj_roots_out:
@@ -138,14 +116,14 @@ 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.
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 Novel Project` builds. 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 project index, so
the tags and references defined in it will not show up anywhere else.
.. _a_proj_roots_orph:
.. _a_proj_roots_orphaned:
Recovered Documents
-------------------
@@ -153,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, if possible.
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
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. Only if the :guilabel:`Novel` folder is
missing will it give up.
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 "Recovered File N" where N is a
sequential number.
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:
@@ -173,11 +151,11 @@ sequential number.
Project Lockfile
----------------
To prevent lost documents caused by file conflicts when novelWriter projects are synced with file
synchronisation tools, a project lockfile is written to the project 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 give the option to ignore
this warning, and continue opening the project at your own risk.
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 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.
.. note::
If, for some reason, novelWriter crashes, the lock file may remain even if there are no other
@@ -198,18 +176,18 @@ 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 during export, these folders are
ignored. Only the order of the documents themselves matter.
is processing the documents in the novel, 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 the user 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
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.
.. tip::
You can 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.
.. 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:
@@ -217,15 +195,16 @@ documents.
Project Documents
=================
New documents can be created from the tool bar in the Project Tree, or by pressing
:kbd:`Ctrl`:kbd:`N`. This will open the create new item menu and let you choose between a number of
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`.
Other settings for project items are available from the context menu that you can activate by
right-clicking on an item in the Project Tree. The :guilabel:`Transform` submenu includes options
for converting, splitting, or merging items.
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.
.. _a_proj_files_counts:
@@ -234,16 +213,17 @@ Word Counts
-----------
A character, word and paragraph count is maintained for each document, as well as for each section
of a document following a header. The word count and change of words in the current session is
displayed in the footer of any document open in the editor, and all stats are shown in the details
panel below the project tree for any document selected in the project or novel tree.
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.
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.
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 form
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`.
@@ -253,7 +233,7 @@ Project Settings
================
The :guilabel:`Project Settings` can be accessed from the :guilabel:`Project` menu, or by pressing
:kbd:`Ctrl`:kbd:`Shift`:kbd:`,`. This will open a dialog box, with a set of tabs.
:kbd:`Ctrl+Shift+,`. This will open a dialog box, with a set of tabs.
Settings Tab
@@ -263,26 +243,26 @@ The :guilabel:`Settings` tab holds the project name, title, and author settings.
The :guilabel:`Project Name` can be set to a different value than the :guilabel:`Novel Title`. The
difference between them is simply that the :guilabel:`Project Name` is used for the GUI (main
window title) and for generating the backup files. The intention is that the
:guilabel:`Project Name` should remain unchanged throughout the project's lifetime, otherwise the
name of exported files and backup files may change too.
window title) and for generating backup files. The intention is that the :guilabel:`Project Name`
should remain unchanged throughout the project's lifetime, otherwise the name of exported files and
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.
setting. The project language can also be changed from the :guilabel:`Tools` menu.
Status and Importance Tabs
--------------------------
Each document or folder of type :guilabel:`Novel` can be given a *Status*_* label accompanied by a
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.
These are purely there for the user's convenience, and you are not required to use them for any
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
use these to indicate at what stage of completion each novel document is, or how important the
content of a note is to the story. You don't have to use them this way, that's just what they were
@@ -302,7 +282,7 @@ A set of automatically replaced keywords can be added in this tab. The keywords
will be replaced by the text in the right column when documents are opened in the viewer. They will
also be applied to manuscript builds.
The auto-replace feature will replace text in angle brackets that are in this list. The syntax
The auto-replace feature will replace text in angle brackets that is in this list. The syntax
highlighter will add an alternate colour to text matching the syntax, but it doesn't check if the
text is in this list.
@@ -332,7 +312,7 @@ It is also possible to disable automated backups for a given project in
.. 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 folder name for the zip files.
: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.
@@ -343,19 +323,19 @@ Writing Statistics
When you work on a project, a log file records when you opened it, when you closed it, and the
total word counts of your novel documents and notes at the end of the session, provided that the
session lasted either more than 5 minutes, or that the total word count changed. You can view this
file in the ``meta`` folder in the directory where you saved your project. The file is named
``sessionStats.log``.
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 this file is available in the :guilabel:`Tools` menu under
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.
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
application like for instance Libre Office Calc.
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`.
.. versionadded:: 1.2
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`.
docs/source/project_references.rst
+175
View File
@@ -0,0 +1,175 @@
.. _a_references:
*******************
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
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.
This is perhaps one of the features that makes novelWriter quite different than 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.
.. tip::
If you find the Tags and Reference system difficult to follow just from reading this chapter,
you can create a new project in novelWriter and select to "Fill the project with example files"
in the :guilabel:`New Project Wizard`. The example project contains several examples of tags and
references.
.. _a_references_metadata:
Metadata in novelWriter
=======================
The structure of your novelWriter project is inferred from the :term:`headings` within the
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.
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,
you need to assign it a tag.
.. _a_references_tags:
How to Use Tags
===============
A "tag" in novelWriter is a word or phrase that you define as belonging to a heading. Tags are set
by using the ``@tags`` :term:`keyword`. The full format of a tag is ``@tag: tagname``, where
``tagname`` is an identifier of your choosing. You can only set *one* tag per heading, and the tag
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.
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.
The syntax highlighter will alert 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
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:
.. code-block:: none
# Jane Doe
@tag: Jane
Some information about the character Jane Doe.
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 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.
.. _a_references_references:
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 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.
``@pov``
The point-of-view character for the current section. The target must be a note tag in a
:guilabel:`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.
``@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.
``@plot``
The plot or subplot advanced in the current section. The target must be a note tag in a
:guilabel:`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.
``@location``
The location the current section takes place in. The target must be a note tag in a
:guilabel:`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.
``@entity``
Entities present in the current section. The target must be a note tag in a
:guilabel:`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.
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.
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
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.
Example of a novel document with references to characters and plots:
.. code-block:: none
## Chapter 1
@pov: Jane
### Scene 1
@char: John, Sam
@plot: Main
Once upon a time ...
docs/source/project_structure.rst
+21 -115
View File
@@ -4,10 +4,16 @@
Novel Structure
***************
This section covers the structure of a novel project.
This chapter covers the structure of a novel project.
It concerns documents under the :guilabel:`Novel` type root folder only. There are some
restrictions and features that only apply to these types of documents.
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.
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
:guilabel:`Preferences`.
.. _a_struct_heads:
@@ -23,8 +29,9 @@ title. See also the :ref:`a_fmt` section for more details about the markdown syn
.. 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 Outline as well as the Novel Tree. Each
heading also starts a new region where new references and tags can be defined.
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`.
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:
@@ -32,7 +39,7 @@ The syntax for the four basic header types, and the two special header types, is
**Header Level 1: Partition**
This header level signifies that the text refers to a top level partition. 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 header level explained in :ref:`a_fmt_head`.
The novel title itself should use the special header level ``#!`` covered in :ref:`a_fmt_head`.
**Header Level 2: Chapter**
This header level signifies a chapter level partition. Each time you want to start a new
@@ -49,18 +56,19 @@ The syntax for the four basic header types, and the two special header types, is
**Header Level 4: Section**
This header level signifies a sub-scene level partition, usually called a "section" in the
documentation and the user interface. These can be useful if you want to change tag references
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.
Page breaks are automatically added before level 1 and 2 headers when you build your project to a
format that supports page breaks, or when you print the document directly from the build tool. If
you want page breaks in other places, you have to specify them manually. See :ref:`a_fmt_break`.
format that supports page breaks, or when you print the document directly from the
:guilabel:`Manuscript Build` tool. 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 titles when building the manuscript. For
instance, chapter numbers can be applied automatically, and so can scene numbers if you want
them in a draft manuscript. See the :ref:`a_export` page for more details.
them in a draft manuscript. See the :ref:`a_manuscript` page for more details.
.. _a_struct_heads_title:
@@ -89,13 +97,13 @@ 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 cam add a ``!`` to the level 2 header formatting code to tell the
chapters separate from this, you cam add an ``!`` to the level 2 header formatting code to tell the
build tool to skip these chapters.
``##! Unnumbered Chapter Title``
There is a separate formatting feature for such chapters in the :guilabel:`Build Novel Project`
tool as well. See the :ref:`a_export` page for more details. When building a document of a format
There is a separate formatting feature for such chapters 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.
@@ -104,105 +112,3 @@ normal chapters.
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_tags:
Note References
===============
Each text partition, indicated by a heading of any level, can contain references to tags set in the
project notes of the project. The references are gathered by the indexer and used to generate the
Outline View. This section covers how to make references to tags. See :ref:`a_notes_tags` for how
to define tags the references can point to.
References and tags are also clickable in the document editor and viewer, making it easy to
navigate between reference notes while writing. Clicked links are always opened in the view panel.
References are set as a 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.
``@pov``
The point-of-view character for the current section. The target must be a note tag in a
:guilabel:`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.
``@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.
``@plot``
The plot or subplot advanced in the current section. The target must be a note tag in a
:guilabel:`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.
``@location``
The location the current section takes place in. The target must be a note tag in a
:guilabel:`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.
``@entity``
Entities present in the current section. The target must be a note tag in a
:guilabel:`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.
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.
Example of a novel document with references to characters and plots:
.. code-block:: none
:linenos:
## Chapter 1
@pov: Jane
### Scene 1
@char: John, Sam
@plot: Main
Once upon a time ...
.. _a_struct_layout:
Document Layout
===============
All documents in the project can have a layout format set. Previously, there were multiple layouts
available to change how the documents where formatted on export. These have now been reduced to
just two layouts: :guilabel:`Novel Document` and :guilabel:`Project Note`.
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. Project notes can be added anywhere in the
project.
The project tree can distinguish between the different layouts and header levels of the documents
using coloured icons, and optionally add emphasis on the label (See the :guilabel:`Preferences`.)
For novel documents, the heading level of the first heading is recorded, and indicated by the icon.
.. tip::
You can always start writing with a coarse setup with one or a few documents, and then later use
the split tool to split the documents into separate chapter and scene documents. You can split a
document on any of the four header levels.
docs/source/usage_breakdown.rst
+3 -3
View File
@@ -152,7 +152,7 @@ The project tree will select an icon for the document based on the first heading
This header level structure is only taken into account for :term:`novel documents`. For
:term:`project notes`, the header levels have no structural meaning, and the user is free to do
whatever they want. See :ref:`a_struct` and :ref:`a_notes` for more details.
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
@@ -177,12 +177,12 @@ 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_export_options` for more details.
See :ref:`a_manuscript_build` for more details.
.. versionadded:: 2.1
You can now define multiple build definitions in the :guilabel:`Build Manuscript` tool. This
allows you to define specific settings for various types of draft documents, outline documents,
and manuscript formats. See :ref:`a_export` for more details.
and manuscript formats. See :ref:`a_manuscript` for more details.
.. _a_breakdown_storage:
docs/source/usage_format.rst
+2 -2
View File
@@ -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_struct_tags` section. They can also be
inserted at the cursor position in the editor via the :guilabel:`Insert` menu.
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.
.. _a_fmt_align:
docs/source/usage_project.rst
+47 -5
View File
@@ -58,16 +58,58 @@ At the top of the tree, you will find a set of buttons.
folders. You can also activate this dropdown menu by pressing :kbd:`Ctrl+N`.
* The last button is a menu of further actions you can apply to the project tree.
.. tip::
Under the :guilabel:`Transform` submenu in the context menu of an item, you will find several
options on how to change a document or folder. This includes changing between document and note,
splitting them into multiple documents, or merging child items into a single document.
Below the project tree you will find a small details panel showing the full information of the
currently selected item. This panel also includes the latest paragraph and character counts in
addition to the word count.
.. _a_ui_tree_split_merge:
Splitting and Merging Documents
-------------------------------
Under the :guilabel:`Transform` submenu in the context menu of an item in the project tree, you
will find several options on how to change a document or folder. This includes changing between
document and note, but also splitting them into multiple documents, or merging child items into a
single document.
Splitting Documents
^^^^^^^^^^^^^^^^^^^
.. figure:: images/fig_project_split_tool.png
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.
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 to the :guilabel:`Trash` folder.
Merging Documents
^^^^^^^^^^^^^^^^^
.. figure:: images/fig_project_merge_tool.png
The :guilabel:`Merge Documents` dialog.
You have two options for merging documents that are child elements of another document. You can
either :guilabel:`Merge Child Items into Self` and :guilabel:`Merge Child Items into New`. The
first option will pull all content of child items and merge them into the parent document, while
the second option will create a new document in the process.
When merging documents in a folder, you only have the latter process is possible, so only the
choice :guilabel:`Merge Documents in Folder` is available.
In either case, the :guilabel:`Merge Documents` dialog will let you exclude documents you don't
want to include, and it also lets you reorder them if you wish.
.. _a_ui_tree_status:
Document Importance and Status