Merge branch 'main' into update_i18n
This commit is contained in:
Veronica Berglyd Olsen
@@ -1,6 +1,7 @@
|
||||
docutils>=0.17.1
|
||||
pygments>=2.7
|
||||
sphinx-book-theme
|
||||
sphinx-copybutton
|
||||
sphinx-design
|
||||
sphinx-favicon
|
||||
sphinx-intl
|
||||
|
||||
+1
-1
@@ -40,7 +40,7 @@ os.environ["TZ"] = "Europe/Oslo"
|
||||
time.tzset()
|
||||
|
||||
needs_sphinx = "5.0"
|
||||
extensions = ["sphinx_design"]
|
||||
extensions = ["sphinx_design", "sphinx_copybutton"]
|
||||
templates_path = ["_templates"]
|
||||
source_suffix = ".rst"
|
||||
master_doc = "index"
|
||||
|
||||
@@ -0,0 +1,92 @@
|
||||
.. _docs_features_dialogue:
|
||||
|
||||
*********************
|
||||
Dialogue Highlighting
|
||||
*********************
|
||||
|
||||
Dialogue recognition and colour highlighting is available both while you're writing and in
|
||||
generated manuscript documents.
|
||||
|
||||
The default language settings in novelWriter are for English. That includes the dialogue
|
||||
highlighting settings. But many dialogue styles are supported. You can tune a number of settings
|
||||
to fit your language and style preferences in the "Text Highlighting" section in **Preferences**.
|
||||
You can mix and match these settings.
|
||||
|
||||
.. figure:: images/fig_dialogue_highlighting.png
|
||||
|
||||
The **Text Highlighting** section of **Preferences**.
|
||||
|
||||
|
||||
Quoted Dialogue
|
||||
===============
|
||||
|
||||
By default, dialogue highlighting is enabled for the double quote symbols you have defined in the
|
||||
**Quotation Style** section of **Preferences**.
|
||||
|
||||
.. figure:: images/fig_dialogue_quote_styles.png
|
||||
|
||||
The **Quotation Style** section of **Preferences**.
|
||||
|
||||
You can change which quote symbols are highlighted by selecting one of "None", "Single", "Double",
|
||||
or "Both" from the "Highlight dialogue" setting under **Text Highlighting**.
|
||||
|
||||
You can also enable or disable the "Allow open-ended dialogue" setting to allow for the style where
|
||||
multi-paragraph dialogue is not closed until the last paragraph.
|
||||
|
||||
.. admonition:: Limitations
|
||||
|
||||
Dialogue highlighting for single quotes is difficult to process when the same single quote
|
||||
symbol is also used for apostrophes. There isn't a good solution to this. Your best option in
|
||||
the cases where the highlighting is wrong is to insert an alternative apostrophe symbol instead.
|
||||
See :ref:`docs_more_typographical_symbols_apostrophe` for more details.
|
||||
|
||||
|
||||
Alternative Dialogue
|
||||
====================
|
||||
|
||||
You can use the "Alternative dialogue symbols" setting for custom dialogue wrapper symbols. These
|
||||
are highlighted in a different colour than regular dialogue.
|
||||
|
||||
The intended use case here is if you use an alternative style to distinguish a different style of
|
||||
communication. The feature idea came from a science fiction series where mind-to-mind communication
|
||||
used a different quotation style.
|
||||
|
||||
|
||||
Dialogue Line Symbols
|
||||
=====================
|
||||
|
||||
In some languages, a single symbol at the start of a paragraph can indicate that the whole
|
||||
paragraph is dialogue. For instance, this symbol can be a short dash (en dash).
|
||||
|
||||
.. figure:: images/fig_dialogue_line.png
|
||||
|
||||
An example of dialogue starting with a short dash.
|
||||
|
||||
You can enable this feature by adding the symbols to the "Dialogue line symbols" setting. Multiple
|
||||
symbols are allowed.
|
||||
|
||||
|
||||
Dialogue with Narrator Break
|
||||
============================
|
||||
|
||||
The dialogue symbol setting will not detect if the dialogue ends in the paragraph. In some styles
|
||||
there is no way to actually indicate the switch from dialogue to narration; in others there are.
|
||||
These a narrator break symbols are usually dashes. You can select one of the supported dash symbols
|
||||
for narrator breaks. These can be used with any of the above dialogue recognition settings.
|
||||
|
||||
.. figure:: images/fig_dialogue_narrator_break.png
|
||||
|
||||
An example of dialogue starting with a short dash and a long dash narrator break.
|
||||
|
||||
|
||||
Alternating Dialogue and Narration
|
||||
==================================
|
||||
|
||||
The alternating dialogue and narration style is supported with the "Alternating dialogue/narration
|
||||
symbol" setting. It can be set to one of the supported dashes. This style will switch into dialogue
|
||||
mode when it first encounters the selected dash in a paragraph, and switch back out when it sees
|
||||
the next one, and so forth.
|
||||
|
||||
.. figure:: images/fig_dialogue_alternating.png
|
||||
|
||||
An example of alternating dialogue and narration using a long dash.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 45 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
|
Before Width: | Height: | Size: 81 KiB After Width: | Height: | Size: 81 KiB |
@@ -1,4 +1,4 @@
|
||||
.. _a_kb:
|
||||
.. _docs_features_shortcuts:
|
||||
|
||||
******************
|
||||
Keyboard Shortcuts
|
||||
@@ -8,11 +8,10 @@ Most features in novelWriter are available as keyboard shortcuts. This is a refe
|
||||
shortcuts. Most of them are also listed in the application's user interface.
|
||||
|
||||
.. note::
|
||||
|
||||
On MacOS, replace :kbd:`Ctrl` with :kbd:`Cmd`.
|
||||
|
||||
|
||||
.. _a_kb_main:
|
||||
|
||||
Main Window Shortcuts
|
||||
=====================
|
||||
|
||||
@@ -38,8 +37,6 @@ Main Window Shortcuts
|
||||
":kbd:`Shift+F6`", "Open the **Project Details** dialog"
|
||||
|
||||
|
||||
.. _a_kb_tree:
|
||||
|
||||
Project Tree Shortcuts
|
||||
======================
|
||||
|
||||
@@ -62,8 +59,6 @@ Project Tree Shortcuts
|
||||
":kbd:`Ctrl+Shift+Del`", "Move the selected item to Trash"
|
||||
|
||||
|
||||
.. _a_kb_editor:
|
||||
|
||||
Document Editor Shortcuts
|
||||
=========================
|
||||
|
||||
@@ -120,7 +115,7 @@ Other Editor Shortcuts
|
||||
":kbd:`Ctrl+.`", "Open the context menu at the current cursor location"
|
||||
":kbd:`Ctrl+A`", "Select all text in the document"
|
||||
":kbd:`Ctrl+C`", "Copy selected text to clipboard"
|
||||
":kbd:`Ctrl+K`", "Activate the insert commands (see list in :ref:`a_kb_ins`)"
|
||||
":kbd:`Ctrl+K`", "Activate the insert commands (see list in :ref:`docs_features_shortcuts_insert`)"
|
||||
":kbd:`Ctrl+R`", "Open or reload the current document in the viewer"
|
||||
":kbd:`Ctrl+S`", "Save the current document"
|
||||
":kbd:`Ctrl+V`", "Paste text from clipboard to cursor position"
|
||||
@@ -135,7 +130,7 @@ Other Editor Shortcuts
|
||||
":kbd:`Ctrl+Shift+A`", "Select all text in the current paragraph"
|
||||
|
||||
|
||||
.. _a_kb_ins:
|
||||
.. _docs_features_shortcuts_insert:
|
||||
|
||||
Insert Shortcuts
|
||||
----------------
|
||||
@@ -184,8 +179,6 @@ a key or key combination for the inserted content.
|
||||
":kbd:`Ctrl+K`, :kbd:`Shift+Space`", "Insert a thin space"
|
||||
|
||||
|
||||
.. _a_kb_viewer:
|
||||
|
||||
Document Viewer Shortcuts
|
||||
=========================
|
||||
|
||||
@@ -1,25 +1,26 @@
|
||||
.. _a_story_structure:
|
||||
.. _docs_features_story:
|
||||
|
||||
************************
|
||||
Story Structure Comments
|
||||
************************
|
||||
**************
|
||||
Story Comments
|
||||
**************
|
||||
|
||||
|
||||
As of version 2.7, story structure annotations using the ``%story`` style of comment is supported.
|
||||
To use the feature, make the first word of a comment ``story``, followed by a period, a structure
|
||||
term, a colon, a space and the text for that term.
|
||||
|
||||
Here's an example:
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
%story.term: text
|
||||
A special set of comment styles allow for annotating your text with structure information. There
|
||||
are two styles of comments available. They are an extension to regular comments as described in
|
||||
:ref:`docs_usage_comments`.
|
||||
|
||||
.. versionadded:: 2.7
|
||||
|
||||
|
||||
Story Structure Comments
|
||||
========================
|
||||
|
||||
You can annotate story structure by using the ``%Story`` style of comment. To use the feature,
|
||||
make the first word of a comment ``Story``, followed by a period, a structure term, a colon, a
|
||||
space and the text for that term.
|
||||
|
||||
|
||||
Usage
|
||||
=====
|
||||
-----
|
||||
|
||||
The story term can be anything that you want to track in the manuscript. This construct is intended
|
||||
to make it easier to extract metadata from a work to perform a structural analysis of the story.
|
||||
@@ -33,6 +34,8 @@ story is composed of "beats", and that each beat has an inciting incident, a com
|
||||
crisis, and a resolution. One might capture these elements of a beat where a character overcomes
|
||||
their fear of giving a speech as:
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
### Scene
|
||||
@@ -56,7 +59,7 @@ fast-paced scenes without a break that readers might become fatigued or over-sti
|
||||
|
||||
|
||||
Output
|
||||
======
|
||||
------
|
||||
|
||||
The story structure comments can be included in the manuscript, and are formatted similarly to
|
||||
the synopsis comments:
|
||||
@@ -67,3 +70,41 @@ the synopsis comments:
|
||||
|
||||
When you export your project data from the Outline View, all story structure terms are added as
|
||||
columns to the exported file, which can then be opened in the spread sheet software of your choice.
|
||||
|
||||
|
||||
Story Notes
|
||||
===========
|
||||
|
||||
Story notes are similar to story structure comments, but have no predefined meaning. Essentially
|
||||
they are a generalisation of the story structure comment, and the only point of having this
|
||||
additional format is to allow you do filter them in and out of your manuscript independently.
|
||||
|
||||
You can annotate story notes by using the ``%Note`` style of comment. To use the feature,
|
||||
make the first word of a comment ``Note``, followed by a period, a term, a colon, a space and the
|
||||
text for the note.
|
||||
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
These notes are free form, but one intended use case is to add consistency annotations to your text
|
||||
to remind yourself where you have described something that must be checked against other parts of
|
||||
your text later on.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
### Scene
|
||||
|
||||
%Synopsis: Carol overcomes her fear of giving a speech.
|
||||
|
||||
%Note.consistency: This is the first time in the story Carol gives a speech.
|
||||
|
||||
|
||||
Output
|
||||
------
|
||||
|
||||
Story notes are included in the manuscript in exactly the same way story structure comments are,
|
||||
but has a separate inclusion setting in the build settings. They are also included in CSV exports
|
||||
from the **Outline View**.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 63 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 101 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 185 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 516 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 535 KiB |
+33
-47
@@ -16,14 +16,6 @@ storage for robustness.
|
||||
:align: center
|
||||
:width: 500
|
||||
|
||||
The project storage is suitable for version control software, and also well suited for file
|
||||
synchronisation tools. All text is saved as plain text files, and your project data as standard
|
||||
data formats in XML and JSON. See :ref:`a_storage` for more details.
|
||||
|
||||
Any operating system that has Python 3 and the Qt 6 libraries should be able to run novelWriter.
|
||||
It runs fine on Linux, Windows and MacOS, and users have tested it on other platforms as well.
|
||||
See :ref:`a_started` for more details.
|
||||
|
||||
**Useful Links**
|
||||
|
||||
* Website: https://novelwriter.io
|
||||
@@ -40,64 +32,58 @@ See :ref:`a_started` for more details.
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
Main Page <self>
|
||||
self
|
||||
More Documents <https://novelwriter.io/more/>
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Introduction
|
||||
:caption: Getting Started
|
||||
:hidden:
|
||||
|
||||
int_introduction
|
||||
int_overview
|
||||
int_started
|
||||
int_howto
|
||||
int_glossary
|
||||
usage/introduction
|
||||
usage/organising_project
|
||||
usage/chapters_and_scenes
|
||||
usage/basic_formatting
|
||||
usage/comments
|
||||
usage/tags_and_references
|
||||
usage/alignment_and_indent
|
||||
usage/advanced_formatting
|
||||
usage/front_back_matter
|
||||
usage/howto
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Using novelWriter
|
||||
:caption: The User Interface
|
||||
:hidden:
|
||||
|
||||
usage_breakdown
|
||||
usage_project
|
||||
usage_writing
|
||||
usage_format
|
||||
usage_shortcuts
|
||||
usage_typography
|
||||
user_interface/main_window
|
||||
user_interface/projects
|
||||
user_interface/editor_viewer
|
||||
user_interface/split_and_merge
|
||||
user_interface/manuscript
|
||||
user_interface/statistics
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Organising Your Project
|
||||
:caption: Other Features
|
||||
:hidden:
|
||||
|
||||
project_overview
|
||||
project_structure
|
||||
project_references
|
||||
project_manuscript
|
||||
features/dialogue
|
||||
features/story_comments
|
||||
features/shortcuts
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Writing Aids
|
||||
:caption: In-Depth Topics
|
||||
:hidden:
|
||||
|
||||
writing_story
|
||||
more/counting
|
||||
more/typography
|
||||
more/customise
|
||||
more/handling_errors
|
||||
more/project_format
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Additional Details
|
||||
:hidden:
|
||||
|
||||
more_customise
|
||||
more_projectformat
|
||||
more_counting
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Technical Topics
|
||||
:hidden:
|
||||
|
||||
tech_locations
|
||||
tech_storage
|
||||
tech_source
|
||||
tech_tests
|
||||
technical/locations
|
||||
technical/storage
|
||||
technical/source
|
||||
technical/tests
|
||||
|
||||
@@ -1,64 +0,0 @@
|
||||
.. _a_glossary:
|
||||
|
||||
********
|
||||
Glossary
|
||||
********
|
||||
|
||||
.. glossary::
|
||||
:sorted:
|
||||
|
||||
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:`a_proj_roots`.
|
||||
|
||||
Novel Documents
|
||||
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
|
||||
A tag is a user defined value assigned as a tag to a section of your :term:`Project Notes`.
|
||||
It is optional, and can be defined once per heading. It is set using the :term:`keyword`
|
||||
syntax ``@tag: value``, where ``value`` is the user defined part. Each tag can be referenced
|
||||
in another file using one of the :term:`reference` keywords. See :ref:`a_references` chapter
|
||||
for more details.
|
||||
|
||||
Reference
|
||||
A reference is one of a set of :term:`keywords<keyword>` that can be used to link to a
|
||||
:term:`tag` in another document. The reference keywords are specific to the different
|
||||
:term:`root folder` types. A full overview is available in the :ref:`a_references` chapter.
|
||||
|
||||
Project Index
|
||||
The project index is a record of all headings in a project, with all their meta data like
|
||||
synopsis comments, :term:`tags<tag>` and :term:`references<reference>`. The project index is
|
||||
kept up to date automatically, but can also be regenerated manually from the
|
||||
:guilabel:`Tools` menu or by pressing :kbd:`F9`.
|
||||
|
||||
Context Menu
|
||||
A context menu is a menu that pops up when you right click something in the user interface.
|
||||
In novelWriter, you can often also open a context menu by pressing the keyboard shortcut
|
||||
:kbd:`Ctrl+.`.
|
||||
|
||||
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 heading levels don't
|
||||
matter. For more details on headings in novel documents, see :ref:`a_struct_heads`.
|
||||
|
||||
Keyword
|
||||
A keyword in novelWriter is a special command you put in the text of your documents. They are
|
||||
not standard Markdown, but are used in novelWriter to add information that is interpreted by
|
||||
the application. For instance, keywords are used for :term:`tags<tag>` and
|
||||
:term:`references<reference>`.
|
||||
|
||||
Keywords must always be on their own line, and the first character of the line must always be
|
||||
the ``@`` character. The keyword must also always be followed by a ``:`` character, and the
|
||||
values passed to the command are added after this, separated by commas.
|
||||
@@ -1,129 +0,0 @@
|
||||
.. _a_intro:
|
||||
|
||||
********
|
||||
Overview
|
||||
********
|
||||
|
||||
.. _Snowflake: https://www.advancedfictionwriting.com/articles/snowflake-method/
|
||||
.. _Markdown: https://en.wikipedia.org/wiki/Markdown
|
||||
|
||||
At its core, novelWriter is a multi-document plain text editor. The idea is to let you edit your
|
||||
text without having to deal with formatting until you generate a draft document or manuscript.
|
||||
Instead, you can focus on the writing right from the start.
|
||||
|
||||
Of course, you probably need *some* formatting for your text. At the very least you need emphasis.
|
||||
Most people are familiar with adding emphasis using ``_underscores_`` and ``**asterisks**``. This
|
||||
formatting standard comes from Markdown_ and is supported by novelWriter. It also uses Markdown
|
||||
formatting for defining document headings. If you need more specialised formatting, additional
|
||||
formatting options are available using a shortcode format. See :ref:`a_fmt_shortcodes` for more
|
||||
details.
|
||||
|
||||
.. admonition:: Limitations
|
||||
|
||||
novelWriter is designed for writing fiction, so the formatting features available are limited to
|
||||
those relevant for this purpose. It is *not* suitable for technical writing, and it is *not* a
|
||||
full-featured Markdown editor.
|
||||
|
||||
It is also not intended as a tool for organising research for writing, and therefore lacks
|
||||
formatting features you may need for this purpose. The notes feature in novelWriter is mainly
|
||||
intended for character profiles and plot outlines.
|
||||
|
||||
Your novel project in novelWriter is organised as a collection of separate plain text documents
|
||||
instead of a single, large document. The idea is to make it easier to reorganise your project
|
||||
structure without having to cut and paste text between chapters and scenes.
|
||||
|
||||
There are two kinds of documents in your project: :term:`Novel Documents` are documents that are
|
||||
part of your story. The other kind of documents are :term:`Project Notes`, which are intended for
|
||||
your notes about your characters, your world building, and so on.
|
||||
|
||||
You can at any point split the individual documents by their headings up into multiple documents,
|
||||
or merge multiple documents into a single document. This makes it easier to use variations of the
|
||||
Snowflake_ method for writing. You can start by writing larger structure-focused documents, like
|
||||
for instance one document per act, and later effortlessly split these up into individual chapter or
|
||||
scene documents.
|
||||
|
||||
|
||||
.. _a_intro_features:
|
||||
|
||||
Key Features
|
||||
============
|
||||
|
||||
Below are some key features of novelWriter.
|
||||
|
||||
**Focus on writing**
|
||||
The aim of the user interface is to let you focus on writing instead of spending time formatting
|
||||
text. Formatting is therefore limited to a small set of formatting tags for simple things like
|
||||
text emphasis and paragraph alignment. Additional shortcodes are available for special
|
||||
formatting cases when you need them.
|
||||
|
||||
When you really want to focus on just writing, you can switch the editor into **Focus Mode**
|
||||
where only the text editor panel itself is visible, and the project structure view is hidden
|
||||
away.
|
||||
|
||||
**Keep an eye on your notes**
|
||||
The main window can optionally show a document viewer to the right of the editor. The viewer
|
||||
is intended for displaying another scene document, your character notes, plot notes, or any
|
||||
other document you may need to reference while writing. It is not intended as a preview panel
|
||||
for the document you're editing, but if you wish, you can also use it for this purpose.
|
||||
|
||||
**Organise your documents how you like**
|
||||
You can split your novel project up into as many individual documents as you want to. When you
|
||||
build the project into a manuscript, they are all glued together in the top-to-bottom order in
|
||||
which they appear in the project tree. You can use as few text documents as you like, but
|
||||
splitting the project up into chapters and scenes means you can easily reorder them using the
|
||||
drag-and-drop feature of the project tree. You can also start out with fewer documents and then
|
||||
later split them into multiple documents based on chapter and scene headings.
|
||||
|
||||
**Multi-novel project support**
|
||||
The main parts of your project is split up into top level special folders called "Root" folders.
|
||||
Your main story text lives in the "Novel" root folder. You can have multiple such folders in a
|
||||
project, and rename them to whatever you want. This allows you to keep a series of individual
|
||||
novels with the same characters and world building in the same project, and create manuscripts
|
||||
for them separately.
|
||||
|
||||
**Keep track of your story elements**
|
||||
All documents in your project can be assigned a :term:`tag` that you can then :term:`reference`
|
||||
from any other document or note. In fact, you can add a new tag under each heading of a note if
|
||||
you need to be able to reference specific sections of it, or you want to keep several topics or
|
||||
scenes in the same document.
|
||||
|
||||
**Get an overview of your story**
|
||||
It is not the documents themselves that define the chapters and scenes of your story, but the
|
||||
headings within them. In the **Outline View** on the main window you can see an outline of all
|
||||
the chapter and scene headings of each novel root folder in your project. If they have any
|
||||
references in them, like which character is in what chapter and scene, these are listed in
|
||||
additional columns.
|
||||
|
||||
You can also add a synopsis to each chapter or scene, which can be listed here as well. You have
|
||||
the option to add or remove columns of information from this outline. A subset of the outline
|
||||
information is also available in the **Novel View** as an alternative view to the project tree.
|
||||
|
||||
**Get an overview of your story elements**
|
||||
Under the document viewer panel you will find a series of tabs that show the different story
|
||||
elements you have created tags for. The tabs are sorted into **Characters**, **Plots**, etc,
|
||||
depending on which categories you are using in your story. This panel can be hidden to free up
|
||||
space when you don't need it.
|
||||
|
||||
**Assembling your manuscript**
|
||||
Whether you want to assemble a manuscript, or export all your notes, or generate an outline of
|
||||
your chapters and scenes with a synopsis included, you can use the **Build Manuscript** tool to
|
||||
do so. The tool lets you select what information you want to include in the generated document,
|
||||
and how it is formatted. You can send the result to a printer, or generate an Open Document or
|
||||
Word Document file that can be opened by most office type word processors. You can also generate
|
||||
the result as HTML, or Markdown, both suitable for further conversion to other formats.
|
||||
|
||||
|
||||
.. _a_intro_screenshots:
|
||||
|
||||
Screenshots
|
||||
===========
|
||||
|
||||
.. figure:: images/screenshot_light.png
|
||||
:class: dark-light
|
||||
|
||||
novelWriter with light colour theme
|
||||
|
||||
.. figure:: images/screenshot_dark.png
|
||||
:class: dark-light
|
||||
|
||||
novelWriter with dark colour theme
|
||||
@@ -1,100 +0,0 @@
|
||||
.. _a_reading:
|
||||
|
||||
******************
|
||||
What to Read First
|
||||
******************
|
||||
|
||||
The documentation of novelWriter is quite extensive. There are a lot of features to get used to,
|
||||
but you don't need to know all of them to get started.
|
||||
|
||||
The chapters below labelled "Essential Information" are the ones you need to know to use the
|
||||
application correctly. By "correctly" it is meant: in a way so novelWriter understands the basic
|
||||
structure of your text. It collects a lot of information from your text and uses it to display the
|
||||
structure of it in various ways to help you get an overview of your writing.
|
||||
|
||||
The chapters labelled "Recommended Reading" includes additional information on how the different
|
||||
parts if the application work and what the features do.
|
||||
|
||||
The "Optional" and "Lookup" chapters contain additional information or lookup tables that are not
|
||||
essential for using the application.
|
||||
|
||||
|
||||
Using novelWriter
|
||||
=================
|
||||
|
||||
In order to use novelWriter effectively, you need to know the basics of how it works. The following
|
||||
chapters will explain the main principles. They start with the basics, and get more detailed as you
|
||||
read on.
|
||||
|
||||
:ref:`a_breakdown` -- Essential Information
|
||||
This chapter explains the basics of how the application works and what it can and cannot do.
|
||||
|
||||
:ref:`a_ui_project` -- Recommended Reading
|
||||
This chapter will give you a more detailed explanation of how you can use the user interface
|
||||
components to organise and view your project work.
|
||||
|
||||
:ref:`a_ui_writing` -- Recommended Reading
|
||||
This chapter will give you a more detailed explanation of how the text editor and viewer work.
|
||||
|
||||
:ref:`a_fmt` -- Essential Information
|
||||
This chapter covers how you should format your text. The editor is plain text, so text
|
||||
formatting requires some basic markup. The structure of your novel is also inferred from how you
|
||||
use headings. Tags and references are implemented by special keywords.
|
||||
|
||||
:ref:`a_kb` -- Optional / Lookup
|
||||
This chapter lists all the keyboard shortcuts in novelWriter and what they do. Most of the
|
||||
shortcuts are also listed next to their menu entries inside the app, or in tool tips. This
|
||||
chapter is mostly for reference.
|
||||
|
||||
:ref:`a_typ` -- Optional
|
||||
This chapter gives you an overview of the special typographical symbols available in
|
||||
novelWriter. The auto-replace feature can handle the insertion of standard quote symbols for
|
||||
your language, and other special characters. If you use any symbols aside from these, their
|
||||
intended use is explained here.
|
||||
|
||||
|
||||
Organising Your Projects
|
||||
========================
|
||||
|
||||
In addition to managing a collection of plain text files, novelWriter can interpret and map the
|
||||
structure of your novel and show you additional information about its flow and content. In order
|
||||
to take advantage of these features, you must structure your text in a specific way and add some
|
||||
meta data for it to extract.
|
||||
|
||||
:ref:`a_proj` -- Essential Information
|
||||
This chapter explains how you organise the content of your project, and how to set up automated
|
||||
backups of your work.
|
||||
|
||||
:ref:`a_struct` -- Essential Information
|
||||
This chapter covers the way your novel's structure is encoded into the text documents. It
|
||||
explains how the different levels of headings are used, and some special formatting for
|
||||
different kinds of headings.
|
||||
|
||||
:ref:`a_references` -- Recommended Reading
|
||||
This chapter explains how you organise your notes, and how the Tags and References system works.
|
||||
This system lets you cross-link your documents in your project, and display these references in
|
||||
the application interface.
|
||||
|
||||
:ref:`a_manuscript` -- Recommended Reading
|
||||
This chapter explains how the **Manuscript Build** tool works, how you can control the way
|
||||
chapter titles are formatted, and how scene and section breaks are handled.
|
||||
|
||||
|
||||
Writing Aids
|
||||
============
|
||||
|
||||
We are in the process of adding tools to novelWriter that can be used to track more information
|
||||
about your project to assist in your writing. These tools are entirely optional and will not be in
|
||||
your way if you choose to not use them.
|
||||
|
||||
:ref:`a_story_structure` -- Writing Tools
|
||||
Story structure comments are a way to add meta data that can be used to analyse the structure of
|
||||
your writing. These comments can be exported to spreadsheets for analysis.
|
||||
|
||||
|
||||
Additional Details & Technical Topics
|
||||
=====================================
|
||||
|
||||
The Additional Details and the Technical Topics sections contain more in-depth information about
|
||||
how various bits of novelWriter works. This information is not essential to getting started using
|
||||
novelWriter.
|
||||
@@ -1,170 +0,0 @@
|
||||
.. _a_started:
|
||||
|
||||
**********************
|
||||
Setup and Installation
|
||||
**********************
|
||||
|
||||
.. _Enchant: http://rrthomas.github.io/enchant/
|
||||
.. _GitHub: https://github.com/vkbo/novelWriter
|
||||
.. _Downloads page: https://download.novelwriter.io
|
||||
.. _PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter
|
||||
.. _Pre-Release PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter-pre
|
||||
.. _PyPi: https://pypi.org/project/novelWriter/
|
||||
.. _python.org: https://www.python.org/downloads/
|
||||
.. _Releases: https://github.com/vkbo/novelWriter/releases
|
||||
.. _AppImage: https://appimage.org/
|
||||
|
||||
Ready-made packages and installers for novelWriter are available for all major platforms, including
|
||||
Linux, Windows and MacOS, from the `Downloads page`_. See below for additional install instructions
|
||||
for each platform.
|
||||
|
||||
You can also install novelWriter from the Python Package Index (PyPi_). See :ref:`a_started_pip`.
|
||||
Installing from PyPi does not set up icon launchers, so you will either have to do this yourself,
|
||||
or start novelWriter from the command line.
|
||||
|
||||
Spell checking in novelWriter is provided by a third party library called Enchant_. Generally, it
|
||||
should pull dictionaries from your operating system automatically. However, on Windows they must be
|
||||
installed manually. See :ref:`a_custom_dict` for more details.
|
||||
|
||||
|
||||
.. _a_started_windows:
|
||||
|
||||
Installing on Windows
|
||||
=====================
|
||||
|
||||
You can install novelWriter with both Python and library dependencies embedded using the Windows
|
||||
Installer (setup.exe) file from the `Downloads page`_, or from the Releases_ page on GitHub_.
|
||||
Installing it should be straightforward.
|
||||
|
||||
If you have any issues, try uninstalling the previous version and making a fresh install. If you
|
||||
already had a version installed via a different method, you should uninstall that first as having
|
||||
multiple installations has been known to cause problems.
|
||||
|
||||
|
||||
.. _a_started_linux:
|
||||
|
||||
Installing on Linux
|
||||
===================
|
||||
|
||||
A Debian package can be downloaded from the `Downloads page`_, or from the Releases_ page on
|
||||
GitHub_. This package should work on both Debian, Ubuntu and Linux Mint, at least.
|
||||
|
||||
If you prefer, you can also add the novelWriter repository on Launchpad to your package manager.
|
||||
The Launchpad packages `are signed by the author <https://launchpad.net/~vkbo>`__.
|
||||
|
||||
|
||||
Ubuntu
|
||||
------
|
||||
|
||||
You can add the Ubuntu PPA_ and install novelWriter with the following commands.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo add-apt-repository ppa:vkbo/novelwriter
|
||||
sudo apt update
|
||||
sudo apt install novelwriter
|
||||
|
||||
If you want the `Pre-Release PPA`_ instead, add the ``ppa:vkbo/novelwriter-pre`` repository.
|
||||
|
||||
|
||||
Debian and Mint
|
||||
---------------
|
||||
|
||||
Since this is a pure Python package, the Launchpad PPA can in principle also be used on Debian or
|
||||
Mint. However, the above command will fail to add the signing key, as it is Ubuntu-specific.
|
||||
|
||||
Instead, run the following commands to add the repository and key:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo gpg --no-default-keyring --keyring /usr/share/keyrings/novelwriter-ppa-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys F19F1FCE50043114
|
||||
echo "deb [signed-by=/usr/share/keyrings/novelwriter-ppa-keyring.gpg] http://ppa.launchpad.net/vkbo/novelwriter/ubuntu noble main" | sudo tee /etc/apt/sources.list.d/novelwriter.list
|
||||
|
||||
Then run the update and install commands as for Ubuntu:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo apt update
|
||||
sudo apt install novelwriter
|
||||
|
||||
.. tip::
|
||||
If you get an error message like ``gpg: failed to create temporary file`` when importing the key
|
||||
from the Ubuntu keyserver, try creating the folder it fails on, and import the key again:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkdir /root/.gnupg/
|
||||
|
||||
|
||||
AppImage Releases
|
||||
-----------------
|
||||
|
||||
For other Linux distros than the ones mentioned above, the primary option is AppImage_. These are
|
||||
completely standalone images for the app that include the necessary environment to run novelWriter.
|
||||
They can of course be run on any Linux distro, if you prefer this to native packages.
|
||||
|
||||
.. note::
|
||||
novelWriter generally doesn't support Python versions that have reached end of life. If your
|
||||
Linux distro still uses older Python versions and novelWriter won't run, you may want to try the
|
||||
AppImage instead.
|
||||
|
||||
|
||||
.. _a_started_macos:
|
||||
|
||||
Installing on MacOS
|
||||
===================
|
||||
|
||||
You can install novelWriter with both its Python and library dependencies embedded using the DMG
|
||||
application image file from the `Downloads page`_, or from the Releases_ page on GitHub_.
|
||||
Installing it should be straightforward.
|
||||
|
||||
* Download the DMG file and open it. Then drag the novelWriter icon to the :guilabel:`Applications`
|
||||
folder on the right. This will install it into your :guilabel:`Applications`.
|
||||
* The first time you try to launch it, it will say that the bundle cannot be verified, simply press
|
||||
the :guilabel:`Open` button to add an exception.
|
||||
* If you are not presented with an :guilabel:`Open` button in the dialog, launch the application
|
||||
again by right clicking on the application in Finder and selecting :guilabel:`Open` from the
|
||||
context menu.
|
||||
|
||||
The context menu can also be accessed by option-clicking if you have a one button mouse. This is
|
||||
done by holding down the option key on your keyboard and clicking on the application in Finder.
|
||||
|
||||
.. note::
|
||||
The novelWriter DMG is not signed because Apple doesn't currently provide a way for non-profit
|
||||
open source projects to properly sign their installers. The novelWriter project doesn't have the
|
||||
funding to pay for a commercial software signing certificate.
|
||||
|
||||
|
||||
.. _a_started_pip:
|
||||
|
||||
Installing from PyPi
|
||||
====================
|
||||
|
||||
novelWriter is also available on the Python Package Index, or PyPi_. This install method works on
|
||||
all supported operating systems with a suitable Python environment.
|
||||
|
||||
To install from PyPi you must first have the ``python`` and ``pip`` commands available on your
|
||||
system. You can download Python from `python.org`_. It is recommended that you install the latest
|
||||
version. If you are on Windows, also make sure to select the "Add Python to PATH" option during
|
||||
installation.
|
||||
|
||||
To install novelWriter from PyPi, use the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install novelwriter
|
||||
|
||||
To upgrade an existing installation, use:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install --upgrade novelwriter
|
||||
|
||||
When installing via pip, novelWriter can be launched from command line with:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
novelwriter
|
||||
|
||||
Make sure the install location for pip is in your PATH variable. This is not always the case by
|
||||
default, and then you may get a "Not Found" error when running the ``novelwriter`` command.
|
||||
@@ -1,13 +1,13 @@
|
||||
.. _a_counting:
|
||||
.. _docs_more_counting:
|
||||
|
||||
********************
|
||||
Word and Text Counts
|
||||
********************
|
||||
|
||||
This is an overview of how words and other counts of your text are performed. The counting rules
|
||||
should be relatively standard, and are compared to Libre Office Writer rules.
|
||||
should be relatively standard, and are comparable to Libre Office Writer rules.
|
||||
|
||||
The counts provided in the app on the raw text is meant to be approximate. For more accurate
|
||||
The counts provided in the app on the raw text are meant to be approximate. For more accurate
|
||||
counts, you need to build your manuscript in the **Manuscript Tool** and check the counts on the
|
||||
generated preview.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
.. _a_custom:
|
||||
.. _docs_more_custom:
|
||||
|
||||
**************
|
||||
Customisations
|
||||
@@ -11,7 +11,7 @@ There are a few ways you can customise novelWriter yourself. Currently, you can
|
||||
your own syntax themes, and install additional dictionaries.
|
||||
|
||||
|
||||
.. _a_custom_dict:
|
||||
.. _docs_more_custom_dict:
|
||||
|
||||
Spell Check Dictionaries
|
||||
========================
|
||||
@@ -19,6 +19,7 @@ Spell Check Dictionaries
|
||||
novelWriter uses Enchant_ as the spell checking tool. Depending on your operating system, it may or
|
||||
may not load all installed spell check dictionaries automatically.
|
||||
|
||||
|
||||
Linux and MacOS
|
||||
---------------
|
||||
|
||||
@@ -26,6 +27,7 @@ On Linux and MacOS, you generally only have to install hunspell, aspell or myspe
|
||||
your system like you do for other applications. See your distro or OS documentation for how to do
|
||||
this. These dictionaries should show up as available spell check languages in novelWriter.
|
||||
|
||||
|
||||
Windows
|
||||
-------
|
||||
|
||||
@@ -61,7 +63,7 @@ You can find the various dictionaries on the `Free Desktop`_ website.
|
||||
each line and download that.
|
||||
|
||||
|
||||
.. _a_custom_theme:
|
||||
.. _docs_more_custom_theme:
|
||||
|
||||
Syntax and GUI Themes
|
||||
=====================
|
||||
@@ -84,17 +86,17 @@ Remember to also change the name of your theme by modifying the ``name`` setting
|
||||
file, otherwise you may not be able to distinguish them in **Preferences**.
|
||||
|
||||
For novelWriter to be able to locate the custom theme files, you must copy them to the
|
||||
:ref:`a_locations_data` location in your home or user area. There should be a folder there named
|
||||
:ref:`docs_technical_locations_data` location in your home or user area. There should be a folder there named
|
||||
``syntax`` for syntax themes, just ``themes`` for GUI themes, and ``icons`` for icon themes. These
|
||||
folders are created the first time you start novelWriter.
|
||||
|
||||
Once the files are copied there, they should show up in **Preferences** with the label you
|
||||
set as ``name`` inside the file.
|
||||
|
||||
.. versionadded:: 2.0
|
||||
The ``icontheme`` value was added to GUI themes. Make sure you set this value in existing custom
|
||||
themes. Otherwise, novelWriter will try to guess your icon theme, and may not pick the most
|
||||
suitable one.
|
||||
.. note::
|
||||
|
||||
The theme file formats change regularly in new releases. It is up to you to keep custom theme
|
||||
files up to date.
|
||||
|
||||
|
||||
Custom GUI and Icons Theme
|
||||
@@ -112,7 +114,26 @@ A GUI theme ``.conf`` file consists of the following settings:
|
||||
url = https://example.com
|
||||
license = CC BY-SA 4.0
|
||||
licenseurl = https://creativecommons.org/licenses/by-sa/4.0/
|
||||
icontheme = typicons_light
|
||||
|
||||
[Icons]
|
||||
default = 100, 100, 100
|
||||
faded = 100, 100, 100
|
||||
red = 255, 0, 0
|
||||
orange = 255, 128, 0
|
||||
yellow = 255, 255, 0
|
||||
green = 0, 255, 0
|
||||
aqua = 0, 255, 255
|
||||
blue = 0, 0, 255
|
||||
purple = 255, 0, 255
|
||||
|
||||
[Project]
|
||||
root = 0, 255, 255
|
||||
folder = 255, 255, 0
|
||||
file = 100, 100, 100
|
||||
title = 0, 255, 0
|
||||
chapter = 255, 0, 0
|
||||
scene = 0, 0, 255
|
||||
note = 255, 255, 0
|
||||
|
||||
[Palette]
|
||||
window = 100, 100, 100
|
||||
@@ -134,24 +155,23 @@ A GUI theme ``.conf`` file consists of the following settings:
|
||||
helptext = 0, 0, 0
|
||||
fadedtext = 128, 128, 128
|
||||
errortext = 255, 0, 0
|
||||
statusnone = 120, 120, 120
|
||||
statussaved = 2, 133, 37
|
||||
statusunsaved = 200, 15, 39
|
||||
|
||||
In the Main section you must at least define the ``name`` and ``icontheme`` settings. The
|
||||
``icontheme`` settings should correspond to one of the internal icon themes, either
|
||||
``typicons_light`` or ``typicons_dark``, or to an icon theme in your custom icons directory. The
|
||||
setting must match the icon theme's folder name.
|
||||
In the Main section you must at least define the ``name`` settings.
|
||||
|
||||
The Palette values correspond to the Qt enum values for ``QPalette::ColorRole``, see the
|
||||
`Qt documentation <https://doc.qt.io/qt-6/qpalette.html#ColorRole-enum>`_ for more details. The
|
||||
colour values are RGB numbers on the format ``r, g, b`` where each is an integer from ``0`` to
|
||||
``255``. Omitted values are not loaded and will use default values. If the ``helptext`` colour is
|
||||
not defined, it is computed as a colour between the ``window`` and ``windowtext`` colour.
|
||||
Additional shades of some of the colours are also computed. These are mainly used for 3D effects.
|
||||
|
||||
.. versionadded:: 2.5
|
||||
The ``fadedtext`` and ``errortext`` theme colour entries were added.
|
||||
|
||||
.. versionadded:: 2.7
|
||||
The ``icontheme`` setting was dropped as the icon theme is now its own setting.
|
||||
The ``[Icons]`` and ``[Project]`` sections were added, and the ``status*`` settings removed.
|
||||
|
||||
|
||||
Custom Syntax Theme
|
||||
-------------------
|
||||
@@ -0,0 +1,62 @@
|
||||
.. _docs_more_errors:
|
||||
|
||||
***************
|
||||
Handling Errors
|
||||
***************
|
||||
|
||||
In case something goes wrong, novelWriter has a few built-in features to reduce the chance your
|
||||
work is lost. In case of a crash, it will also try to save whatever changes you have made before
|
||||
exiting, if this is at all possible.
|
||||
|
||||
The storage solution is designed to save each text document independently, so only the document
|
||||
you're working on is actually at a risk of losing data in the event of a crash.
|
||||
|
||||
|
||||
.. _docs_more_errors_orphaned:
|
||||
|
||||
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 storage folder
|
||||
that aren't tracked in the core project file. These files, when discovered, are recovered and added
|
||||
back into the project when a project is opened.
|
||||
|
||||
The discovered files are scanned for metadata that give clues as to where the document may
|
||||
previously have been located in the project. The project loading routine will try to put them back
|
||||
as close as possible to this location, if it still exists. Generally, it will be appended to the
|
||||
end of the folder where it previously was located. If that folder doesn't exist, it will try to add
|
||||
it to the correct root folder type. If it cannot figure out which root folder is correct, the
|
||||
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
|
||||
be named after its internal key, which is a string of characters and numbers.
|
||||
|
||||
|
||||
.. _docs_more_errors_lock:
|
||||
|
||||
Project Lockfile
|
||||
================
|
||||
|
||||
To prevent data loss caused by file conflicts when novelWriter projects are synchronised via 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 that 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 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
|
||||
the project are in fact open, you are likely to cause inconsistencies and create diverging
|
||||
project files, potentially resulting in loss of data and orphaned files. You are not likely to
|
||||
lose any actual text unless both instances have the same document open in the editor, and
|
||||
novelWriter will try to resolve project inconsistencies the next time you open the project.
|
||||
@@ -1,12 +1,9 @@
|
||||
.. _a_prjfmt:
|
||||
.. _docs_more_project_formats:
|
||||
|
||||
**********************
|
||||
Project Format Changes
|
||||
**********************
|
||||
|
||||
.. _File Format Spec 1.5: _static/fileformatspec15.pdf
|
||||
.. _documentation: https://docs.novelwriter.io/
|
||||
|
||||
Most of the changes to the file formats over the history of novelWriter have no impact on the
|
||||
user side of things. The project files are generally updated automatically. However, some of the
|
||||
changes require minor actions from the user.
|
||||
@@ -17,13 +14,14 @@ where applicable.
|
||||
A full project file format specification is available under "More Documents".
|
||||
|
||||
.. caution::
|
||||
|
||||
When you update a project from one format version to the next, the project can no longer be
|
||||
opened by a version of novelWriter prior to the version where the new file format was
|
||||
introduced. You will get a notification about any updates to your project file format and will
|
||||
have the option to decline the upgrade.
|
||||
|
||||
|
||||
.. _a_prjfmt_1_5:
|
||||
.. _docs_more_project_formats_1_5:
|
||||
|
||||
Format 1.5 Changes
|
||||
==================
|
||||
@@ -37,7 +35,7 @@ heading of the document is now saved to the item rather than in the index. The c
|
||||
automatically the first time a project is loaded. No user action is required.
|
||||
|
||||
|
||||
.. _a_prjfmt_1_4:
|
||||
.. _docs_more_project_formats_1_4:
|
||||
|
||||
Format 1.4 Changes
|
||||
==================
|
||||
@@ -51,7 +49,7 @@ compact format that is simpler and faster to parse, and easier to extend. The co
|
||||
automatically the first time a project is loaded. No user action is required.
|
||||
|
||||
|
||||
.. _a_prjfmt_1_3:
|
||||
.. _docs_more_project_formats_1_3:
|
||||
|
||||
Format 1.3 Changes
|
||||
==================
|
||||
@@ -71,25 +69,26 @@ should be used only a few places in any given project. These are as follows:
|
||||
**Title Pages**
|
||||
|
||||
* The formatting of the level one title on the title page must be changed from ``# Title Text`` to
|
||||
``#! Title Text`` in order to retain the previous functionality. See :ref:`a_fmt_head`.
|
||||
``#! Title Text`` in order to retain the previous functionality.
|
||||
See :ref:`docs_usage_headings_levels`.
|
||||
* Any text that was previously centred on the page must be manually centred using the text
|
||||
alignment feature. See :ref:`a_fmt_align`.
|
||||
alignment feature. See :ref:`docs_usage_align_indent`.
|
||||
|
||||
**Unnumbered Chapters**
|
||||
|
||||
* Since the specific layout for unnumbered chapters has been dropped, such chapters must all use
|
||||
the ``##! Chapter Name`` formatting code instead of ``## Chapter Name``. This also includes
|
||||
chapters marked by an asterisk: ``## *Chapter Name``, as this feature has also been dropped.
|
||||
See :ref:`a_fmt_head`.
|
||||
See :ref:`docs_usage_headings_levels`.
|
||||
|
||||
**Plain Pages**
|
||||
|
||||
* The layout named "Plain Page" has also been removed. The only feature of this layout was that it
|
||||
ensured that the content always started on a fresh page. In the new format, fresh pages can be
|
||||
set anywhere in the text with the ``[NEW PAGE]`` code. See :ref:`a_fmt_break`.
|
||||
set anywhere in the text with the ``[new page]`` code. See :ref:`docs_usage_formatting_breaks`.
|
||||
|
||||
|
||||
.. _a_prjfmt_1_2:
|
||||
.. _docs_more_project_formats_1_2:
|
||||
|
||||
Format 1.2 Changes
|
||||
==================
|
||||
@@ -97,9 +96,10 @@ Format 1.2 Changes
|
||||
This project format was introduced in novelWriter version 0.10.
|
||||
|
||||
With this format, the way auto-replace entries were stored in the main project XML file changed.
|
||||
Conversion from this format is done automatically.
|
||||
|
||||
|
||||
.. _a_prjfmt_1_1:
|
||||
.. _docs_more_project_formats_1_1:
|
||||
|
||||
Format 1.1 Changes
|
||||
==================
|
||||
@@ -110,10 +110,11 @@ With this format, the ``content`` folder was introduced in the project storage.
|
||||
novelWriter documents were saved in a series of folders numbered from ``data_0`` to ``data_f``.
|
||||
|
||||
It also reduces the number of meta data and cache files. These files are automatically deleted if
|
||||
an old project is opened. This was also when the Table of Contents file was introduced.
|
||||
an old project is opened. This was also when the Table of Contents file was introduced. Conversion
|
||||
from this format is done automatically.
|
||||
|
||||
|
||||
.. _a_prjfmt_1_0:
|
||||
.. _docs_more_project_formats_1_0:
|
||||
|
||||
Format 1.0 Changes
|
||||
==================
|
||||
@@ -1,4 +1,4 @@
|
||||
.. _a_typ:
|
||||
.. _docs_more_typographical:
|
||||
|
||||
*******************
|
||||
Typographical Notes
|
||||
@@ -12,26 +12,22 @@ Typographical Notes
|
||||
novelWriter has some support for typographical symbols that are not usually easily available in
|
||||
many text editors. This includes for instance the proper unicode quotation marks, dashes, ellipsis,
|
||||
thin spaces, etc. All these symbols are available from the **Insert** menu, and via
|
||||
keyboard shortcuts. See :ref:`a_kb_ins`.
|
||||
keyboard shortcuts. See :ref:`docs_features_shortcuts_insert`.
|
||||
|
||||
This chapter provides some additional information on how novelWriter handles these symbols.
|
||||
|
||||
|
||||
.. _a_typ_notes:
|
||||
|
||||
Special Notes on Symbols
|
||||
========================
|
||||
|
||||
This section contains additional notes on the available special symbols.
|
||||
|
||||
|
||||
Dashes and Ellipsis
|
||||
-------------------
|
||||
===================
|
||||
|
||||
With the auto-replace feature enabled (see :ref:`a_ui_edit_auto`), multiple hyphens are converted
|
||||
automatically to short and long dashes, and three dots to ellipsis. The last auto-replace can
|
||||
always be reverted with the undo command :kbd:`Ctrl+Z`, reverting the text to what you typed before
|
||||
the automatic replacement occurred.
|
||||
With the auto-replace feature enabled (see :ref:`docs_ui_edit_view_auto`), two and three hyphens
|
||||
are converted automatically to short and long dashes, four hyphens to a horizontal bar, and three
|
||||
dots to ellipsis.
|
||||
|
||||
.. tip::
|
||||
|
||||
The last auto-replace can always be reverted with the undo command :kbd:`Ctrl+Z`, reverting the
|
||||
text to what you typed before the automatic replacement occurred.
|
||||
|
||||
In addition, "Figure Dash" is available. The Figure Dash is a dash that has the same width as the
|
||||
numbers of the same font, for most fonts. It helps to align numbers nicely in columns when you need
|
||||
@@ -39,24 +35,22 @@ to use a dash in them.
|
||||
|
||||
|
||||
Single and Double Quotes
|
||||
------------------------
|
||||
========================
|
||||
|
||||
All the different quotation marks listed on the `Quotation Mark`_ Wikipedia page are available, and
|
||||
can be selected as auto-replaced symbols for straight single and double quote key strokes. The
|
||||
settings can be found in **Preferences**.
|
||||
|
||||
Ordinarily, text wrapped in quotes are highlighted by the editor. This is meant as a convenience
|
||||
for highlighting dialogue between characters. This feature can be disabled in
|
||||
**Preferences** if this feature isn't wanted.
|
||||
If your text contains straight single and double quotes, there are two convenience functions in the
|
||||
**Format** menu that can be used to re-format a selected section of text with the correct quote
|
||||
symbols.
|
||||
|
||||
The editor distinguishes between text wrapped in regular straight double quotes and the
|
||||
user-selected double quote symbols. This is to help the writer recognise which parts of the text
|
||||
are not using the chosen quote symbols. Two convenience functions in the **Format** menu
|
||||
can be used to re-format a selected section of text with the correct quote symbols.
|
||||
You can enable dialogue recognition and colour highlighting for novel documents.
|
||||
See :ref:`docs_features_dialogue` for more details.
|
||||
|
||||
|
||||
Single and Double Prime
|
||||
------------------------
|
||||
=======================
|
||||
|
||||
Both single and double prime symbols are available in the **Insert** menu. These symbols
|
||||
are the correct symbols to use for unit symbols for feet, inches, minutes, and seconds. The usage
|
||||
@@ -66,8 +60,10 @@ codes. Using these correctly will also prevent the auto-replace and dialogue hig
|
||||
misunderstanding their meaning in the text.
|
||||
|
||||
|
||||
.. _docs_more_typographical_symbols_apostrophe:
|
||||
|
||||
Modifier Letter Apostrophe
|
||||
--------------------------
|
||||
==========================
|
||||
|
||||
The auto-replace feature will consider any right-facing single straight quote as a quote symbol,
|
||||
even if it is intended as an apostrophe. This also includes the syntax highlighter, which may
|
||||
@@ -79,13 +75,15 @@ right single quotation marks, depending on the font. There is a Wikipedia articl
|
||||
`Modifier letter apostrophe`_ with more details.
|
||||
|
||||
.. note::
|
||||
|
||||
On export with the **Build Manuscript** tool, these apostrophes will be replaced
|
||||
automatically with the corresponding right hand single quote symbol as is generally recommended.
|
||||
Therefore it doesn't really matter if you only use them to correct syntax highlighting.
|
||||
Therefore it doesn't really matter if you only use them to correct syntax highlighting in some
|
||||
places, and not others.
|
||||
|
||||
|
||||
Special Space Symbols
|
||||
---------------------
|
||||
White Space Symbols
|
||||
===================
|
||||
|
||||
A few variations of the regular space character is supported. The correct typographical way to
|
||||
separate a number from its unit is with a `thin space`_. It is usually 2/3 the width of a regular
|
||||
@@ -97,5 +95,11 @@ A regular space can also be made into a non-breaking space if needed.
|
||||
All non-breaking spaces are highlighted with a differently coloured background to make it easier to
|
||||
spot them in the text. The colour will depend on the selected colour theme.
|
||||
|
||||
The thin and non-breaking spaces are converted to their corresponding HTML codes on export to HTML
|
||||
format.
|
||||
You can insert these spaces in your text using the following keyboard combinations:
|
||||
|
||||
* A non-breaking space can be inserted with :kbd:`Ctrl+K`, :kbd:`Space`.
|
||||
* Thin spaces are also supported, and can be inserted with :kbd:`Ctrl+K`, :kbd:`Shift+Space`.
|
||||
* Non-breaking thin space can be inserted with :kbd:`Ctrl+K`, :kbd:`Ctrl+Space`.
|
||||
|
||||
These are all insert features, and the **Insert** menu has more. The keyboard shortcuts for them
|
||||
are also listed in :ref:`docs_features_shortcuts`.
|
||||
@@ -1,409 +0,0 @@
|
||||
.. _a_proj:
|
||||
|
||||
*****************
|
||||
Managing Projects
|
||||
*****************
|
||||
|
||||
Your text in novelWriter is organised into projects. Each project is meant to contain one novel
|
||||
and associated notes. If you have multiple novels in a series, with the same characters and shared
|
||||
notes, it is also possible to keep all of them in the same project.
|
||||
|
||||
.. _a_proj_new:
|
||||
|
||||
Creating 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 **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 **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.
|
||||
|
||||
|
||||
Template Projects
|
||||
-----------------
|
||||
|
||||
From the Welcome dialog you can also create a new from another existing project. If you have a
|
||||
specific structure you want to use for all your new projects, you can create a dedicated project to
|
||||
be used as a template, and select to copy an existing project from the :guilabel:"Prefill Project"
|
||||
option from the **New Project** form.
|
||||
|
||||
|
||||
.. _a_proj_roots:
|
||||
|
||||
Project Structure
|
||||
=================
|
||||
|
||||
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 **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 **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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
**Plot**
|
||||
This is the root folder type where main plots can be outlined. It is optional, but adding at
|
||||
least brief notes can be useful in order to tag plot elements for the **Outline View**. Tags in
|
||||
this folder can be references using the ``@plot`` keyword.
|
||||
|
||||
**Characters**
|
||||
Character notes go in this root folder type. These are especially important if you want to use
|
||||
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.
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
**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 are closely tied to the tags and reference system. Each folder type corresponds to
|
||||
categories of tags that can be used to reference them. For more information about the tags listed,
|
||||
see :ref:`a_references_references`.
|
||||
|
||||
There is also a ``@mention`` keyword that can be used to reference any tag.
|
||||
See :ref:`a_references_references` for more details.
|
||||
|
||||
.. note::
|
||||
|
||||
You can rename root folders to whatever you want. However, this doesn't change the reference
|
||||
keyword or what they do.
|
||||
|
||||
|
||||
.. _a_proj_roots_del:
|
||||
|
||||
Deleted Documents
|
||||
-----------------
|
||||
|
||||
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 **Project** menu, or by pressing
|
||||
:kbd:`Ctrl+Shift+Del`. Root folders can only be removed when they are empty.
|
||||
|
||||
|
||||
.. _a_proj_roots_out:
|
||||
|
||||
Archived Documents
|
||||
------------------
|
||||
|
||||
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 **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.
|
||||
|
||||
In addition to using folders. it is also 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:
|
||||
|
||||
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 storage folder
|
||||
that aren't tracked in the core project file. These files, when discovered, are recovered and added
|
||||
back into the project when a project is opened.
|
||||
|
||||
The discovered files are scanned for metadata that give clues as to where the document may
|
||||
previously have been located in the project. The project loading routine will try to put them back
|
||||
as close as possible to this location, if it still exists. Generally, it will be appended to the
|
||||
end of the folder where it previously was located. If that folder doesn't exist, it will try to add
|
||||
it to the correct root folder type. If it cannot figure out which root folder is correct, the
|
||||
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
|
||||
be named after its internal key, which is a string of characters and numbers.
|
||||
|
||||
|
||||
.. _a_proj_roots_lock:
|
||||
|
||||
Project Lockfile
|
||||
----------------
|
||||
|
||||
To prevent data loss caused by file conflicts when novelWriter projects are synchronised via 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 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
|
||||
the project are in fact open, you are likely to cause inconsistencies and create diverging
|
||||
project files, potentially resulting in loss of data and orphaned files. You are not likely to
|
||||
lose any actual text unless both instances have the same document open in the editor, and
|
||||
novelWriter will try to resolve project inconsistencies the next time you open the project.
|
||||
|
||||
|
||||
.. _a_proj_files:
|
||||
|
||||
Project Documents
|
||||
=================
|
||||
|
||||
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 **Rename Item** from the **Project** menu, or by
|
||||
pressing :kbd:`F2` when a document or folder is selected.
|
||||
|
||||
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 **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
|
||||
|
||||
|
||||
.. _a_proj_files_counts:
|
||||
|
||||
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 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 :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 **Tools** menu, or by pressing :kbd:`F9`.
|
||||
|
||||
The rules for how the counts are made is covered in more detail in :ref:`a_counting`.
|
||||
|
||||
|
||||
.. _a_proj_settings:
|
||||
|
||||
Project Settings
|
||||
================
|
||||
|
||||
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 **Settings** tab holds the project name, author, and language settings.
|
||||
|
||||
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 **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 **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 **Novel** can be given a "Status" label accompanied by a coloured
|
||||
icon with an optional shape selected from a list of pre-defined shapes. Each document or folder of
|
||||
the remaining types can be given an "Importance" label with the same customisation options.
|
||||
|
||||
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
|
||||
intended for, but you can make them whatever you want.
|
||||
|
||||
Both status and importance labels can be exported and imported so you can share them between
|
||||
projects, or define a standard set for all your writing projects. When you import labels to a
|
||||
project, they are always added as *new* labels.
|
||||
|
||||
See also :ref:`a_ui_tree_status`.
|
||||
|
||||
.. note::
|
||||
|
||||
The status or importance level currently in use by one or more documents cannot be deleted, but
|
||||
they can be edited.
|
||||
|
||||
|
||||
Auto-Replace Tab
|
||||
----------------
|
||||
|
||||
A set of automatically replaced keywords can be added in this tab. The keywords in the left column
|
||||
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 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.
|
||||
|
||||
.. note::
|
||||
A keyword cannot contain spaces. The angle brackets are added by default, and when used in the
|
||||
text are a part of the keyword to be replaced. This is to ensure that parts of the text aren't
|
||||
unintentionally replaced by the content of the list.
|
||||
|
||||
|
||||
.. _a_proj_backup:
|
||||
|
||||
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 **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 **Project Name** as
|
||||
defined in :ref:`a_proj_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 **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:
|
||||
|
||||
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. 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 **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
|
||||
application like for instance Libre Office Calc or Excel.
|
||||
|
||||
.. 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 **Preferences**.
|
||||
|
||||
|
||||
Session Timer
|
||||
-------------
|
||||
|
||||
A session timer is by default visible in the status bar. The icon will show you a clock icon when
|
||||
you are active, and a pause icon when you are considered "idle" per the criteria mentioned above.
|
||||
|
||||
If you do not wish to see the timer, you can click on it once to hide it. The icon will still be
|
||||
visible. Click the icon once more to display the timer again.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
As of version 2.6, clicking the timer text or icon in the status bar will toggle its visibility.
|
||||
@@ -1,244 +0,0 @@
|
||||
.. _a_references:
|
||||
|
||||
*******************
|
||||
Tags and References
|
||||
*******************
|
||||
|
||||
In novelWriter there are no forms or tables to fill in to define characters, locations or other
|
||||
elements of your story. Instead, you create :term:`project notes` which you can mark as
|
||||
representing these story elements by creating a :term:`tag`. Whenever you want to link a piece of
|
||||
your story to a note defining a story element, like a character, you create a :term:`reference`
|
||||
back to that tag. You can also cross-link your project notes in the same way.
|
||||
|
||||
This is perhaps one of the features that makes novelWriter different from other, similar
|
||||
applications. It is therefore not always obvious to new users how this is supposed to work, so
|
||||
this chapter hopes to explain in more detail how to use this tags and references system.
|
||||
|
||||
.. 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 **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:
|
||||
|
||||
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 the documents directly.
|
||||
|
||||
If you split your project into separate documents for each scene, this distinction may not matter.
|
||||
However, there are several benefits to using documents at a larger structural scale when first
|
||||
starting your project. For instance, it may make more sense to define all your scenes, and even
|
||||
chapters, in a single document at first, or perhaps a document per act. You can later split these
|
||||
documents up using the document split feature. See :ref:`a_ui_tree_split_merge` for more details.
|
||||
|
||||
You can do the same with your notes. You can treat each heading as an independent element of your
|
||||
notes that can be referenced somewhere else. That way you can collect all your minor or background
|
||||
characters in a single note file, and still be able to reference them individually by separating
|
||||
them with headings and assigning each a tag. Or, you can lay out your plot in a single document and
|
||||
have a tag for each plot stage under separate headings.
|
||||
|
||||
|
||||
.. _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 ``@tag`` :term:`keyword`.
|
||||
|
||||
The basic format of a tag is ``@tag: tagName``.
|
||||
|
||||
An alternative format of a tag is ``@tag: tagName | displayName``.
|
||||
|
||||
``tagName`` (Required)
|
||||
This is a unique identifier of your choosing. It is the value you use later for making
|
||||
references back to this document, or section of the document.
|
||||
|
||||
``displayName`` (Optional)
|
||||
This is an optional display name used for the tag. When you build your manuscript, you can for
|
||||
instance insert the point of view character name directly into chapter headings. By default, the
|
||||
``tagName`` value is used in such headings, but if you use a shortened format internally in your
|
||||
project, you can use this to specify a more suitable format for your manuscript headings.
|
||||
|
||||
You can only set **one** tag per heading, and the tag has to be unique across **all** documents in
|
||||
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 **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
|
||||
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 colour
|
||||
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 **Manuscript Build** tool.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
|
||||
Tags are no longer case sensitive. The tags are by default displayed with the capitalisation you
|
||||
use when defining the tag, but you don't have to use the same capitalisation when referencing
|
||||
it later.
|
||||
|
||||
.. versionadded:: 2.3
|
||||
|
||||
Tags can have an optional display name for manuscript builds.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
You can now add tags also to Novel Documents. These can be used for cross-referencing between
|
||||
chapters and scenes, and also from notes if desired.
|
||||
|
||||
Example of a heading with a tag for a character of the story:
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
# Character: Jane Doe
|
||||
|
||||
@tag: Jane | Jane Doe
|
||||
|
||||
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 with the value "Jane", and you will
|
||||
be able to reference it in any of your other documents using the reference keywords for characters.
|
||||
It will also show up in the Character tab in the Reference panel below the document viewer, and in
|
||||
the reference auto-completer menu in the editor when you fill in references. See :ref:`a_ui_view`
|
||||
and :ref:`a_references_completer`.
|
||||
|
||||
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 available root folder types. They are also
|
||||
covered in the next section.
|
||||
|
||||
|
||||
.. _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 **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
|
||||
reference keywords allow multiple values.
|
||||
|
||||
``@pov``
|
||||
The point-of-view character for the current section. The target must be a note tag in a
|
||||
**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 **Character** type
|
||||
root folder.
|
||||
|
||||
``@char``
|
||||
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 **Plot**
|
||||
type root folder.
|
||||
|
||||
``@time``
|
||||
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
|
||||
**Locations** type root folder.
|
||||
|
||||
``@object``
|
||||
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 an **Entities** type
|
||||
root folder.
|
||||
|
||||
``@custom``
|
||||
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.
|
||||
|
||||
``@mention``
|
||||
Anything mentioned, but not present in the current section. It is intended for those cases where
|
||||
you reveal details about a character or place in a scene without it being otherwise a part of
|
||||
it. This can be useful when checking for consistency later. Any tag in any root note folder can
|
||||
be listed under mentions.
|
||||
|
||||
``@story``
|
||||
This is used when referencing a Novel Document, like a scene or chapter, from somewhere else in
|
||||
your project.
|
||||
|
||||
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 **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 **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 **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
|
||||
**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:
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
## Chapter 1
|
||||
|
||||
@pov: Jane
|
||||
|
||||
### Scene 1
|
||||
|
||||
@char: John, Sam
|
||||
@plot: Main
|
||||
|
||||
Once upon a time ...
|
||||
|
||||
|
||||
.. _a_references_completer:
|
||||
|
||||
The References Auto-Completer
|
||||
-----------------------------
|
||||
|
||||
An auto-completer context menu will show up automatically in the document editor when you type the
|
||||
character ``@`` on a new line. It will first suggest tag or reference keywords for you to add, and
|
||||
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 **Create Note for
|
||||
Tag** from the menu.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
@@ -1,163 +0,0 @@
|
||||
.. _a_struct:
|
||||
|
||||
***************
|
||||
Novel Structure
|
||||
***************
|
||||
|
||||
This chapter covers the structure of a novel project.
|
||||
|
||||
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 project tree can distinguish between the different heading levels of the novel documents using
|
||||
coloured icons, and optionally add emphasis on the label. Emphasis can be enabled in
|
||||
**Preferences**.
|
||||
|
||||
|
||||
.. _a_struct_heads:
|
||||
|
||||
Importance of Headings
|
||||
======================
|
||||
|
||||
Subfolders under root folders have no impact on the structure of the novel itself. The structure is
|
||||
instead dictated by the heading level of the headings within the documents.
|
||||
|
||||
Four levels of headings are supported, signified by the number of hashes (``#``) preceding the
|
||||
title. See also the :ref:`a_fmt` section for more details about the markup syntax.
|
||||
|
||||
.. 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 **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 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 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. 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. 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 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.
|
||||
|
||||
Page breaks can be automatically added before titles, 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
|
||||
instance, chapter numbers can be applied automatically, and so can scene numbers if you want
|
||||
them in a draft manuscript. You can also insert point-of-view character names in chapter titles.
|
||||
See the :ref:`a_manuscript` page for more details.
|
||||
|
||||
.. note::
|
||||
|
||||
As of 2.6, the heading levels internally in novelWriter do not map directly to heading levels in
|
||||
manuscript documents. In manuscript documents, chapters are considered the top level heading,
|
||||
and partitions become plain text paragraphs with a larger font.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
|
||||
.. _a_struct_heads_title:
|
||||
|
||||
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 in it. 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.
|
||||
|
||||
You can also add the author name and address above this if this is required by the manuscript
|
||||
format you use, and additional space added before the title.
|
||||
|
||||
This is the title page novelWriter generates automatically for a new project as of version 2.6:
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
Jane Doe[br]
|
||||
Address 1[br]
|
||||
Address 2 <<
|
||||
|
||||
[vspace:5]
|
||||
|
||||
#! My Novel
|
||||
|
||||
>> **By Jane Doe** <<
|
||||
|
||||
>> Word Count: [field:textWords] <<
|
||||
|
||||
The title is by default centred on the page. You can add more text to the page as you wish, like
|
||||
for instance the author's name and details.
|
||||
|
||||
If you want an additional page of text after the title page, starting on a fresh page, you can add
|
||||
``[new page]`` on a line by itself, and continue the text after it. This will insert a page break
|
||||
before the text. See also :ref:`a_fmt_break`.
|
||||
|
||||
|
||||
.. _a_struct_heads_unnum:
|
||||
|
||||
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 when adding numbers.
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
##! Unnumbered Chapter Title
|
||||
|
||||
Chapter Text
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. _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
|
||||
@@ -1,4 +1,4 @@
|
||||
.. _a_locations:
|
||||
.. _docs_technical_locations:
|
||||
|
||||
**************
|
||||
File Locations
|
||||
@@ -10,7 +10,7 @@ novelWriter will create a few files on your system outside of the application fo
|
||||
file locations are described in this chapter.
|
||||
|
||||
|
||||
.. _a_locations_conf:
|
||||
.. _docs_technical_locations_conf:
|
||||
|
||||
Configuration
|
||||
=============
|
||||
@@ -33,7 +33,7 @@ user's username on Windows.
|
||||
different way, these locations may also be different.
|
||||
|
||||
|
||||
.. _a_locations_data:
|
||||
.. _docs_technical_locations_data:
|
||||
|
||||
Application Data
|
||||
================
|
||||
@@ -62,4 +62,4 @@ The Application Data location also holds several folders:
|
||||
|
||||
``icons``, ``syntax`` and ``themes``
|
||||
These folders are empty by default, but this is where the user can store custom theme files.
|
||||
See :ref:`a_custom` for more details.
|
||||
See :ref:`docs_more_custom` for more details.
|
||||
@@ -1,4 +1,4 @@
|
||||
.. _a_source:
|
||||
.. _docs_technical_source:
|
||||
|
||||
*******************
|
||||
Running from Source
|
||||
@@ -12,6 +12,7 @@ This chapter describes various ways of running novelWriter directly from the sou
|
||||
to build the various components like the translation files and documentation.
|
||||
|
||||
.. note::
|
||||
|
||||
The text below assumes the command ``python`` corresponds to a Python 3 executable. Python 2 is
|
||||
now deprecated, but on many systems the command ``python3`` may be needed instead. Likewise,
|
||||
``pip`` may need to be replaced with ``pip3``.
|
||||
@@ -22,10 +23,10 @@ by running:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
python pkgutils.py help
|
||||
python pkgutils.py --help
|
||||
|
||||
|
||||
.. _a_source_depend:
|
||||
.. _docs_technical_source_depend:
|
||||
|
||||
Dependencies
|
||||
============
|
||||
@@ -50,13 +51,14 @@ source, dependencies can still be installed from PyPi with:
|
||||
pip install -r requirements.txt
|
||||
|
||||
.. note::
|
||||
|
||||
On Linux distros, the Qt library is usually split up into multiple packages. In some cases,
|
||||
secondary dependencies may not be installed automatically. For novelWriter, the library files
|
||||
for rendering the SVG icons may be left out and needs to be installed manually. This is the
|
||||
case on for instance Arch Linux.
|
||||
|
||||
|
||||
.. _a_source_install:
|
||||
.. _docs_technical_source_install:
|
||||
|
||||
Build and Install from Source
|
||||
=============================
|
||||
@@ -89,7 +91,7 @@ different:
|
||||
pip install --user dist/novelWriter-2.0.7-py3-none-any.whl
|
||||
|
||||
|
||||
.. _a_source_i18n:
|
||||
.. _docs_technical_source_i18n:
|
||||
|
||||
Building the Translation Files
|
||||
==============================
|
||||
@@ -109,12 +111,13 @@ This requires that the Qt Linguist tool is installed on your system. On Ubuntu a
|
||||
needed package is called ``qttools5-dev-tools``.
|
||||
|
||||
.. note::
|
||||
|
||||
If you want to improve novelWriter with translation files for another language, or update an
|
||||
existing translation, instructions for how to contribute can be found in the ``README.md`` file
|
||||
in the ``i18n`` folder of the source code.
|
||||
|
||||
|
||||
.. _a_source_sample:
|
||||
.. _docs_technical_source_sample:
|
||||
|
||||
Building the Example Project
|
||||
============================
|
||||
@@ -128,7 +131,7 @@ running:
|
||||
python pkgutils.py sample
|
||||
|
||||
|
||||
.. _a_source_docs:
|
||||
.. _docs_technical_source_docs:
|
||||
|
||||
Building the Documentation
|
||||
==========================
|
||||
@@ -1,12 +1,54 @@
|
||||
.. _a_storage:
|
||||
.. _docs_technical_storage:
|
||||
|
||||
******************
|
||||
How Data is Stored
|
||||
******************
|
||||
|
||||
.. _version control: https://en.wikipedia.org/wiki/Version_control
|
||||
|
||||
This chapter contains details of how novelWriter stores and handles the project data.
|
||||
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
The files of a novelWriter project are stored in a dedicated project folder. The project structure
|
||||
is kept in a file at the root of this folder called ``nwProject.nwx``. All the document files and
|
||||
associated meta data are stored in other folders below the project folder.
|
||||
|
||||
This way of storing data was chosen for several reasons.
|
||||
|
||||
Firstly, all the text you add to your project is saved directly to your project folder in separate
|
||||
files. Only the project structure and the text you are currently editing is stored in memory at any
|
||||
given time, which means there is a smaller risk of losing data if the application or your computer
|
||||
crashes.
|
||||
|
||||
Secondly, having multiple small files means it is very easy to synchronise them between computers
|
||||
with standard file synchronisation tools.
|
||||
|
||||
Thirdly, if you use `version control`_ software to track the changes to your project, the file
|
||||
formats used for the files are well suited. All the JSON documents have line breaks and indents as
|
||||
well, which makes it easier to track them with version control software.
|
||||
|
||||
.. note::
|
||||
|
||||
Since novelWriter has to keep track of a bunch of files and folders when a project is open, it
|
||||
may not run well on some virtual file systems. A file or folder must be accessible with exactly
|
||||
the path it was saved or created with. An example where this is not the case is the way Google
|
||||
Drive is mapped on Linux Gnome desktops using gvfs/gio.
|
||||
|
||||
.. caution::
|
||||
|
||||
You should not add additional files to the project folder yourself. Nor should you, as a rule,
|
||||
manually edit files within it. If you really must manually edit the text files, e.g. with some
|
||||
automated task you want to perform, you need to rebuild the Project Index when you open
|
||||
the project again.
|
||||
|
||||
Editing text files in the ``content`` folder is less risky as these are just plain text. Editing
|
||||
the main project XML file, however, may make the project file unreadable and you may crash
|
||||
novelWriter and lose project structure information and project settings.
|
||||
|
||||
|
||||
Project Structure
|
||||
=================
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
.. _a_pytest:
|
||||
.. _docs_technical_pytest:
|
||||
|
||||
*************
|
||||
Running Tests
|
||||
@@ -0,0 +1,149 @@
|
||||
.. _docs_usage_formatting:
|
||||
|
||||
*******************
|
||||
Advanced Formatting
|
||||
*******************
|
||||
|
||||
Standard Markdown formatting is somewhat limited, so novelWriter has some additional formatting
|
||||
codes for special use cases. These codes are all based on brackets, and some allow an additional
|
||||
value to be set after a colon.
|
||||
|
||||
This section covers all these formatting codes.
|
||||
|
||||
|
||||
.. _docs_usage_formatting_shortcodes:
|
||||
|
||||
Formatting with Shortcodes
|
||||
==========================
|
||||
|
||||
For basic formatting, like emphasis, you should use the standard Markdown style formatting tags
|
||||
descried in :ref:`docs_usage_basics_emphasis` whenever possible.
|
||||
|
||||
For additional formatting options, you can use shortcodes. Shortcodes is a form of in-line codes
|
||||
that wrap the section of text to be formatted. Shortcodes can be nested to apply multiple formats
|
||||
to the same piece of text.
|
||||
|
||||
These shortcodes are intended for special formatting cases, or more complex cases that cannot be
|
||||
solved with simple Markdown-like formatting codes. Available shortcodes are listed below.
|
||||
|
||||
.. csv-table:: Shortcodes Formats
|
||||
:header: "Syntax", "Description"
|
||||
:widths: 40, 60
|
||||
:class: "tight-table"
|
||||
|
||||
"``[b]text[/b]``", "Text is displayed as bold text."
|
||||
"``[i]text[/i]``", "Text is displayed as italicised text."
|
||||
"``[s]text[/s]``", "Text is displayed as strike through text."
|
||||
"``[u]text[/u]``", "Text is displayed as underlined text."
|
||||
"``[m]text[/m]``", "Text is displayed as highlighted text."
|
||||
"``[sup]text[/sup]``", "Text is displayed as superscript text."
|
||||
"``[sub]text[/sub]``", "Text is displayed as subscript text."
|
||||
"``[footnote:key]``", "A reference to a :ref:`footnote comment <docs_usage_comments_footnotes>`."
|
||||
|
||||
Unlike Markdown style codes, these can be used anywhere within a paragraph. Even in the middle of a
|
||||
word if you need to. You can also freely combine them to form more complex formatting.
|
||||
|
||||
The shortcodes are available from the **Format** menu and in the editor toolbar, which can be
|
||||
activated by clicking the left-most icon button in the editor header.
|
||||
|
||||
.. note::
|
||||
|
||||
Shortcodes are not processed until you generate a preview or generate a manuscript document. So
|
||||
there is no highlighting of the text between the formatting markers. There is also no check that
|
||||
your markers make sense. You must ensure that you have both the opening and closing formatting
|
||||
markers where you want them.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
|
||||
|
||||
.. _docs_usage_formatting_breaks:
|
||||
|
||||
Vertical Space and Page Breaks
|
||||
==============================
|
||||
|
||||
You can apply page breaks to partition, chapter and scene headings for novel documents from the
|
||||
**Manuscript Build** tool. If you need to add a page break or additional vertical spacing in other
|
||||
places, there are special codes available for this purpose.
|
||||
|
||||
Adding more than one line break between paragraphs will **not** increase the space between those
|
||||
paragraphs when generating a manuscript document. To add additional space between paragraphs, add
|
||||
the text ``[vspace]`` on a line of its own, and the **Manuscript Build** tool will insert a blank
|
||||
paragraph in its place.
|
||||
|
||||
If you need multiple blank paragraphs just add a colon and a number to the above code. For
|
||||
instance, writing ``[vspace:3]`` will insert three blank paragraphs.
|
||||
|
||||
If you need to add a page break somewhere, put the text ``[new page]`` on a line by itself before
|
||||
the text you wish to start on a new page.
|
||||
|
||||
.. note::
|
||||
|
||||
The page break code is applied to the text that follows it. It adds a "page break before" mark
|
||||
to the text when exporting to HTML or Open Document. This means that a ``[new page]`` code which
|
||||
has no text following it will not result in a page break.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
This is a text paragraph.
|
||||
|
||||
[vspace:2]
|
||||
|
||||
This is another text paragraph, but there will be two empty paragraphs
|
||||
between them.
|
||||
|
||||
[new page]
|
||||
|
||||
This text will start on a new page if the build format supports pages.
|
||||
|
||||
|
||||
.. _docs_usage_formatting_counts:
|
||||
|
||||
Inserting Word Counts in the Text
|
||||
=================================
|
||||
|
||||
The cover page of a manuscript normally has the word count stated on it. Any statistics value
|
||||
collected by novelWriter can be inserted into any document using a special shortcode. You can
|
||||
insert the code for any of the available statistics values from the **Insert** menu under
|
||||
**Word/Character Count**.
|
||||
|
||||
The value inserted is the actual count for your entire manuscript, so it is not populated until you
|
||||
run the **Manuscript Build** tool. Until then they will show up as "0" in the viewer panel.
|
||||
|
||||
The available codes are:
|
||||
|
||||
.. csv-table:: Stats Shortcodes
|
||||
:header: "Code", "Description"
|
||||
:class: "tight-table"
|
||||
|
||||
"``[field:allChars]``", "Characters"
|
||||
"``[field:textChars]``", "Characters in Text"
|
||||
"``[field:titleChars]``", "Characters in Headings"
|
||||
"``[field:paragraphCount]``", "Paragraphs"
|
||||
"``[field:titleCount]``", "Headings"
|
||||
"``[field:allWordChars]``", "Characters, No Spaces"
|
||||
"``[field:textWordChars]``", "Characters in Text, No Spaces"
|
||||
"``[field:titleWordChars]``", "Characters in Headings, No Spaces"
|
||||
"``[field:allWords]``", "Words"
|
||||
"``[field:textWords]``", "Words in Text"
|
||||
"``[field:titleWords]``", "Words in Headings"
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
This is an example cover page. A similar page is automatically generated when you create a new
|
||||
project.
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
Jane Smith[br]
|
||||
42 Main Street[br]
|
||||
1234 Capital City <<
|
||||
|
||||
[vspace:5]
|
||||
|
||||
#! Example
|
||||
|
||||
>> **By Jane Smith** <<
|
||||
|
||||
>> Word Count: [field:textWords] <<
|
||||
@@ -0,0 +1,78 @@
|
||||
.. _docs_usage_align_indent:
|
||||
|
||||
*************************
|
||||
Alignment and Indentation
|
||||
*************************
|
||||
|
||||
The Markdown standard doesn't have commands for aligning text, so novelWriter adds its own syntax
|
||||
for this. It also has syntax for indentation, which is similar to Markdown block quotes.
|
||||
|
||||
|
||||
Paragraph Alignment and Indentation
|
||||
===================================
|
||||
|
||||
All documents have the text by default aligned to the left or justified, depending on your setting
|
||||
in **Preferences**.
|
||||
|
||||
You can override the default text alignment on individual paragraphs by specifying alignment tags.
|
||||
These tags are double angle brackets. Either ``>>`` or ``<<``. You put them either before or after
|
||||
the paragraph, and they will "push" the text towards the edge the brackets point towards. This
|
||||
should be fairly intuitive.
|
||||
|
||||
Indentation uses a similar syntax. But here you use a single ``>`` or ``<`` to "push" the text away
|
||||
from the edge.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
.. csv-table:: Text Alignment and Indentation
|
||||
:header: "Syntax", "Description"
|
||||
:widths: 40, 60
|
||||
:class: "tight-table"
|
||||
|
||||
"``>> Right aligned text``", "The text paragraph is right-aligned."
|
||||
"``Left aligned text <<``", "The text paragraph is left-aligned."
|
||||
"``>> Centred text <<``", "The text paragraph is centred."
|
||||
"``> Left indented text``", "The text has an increased left margin."
|
||||
"``Right indented text <``", "The text has an increased right margin."
|
||||
"``> Left/right indented text <``", "The text has both margins increased."
|
||||
|
||||
.. note::
|
||||
|
||||
The text editor will not show the alignment and indentation live. But the viewer will show them
|
||||
when you open the document there. It will of course also be reflected in the document generated
|
||||
from the **Manuscript Build** tool as long as the format supports paragraph alignment.
|
||||
|
||||
|
||||
Alignment with Line Breaks
|
||||
==========================
|
||||
|
||||
If you have line breaks in the paragraph, the markers for all the lines are combined and used for
|
||||
the entire paragraph. For the following text, all lines will be centred:
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
>> I am the very model of a modern Major-General
|
||||
I've information vegetable, animal, and mineral
|
||||
I know the kings of England, and I quote the fights historical
|
||||
From Marathon to Waterloo, in order categorical <<
|
||||
|
||||
|
||||
Alignment with First Line Indent
|
||||
================================
|
||||
|
||||
If you have first line indent enabled in your manuscript build settings, you probably want to
|
||||
disable it for text in verses. Adding any alignment tags will cause the first line indent to be
|
||||
switched off for that paragraph.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
The following text will always be aligned against the left margin:
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
I am the very model of a modern Major-General <<
|
||||
I've information vegetable, animal, and mineral
|
||||
I know the kings of England, and I quote the fights historical
|
||||
From Marathon to Waterloo, in order categorical
|
||||
@@ -0,0 +1,95 @@
|
||||
.. _docs_usage_basics:
|
||||
|
||||
****************
|
||||
Basic Formatting
|
||||
****************
|
||||
|
||||
.. _Markdown: https://en.wikipedia.org/wiki/Markdown
|
||||
|
||||
The basic text formatting syntax of novelWriter is based on Markdown_. It is only a subset of the
|
||||
Markdown syntax though. Lists, images, and links are not supported.
|
||||
|
||||
That said, URLs in the text should automatically be highlighted and become clickable. However, only
|
||||
URLs starting with "http" or "https" are recognised. In the editor, you must hold down the
|
||||
:kbd:`Ctrl` key when clicking a URL to follow it.
|
||||
|
||||
|
||||
.. _docs_usage_basics_paragraphs:
|
||||
|
||||
Text Paragraphs
|
||||
===============
|
||||
|
||||
A text paragraph is indicated by a blank line. That is, you need two line breaks to separate two
|
||||
fragments of text into two paragraphs. Single line breaks are treated as line breaks within a
|
||||
paragraph.
|
||||
|
||||
It is important that you actually follow this rule. You should not, for instance, mimic indented
|
||||
paragraphs manually in the editor. This, and a lot of other formatting options that can be
|
||||
applied to text paragraphs in the :ref:`Manuscript Tool <docs_ui_manuscript>` depend on paragraphs
|
||||
being separated by blank lines.
|
||||
|
||||
:bdg-success:`Correct`
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
### Scene
|
||||
|
||||
This is a text paragraph.
|
||||
|
||||
This is another text paragraph.
|
||||
|
||||
:bdg-danger:`Incorrect`
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
### Scene
|
||||
|
||||
This is a text paragraph.
|
||||
This is meant to be another text paragraph.
|
||||
|
||||
If you do as shown in the "Incorrect" example, novelWriter will understand this as a single
|
||||
paragraph with two lines.
|
||||
|
||||
|
||||
.. _docs_usage_basics_emphasis:
|
||||
|
||||
Text Emphasis with Markdown
|
||||
===========================
|
||||
|
||||
A minimal set of Markdown text emphasis styles are supported for text paragraphs.
|
||||
|
||||
``_text_``
|
||||
The text is rendered as emphasised text (italicised).
|
||||
|
||||
``**text**``
|
||||
The text is rendered as strongly emphasised text (bold).
|
||||
|
||||
``~~text~~``
|
||||
Strike through text.
|
||||
|
||||
In Markdown guides it is often recommended to differentiate between strong emphasis and emphasis
|
||||
by using ``**`` for strong and ``_`` for emphasis, although Markdown generally also supports ``__``
|
||||
for strong and ``*`` for emphasis. However, since the differentiation makes the highlighting and
|
||||
conversion significantly simpler and faster, in novelWriter this is a rule, not just a
|
||||
recommendation.
|
||||
|
||||
In addition, the following rules apply:
|
||||
|
||||
1. The emphasis and strike through formatting tags do not allow spaces between the words and the
|
||||
tag itself. That is, ``**text**`` is valid, ``**text **`` is not.
|
||||
2. More generally, the delimiters must be on the outer edge of words. That is, ``some **text in
|
||||
bold** here`` is valid, ``some** text in bold** here`` is not.
|
||||
3. If using both ``**`` and ``_`` to wrap the same text, the underscore must be the **inner**
|
||||
wrapper. This is due to the underscore also being a valid word character, so if they are on the
|
||||
outside, they violate rule 2.
|
||||
4. Text emphasis does not span past line breaks. If you need to add emphasis to multiple lines or
|
||||
paragraphs, you must apply it to each of them in turn.
|
||||
5. Text emphasis can only be used in comments and paragraphs. Headings and meta data tags don't
|
||||
allow for formatting, and any formatting markup will be displayed as-is.
|
||||
|
||||
.. tip::
|
||||
|
||||
novelWriter supports standard escape syntax for the emphasis markup characters in case the
|
||||
editor misunderstands your intended usage of them. That is, ``\*``, ``\_`` and ``\~`` will
|
||||
generate a plain ``*``, ``_`` and ``~``, respectively, without interpreting them as part of the
|
||||
markup.
|
||||
@@ -0,0 +1,96 @@
|
||||
.. _docs_usage_headings:
|
||||
|
||||
*******************
|
||||
Chapters and Scenes
|
||||
*******************
|
||||
|
||||
.. _Markdown: https://en.wikipedia.org/wiki/Markdown
|
||||
|
||||
Since novelWriter uses a plain text format, the structure of your novel must follow a certain set
|
||||
of simple rules. For documents in a **Novel** type root folder, it is the heading that determines
|
||||
if the document is a chapter or a scene.
|
||||
|
||||
The formatting of headings is based on Markdown_. A heading is indicated by a line starting with
|
||||
one or more ``#`` characters. It accepts up to four of these. You can use multiple headings in the
|
||||
same document, but it is the first heading that determines which icon and information is displayed
|
||||
in the project tree.
|
||||
|
||||
.. note::
|
||||
|
||||
You can use the same heading levels for your notes in the other root folders, but they aren't
|
||||
treated as chapters or scenes, so there you are free to use them as you want.
|
||||
|
||||
|
||||
.. _docs_usage_headings_levels:
|
||||
|
||||
Heading Levels
|
||||
==============
|
||||
|
||||
.. figure:: images/fig_heading_levels.png
|
||||
|
||||
An illustration of how heading levels correspond to the novel structure.
|
||||
|
||||
Four levels of headings are understood for novel documents. You can pick and choose from these as
|
||||
you want, but if your story has chapters, you should use these headings to indicate them. If you
|
||||
also add scene headings, you have better control of how your scene separators are formatted in your
|
||||
manuscript. The chapter and scenes headings are also displayed in the
|
||||
:ref:`Novel View <docs_ui_main_novel>` and :ref:`Outline View <docs_ui_main_outline>`.
|
||||
|
||||
``# Title Text``
|
||||
This is a heading level one. This heading indicates the start of a new partition. Partitions are
|
||||
for when you want to split your story into "Part 1", "Part 2", etc. You can also choose to use
|
||||
them for splitting the text up into acts, and then hide these headings in your manuscript so
|
||||
that they are not included in the output.
|
||||
|
||||
``## Chapter Title``
|
||||
This is a heading level two. This heading indicates the start of a new chapter. Chapter numbers
|
||||
can be inserted automatically when building the manuscript, so you don't have to do this in the
|
||||
title. See :ref:`docs_ui_manuscript_head_numbers` for more details.
|
||||
|
||||
``### Scene Title``
|
||||
This is a heading level three. This heading indicates the start of a new scene. Scene numbers or
|
||||
scene separators can be inserted automatically when building the manuscript, so you can use the
|
||||
title field as a working title for your scenes if you wish, but you must provide a minimal
|
||||
title.
|
||||
|
||||
``#### Section Title``
|
||||
This is a heading level four. This heading indicates the start of a new section. Section titles
|
||||
can be replaced by separators or ignored completely when building the manuscript. The meaning of
|
||||
a section is really whatever you want it to be. You can use it to split your scenes up into
|
||||
chunks, or into separate documents.
|
||||
|
||||
For headings level one through three, adding a ``!`` modifies the meaning of the heading. The
|
||||
alternative meaning of the heading is only relevant when you generate your manuscript, but you may
|
||||
want to keep the use cases in mind while writing.
|
||||
|
||||
``#! Title Text``
|
||||
This tells the **Manuscript Build** tool that the level one heading is intended to be used for
|
||||
the novel or notes folder's main title, like for instance the novel title on the cover page.
|
||||
When building the manuscript, this will use a different styling of the title, which you can
|
||||
modify independently from how partition titles are styled.
|
||||
See :ref:`docs_usage_front_back_matter_title` for more details.
|
||||
|
||||
``##! Chapter Title``
|
||||
This tells the **Manuscript Build** tool to not assign a chapter number to this chapter title if
|
||||
automatic chapter numbers are enabled. Such titles are useful for prologues and epilogues for
|
||||
instance. See :ref:`docs_usage_front_back_matter_unnumbered` for more details.
|
||||
|
||||
``###! Scene Title``
|
||||
This is an alternative scene heading that can be formatted differently in the **Manuscript
|
||||
Build** tool. It is intended for separating "soft" and "hard" scene breaks. Aside from this, it
|
||||
behaves identically to a regular scene heading. See :ref:`docs_ui_manuscript_head_hard_soft`
|
||||
for more details.
|
||||
|
||||
The formatting of these headings can be customised quite extensively in the
|
||||
:ref:`Manuscript Tool <docs_ui_manuscript>`, which is covered in a separate part of the
|
||||
documentation.
|
||||
|
||||
.. note::
|
||||
|
||||
The space after the ``#`` or ``!`` character is mandatory. The editor will change colour and
|
||||
font size when the heading is correctly formatted.
|
||||
|
||||
Page breaks can be automatically added before titles, 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:`docs_usage_formatting_breaks` for more details.
|
||||
@@ -0,0 +1,164 @@
|
||||
.. _docs_usage_comments:
|
||||
|
||||
******************
|
||||
Comments and Notes
|
||||
******************
|
||||
|
||||
You can add comments to your text that are not a part of the story. Regular comments are intended
|
||||
for you to add notes to yourself inside the text, which may be useful when you revise your drafts.
|
||||
However, there are several types of comments you can use.
|
||||
|
||||
This section covers the basic comment types. There are a couple of advanced features that use
|
||||
comment syntax too, but they are covered later.
|
||||
|
||||
|
||||
.. _docs_usage_comments_plain:
|
||||
|
||||
Plain Comments
|
||||
==============
|
||||
|
||||
A plain comment is a line or paragraph that starts with the character ``%`` as its first character.
|
||||
You can put them wherever you like in your documents, and you can choose to include or exclude them
|
||||
from your manuscript.
|
||||
|
||||
For the most part, novelWriter completely ignores these comments. They are not included in your
|
||||
word or character counts either, and are only displayed in the document viewer panel if you enable
|
||||
them.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
### Scene
|
||||
|
||||
A regular text paragraph in the scene.
|
||||
|
||||
% A comment you've added for your own notes.
|
||||
|
||||
Another regular text paragraph in the scene.
|
||||
|
||||
|
||||
.. _docs_usage_comments_synopsis:
|
||||
|
||||
Synopsis or Description Comments
|
||||
================================
|
||||
|
||||
A special kind of comments are **Synopsis** and **Short Description** comments. They are different
|
||||
from plain comments in that they can be displayed alongside other information about a scene or a
|
||||
character or other story element described in a note. As with plain comments, they can be included
|
||||
in your manuscript, but they are formatted differently than plain comments.
|
||||
|
||||
.. note::
|
||||
|
||||
A summary or description comment can be used once, and only once, for each heading as they are
|
||||
considered a description of the content of the text under that heading. If you add two such
|
||||
comments under the same heading, the last one will be used.
|
||||
|
||||
|
||||
Synopsis
|
||||
--------
|
||||
|
||||
A **Synopsis** comment is intended for adding a summary of your chapters and scenes.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
### Scene
|
||||
|
||||
%Synopsis: A summary of the content of the scene.
|
||||
|
||||
The actual scene text.
|
||||
|
||||
|
||||
Short Description
|
||||
-----------------
|
||||
|
||||
A **Short Description** comment behaves exactly the same as a synopsis comment, but is intended as
|
||||
a description of a story element, like a character.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
# Characters
|
||||
|
||||
## Darth Vader
|
||||
|
||||
%Short: A Sith Lord that used to be a Jedi.
|
||||
|
||||
Your text about the character.
|
||||
|
||||
## Luke Skywalker
|
||||
|
||||
%Short: A Jedi. The son of Darth Vader.
|
||||
|
||||
Your text about the character.
|
||||
|
||||
.. note::
|
||||
|
||||
The ``%Synopsis:`` and ``%Short:`` comment prefixes are interchangeable, but when you include
|
||||
them in the manuscript, they are labelled based on the prefix, so the latter may make more sense
|
||||
for a Character note than the former.
|
||||
|
||||
|
||||
.. _docs_usage_comments_footnotes:
|
||||
|
||||
Footnote Comments
|
||||
=================
|
||||
|
||||
Footnotes are added with a shortcode, paired with a matching comment for the actual footnote text.
|
||||
The matching is done with a key that links the two. If you insert a footnote from the **Insert**
|
||||
menu, a unique key is generated for you. Shortcodes in general are covered in more detail in
|
||||
:ref:`docs_usage_formatting_shortcodes`.
|
||||
|
||||
The insert footnote feature will add the footnote shortcode marker at the position of your cursor
|
||||
in the editor panel, and create the associated footnote comment right after the paragraph. It will
|
||||
then move the cursor there so you can immediately start typing the footnote text.
|
||||
|
||||
The footnote comment can be anywhere in the document, so if you wish to move them to, say, the
|
||||
bottom of the text, you are free to do so.
|
||||
|
||||
Footnote keys are only required to be unique within a document, so if you copy, move or merge text,
|
||||
you must make sure the keys are not duplicated. If you use the automatically generated keys from
|
||||
the **Insert** menu, they are unique among all indexed documents. They are not guaranteed to be
|
||||
unique against footnotes in the **Archive** or **Trash** folder though, but the chance of
|
||||
accidentally generating the same key twice in a project is relatively small.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
### Scene
|
||||
|
||||
This is a text paragraph with a footnote[footnote:fn1] in the middle.
|
||||
|
||||
%Footnote.fn1: This is the text of the footnote.
|
||||
|
||||
.. versionadded:: 2.5
|
||||
|
||||
|
||||
.. _docs_usage_comments_ignored:
|
||||
|
||||
Ignored Text
|
||||
============
|
||||
|
||||
If you want to completely ignore some of the text in your documents, but are not ready to delete
|
||||
it, you can add ``%~`` before the text paragraph or line. This will cause novelWriter to skip the
|
||||
text entirely when generating previews or building manuscripts.
|
||||
|
||||
This is a better way of removing text than converting them to regular comments, as you may want to
|
||||
include regular comments in your previews or draft manuscript.
|
||||
|
||||
You can toggle the ignored text feature on and off for a paragraph by pressing :kbd:`Ctrl+Shift+D`
|
||||
on your keyboard with your cursor somewhere in the paragraph.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
### Scene
|
||||
|
||||
%~ This text is ignored.
|
||||
|
||||
This text is a regular paragraph.
|
||||
@@ -0,0 +1,79 @@
|
||||
.. _docs_usage_front_back_matter:
|
||||
|
||||
*********************
|
||||
Front and Back Matter
|
||||
*********************
|
||||
|
||||
Front and back matter documents are documents that go before and after your main story text. They
|
||||
can include pages like your cover page, content tables, prologues, epilogues, etc. These special
|
||||
pages and sections are supported to some extent by novelWriter.
|
||||
|
||||
|
||||
.. _docs_usage_front_back_matter_title:
|
||||
|
||||
The Title Page
|
||||
==============
|
||||
|
||||
It is recommended that you add a document at the very top of each **Novel** root folder with the
|
||||
novel title in it. 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.
|
||||
|
||||
You can also add the author name and address above this if this is required by the manuscript
|
||||
format you use, and additional space added before the title.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
This is the title page novelWriter generates automatically for a new project as of version 2.6:
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
Jane Doe[br]
|
||||
Address Line 1[br]
|
||||
Address Line 2 <<
|
||||
|
||||
[vspace:5]
|
||||
|
||||
#! My Novel
|
||||
|
||||
>> **By Jane Doe** <<
|
||||
|
||||
>> Word Count: [field:textWords] <<
|
||||
|
||||
The title is by default centred on the page. You can add more text to the page as you wish, like
|
||||
for instance the author's name and details.
|
||||
|
||||
The default title page inserts the word count for text only, but you can add other counts too.
|
||||
See :ref:`docs_usage_formatting_counts` for more details.
|
||||
|
||||
|
||||
.. _docs_usage_front_back_matter_pages:
|
||||
|
||||
Additional Pages
|
||||
================
|
||||
|
||||
If you want an additional page of text after the title page, starting on a fresh page, you can add
|
||||
``[new page]`` on a line by itself, and continue the text after it. This will insert a page break
|
||||
before the text. See :ref:`docs_usage_formatting_breaks` for more details.
|
||||
|
||||
|
||||
.. _docs_usage_front_back_matter_unnumbered:
|
||||
|
||||
Unnumbered Chapters
|
||||
===================
|
||||
|
||||
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 when adding numbers.
|
||||
|
||||
Unnumbered chapters are useful for prologue and epilogue chapters, and also for interlude chapters
|
||||
if you use those in your text. There is a separate formatting feature for such chapter titles in
|
||||
the **Manuscript Build** tool. See the :ref:`docs_ui_manuscript` page for more details.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
##! Unnumbered Chapter Title
|
||||
|
||||
Chapter Text
|
||||
@@ -1,4 +1,4 @@
|
||||
.. _a_howto:
|
||||
.. _docs_usage_howto:
|
||||
|
||||
*************
|
||||
Tips & Tricks
|
||||
@@ -33,7 +33,7 @@ Managing the Project
|
||||
and :guilabel:`Merge Documents in Folder`.
|
||||
|
||||
In the dialog that pops up, the documents will be in the same order as in the folder, but you
|
||||
can rearrange them here of you wish. See :ref:`a_ui_tree_split_merge` for more details.
|
||||
can rearrange them here of you wish. See :ref:`docs_ui_split_merge` for more details.
|
||||
|
||||
.. dropdown:: How do I share status or importance labels between projects?
|
||||
:animate: fade-in-slide-down
|
||||
@@ -76,7 +76,7 @@ Layout Tricks
|
||||
indented, you can disable the indentation by explicitly adding text alignment. For instance by
|
||||
adding ``<<`` to the end to left-align it. Aligned paragraphs are not indented.
|
||||
|
||||
See :ref:`a_fmt_align` for more details.
|
||||
See :ref:`docs_usage_align_indent` for more details.
|
||||
|
||||
|
||||
Organising Your Text
|
||||
@@ -102,7 +102,7 @@ Organising Your Text
|
||||
**Build Manuscript** tool will let you define a different format for scenes using the ``###``
|
||||
and ``###!`` heading codes when you generate your manuscript. You can for instance add the
|
||||
common "``* * *``" for hard breaks and select to hide soft scene breaks, which will just insert
|
||||
an empty paragraph in their place. See :ref:`a_manuscript_settings` for more details.
|
||||
an empty paragraph in their place. See :ref:`docs_ui_manuscript_settings` for more details.
|
||||
|
||||
.. versionadded:: 2.4
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 259 KiB |
@@ -0,0 +1,57 @@
|
||||
.. _docs_usage:
|
||||
|
||||
************
|
||||
Introduction
|
||||
************
|
||||
|
||||
.. _Markdown: https://en.wikipedia.org/wiki/Markdown
|
||||
|
||||
In a nutshell, novelWriter is a plain text editor that lets you organise one or more novels and
|
||||
associated notes as many smaller documents. You can at any time generate standard document formats
|
||||
from these plain text documents. Whether it is an outline of your story, a draft, a complete
|
||||
manuscript, or even a collection of your character notes or other notes.
|
||||
|
||||
|
||||
Why Plain Text?
|
||||
===============
|
||||
|
||||
The idea is to let you be creative without having to deal with formatting while you are writing, or
|
||||
be distracted by it.
|
||||
|
||||
Of course, you probably need *some* form of minimal formatting for your text. At the very least you
|
||||
need emphasis. Most people are familiar with adding emphasis using ``_underscores_`` and
|
||||
``**asterisks**``. This formatting standard comes from Markdown_ and is supported by novelWriter.
|
||||
It also uses Markdown formatting for defining document headings, which is how you distinguish
|
||||
between chapters and scenes.
|
||||
|
||||
For those special cases where you need more complex formatting, a set of shortcodes are available.
|
||||
To make these codes easier to use, a dropdown button bar is available in the editor panel with
|
||||
standard format buttons. So don't worry. You don't have to learn any of these codes.
|
||||
|
||||
|
||||
Adding Meta Data
|
||||
================
|
||||
|
||||
In addition to the body text of your story, novelWriter allows you to enter some additional meta
|
||||
data into your text documents to indicate things like which characters are present in a chapter or
|
||||
scene, whose point of view we're seeing, what location the events take place in, and so on.
|
||||
|
||||
Since the editor is plain text, this is done on special lines of text starting with an ``@``
|
||||
character. The editor will show an auto-complete menu to help you write these lines. We will talk
|
||||
more about this later.
|
||||
|
||||
You can also add your own author's comments in your text, without these comments becoming a part of
|
||||
the story itself. A comment line starts with a ``%`` character. There are different types of
|
||||
comments, and an auto-complete menu can help you here too. More about this later as well.
|
||||
|
||||
.. admonition:: Limitations
|
||||
|
||||
Please keep in mind that novelWriter is designed for writing fiction, so the formatting features
|
||||
available are limited to those relevant for this purpose. It is *not* suitable for technical
|
||||
writing. It is also *not* a full-featured Markdown editor.
|
||||
|
||||
In addition, novelWriter is not intended as a tool for organising research for writing, and
|
||||
therefore lacks formatting features you may need for this purpose. The notes feature in is
|
||||
mainly intended for character profiles and plot outlines. It is recommended to use a proper
|
||||
note-taking tool for research. This is anyway more practical as you may use the same research
|
||||
for multiple projects.
|
||||
@@ -0,0 +1,202 @@
|
||||
.. _docs_usage_project:
|
||||
|
||||
***********************
|
||||
Organising Your Project
|
||||
***********************
|
||||
|
||||
Your project is organised into a set of top level folders called "Root Folders", which each have
|
||||
specific meaning in the project. Your project documents and notes are stored under these root
|
||||
folders. All the content of your project is available in the **Project Content** panel on the left
|
||||
side of the main window.
|
||||
|
||||
.. figure:: images/fig_project_tree.png
|
||||
|
||||
The **Project Content** tree populated with example documents.
|
||||
|
||||
Each line in the project tree shows the name of each item, its word count (or alternatively
|
||||
character count), an icon for :ref:`docs_usage_project_active`, and a custom icon for
|
||||
:ref:`docs_usage_project_status` of each item. These latter two are covered alter in this section.
|
||||
|
||||
You can add, view and edit documents in the project tree by right-clicking on them. Some features
|
||||
are also located in the buttons along the top, next to the **Project Content** label.
|
||||
|
||||
|
||||
.. _docs_usage_project_roots:
|
||||
|
||||
How Root Folders Work
|
||||
=====================
|
||||
|
||||
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. Each type of root folder has a distinct icon.
|
||||
|
||||
The documents that make up your story go into a root folder of type **Novel**. Your notes go into
|
||||
the other root folders. These other root folder types are separated into types depending on what
|
||||
kind of notes go into them. This is not only for organisation. It also matters to how you can
|
||||
reference these notes later. We will come back to this in the :ref:`docs_usage_tags_refs` section.
|
||||
|
||||
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.
|
||||
|
||||
The intended usage of each type of root folder is listed below. However, aside from the **Novel**
|
||||
folder, no restrictions are applied by novelWriter on what you put in them. You can use them
|
||||
however you want.
|
||||
|
||||
|
||||
Root Folder Types
|
||||
-----------------
|
||||
|
||||
**Novel** (Story)
|
||||
This is where you put the documents that are part of your story. You can create multiple Novel
|
||||
folders if you wish, but various parts of the application assumes each Novel folder belong to
|
||||
one novel.
|
||||
|
||||
The Novel folder is somewhat special in that it can contain documents for chapters, scenes and
|
||||
story partitions. How this is indicated is covered in the section :ref:`docs_usage_headings`.
|
||||
|
||||
**Plot** (Notes)
|
||||
This is where you can keep notes and outlines of your story plots. Such notes can be
|
||||
particularly useful if you have outlines for sub plot. You can make references to these subplots
|
||||
from the scene documents, which makes it easier to track story progress.
|
||||
|
||||
**Characters** (Notes)
|
||||
Character notes go in this root folder type. For your main characters, you may want to make one
|
||||
document for each character. For smaller characters you can put multiple into the same document.
|
||||
In your chapters and scenes you can reference these character notes as point-of-view or focus
|
||||
characters.
|
||||
|
||||
**Locations** (Notes)
|
||||
The locations where your story takes place can be documented here. This, together with Plot and
|
||||
Characters are the key story elements to track, and to reference from your chapter and scene
|
||||
documents.
|
||||
|
||||
**Timeline** (Notes)
|
||||
If the story has multiple plot timelines or jumps in time within the same plot, this folder type
|
||||
can be used to track this.
|
||||
|
||||
**Objects** (Notes)
|
||||
Important objects in the story, for instance physical objects that change hands often, can be
|
||||
tracked here.
|
||||
|
||||
**Entities** (Notes)
|
||||
Does your plot have many powerful organisations or companies? Or other entities that are part of
|
||||
the plot? They can be organised here.
|
||||
|
||||
**Custom** (Notes)
|
||||
The custom root folder type can be used for tracking anything else not covered by the above
|
||||
options.
|
||||
|
||||
**Templates**
|
||||
Any document added under this root folder will be made available as template options when
|
||||
creating new documents. See :ref:`docs_usage_project_documents_templates` for more details.
|
||||
|
||||
**Archive**
|
||||
If you don't want to delete a document, or put it in the **Trash** folder where it may be
|
||||
deleted, but still want it out of your main project, you can put it in this folder. The contents
|
||||
of the document will be ignored by the scanner that looks for tags, and it will be ignored in
|
||||
any outline view and in your manuscript.
|
||||
|
||||
**Trash**
|
||||
This folder behaves like you expect. Anything dropped in here can be deleted permanently from
|
||||
the project, and the content doesn't show up anywhere else in novelWriter.
|
||||
|
||||
The root folder types are closely tied to the tags and reference system. Each folder type for novel
|
||||
and notes corresponds to one or more categories of tags that can be used to reference the content
|
||||
in them. See :ref:`docs_usage_tags_refs` for more details.
|
||||
|
||||
.. tip::
|
||||
|
||||
The root folders have standard names, but you can rename them to whatever you want.
|
||||
|
||||
|
||||
.. _docs_usage_project_folders:
|
||||
|
||||
Regular Folders
|
||||
===============
|
||||
|
||||
You can add regular folders anywhere you want in the project. 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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
.. _docs_usage_project_documents:
|
||||
|
||||
Documents
|
||||
=========
|
||||
|
||||
You can add documents anywhere you want in your project structure. You can even add documents as
|
||||
child items of other documents, just as if they were folders. This makes it easy to associate a set
|
||||
of scenes with their chapter. You can also do this in your notes, where you for instance may have a
|
||||
hierarchy of your locations.
|
||||
|
||||
The name on a document in the project tree is not linked to any headings in the document text.
|
||||
Think of the document name as a file name. You can rename a document, or any other item in the
|
||||
project, at any time.
|
||||
|
||||
Documents come in two types:
|
||||
|
||||
**Novel Documents**
|
||||
These are the documents that make up your story or novel. They can only be added under a root
|
||||
folder of type **Novel**. You can technically also add them under **Archive**. See
|
||||
:ref:`docs_usage_headings` for more details on how these documents are handled by novelWriter.
|
||||
|
||||
**Project Notes**
|
||||
These are the documents where you keep your notes. You can add them anywhere in your project,
|
||||
including under **Novel** type folders. If you do add them there, they are not treated as a part
|
||||
of the story by default.
|
||||
|
||||
You can convert between the two types of documents where both types are allowed. You can also
|
||||
convert folders into documents, which may sometimes be convenient too.
|
||||
|
||||
Another convenient feature is that documents can be split into sub-documents by its headings, or
|
||||
multiple documents merged into one. This is particularly useful if you start out with larger
|
||||
structural documents, like one containing all chapters and scenes in an act, and then split those
|
||||
when you start writing. See :ref:`docs_ui_split_merge` for more details.
|
||||
|
||||
|
||||
.. _docs_usage_project_documents_templates:
|
||||
|
||||
Document Templates
|
||||
------------------
|
||||
|
||||
If you wish to create template documents to be used when creating new documents, like for 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
|
||||
|
||||
|
||||
.. _docs_usage_project_active:
|
||||
|
||||
Active and Inactive Documents
|
||||
=============================
|
||||
|
||||
A document can be set as "Active" or "Inactive", which alters the icon in the third column of the
|
||||
project tree. These are mostly intended for your convenience as they will indicate whether the
|
||||
document is meant to be included in the manuscript or not. You can think of an inactive status as a
|
||||
whole-document out-take. It allows you to take it out without moving it to **Archive**.
|
||||
|
||||
Inactive documents are by default excluded from your manuscript, but you can override this if you
|
||||
wish. See :ref:`docs_ui_manuscript_selection` for more details.
|
||||
|
||||
|
||||
.. _docs_usage_project_status:
|
||||
|
||||
Importance and Status
|
||||
=====================
|
||||
|
||||
Each document or folder in your project can have either a "Status" or "Importance" label set. These
|
||||
are labels and icons that you control and define yourself, and novelWriter doesn't use them for
|
||||
anything. You can modify these labels in **Project Settings**.
|
||||
See :ref:`docs_ui_projects_settings_status` for more details.
|
||||
|
||||
The "Status" labels are intended to tag a novel document as for instance a draft or as completed,
|
||||
and the "Importance" labels are intended to tag character notes, or other project notes, as for
|
||||
instance a main, major, or minor character or story element.
|
||||
|
||||
Whether a document uses a "Status" or "Importance" label depends on which root folder it lives in.
|
||||
If it's in a **Novel** type folder, it uses the "Status" label, otherwise it uses an "Importance"
|
||||
label.
|
||||
@@ -0,0 +1,231 @@
|
||||
.. _docs_usage_tags_refs:
|
||||
|
||||
*******************
|
||||
Tags and References
|
||||
*******************
|
||||
|
||||
One of the core features of novelWriter is its **Tags and References** system. This is perhaps one
|
||||
of the features that makes novelWriter different from other similar applications. It is therefore
|
||||
not always obvious to new users how this is supposed to work.
|
||||
|
||||
In novelWriter there are no forms or tables to fill in to define characters, locations or other
|
||||
elements of your story. Instead, you create documents in one of the root folders for notes. Within
|
||||
these documents you can set **tags**, like for instance for your main character. If you then want
|
||||
to annotate a scene with this character as its point-of-view, you create a **reference** to the
|
||||
tag.
|
||||
|
||||
.. 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 **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.
|
||||
|
||||
|
||||
.. _docs_usage_tags_refs_tags:
|
||||
|
||||
How to Use Tags
|
||||
===============
|
||||
|
||||
The structure of your novelWriter project is inferred from the headings within the documents, not
|
||||
the documents themselves. See :ref:`docs_usage_headings` for more details. Therefore, metadata is
|
||||
also associated with headings, and not the documents themselves.
|
||||
|
||||
A "tag" in novelWriter is a word or phrase that you define as belonging to a heading. Tags are set
|
||||
by using the ``@tag`` keyword.
|
||||
|
||||
The basic format of a tag is ``@tag: TagName``.
|
||||
|
||||
An alternative format of a tag is ``@tag: TagName | Display Name``.
|
||||
|
||||
``tagName`` (Required)
|
||||
This is a unique identifier of your choosing. It is the value you use later for making
|
||||
references back to the heading in the document. The tag must be unique.
|
||||
|
||||
``Display Name`` (Optional)
|
||||
This is an optional display name used for the tag. When you build your manuscript, you can for
|
||||
instance insert the point-of-view character name directly into chapter titles. By default, the
|
||||
``tagName`` value is used in such headings, but if you use a shortened format internally in your
|
||||
project, you can use the display name to specify a more suitable format for your chapter title.
|
||||
|
||||
.. note::
|
||||
|
||||
You can only set **one** tag per heading, and the tag has to be unique across **all** documents
|
||||
in 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 **Outline View** and in the **References** panel under the
|
||||
document viewer when a document is open in the viewer. See :ref:`docs_ui_main_outline` and
|
||||
:ref:`docs_ui_edit_view_view_references` for more details.
|
||||
|
||||
The editor will indicate to you that the keyword is correctly used and that the tag is allowed,
|
||||
that is, the tag is unique, by adding a colour highlighting to it. An invalid tag should have a
|
||||
wiggly line under it, and will not receive the colour that valid tags do.
|
||||
|
||||
The tag is the only part of notes that novelWriter uses. The rest of the document content is there
|
||||
for you to use in whatever way you wish.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
|
||||
Tags are no longer case sensitive. The tags are by default displayed with the capitalisation you
|
||||
use when defining the tag, but you don't have to use the same capitalisation when referencing
|
||||
it later.
|
||||
|
||||
.. versionadded:: 2.3
|
||||
|
||||
Tags can have an optional display name for manuscript builds.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
You can now add tags also to Novel Documents. These can be used for cross-referencing between
|
||||
chapters and scenes, and also from notes if desired.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
Example of a note document for a character with a tag set:
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
# Character: Jane Doe
|
||||
|
||||
@tag: Jane | Jane Doe
|
||||
|
||||
Some information about the character Jane Doe.
|
||||
|
||||
When this is done in a document in a root folder of type **Characters**, the tag is automatically
|
||||
treated as an available character in your project with the value "Jane". You will then be able to
|
||||
reference "Jane" in any of your other documents using the reference keywords for characters.
|
||||
|
||||
The character "Jane" will also show up in the **Character** tab in the **Reference** panel below
|
||||
the document viewer.
|
||||
|
||||
.. note::
|
||||
|
||||
It is the root folder type that defines what category of story elements the tag is indexed
|
||||
under. See :ref:`docs_usage_project_roots` for more details.
|
||||
|
||||
|
||||
.. _docs_usage_tags_refs_refs:
|
||||
|
||||
How to Use References
|
||||
=====================
|
||||
|
||||
Each heading of any level in your project can contain references to tags set in your notes. The
|
||||
references are gathered by the project index and used to generate the **Outline View**, among other
|
||||
things.
|
||||
|
||||
References are set with a special keyword, with a list of corresponding tags. The valid keywords
|
||||
are listed below. The format of a reference line is ``@keyword: value1, [value2] ... [valueN]``.
|
||||
All reference keywords allow multiple values.
|
||||
|
||||
``@pov``
|
||||
The point-of-view character for the current section. The target must be a note tag in a
|
||||
**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 the point-of-view character. The target must be a note tag in a **Character** type
|
||||
root folder.
|
||||
|
||||
``@char``
|
||||
For 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 **Plot**
|
||||
type root folder.
|
||||
|
||||
``@time``
|
||||
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
|
||||
**Locations** type root folder.
|
||||
|
||||
``@object``
|
||||
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 an **Entities** type
|
||||
root folder.
|
||||
|
||||
``@custom``
|
||||
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.
|
||||
|
||||
``@mention``
|
||||
For anything, anyone or anyplace mentioned, but not present in the current section. It is
|
||||
intended for those cases where you reveal details about a character or place in a scene without
|
||||
otherwise being a part of it. This can be useful when checking for consistency later. Any tag in
|
||||
any root note folder can be listed under ``@mention``.
|
||||
|
||||
``@story``
|
||||
This is used when referencing a Novel Document, like a scene or chapter, from somewhere else in
|
||||
your project. It is possible to also set tags in documents in a **Novel** type folder, and this
|
||||
is the keyword you use to reference those.
|
||||
|
||||
When tags and references are used correctly, it will be indicated by highlight colours in the
|
||||
editor.
|
||||
|
||||
.. 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 **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 **Create Note for Tag**. This will generate a new note automatically in the correct type
|
||||
of root folder, with the new tag defined.
|
||||
|
||||
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.
|
||||
|
||||
Your 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
|
||||
**Manuscript Build** tool, the cross-references become clickable links in the exported HTML
|
||||
document as well.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
Example of a novel document with references to characters and plots:
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
## Chapter 1
|
||||
|
||||
@pov: Jane
|
||||
|
||||
### Scene 1
|
||||
|
||||
@char: John, Sam
|
||||
@plot: Main
|
||||
|
||||
Once upon a time ...
|
||||
|
||||
|
||||
.. _docs_usage_tags_refs_completer:
|
||||
|
||||
Auto-Completion in the Editor
|
||||
-----------------------------
|
||||
|
||||
An auto-completer context menu will show up automatically in the document editor when you type the
|
||||
character ``@`` on a new line. It will first suggest tag or reference keywords for you to add, and
|
||||
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. Notes for new references can be created by right-clicking on them and selecting **Create
|
||||
Note for Tag** from the menu.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
@@ -1,290 +0,0 @@
|
||||
.. _a_breakdown:
|
||||
|
||||
************
|
||||
How it Works
|
||||
************
|
||||
|
||||
.. _Fusion: https://doc.qt.io/qt-6/gallery.html
|
||||
.. _Pandoc: https://pandoc.org/
|
||||
.. _Open Document: https://en.wikipedia.org/wiki/OpenDocument
|
||||
.. _Office Open XML: https://en.wikipedia.org/wiki/Office_Open_XML
|
||||
.. _version control: https://en.wikipedia.org/wiki/Version_control
|
||||
|
||||
The main features of novelWriter are listed in the :ref:`a_intro` chapter. In this chapter, we go
|
||||
into some more details on how they are implemented. This is intended as an overview. Later on in
|
||||
this documentation these features will be covered in more detail.
|
||||
|
||||
|
||||
.. _a_breakdown_design:
|
||||
|
||||
GUI Layout and Design
|
||||
=====================
|
||||
|
||||
The user interface of novelWriter is intended to be as minimalistic as practically possible, while
|
||||
at the same time provide useful features needed for writing a novel.
|
||||
|
||||
The main window does not by default have an editor toolbar like many other applications do. This
|
||||
reduces clutter, and since the documents are formatted with style tags, it is not needed most of
|
||||
the time. Still, a small formatting toolbar can be popped out by clicking the left-most button in
|
||||
the header of the document editor. It gives quick access to standard formatting codes.
|
||||
|
||||
Most formatting features supported are available through convenient keyboard shortcuts. They are
|
||||
also available in the main menu under **Format**, so you don't have to look up formatting codes
|
||||
every time you need them. For reference, a list of all shortcuts can be found in the :ref:`a_kb`
|
||||
chapter.
|
||||
|
||||
.. note::
|
||||
novelWriter is not intended to be a full office type word processor. It doesn't support images,
|
||||
links, tables, and other complex structures and objects often needed for such documents.
|
||||
Formatting is limited to headings, in-line basic text formats, text alignment, and a few other
|
||||
simple features.
|
||||
|
||||
On the left side of the main window, you will find a sidebar. This bar has buttons for the standard
|
||||
views you can switch between, a quick link to the **Build Manuscript** tool, and a set of
|
||||
project-related tools and quick access to settings at the bottom.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
|
||||
A number of new formatting options were added in 2.2 to allow for some special formatting cases.
|
||||
At the same time, a small formatting toolbar was added to the editor. It is hidden by default,
|
||||
but can be opened by pressing the button in the top--left corner of the editor header.
|
||||
|
||||
|
||||
Project Tree and Editor View
|
||||
----------------------------
|
||||
|
||||
.. figure:: images/fig_project_tree_view.png
|
||||
|
||||
A screenshot of the Project Tree and Editor View.
|
||||
|
||||
When the application is in **Project Tree View** mode, the work area of the main window is split in
|
||||
two, or optionally three, panels. The left-most panel contains the project tree and all the
|
||||
documents in your project. The second panel is the document editor.
|
||||
|
||||
An optional third panel on the right side contains a document viewer which can view any document in
|
||||
your project independently of what is open in the document editor. This panel is not intended as a
|
||||
preview window, although you can use it for this purpose if you wish. For instance if you need to
|
||||
check that the formatting tags behave as you expect. However, the main purpose of the viewer is for
|
||||
viewing your notes next to your editor while you're writing.
|
||||
|
||||
The editor also has a **Focus Mode** you can toggle either from the menu, from the icon in the
|
||||
editor's header, or by pressing :kbd:`F8`. When **Focus Mode** is enabled, all the user interface
|
||||
elements other than the document editor itself are hidden away.
|
||||
|
||||
The project tree will highlight with a different background colour the document that is currently
|
||||
open in the editor.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
You can now drag and drop documents from the project tree onto the editor or viewer panels to
|
||||
open them.
|
||||
|
||||
|
||||
Novel View and Editor View
|
||||
--------------------------
|
||||
|
||||
.. figure:: images/fig_novel_tree_view.png
|
||||
|
||||
A screenshot of the Novel Tree and Editor View.
|
||||
|
||||
When the application is in **Novel Tree View** mode, the project tree is replaced by an overview of
|
||||
your novel structure for a specific Novel :term:`root folder`. Instead of showing individual
|
||||
documents, the tree now shows all headings of your novel text. This includes multiple headings
|
||||
within the same document.
|
||||
|
||||
Each heading is indented according to the heading level, not its parent/child relationship to other
|
||||
elements of your project. You can open and edit your novel documents from this view as well. All
|
||||
headings contained in the currently open document should be highlighted in the view to indicate
|
||||
which ones belong together in the same document.
|
||||
|
||||
If you have multiple **Novel** type root folders, the header of the novel view becomes a dropdown
|
||||
box. You can then switch between them by clicking the :guilabel:`Outline of ...` text. You can also
|
||||
click the novel icon button next to it.
|
||||
|
||||
Generally, the novel view should update when you make changes to the novel structure, including
|
||||
edits of the current document in the editor. The information is only updated when the automatic
|
||||
save of the document is triggered, or you manually press :kbd:`Ctrl+S` to save changes. (You can
|
||||
adjust the auto-save interval in **Preferences**.) You can also regenerate the whole novel view by
|
||||
pressing the refresh button in the novel view header.
|
||||
|
||||
It is possible to show an optional third column in the novel view. The settings are available from
|
||||
the menu button in the toolbar.
|
||||
|
||||
If you click the triangular icon to the right of each item, a tooltip will pop out showing all the
|
||||
meta data collected for that heading.
|
||||
|
||||
|
||||
Novel Outline View
|
||||
------------------
|
||||
|
||||
.. figure:: images/fig_outline_view.png
|
||||
|
||||
A screenshot of the Novel Outline View.
|
||||
|
||||
When the application is in **Novel Outline View** mode, the tree, editor and viewer are replaced by
|
||||
a large table that shows the entire novel structure with all the tags and references listed. Pretty
|
||||
much all collected meta data is available here in different columns.
|
||||
|
||||
You can select which novel root folder to display from the dropdown box, and you can select which
|
||||
columns to show or hide from the menu button. You can also rearrange the columns by drag and drop.
|
||||
The app remembers your column order and sizes between sessions, and for each individual project.
|
||||
|
||||
|
||||
Colour Themes
|
||||
-------------
|
||||
|
||||
By default, novelWriter uses a light colour theme. You can also choose between a standard dark
|
||||
theme that have neutral colours, or a series of other included themes, from **Preferences**.
|
||||
|
||||
If you wish, you *can* create your own colour themes, and even have them added to the application.
|
||||
See :ref:`a_custom_theme` for more details.
|
||||
|
||||
Switching the GUI colour theme does not affect the colours of the editor and viewer. They have
|
||||
separate colour selectable from the "Document colour theme" setting in **Preferences**. They are
|
||||
separated because there are a lot more options to choose from for the editor and viewer.
|
||||
|
||||
.. note::
|
||||
|
||||
If you switch between light and dark mode on the GUI, you should also switch editor theme to
|
||||
match, otherwise icons may be hard to see in the editor and viewer.
|
||||
|
||||
|
||||
Project Search
|
||||
--------------
|
||||
|
||||
A global search tool is available from the side bar. It allows you to search through your entire
|
||||
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
|
||||
|
||||
|
||||
Switching Focus
|
||||
---------------
|
||||
|
||||
If the project or novel view does not have focus, pressing :kbd:`Ctrl+T` switches focus to
|
||||
whichever of the two is visible. If one of them already has focus, the key press will switch
|
||||
between them instead.
|
||||
|
||||
Likewise, pressing :kbd:`Ctrl+E` will switch focus to the document editor or viewer, or if any of
|
||||
them already have focus, it will switch focus between them,
|
||||
|
||||
These two shortcuts make it possible to jump between all these GUI elements without having to reach
|
||||
for the mouse or touchpad.
|
||||
|
||||
|
||||
.. _a_breakdown_project:
|
||||
|
||||
Project Layout
|
||||
==============
|
||||
|
||||
This is a brief introduction to how you should structure your writing projects. All of this will be
|
||||
covered in more detail later.
|
||||
|
||||
The main point of novelWriter is that you are free to organise your project documents as you wish
|
||||
into sub-folders or sub-documents, and split the text between these documents in whatever way suits
|
||||
you. All that matters to novelWriter is the linear order the documents appear at in the project
|
||||
tree (top to bottom). The chapters, scenes and sections of the novel are determined by the headings
|
||||
within those documents.
|
||||
|
||||
.. figure:: images/fig_header_levels.png
|
||||
|
||||
An illustration of how heading levels correspond to the novel structure.
|
||||
|
||||
The four heading levels, **Level 1** to **Level 4**, are treated as follows:
|
||||
|
||||
* **Level 1** is used for the novel title, and for partitions.
|
||||
* **Level 2** is used for chapter tiles.
|
||||
* **Level 3** is used for scene titles -- optionally replaced by separators.
|
||||
* **Level 4** is for section titles within scenes, if such granularity is needed.
|
||||
|
||||
The project tree will select an icon for the document based on the first heading in it.
|
||||
|
||||
This heading level structure is only taken into account for :term:`novel documents`. For
|
||||
:term:`project notes`, the heading levels have no structural meaning, and you are free to use them
|
||||
however you want. See :ref:`a_struct` and :ref:`a_references` for more details.
|
||||
|
||||
.. tip::
|
||||
|
||||
You can add documents as child items of other documents. This is often more useful than adding
|
||||
folders, since you anyway may want to have the chapter heading in a separate document from your
|
||||
individual scene documents so that you can rearrange scene documents freely without affecting
|
||||
chapter placement.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
The heading levels for partitions, chapters and scenes only apply within novelWriter. When you
|
||||
generate your manuscript, chapters are considered as the topmost heading level, with scenes
|
||||
below it. Partitions are inserted as text elements in most formats.
|
||||
|
||||
|
||||
.. _a_breakdown_export:
|
||||
|
||||
Building a Manuscript
|
||||
=====================
|
||||
|
||||
The project can at any time be assembled into a range of different formats through the
|
||||
**Build Manuscript** tool. Natively, novelWriter supports `Open Document`_, Microsoft Word Document
|
||||
(known as `Office Open XML`_), HTML5, and various flavours of Markdown. You can also generate a PDF
|
||||
document.
|
||||
|
||||
The HTML5 format is suitable for conversion by a number of other tools like Pandoc_, or for
|
||||
importing into word processors if the Open Document or Word Document format isn't suitable. The
|
||||
Open Document format is supported by most office type applications, so is the Word Document format.
|
||||
In addition, printing is also possible.
|
||||
|
||||
For advanced processing, you can export the content of the project to a JSON file. This is useful
|
||||
if you want 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 it into the novel documents.
|
||||
|
||||
See :ref:`a_manuscript` for more details.
|
||||
|
||||
.. versionadded:: 2.1
|
||||
|
||||
You can now define multiple build definitions in the **Build Manuscript** tool. This allows you
|
||||
to define specific settings for various types of draft documents, outline documents, and
|
||||
manuscript formats. See :ref:`a_manuscript` for more details.
|
||||
|
||||
|
||||
.. _a_breakdown_storage:
|
||||
|
||||
Project Storage
|
||||
===============
|
||||
|
||||
The files of a novelWriter project are stored in a dedicated project folder. The project structure
|
||||
is kept in a file at the root of this folder called ``nwProject.nwx``. All the document files and
|
||||
associated meta data are stored in other folders below the project folder. For a more technical
|
||||
description of what all the files mean and how they're organised, see the :ref:`a_storage` section.
|
||||
|
||||
This way of storing data was chosen for several reasons.
|
||||
|
||||
Firstly, all the text you add to your project is saved directly to your project folder in separate
|
||||
files. Only the project structure and the text you are currently editing is stored in memory at any
|
||||
given time, which means there is a smaller risk of losing data if the application or your computer
|
||||
crashes.
|
||||
|
||||
Secondly, having multiple small files means it is very easy to synchronise them between computers
|
||||
with standard file synchronisation tools.
|
||||
|
||||
Thirdly, if you use `version control`_ software to track the changes to your project, the file
|
||||
formats used for the files are well suited. All the JSON documents have line breaks and indents as
|
||||
well, which makes it easier to track them with version control software.
|
||||
|
||||
.. note::
|
||||
|
||||
Since novelWriter has to keep track of a bunch of files and folders when a project is open, it
|
||||
may not run well on some virtual file systems. A file or folder must be accessible with exactly
|
||||
the path it was saved or created with. An example where this is not the case is the way Google
|
||||
Drive is mapped on Linux Gnome desktops using gvfs/gio.
|
||||
|
||||
.. caution::
|
||||
|
||||
You should not add additional files to the project folder yourself. Nor should you, as a rule,
|
||||
manually edit files within it. If you really must manually edit the text files, e.g. with some
|
||||
automated task you want to perform, you need to rebuild the :term:`Project Index` when you open
|
||||
the project again.
|
||||
|
||||
Editing text files in the ``content`` folder is less risky as these are just plain text. Editing
|
||||
the main project XML file, however, may make the project file unreadable and you may crash
|
||||
novelWriter and lose project structure information and project settings.
|
||||
@@ -1,470 +0,0 @@
|
||||
.. _a_fmt:
|
||||
|
||||
********************
|
||||
Formatting Your Text
|
||||
********************
|
||||
|
||||
The novelWriter text editor is a plain text editor that uses formatting codes for setting meta data
|
||||
values and allowing for some text formatting. The syntax is based on Markdown, but novelWriter is
|
||||
**not** a Markdown editor. It supports basic formatting like emphasis (italic), strong importance
|
||||
(bold) and strike through text, as well as four levels of headings. For some further complex
|
||||
formatting needs, a set of shortcodes can be used.
|
||||
|
||||
In addition to formatting codes, novelWriter allows for comments, a synopsis tag, and a number of
|
||||
keyword and value sets used for :term:`tags<tag>` and :term:`references<reference>`. There are also
|
||||
some codes that apply to whole paragraphs. See :ref:`a_fmt_text` for more details.
|
||||
|
||||
URLs should also be highlighted and become clickable. However, only URLs starting with "http" or
|
||||
"https" are recognised. In the editor, you must hold down the :kbd:`Ctrl` key when clicking a URL
|
||||
to follow it.
|
||||
|
||||
|
||||
.. _a_fmt_hlight:
|
||||
|
||||
Syntax Highlighting
|
||||
===================
|
||||
|
||||
The editor has a syntax highlighter feature that is meant to help you know when you've used the
|
||||
formatting tags or other features correctly. It will change the colour and font size of your
|
||||
headings, change the text colour of emphasised text, and it can also show you where you have
|
||||
dialogue in your text.
|
||||
|
||||
.. figure:: images/fig_references.png
|
||||
|
||||
An example of the colour highlighting of references. "Bob" is not defined, and "@blabla" is not
|
||||
a valid reference type.
|
||||
|
||||
When you use the keywords to set tags and references, these also change colour. Correct keywords
|
||||
have a distinct colour, and the references themselves will get a colour if they are valid. Invalid
|
||||
references will get a squiggly error line underneath. The same applies to duplicate tags.
|
||||
|
||||
There are a number of syntax highlighter colour themes available, both for light and dark GUIs. You
|
||||
can select them from **Preferences**.
|
||||
|
||||
|
||||
.. _a_fmt_head:
|
||||
|
||||
Headings
|
||||
========
|
||||
|
||||
.. figure:: images/fig_header_levels.png
|
||||
|
||||
An illustration of how heading levels correspond to the novel structure.
|
||||
|
||||
Four levels of headings are allowed. For :term:`project notes`, they are free to be used as you see
|
||||
fit. That is, novelWriter doesn't assign the different headings any particular meaning. However,
|
||||
for :term:`novel documents` they indicate the structural level of the novel and must be used
|
||||
correctly to produce the intended result. See :ref:`a_struct_heads` for more details.
|
||||
|
||||
``# Title Text``
|
||||
Heading level one. For novel documents, the level indicates the start of a new partition.
|
||||
Partitions are for when you want to split your story into "Part 1", "Part 2", etc. You can also
|
||||
choose to use them for splitting the text up into acts, and then hide these headings in your
|
||||
manuscript.
|
||||
|
||||
``## Title Text``
|
||||
Heading level two. For novel documents, the level indicates the start of a new chapter. Chapter
|
||||
numbers can be inserted automatically when building the manuscript.
|
||||
|
||||
``### Title Text``
|
||||
Heading level three. For novel documents, the level indicates the start of a new scene. Scene
|
||||
numbers or scene separators can be inserted automatically when building the manuscript, so you
|
||||
can use the title field as a working title for your scenes if you wish, but you must provide a
|
||||
minimal title.
|
||||
|
||||
``#### Title Text``
|
||||
Heading level four. For novel documents, the level indicates the start of a new section. Section
|
||||
titles can be replaced by separators or ignored completely when building the manuscript.
|
||||
|
||||
For headings level one through three, adding a ``!`` modifies the meaning of the heading:
|
||||
|
||||
``#! Title Text``
|
||||
This tells the build tool that the level one heading is intended to be used for the novel or
|
||||
notes folder's main title, like for instance the novel title on the cover page. When building
|
||||
the manuscript, this will use a different styling.
|
||||
|
||||
``##! Title Text``
|
||||
This tells the build tool to not assign a chapter number to this chapter title if automatic
|
||||
chapter numbers are being used. Such titles are useful for prologues and epilogues for instance.
|
||||
See :ref:`a_struct_heads_unnum` for more details.
|
||||
|
||||
``###! Title Text``
|
||||
This is an alternative scene heading that can be formatted differently in the **Manuscript
|
||||
Build** tool. It is intended for separating "soft" and "hard" scene breaks. Aside from this, it
|
||||
behaves identically to a regular scene heading. See :ref:`a_struct_heads_scenes` for more
|
||||
details.
|
||||
|
||||
.. note::
|
||||
|
||||
The space after the ``#`` or ``!`` character is mandatory. The syntax highlighter will change
|
||||
colour and font size when the heading is correctly formatted.
|
||||
|
||||
|
||||
.. _a_fmt_text:
|
||||
|
||||
Text Paragraphs
|
||||
===============
|
||||
|
||||
A text paragraph is indicated by a blank line. That is, you need two line breaks to separate two
|
||||
fragments of text into two paragraphs. Single line breaks are treated as line breaks within a
|
||||
paragraph.
|
||||
|
||||
In addition, the editor supports a few additional types of white spaces:
|
||||
|
||||
* A non-breaking space can be inserted with :kbd:`Ctrl+K`, :kbd:`Space`.
|
||||
* Thin spaces are also supported, and can be inserted with :kbd:`Ctrl+K`, :kbd:`Shift+Space`.
|
||||
* Non-breaking thin space can be inserted with :kbd:`Ctrl+K`, :kbd:`Ctrl+Space`.
|
||||
|
||||
These are all insert features, and the **Insert** menu has more. The keyboard shortcuts for them
|
||||
are also listed in :ref:`a_kb_ins`.
|
||||
|
||||
Non-breaking spaces are highlighted by the syntax highlighter with an alternate coloured
|
||||
background, depending on the selected theme.
|
||||
|
||||
.. tip::
|
||||
|
||||
Non-breaking spaces are for instance the correct type of space to separate a number from its
|
||||
unit. Generally, non-breaking spaces are used to prevent line wrapping algorithms from adding
|
||||
line breaks where they shouldn't.
|
||||
|
||||
.. note::
|
||||
|
||||
You should not manually apply text indentation in your paragraphs in the editor. These can be
|
||||
added automatically in the **Manuscript Build** tool if you want to have them in the manuscript.
|
||||
Each new paragraph should be separated from the previous content by an empty line and with no
|
||||
indentation.
|
||||
|
||||
|
||||
.. _a_fmt_emph:
|
||||
|
||||
Text Emphasis with Markdown
|
||||
===========================
|
||||
|
||||
A minimal set of Markdown text emphasis styles are supported for text paragraphs.
|
||||
|
||||
``_text_``
|
||||
The text is rendered as emphasised text (italicised).
|
||||
|
||||
``**text**``
|
||||
The text is rendered as strongly emphasised text (bold).
|
||||
|
||||
``~~text~~``
|
||||
Strike through text.
|
||||
|
||||
In Markdown guides it is often recommended to differentiate between strong emphasis and emphasis
|
||||
by using ``**`` for strong and ``_`` for emphasis, although Markdown generally also supports ``__``
|
||||
for strong and ``*`` for emphasis. However, since the differentiation makes the highlighting and
|
||||
conversion significantly simpler and faster, in novelWriter this is a rule, not just a
|
||||
recommendation.
|
||||
|
||||
In addition, the following rules apply:
|
||||
|
||||
1. The emphasis and strike through formatting tags do not allow spaces between the words and the
|
||||
tag itself. That is, ``**text**`` is valid, ``**text **`` is not.
|
||||
2. More generally, the delimiters must be on the outer edge of words. That is, ``some **text in
|
||||
bold** here`` is valid, ``some** text in bold** here`` is not.
|
||||
3. If using both ``**`` and ``_`` to wrap the same text, the underscore must be the **inner**
|
||||
wrapper. This is due to the underscore also being a valid word character, so if they are on the
|
||||
outside, they violate rule 2.
|
||||
4. Text emphasis does not span past line breaks. If you need to add emphasis to multiple lines or
|
||||
paragraphs, you must apply it to each of them in turn.
|
||||
5. Text emphasis can only be used in comments and paragraphs. Headings and meta data tags don't
|
||||
allow for formatting, and any formatting markup will be rendered as-is.
|
||||
|
||||
.. tip::
|
||||
|
||||
novelWriter supports standard escape syntax for the emphasis markup characters in case the
|
||||
editor misunderstands your intended usage of them. That is, ``\*``, ``\_`` and ``\~`` will
|
||||
generate a plain ``*``, ``_`` and ``~``, respectively, without interpreting them as part of the
|
||||
markup.
|
||||
|
||||
|
||||
.. _a_fmt_shortcodes:
|
||||
|
||||
Formatting with Shortcodes
|
||||
==========================
|
||||
|
||||
For additional formatting options, you can use shortcodes. Shortcodes is a form of in-line codes
|
||||
that can be used to change the format of the text that follows and opening code, and last until
|
||||
that formatting region is ended with a closing code.
|
||||
|
||||
These shortcodes are intended for special formatting cases, or more complex cases that cannot be
|
||||
solved with simple Markdown-like formatting codes. Available shortcodes are listed below.
|
||||
|
||||
.. csv-table:: Shortcodes Formats
|
||||
:header: "Syntax", "Description"
|
||||
:widths: 40, 60
|
||||
:class: "tight-table"
|
||||
|
||||
"``[b]text[/b]``", "Text is rendered as bold text."
|
||||
"``[i]text[/i]``", "Text is rendered as italicised text."
|
||||
"``[s]text[/s]``", "Text is rendered as strike through text."
|
||||
"``[u]text[/u]``", "Text is rendered as underlined text."
|
||||
"``[m]text[/m]``", "Text is rendered as highlighted text."
|
||||
"``[sup]text[/sup]``", "Text is rendered as superscript text."
|
||||
"``[sub]text[/sub]``", "Text is rendered as subscript text."
|
||||
|
||||
Unlike Markdown style codes, these can be used anywhere within a paragraph. Even in the middle of a
|
||||
word if you need to. You can also freely combine them to form more complex formatting.
|
||||
|
||||
The shortcodes are available from the **Format** menu and in the editor toolbar, which can be
|
||||
activated by clicking the left-most icon button in the editor header.
|
||||
|
||||
.. note::
|
||||
|
||||
Shortcodes are not processed until you generate a preview or generate a manuscript document. So
|
||||
there is no highlighting of the text between the formatting markers. There is also no check that
|
||||
your markers make sense. You must ensure that you have both the opening and closing formatting
|
||||
markers where you want them.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
|
||||
|
||||
.. _a_fmt_comm:
|
||||
|
||||
Comments and Synopsis
|
||||
=====================
|
||||
|
||||
In addition to the above formatting features, novelWriter also allows for comments in documents.
|
||||
The text of a comment is always ignored by the word counter. The text can also be filtered out
|
||||
when building the manuscript or viewing the document.
|
||||
|
||||
The first word of a comment, followed by a colon, can be one of a set of modifiers that indicates
|
||||
the comment is intended for a specific purpose. For instance, if the comment starts with
|
||||
``Synopsis:``, the comment is treated in a special manner and will show up in the
|
||||
:ref:`a_ui_outline` in a dedicated column. The word ``synopsis`` is not case sensitive. If it is
|
||||
correctly formatted, the syntax highlighter will indicate this by altering the colour of the word.
|
||||
|
||||
The different styles of comments are as follows:
|
||||
|
||||
``% Your comment text ...``
|
||||
This is a comment. The text is not rendered by default (this can be overridden), seen in the
|
||||
document viewer, or counted towards word counts. It is intended for you to make notes in your
|
||||
text for your own sake, whatever that may be, that isn't part of the story text. This is the
|
||||
general format of a comment.
|
||||
|
||||
``%Synopsis: Your synopsis text ...``
|
||||
This is a synopsis comment. It is generally treated in the same way as a regular comment, except
|
||||
that it is also captured by the indexing algorithm and displayed in the :ref:`a_ui_outline`. It
|
||||
can also be filtered separately when building the project to for instance generate an outline
|
||||
document of the whole project.
|
||||
|
||||
``%Short: Your short description ...``
|
||||
This is a short description comment. It is identical to the synopsis comment (they are
|
||||
interchangeable), but is intended to be used for project notes. The text shows up in the
|
||||
Reference panel below the document viewer in the last column labelled **Short Description**.
|
||||
|
||||
``%Footnote.<key>: Your footnote text ...``
|
||||
This is a special comment assigned to a footnote marker. See :ref:`a_fmt_footnote` for how to
|
||||
use them in your text.
|
||||
|
||||
.. note::
|
||||
|
||||
Only one comment can be flagged as a synopsis or short comment for each heading. If multiple
|
||||
comments are flagged as synopsis or short comments, the last one will be used and the rest
|
||||
ignored.
|
||||
|
||||
|
||||
.. _a_fmt_footnote:
|
||||
|
||||
Footnotes
|
||||
=========
|
||||
|
||||
Footnotes are added with a shortcode, paired with a matching comment for the actual footnote text.
|
||||
The matching is done with a key that links the two. If you insert a footnote from the **Insert**
|
||||
menu, a unique key is generated for you.
|
||||
|
||||
The insert feature will add the footnote shortcode marker at the position of your cursor in the
|
||||
text, and create the associated footnote comment right after the paragraph, and move the cursor
|
||||
there so you can immediately start typing the footnote text.
|
||||
|
||||
The footnote comment can be anywhere in the document, so if you wish to move them to, say, the
|
||||
bottom of the text, you are free to do so.
|
||||
|
||||
Footnote keys are only required to be unique within a document, so if you copy, move or merge text,
|
||||
you must make sure the keys are not duplicated. If you use the automatically generated keys from
|
||||
the **Insert** menu, they are unique among all indexed documents. They are not guaranteed to be
|
||||
unique against footnotes in the Archive or Trash folder though, but the chance of accidentally
|
||||
generating the same key twice in a project is relatively small in the first place (1 in 810 000).
|
||||
|
||||
This is what a footnote inserted into a paragraph may look like when completed:
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
This is a text paragraph with a footnote[footnote:fn1] in the middle.
|
||||
|
||||
%Footnote.fn1: This is the text of the footnote.
|
||||
|
||||
.. versionadded:: 2.5
|
||||
|
||||
|
||||
.. _a_fmt_ignore:
|
||||
|
||||
Ignored Text
|
||||
============
|
||||
|
||||
If you want to completely ignore some of the text in your documents, but are not ready to delete
|
||||
it, you can add ``%~`` before the text paragraph or line. This will cause novelWriter to skip the
|
||||
text entirely when generating previews or building manuscripts.
|
||||
|
||||
This is a better way of removing text than converting them to regular comments, as you may want to
|
||||
include regular comments in your previews or draft manuscript.
|
||||
|
||||
You can toggle the ignored text feature on and off for a paragraph by pressing :kbd:`Ctrl+Shift+D`
|
||||
on your keyboard with your cursor somewhere in the paragraph.
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
%~ This text is ignored.
|
||||
|
||||
This text is a regular paragraph.
|
||||
|
||||
|
||||
.. _a_fmt_tags:
|
||||
|
||||
Tags and References
|
||||
===================
|
||||
|
||||
The document editor supports a set of keywords used for setting tags, and making references between
|
||||
documents based on those tags.
|
||||
|
||||
You must use the keyword ``@tag:`` to define a tag. The tag can be set once per section defined by
|
||||
a heading. Setting it multiple times under the same heading will just override the previous
|
||||
setting.
|
||||
|
||||
``@tag: value``
|
||||
A tag keyword followed by the tag value, like for instance the name of a character.
|
||||
|
||||
References can be set anywhere within a section, and are collected according to their category.
|
||||
References are on the form:
|
||||
|
||||
``@keyword: value1, value2, ..., valueN``
|
||||
A reference keyword followed by a value, or a comma separated list of values.
|
||||
|
||||
Tags and references are covered in detail in the :ref:`a_references` chapter. The keywords can be
|
||||
inserted at the cursor position in the editor via the **Insert** menu. If you start typing an ``@``
|
||||
on a new line, and auto-complete menu will also pop up suggesting keywords.
|
||||
|
||||
|
||||
.. _a_fmt_align:
|
||||
|
||||
Paragraph Alignment and Indentation
|
||||
===================================
|
||||
|
||||
All documents have the text by default aligned to the left or justified, depending on your setting
|
||||
in **Preferences**.
|
||||
|
||||
You can override the default text alignment on individual paragraphs by specifying alignment tags.
|
||||
These tags are double angle brackets. Either ``>>`` or ``<<``. You put them either before or after
|
||||
the paragraph, and they will "push" the text towards the edge the brackets point towards. This
|
||||
should be fairly intuitive.
|
||||
|
||||
Indentation uses a similar syntax. But here you use a single ``>`` or ``<`` to push the text away
|
||||
from the edge.
|
||||
|
||||
Examples:
|
||||
|
||||
.. csv-table:: Text Alignment and Indentation
|
||||
:header: "Syntax", "Description"
|
||||
:widths: 40, 60
|
||||
:class: "tight-table"
|
||||
|
||||
"``>> Right aligned text``", "The text paragraph is right-aligned."
|
||||
"``Left aligned text <<``", "The text paragraph is left-aligned."
|
||||
"``>> Centred text <<``", "The text paragraph is centred."
|
||||
"``> Left indented text``", "The text has an increased left margin."
|
||||
"``Right indented text <``", "The text has an increased right margin."
|
||||
"``> Left/right indented text <``", "The text has both margins increased."
|
||||
|
||||
.. note::
|
||||
|
||||
The text editor will not show the alignment and indentation live. But the viewer will show them
|
||||
when you open the document there. It will of course also be reflected in the document generated
|
||||
from the manuscript build tool as long as the format supports paragraph alignment.
|
||||
|
||||
|
||||
Alignment with Line Breaks
|
||||
--------------------------
|
||||
|
||||
If you have line breaks in the paragraph, the markers for all the lines are combined and used for
|
||||
the entire paragraph. For the following text, all lines will be centred:
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
>> I am the very model of a modern Major-General
|
||||
I've information vegetable, animal, and mineral
|
||||
I know the kings of England, and I quote the fights historical
|
||||
From Marathon to Waterloo, in order categorical <<
|
||||
|
||||
|
||||
Alignment with First Line Indent
|
||||
--------------------------------
|
||||
|
||||
If you have first line indent enabled in your Manuscript build settings, you probably want to
|
||||
disable it for text in verses. Adding any alignment tags will cause the first line indent to be
|
||||
switched off for that paragraph.
|
||||
|
||||
The following text will always be aligned against the left margin:
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
I am the very model of a modern Major-General <<
|
||||
I've information vegetable, animal, and mineral
|
||||
I know the kings of England, and I quote the fights historical
|
||||
From Marathon to Waterloo, in order categorical
|
||||
|
||||
|
||||
.. _a_fmt_break:
|
||||
|
||||
Vertical Space and Page Breaks
|
||||
==============================
|
||||
|
||||
You can apply page breaks to partition, chapter and scene headings for novel documents from the
|
||||
**Manuscript Build** tool. If you need to add a page break or additional vertical spacing in other
|
||||
places, there are special codes available for this purpose.
|
||||
|
||||
Adding more than one line break between paragraphs will **not** increase the space between those
|
||||
paragraphs when building the project. To add additional space between paragraphs, add the text
|
||||
``[vspace]`` on a line of its own, and the build tool will insert a blank paragraph in its place.
|
||||
|
||||
If you need multiple blank paragraphs just add a colon and a number to the above code. For
|
||||
instance, writing ``[vspace:3]`` will insert three blank paragraphs.
|
||||
|
||||
If you need to add a page break somewhere, put the text ``[new page]`` on a line by itself before
|
||||
the text you wish to start on a new page.
|
||||
|
||||
.. note::
|
||||
|
||||
The page break code is applied to the text that follows it. It adds a "page break before" mark
|
||||
to the text when exporting to HTML or Open Document. This means that a ``[new page]`` which has
|
||||
no text following it, it will not result in a page break.
|
||||
|
||||
**Example:**
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
This is a text paragraph.
|
||||
|
||||
[vspace:2]
|
||||
|
||||
This is another text paragraph, but there will be two empty paragraphs
|
||||
between them.
|
||||
|
||||
[new page]
|
||||
|
||||
This text will start on a new page if the build format has pages.
|
||||
|
||||
|
||||
.. _a_fmt_stats:
|
||||
|
||||
Inserting Word Counts in the Text
|
||||
=================================
|
||||
|
||||
The cover page of a manuscript normally has the word count stated on it. Any statistics value
|
||||
collected by novelWriter can be inserted into any document. You can generate the code for this from
|
||||
the **Insert** menu under **Word/Character Count**.
|
||||
|
||||
The value inserted is the actual count for your entire manuscript, so it is not populated until you
|
||||
run the **Manuscript Build** tool. Until then they will show up as "0" in the viewer panel.
|
||||
@@ -1,235 +0,0 @@
|
||||
.. _a_ui_project:
|
||||
|
||||
*************
|
||||
Project Views
|
||||
*************
|
||||
|
||||
This chapter covers in more detail the different project views available in novelWriter.
|
||||
|
||||
.. figure:: images/fig_project_tree_detailed.png
|
||||
|
||||
The **Project Content** tree as it appears when loading a sample project.
|
||||
|
||||
|
||||
.. _a_ui_tree:
|
||||
|
||||
The Project Tree
|
||||
================
|
||||
|
||||
The main window contains a project tree in the left-most panel. It shows the entire structure of
|
||||
the project, and has four columns.
|
||||
|
||||
**Column 1**
|
||||
The first column shows the icon and label of each folder, document, or note in your project. The
|
||||
label is not the same as the heading title you set inside the document. However, the document's
|
||||
label will appear in the header above the document text itself so you know where in the project
|
||||
an open document belongs. The icon is selected based on the type of item, and for novel
|
||||
documents, the level of the first heading in the document text.
|
||||
|
||||
**Column 2**
|
||||
The second column shows the word count of the document, or the sum of words of the child items
|
||||
for folders and documents with sub-documents. If the counts seem incorrect, they can be updated
|
||||
by rebuilding the :term:`project index` from the **Tools** menu, or by pressing :kbd:`F9`.
|
||||
|
||||
**Column 3**
|
||||
The third column indicates whether the document is considered active or inactive in the project.
|
||||
You can use this flag to indicate that a document is still in the project, but should not be
|
||||
considered an active part of it. When you run the **Build Manuscript** tool, you can include or
|
||||
exclude documents based on this flag. You can change this value from the right-click
|
||||
:term:`context menu`.
|
||||
|
||||
**Column 4**
|
||||
The fourth column shows the user-defined status or importance labels you've assigned to each
|
||||
project item. See :ref:`a_ui_tree_status` for more details on how to uses these labels. You can
|
||||
select these labels from the :term:`context menu`, and define them in **Project Settings**.
|
||||
|
||||
Right-clicking an item in the project tree will open a context menu under the cursor, displaying
|
||||
a selection of actions that can be performed on the selected item.
|
||||
|
||||
At the top of the project tree, you will find a set of buttons.
|
||||
|
||||
* The first button is a quick links button that will show you a dropdown menu of all the
|
||||
:term:`root folders<root folder>` in your project. Selecting one will move to that position in
|
||||
the tree. You can also activate this menu by pressing :kbd:`Ctrl+L`.
|
||||
* The next two buttons can be used to move items up and down in the project tree. This is the only
|
||||
way to move root folders.
|
||||
* The next button opens a dropdown menu for adding new items to the tree. This includes root
|
||||
folders and template documents. 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.
|
||||
|
||||
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.
|
||||
|
||||
.. tip::
|
||||
|
||||
If you want to set the label of a document to be the same as a header within it, you can
|
||||
right-click a header in the document when it is open in the editor and select
|
||||
:guilabel:`Set as Document Name` from the context menu.
|
||||
|
||||
|
||||
.. _a_ui_tree_split_merge:
|
||||
|
||||
Splitting and Merging Documents
|
||||
-------------------------------
|
||||
|
||||
Under the **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 **Split Document** dialog.
|
||||
|
||||
The **Split Document by Headings** option will open a dialog that allows you to split the selected
|
||||
document into multiple new documents based on the headings it contains. You can select at which
|
||||
heading level the split is to be performed from the dropdown box. The list box will preview which
|
||||
headings will be split into new documents.
|
||||
|
||||
You are given the option to create a folder for these new documents, and whether or not to create a
|
||||
hierarchy of documents. That is, put sections under scenes, and scenes under chapters.
|
||||
|
||||
The source document **is not** deleted in the process, but you have the option to let the tool move
|
||||
the source document to the :guilabel:`Trash` folder.
|
||||
|
||||
|
||||
Merging Documents
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. figure:: images/fig_project_merge_tool.png
|
||||
|
||||
The **Merge Documents** dialog.
|
||||
|
||||
You have two options for merging documents that are child elements of another document. You can
|
||||
either **Merge Child Items into Self** and **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 **Merge Documents in Folder** is available.
|
||||
|
||||
In either case, the **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
|
||||
------------------------------
|
||||
|
||||
Each document or folder in your project can have either a "Status" or "Importance" flag set. These
|
||||
are flags that you control and define yourself, and novelWriter doesn't use them for anything. To
|
||||
modify the labels, go to their respective tabs in **Project Settings**.
|
||||
|
||||
The "Status" flag is intended to tag a :term:`novel document<novel documents>` as for instance a
|
||||
draft or as completed, and the "Importance" flag is intended to tag character notes, or other
|
||||
:term:`project notes`, as for instance a main, major, or minor character or story element.
|
||||
|
||||
Whether a document uses a "Status" or "Importance" flag depends on which :term:`root folder` it
|
||||
lives in. If it's in a **Novel** type folder, it uses the "Status" flag, otherwise it uses an
|
||||
"Importance" flag.
|
||||
|
||||
|
||||
.. _a_ui_tree_dnd:
|
||||
|
||||
Project Tree Drag & Drop
|
||||
------------------------
|
||||
|
||||
The project tree allows drag & drop to allow you to reorder your documents and folders. Moving a
|
||||
document in the project tree will affect the text's position when you assemble your manuscript in
|
||||
the **Manuscript Build** tool.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
|
||||
You can now select multiple items in the project tree by holding down the :kbd:`Ctrl` or
|
||||
:kbd:`Shift` key while selecting items.
|
||||
|
||||
Documents and their folders can be rearranged freely within their root folders. If you move a
|
||||
**Novel Document** out of a **Novel** folder, it will be converted to a **Project Note**. Notes can
|
||||
be moved freely between all root folders, but keep in mind that if you move a note into a **Novel**
|
||||
type root folder, its "Importance" setting will be replaced by a "Status" setting. See
|
||||
:ref:`a_ui_tree_status`. The old value will not be overwritten though, and should be restored if
|
||||
you move it back at some point.
|
||||
|
||||
Root folders in the project tree cannot be dragged and dropped at all. If you want to reorder them,
|
||||
you can move them up or down with respect to each other from the arrow buttons at the top of the
|
||||
project tree, or by pressing :kbd:`Ctrl+Up` or :kbd:`Ctrl+Down` when they are selected.
|
||||
|
||||
.. tip::
|
||||
|
||||
You can drag and drop documents onto the editor or viewer panel to open them.
|
||||
|
||||
|
||||
.. _a_ui_tree_novel:
|
||||
|
||||
The Novel Tree View
|
||||
===================
|
||||
|
||||
.. figure:: images/fig_novel_tree_view.png
|
||||
|
||||
A screenshot of the Novel Tree View.
|
||||
|
||||
An alternative way to view the project structure is the novel view. You can switch to this view by
|
||||
selecting the :guilabel:`Novel View` button in the sidebar. This view is a simplified version of
|
||||
the view in the **Outline View**. It is convenient when you want to browse the structure of the
|
||||
story itself rather than the document files.
|
||||
|
||||
.. note::
|
||||
|
||||
You cannot reorganise the entries in the novel view, or add any new documents, as that would
|
||||
imply restructuring the content of the document files themselves. Any such editing must be done
|
||||
in the project tree. However, you can add new headings to existing documents, or change
|
||||
references, which will be updated in this view when the document is saved.
|
||||
|
||||
|
||||
.. _a_ui_outline:
|
||||
|
||||
The Novel Outline View
|
||||
======================
|
||||
|
||||
.. figure:: images/fig_outline_view.png
|
||||
|
||||
A screenshot of the Novel Outline View.
|
||||
|
||||
The project's **Novel Outline View** is available as another view option from the sidebar. The
|
||||
outline provides an overview of the novel structure, displaying a tree hierarchy of the elements of
|
||||
the novel, that is, the level 1 to 4 headings representing partitions, chapters, scenes and
|
||||
sections.
|
||||
|
||||
The document containing the heading can also be displayed as a separate column, as well as the line
|
||||
number where the heading is defined. Double-clicking an entry will open the corresponding document
|
||||
in the editor and switch to **Project Tree View** mode.
|
||||
|
||||
You can select which novel folder to display from the dropdown menu. You can optionally also choose
|
||||
to show a combination of all novel folders.
|
||||
|
||||
.. note::
|
||||
|
||||
Since the internal structure of the novel does not depend directly on the folder and document
|
||||
structure of the project tree, this view will not necessarily look the same, depending on how
|
||||
you choose to organise your documents. See the :ref:`a_struct` page for more details.
|
||||
|
||||
Various meta data and information extracted from :term:`tags<tag>` can be displayed in columns in
|
||||
the outline. A default set of such columns is visible, but you can turn on or off more columns from
|
||||
the menu button in the toolbar. The order of the columns can also be rearranged by dragging them to
|
||||
a different position. You column settings are saved between sessions on a per-project basis.
|
||||
|
||||
.. note::
|
||||
|
||||
The **Title** column cannot be disabled or moved.
|
||||
|
||||
The information viewed in the outline is based on the :term:`project index`. While novelWriter does
|
||||
its best to keep the index up to date when contents change, you can always rebuild it manually by
|
||||
pressing :kbd:`F9` if something isn't right.
|
||||
|
||||
The outline view itself can be regenerated by pressing the refresh button. By default, the content
|
||||
is refreshed each time you switch to this view.
|
||||
|
||||
The **Synopsis** column of the outline view takes its information from a specially formatted
|
||||
comment. See :ref:`a_fmt_comm`.
|
||||
@@ -1,4 +1,4 @@
|
||||
.. _a_ui_writing:
|
||||
.. _docs_ui_edit_view:
|
||||
|
||||
*********************
|
||||
The Editor and Viewer
|
||||
@@ -9,7 +9,7 @@ The Editor and Viewer
|
||||
This chapter covers in more detail how the document editor and viewer panels work.
|
||||
|
||||
|
||||
.. _a_ui_edit:
|
||||
.. _docs_ui_edit_view_edit:
|
||||
|
||||
Editing a Document
|
||||
==================
|
||||
@@ -20,8 +20,7 @@ Editing a Document
|
||||
|
||||
To edit a document, double-click it in the project tree, press the :kbd:`Return` key while having
|
||||
it selected, or drag and drop it onto the editor panel. This will open the document in the document
|
||||
editor. The editor uses a Markdown-like syntax for some features, and a novelWriter-specific syntax
|
||||
for others. The syntax format is described in the :ref:`a_fmt` chapter.
|
||||
editor.
|
||||
|
||||
The editor has a maximise button, which toggles the **Focus Mode**, and a close button in the
|
||||
top--right corner. On the top--left side you will find a tools button that opens a toolbar with a
|
||||
@@ -37,86 +36,56 @@ be shown. This can be set in **Preferences**.
|
||||
Clicking on the document title bar will select the document in the project tree and thus reveal
|
||||
its location there, making it easier to find in a large project.
|
||||
|
||||
Any :term:`references<reference>` in the editor can be opened in the viewer by moving the cursor to
|
||||
the label and pressing :kbd:`Ctrl+Return`. You can also control-click them with your mouse.
|
||||
Any references in the editor can be opened in the viewer by moving the cursor to the label and
|
||||
pressing :kbd:`Ctrl+Return`. You can also control-click them with your mouse.
|
||||
|
||||
|
||||
Spell Checking
|
||||
--------------
|
||||
|
||||
A third party library called Enchant is used for spell checking in the editor. The controls for
|
||||
spell checking can be found in the **Tools** menu. You can also set spell checking language in
|
||||
spell checking are found in the **Tools** menu. You can also set spell checking language in
|
||||
**Project Settings**.
|
||||
|
||||
This spell checking library comes with support for custom words that you can add by selecting
|
||||
"Add Word to Dictionary" from the context menu when a word is highlighted by the spell checker as
|
||||
misspelled. The custom words are managed on a per-project basis, and can the list of words can be
|
||||
misspelled. The custom words are managed on a per-project basis, and the list of words can be
|
||||
edited from the **Project Word List** tool available from the **Tools** menu.
|
||||
|
||||
.. note::
|
||||
|
||||
Generally, spell checking dictionaries are collected from your operating system, but on Windows
|
||||
they are not. See :ref:`a_custom_dict` for how to add spell checking dictionaries on Windows.
|
||||
they are not. See :ref:`docs_more_custom_dict` for how to add spell checking dictionaries on
|
||||
Windows.
|
||||
|
||||
|
||||
Editor Auto-Completer
|
||||
---------------------
|
||||
Word Counts
|
||||
-----------
|
||||
|
||||
If you type the character ``@`` on a new line, a pop-up menu will appear showing the different
|
||||
available keywords. The list will shorten as you type. Once a keyword command has been selected or
|
||||
typed, the editor may suggest further options based on your project content. See
|
||||
:ref:`a_references_completer` for more details.
|
||||
A character, word, and paragraph count is maintained for each document, as well as for each section
|
||||
of a document following a heading. 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 trees.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
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 project index. If the counts
|
||||
seem wrong, a full project word recount can be initiated by rebuilding the project's index. 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:`docs_more_counting`.
|
||||
|
||||
.. tip::
|
||||
|
||||
For some languages, character count is the more interesting statistics. You can select to
|
||||
display character count instead of word count in the user interface in **Preferences**.
|
||||
|
||||
.. versionadded:: 2.7
|
||||
|
||||
|
||||
.. _a_ui_view:
|
||||
|
||||
Viewing a Document
|
||||
==================
|
||||
|
||||
.. figure:: images/fig_viewer.png
|
||||
|
||||
A screenshot of the Document Viewer panel.
|
||||
|
||||
Any document in the project tree can also be viewed in parallel in a right hand side document
|
||||
viewer. To view a document, press :kbd:`Ctrl+R`, select **View Document** in the menu or context
|
||||
menu, or drag and drop the document onto the viewer panel. If you have a middle mouse button,
|
||||
middle-clicking on the document will also open it in the viewer.
|
||||
|
||||
The document viewed does not have to be the same document as the one currently being edited.
|
||||
However, If you *are* viewing the same document, pressing :kbd:`Ctrl+R` from the editor will update
|
||||
the document with your latest changes. You can also press the reload button in the top--right
|
||||
corner of the viewer panel, next to the close button, to achieve the same thing.
|
||||
|
||||
In the viewer :term:`references<reference>` become clickable links. Clicking them will replace the
|
||||
content of the viewer with the content of the document the reference points to.
|
||||
|
||||
The document viewer keeps a history of viewed documents, which you can navigate with the arrow
|
||||
buttons in the top--left corner of the viewer. If your mouse has backward and forward navigation
|
||||
buttons, these can be used as well. They work just like the backward and forward features in a
|
||||
browser. The left-most button is a dropdown menu for quickly navigation between headings in the
|
||||
document. The edit button on the right will open the viewed document in the editor.
|
||||
|
||||
At the bottom of the view panel there is a **References** panel. (If it is hidden, click the button
|
||||
on the left side of the footer area to reveal it.) This panel contains a References tab with links
|
||||
to all documents referring back to the one you're currently viewing, if any has been defined. If
|
||||
you have created root folders and tags for various story elements like characters and plot points,
|
||||
these will appear as additional tabs in this panel.
|
||||
|
||||
.. note::
|
||||
|
||||
The **References** panel relies on an up-to-date :term:`index<project index>` of the project.
|
||||
The index is maintained automatically. However, if anything is missing, or seems wrong, the
|
||||
index can always be rebuilt by selecting **Rebuild Index** from the **Tools** menu, or by
|
||||
pressing :kbd:`F9`.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
|
||||
The reference panel was redesigned and the additional tabs added.
|
||||
|
||||
|
||||
.. _a_ui_edit_search:
|
||||
.. _docs_ui_edit_view_search:
|
||||
|
||||
Search & Replace
|
||||
================
|
||||
@@ -139,14 +108,8 @@ document when reaching the end. There is also a switch that will try to match th
|
||||
when the replacement is made. That is, it will try to keep the word upper, lower, or capitalised to
|
||||
match the word being replaced.
|
||||
|
||||
.. seealso::
|
||||
|
||||
For more information on the capabilities of the Regular Expression option, see the Qt
|
||||
documentation for the `QRegularExpression <https://doc.qt.io/qt-6/qregularexpression.html>`_
|
||||
class.
|
||||
|
||||
|
||||
.. _a_ui_edit_auto:
|
||||
.. _docs_ui_edit_view_auto:
|
||||
|
||||
Auto-Replace as You Type
|
||||
========================
|
||||
@@ -157,32 +120,69 @@ auto-replace feature from **Preferences**. You can also disable this feature ent
|
||||
.. tip::
|
||||
|
||||
If you don't like auto-replacement, all symbols inserted by this feature are also available in
|
||||
the :guilabel:`Insert` menu, and via :ref:`a_kb_ins`. You may also be using a `Compose Key`_
|
||||
setup, which means you may not need the auto-replace feature at all.
|
||||
the :guilabel:`Insert` menu, and via :ref:`docs_features_shortcuts_insert`. You may also be
|
||||
using a `Compose Key`_ setup, which means you may not need the auto-replace feature at all.
|
||||
|
||||
The editor is able to replace two and three hyphens with short and long dashes, triple points with
|
||||
ellipsis, and replace straight single and double quotes with user-defined quote symbols. It will
|
||||
also try to determine whether to use the opening or closing symbol, although this feature isn't
|
||||
always accurate. Especially distinguishing between closing single quote and apostrophe can be
|
||||
tricky for languages that use the same symbol for these, like English does.
|
||||
The editor is able to replace two and three hyphens with short and long dashes, four dashes with a
|
||||
horizontal bar, three dots with ellipsis, and replace straight single and double quotes with
|
||||
user-defined quote symbols. It will also try to determine whether to use the opening or closing
|
||||
symbol, although this feature isn't always accurate. Especially distinguishing between closing
|
||||
single quote and apostrophe can be tricky for languages that use the same symbol for these, like
|
||||
English does.
|
||||
|
||||
.. tip::
|
||||
|
||||
If the auto-replace feature changes a symbol when you did not want it to change, pressing
|
||||
:kbd:`Ctrl+Z` once after the auto-replacement will undo it without undoing the character
|
||||
you typed before it.
|
||||
you typed.
|
||||
|
||||
|
||||
.. _a_ui_edit_dialogue:
|
||||
.. _docs_ui_edit_view_view:
|
||||
|
||||
Dialogue Highlighting
|
||||
=====================
|
||||
Viewing a Document
|
||||
==================
|
||||
|
||||
The editor and viewer can optionally highlight character dialogue in your novel documents. By
|
||||
default, this feature is set to display text in double quotes as dialogue. In **Preferences**, you
|
||||
can change this to support various other dialogue markers that instead uses dashes to indicate
|
||||
dialogue, like those used in Spanish, Portuguese, Polish, etc.
|
||||
.. figure:: images/fig_viewer.png
|
||||
|
||||
Various styles are supported by changing the settings under "Text Highlighting" in **Preferences**.
|
||||
A screenshot of the Document Viewer panel.
|
||||
|
||||
It is also possible to include the dialogue highlighting in your manuscripts.
|
||||
Any document in the project tree can also be viewed in parallel in a right hand side document
|
||||
viewer. To view a document, press :kbd:`Ctrl+R`, select **View Document** in the menu or context
|
||||
menu, or drag and drop the document onto the viewer panel. If you have a middle mouse button,
|
||||
middle-clicking on the document will also open it in the viewer.
|
||||
|
||||
The document viewed does not have to be the same document as the one currently being edited.
|
||||
However, If you *are* viewing the same document, pressing :kbd:`Ctrl+R` from the editor will update
|
||||
the document with your latest changes. You can also press the reload button in the top--right
|
||||
corner of the viewer panel, next to the close button, to achieve the same thing.
|
||||
|
||||
In the viewer, references become clickable links. Clicking them will replace the content of the
|
||||
viewer with the content of the document the reference points to.
|
||||
|
||||
The document viewer keeps a history of viewed documents, which you can navigate with the arrow
|
||||
buttons in the top--left corner of the viewer. If your mouse has backward and forward navigation
|
||||
buttons, these can be used as well. They work just like the backward and forward features in a
|
||||
browser. The left-most button is a dropdown menu for quickly navigation between headings in the
|
||||
document. The edit button on the right will open the viewed document in the editor.
|
||||
|
||||
|
||||
.. _docs_ui_edit_view_view_references:
|
||||
|
||||
Document References
|
||||
-------------------
|
||||
|
||||
At the bottom of the viewer panel you will find a **References** panel. (If it is hidden, click the
|
||||
button on the left side of the footer area to reveal it.) This panel contains a References tab with
|
||||
links to all documents referring back to the one you're currently viewing, if any has been defined.
|
||||
If you have created root folders and tags for various story elements like characters and plot
|
||||
points, these will appear as additional tabs in this panel.
|
||||
|
||||
.. note::
|
||||
|
||||
The **References** panel relies on an up-to-date project index. The index is maintained
|
||||
automatically. However, if anything is missing, or seems wrong, the index can always be rebuilt
|
||||
by selecting **Rebuild Index** from the **Tools** menu, or by pressing :kbd:`F9`.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
|
||||
The reference panel was redesigned and the additional tabs added.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 74 KiB |
|
Before Width: | Height: | Size: 90 KiB After Width: | Height: | Size: 90 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 96 KiB |
|
Before Width: | Height: | Size: 152 KiB After Width: | Height: | Size: 152 KiB |
|
Before Width: | Height: | Size: 7.1 KiB After Width: | Height: | Size: 7.1 KiB |
|
Before Width: | Height: | Size: 94 KiB After Width: | Height: | Size: 94 KiB |
|
Before Width: | Height: | Size: 121 KiB After Width: | Height: | Size: 121 KiB |
|
Before Width: | Height: | Size: 243 KiB After Width: | Height: | Size: 243 KiB |
|
Before Width: | Height: | Size: 135 KiB After Width: | Height: | Size: 135 KiB |
|
Before Width: | Height: | Size: 25 KiB After Width: | Height: | Size: 25 KiB |
|
Before Width: | Height: | Size: 35 KiB After Width: | Height: | Size: 35 KiB |
|
Before Width: | Height: | Size: 280 KiB After Width: | Height: | Size: 280 KiB |
|
Before Width: | Height: | Size: 123 KiB After Width: | Height: | Size: 123 KiB |
|
Before Width: | Height: | Size: 150 KiB After Width: | Height: | Size: 150 KiB |
@@ -0,0 +1,202 @@
|
||||
.. _docs_ui_main:
|
||||
|
||||
***************
|
||||
The Main Window
|
||||
***************
|
||||
|
||||
The user interface of novelWriter is intended to be as minimalistic as practically possible, while
|
||||
at the same time provide useful features needed for writing a novel.
|
||||
|
||||
The main window does not by default have an editor toolbar like many other applications do. This
|
||||
reduces clutter, and since the documents are formatted with style tags, it is not needed most of
|
||||
the time. Still, a small formatting toolbar can be popped out by clicking the left-most button in
|
||||
the header of the document editor. It gives quick access to standard formatting codes.
|
||||
|
||||
Most formatting features supported are also available through keyboard shortcuts, as well as
|
||||
available in the main menu under **Format**, so you don't have to look up formatting codes every
|
||||
time you need them. For reference, a list of all shortcuts can be found in the
|
||||
:ref:`docs_features_shortcuts` section.
|
||||
|
||||
On the left side of the main window you will find a sidebar. This bar has buttons for the standard
|
||||
views you can switch between, a quick link to the **Build Manuscript** tool, and a set of
|
||||
project-related tools and quick access to settings at the bottom.
|
||||
|
||||
|
||||
Project Tree and Editor View
|
||||
============================
|
||||
|
||||
.. figure:: images/fig_project_tree_view.png
|
||||
|
||||
A screenshot of the Project Tree and Editor View.
|
||||
|
||||
When **Project Tree View** in the sidebar is selected, the work area is split in two, or
|
||||
optionally three, panels. The left-most panel contains the project tree and all the documents in
|
||||
your project. The second panel is the document editor.
|
||||
|
||||
An optional third panel on the right side contains a document viewer which can view any document in
|
||||
your project independently of what is open in the document editor. This panel is not intended as a
|
||||
preview window, although you can use it for this purpose if you wish. For instance if you need to
|
||||
check that the formatting tags behave as you expect. However, the main purpose of the viewer is for
|
||||
viewing your notes next to your editor while you're writing.
|
||||
|
||||
The editor also has a **Focus Mode** you can toggle either from the menu, from the icon in the
|
||||
editor's header, or by pressing :kbd:`F8`. When **Focus Mode** is enabled, all the user interface
|
||||
elements other than the document editor itself are hidden away.
|
||||
|
||||
The project tree will highlight with a different background colour the document that is currently
|
||||
open in the editor.
|
||||
|
||||
|
||||
Drag & Drop
|
||||
-----------
|
||||
|
||||
The project tree allows drag & drop so you to reorder your documents and folders. Moving a document
|
||||
in the project tree will affect the text's position when you assemble your manuscript in the
|
||||
**Manuscript Build** tool.
|
||||
|
||||
Documents and their folders can be rearranged freely within their root folders. If you move a
|
||||
**Novel Document** out of a **Novel** folder, it will be converted to a **Project Note**. Notes can
|
||||
be moved freely between all root folders, but keep in mind that if you move a note into a **Novel**
|
||||
type root folder, its "Importance" setting will be replaced by a "Status" setting. See
|
||||
:ref:`docs_usage_project_status` for more details. The old value will not be overwritten though,
|
||||
and should be restored if you move it back at some point.
|
||||
|
||||
Root folders in the project tree cannot be dragged and dropped at all. If you want to reorder them,
|
||||
you can move them up or down with respect to each other using the arrow buttons at the top of the
|
||||
project tree, or by pressing :kbd:`Ctrl+Up` or :kbd:`Ctrl+Down` when they are selected.
|
||||
|
||||
.. tip::
|
||||
|
||||
You can drag and drop documents onto the editor or viewer panel to open them.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
.. tip::
|
||||
|
||||
You can now select multiple items in the project tree by holding down the :kbd:`Ctrl` or
|
||||
:kbd:`Shift` key while selecting items.
|
||||
|
||||
.. versionadded:: 2.2
|
||||
|
||||
|
||||
.. _docs_ui_main_novel:
|
||||
|
||||
Novel View and Editor View
|
||||
==========================
|
||||
|
||||
.. figure:: images/fig_novel_tree_view.png
|
||||
|
||||
A screenshot of the Novel Tree and Editor View.
|
||||
|
||||
When **Novel Tree View** in the sidebar is selected, the project tree is replaced by an overview of
|
||||
your novel structure for a specific **Novel** type root folder. Instead of showing individual
|
||||
documents, the tree now shows all headings of your text. This includes multiple headings within the
|
||||
same document.
|
||||
|
||||
Each heading is indented according to the heading level, not its parent/child relationship to other
|
||||
elements of your project. You can open and edit your novel documents from this view as well. All
|
||||
headings contained in the currently open document should be highlighted in the view to indicate
|
||||
which ones belong together in the same document.
|
||||
|
||||
If you have multiple **Novel** type root folders, the header of the novel view becomes a dropdown
|
||||
box. You can then switch between them by clicking the :guilabel:`Outline of ...` text. You can also
|
||||
click the novel icon button next to it.
|
||||
|
||||
Generally, the novel view should update when you make changes to the novel structure, including
|
||||
edits of the current document in the editor. The information is only updated when the automatic
|
||||
save of the document is triggered, or you manually press :kbd:`Ctrl+S` to save changes. (You can
|
||||
adjust the auto-save interval in **Preferences**.) You can also regenerate the whole novel view by
|
||||
pressing the refresh button in the novel view header.
|
||||
|
||||
It is possible to show an optional third column in the novel view. The settings are available from
|
||||
the menu button in the toolbar.
|
||||
|
||||
If you click the triangular icon to the right of each item, a tooltip will pop out showing all the
|
||||
meta data collected for that heading.
|
||||
|
||||
.. note::
|
||||
|
||||
You cannot reorganise the entries in the novel view, or add any new documents, as that would
|
||||
imply restructuring the content of the documents themselves. Any such editing must be done in
|
||||
the project tree. However, you can add new headings to existing documents, or change references,
|
||||
which will be updated in this view when the document is saved.
|
||||
|
||||
|
||||
.. _docs_ui_main_outline:
|
||||
|
||||
Novel Outline View
|
||||
==================
|
||||
|
||||
.. figure:: images/fig_outline_view.png
|
||||
|
||||
A screenshot of the Novel Outline View.
|
||||
|
||||
When **Novel Outline View** in the sidebar is selected, the tree, editor and viewer are replaced by
|
||||
a table that shows the entire novel structure with all the tags and references listed. You can
|
||||
select which novel folder to display from the dropdown menu. You can optionally choose to show a
|
||||
combination of all novel folders.
|
||||
|
||||
Pretty much all collected meta data is available in this view. You can select which columns to
|
||||
display from the menu button. This includes various meta data and information extracted from your
|
||||
:ref:`docs_usage_tags_refs`. The order of the columns can also be changed by dragging them to a
|
||||
different position. You column settings are saved between sessions on a per-project basis.
|
||||
|
||||
.. note::
|
||||
|
||||
The **Title** column cannot be disabled or moved.
|
||||
|
||||
The information viewed in the outline is based on the project index. While novelWriter does its
|
||||
best to keep the index up to date when contents change, you can always rebuild it manually by
|
||||
pressing :kbd:`F9` if something isn't right.
|
||||
|
||||
The outline view itself can be regenerated by pressing the refresh button. By default, the content
|
||||
is refreshed each time you switch to this view.
|
||||
|
||||
The **Synopsis** column of the outline view takes its information from a specially formatted
|
||||
comment. See :ref:`docs_usage_comments_synopsis`.
|
||||
|
||||
|
||||
Project Search
|
||||
==============
|
||||
|
||||
A global search tool is available from the side bar. It allows you to search through your entire
|
||||
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. See :ref:`docs_ui_edit_view_search` for more
|
||||
details.
|
||||
|
||||
.. versionadded:: 2.4
|
||||
|
||||
|
||||
Switching Focus
|
||||
===============
|
||||
|
||||
If the project or novel view does not have focus, pressing :kbd:`Ctrl+T` switches focus to
|
||||
whichever of the two is visible. If one of them already has focus, the key press will switch
|
||||
between them instead.
|
||||
|
||||
Likewise, pressing :kbd:`Ctrl+E` will switch focus to the document editor or viewer, or if any of
|
||||
them already have focus, it will switch focus between them.
|
||||
|
||||
These two shortcuts make it possible to jump between all these GUI elements without having to reach
|
||||
for the mouse or touchpad.
|
||||
|
||||
See :ref:`docs_features_shortcuts` for more details.
|
||||
|
||||
|
||||
Colour Themes
|
||||
=============
|
||||
|
||||
By default, novelWriter uses a light colour theme. You can also choose between a standard dark
|
||||
theme that have neutral colours, or a series of other included themes, from **Preferences**.
|
||||
|
||||
If you wish, you *can* create your own colour themes, and even have them added to the application.
|
||||
See :ref:`docs_more_custom_theme` for more details.
|
||||
|
||||
Switching the GUI colour theme does not affect the colours of the editor and viewer. They have
|
||||
separate themes selectable from the "Document colour theme" setting in **Preferences**. They are
|
||||
separated because there are a lot more options to choose from for the editor and viewer.
|
||||
|
||||
.. note::
|
||||
|
||||
If you switch between light and dark mode on the GUI, you should also switch editor theme to
|
||||
match, otherwise icons may be hard to see in the editor and viewer.
|
||||
@@ -1,4 +1,4 @@
|
||||
.. _a_manuscript:
|
||||
.. _docs_ui_manuscript:
|
||||
|
||||
***********************
|
||||
Building the Manuscript
|
||||
@@ -10,14 +10,17 @@ You can at any time build a manuscript, an outline of your notes, or any other t
|
||||
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`.
|
||||
|
||||
.. note::
|
||||
|
||||
The term "Build" in this context means to assemble or generate a single document from a
|
||||
selection of your project documents. You can select between multiple standard document formats.
|
||||
|
||||
.. 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 the build, but otherwise had much the same
|
||||
functionality.
|
||||
This tool is new for version 2.1. A simpler tool was used for earlier versions.
|
||||
|
||||
|
||||
.. _a_manuscript_main:
|
||||
.. _docs_ui_manuscript_main:
|
||||
|
||||
The Manuscript Build Tool
|
||||
=========================
|
||||
@@ -43,29 +46,31 @@ Outline and Word Counts
|
||||
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*.
|
||||
A collapsible panel of word and character counts is also available below the preview pane. 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`.
|
||||
For a detailed description on how they are counted, see :ref:`docs_more_counting`.
|
||||
|
||||
|
||||
.. _a_manuscript_settings:
|
||||
.. _docs_ui_manuscript_settings:
|
||||
|
||||
Build Settings
|
||||
==============
|
||||
|
||||
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.
|
||||
You can edit a build definition 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 **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.
|
||||
and just hit the :guilabel:`Apply` button. You can test the result of your settings change by
|
||||
pressing the :guilabel:`Preview` button in the main **Manuscript Build** window. When you're
|
||||
happy with the result, you can close the settings.
|
||||
|
||||
|
||||
.. _docs_ui_manuscript_selection:
|
||||
|
||||
Document Selection
|
||||
------------------
|
||||
|
||||
@@ -75,19 +80,22 @@ Document Selection
|
||||
The **Selections** page of the **Manuscript Build Settings** dialog.
|
||||
|
||||
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.
|
||||
documents are included in the build. The included documents are indicated by an 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.
|
||||
In the figure, the orange icon and the blue icon indicates which documents are included, and the
|
||||
red icon indicates that a document is explicitly excluded.
|
||||
|
||||
By default, inactive documents are excluded, but you can override this in the filter settings.
|
||||
See :ref:`docs_usage_project_active` for more details.
|
||||
|
||||
|
||||
.. _a_manuscript_settings_head:
|
||||
.. _docs_ui_manuscript_head:
|
||||
|
||||
Formatting Headings
|
||||
-------------------
|
||||
@@ -98,7 +106,7 @@ Formatting Headings
|
||||
The **Headings** page of the **Manuscript Build Settings** dialog.
|
||||
|
||||
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,
|
||||
headings in your 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.
|
||||
|
||||
@@ -110,24 +118,68 @@ 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.
|
||||
|
||||
.. csv-table:: Heading Formats
|
||||
:header: "Code", "Description"
|
||||
:class: "tight-table"
|
||||
|
||||
"``{BR}``", "Insert a line break."
|
||||
"``{Title}``", "Insert the original title text."
|
||||
"``{Chapter}``", "Insert a chapter number."
|
||||
"``{Chapter:Word}``", "Insert a chapter number as a word."
|
||||
"``{Chapter:URoman}``", "Insert a chapter number as an upper case Roman numeral."
|
||||
"``{Chapter:LRoman}``", "Insert a chapter number as an lower case Roman numeral."
|
||||
"``{Scene}``", "Insert a scene number within the current chapter."
|
||||
"``{Scene:Abs}``", "Insert a scene number unique to the whole manuscript."
|
||||
"``{Char:POV}``", "Insert the point-of-view character's :ref:`display name <docs_usage_tags_refs_tags>`."
|
||||
"``{Char:Focus}``", "Insert the focus character's :ref:`display name <docs_usage_tags_refs_tags>`."
|
||||
|
||||
You can preview the result of these format strings by clicking :guilabel:`Apply`, and then clicking
|
||||
:guilabel:`Preview` in the **Manuscript Build** tool main window.
|
||||
|
||||
|
||||
.. _docs_ui_manuscript_head_numbers:
|
||||
|
||||
Automatic Numbering
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The headings formatter allows you to automatically insert chapter and scene numbers into your
|
||||
headings. The automatic chapter number counter will skip all chapter headings marked as unnumbered
|
||||
using the heading format described in :ref:`docs_usage_headings_levels`.
|
||||
|
||||
Scene numbers are mostly intended for use in a draft manuscript. You can either insert absolute
|
||||
scene numbers that counts every scene in the novel, or you can insert per-chapter scene numbers
|
||||
that reset to 1 for each new chapter.
|
||||
|
||||
:bdg-info:`Example`
|
||||
|
||||
This will create a chapter title on the format "Chapter 1: Title Text":
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
Chapter {Chapter}: {Title}
|
||||
|
||||
This will create a scene title on the format "Scene 1.1: Title Text":
|
||||
|
||||
.. code-block:: md
|
||||
|
||||
Scene {Chapter}.{Scene}: {Title}
|
||||
|
||||
|
||||
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 inserted.
|
||||
sections instead, resulting in a gap in the text. You can also enable the :guilabel:`Hide` setting,
|
||||
which will ignore them completely. That is, there won't even be an extra gap inserted.
|
||||
|
||||
Alternatively, if you want a separator text between them, like the common ``* * *``, you can enter
|
||||
the desired separator text as the format. If the format is any piece of static text, it will always
|
||||
be treated as a separator.
|
||||
be treated as a separator. A static separator is only inserted between scenes, as opposed to a
|
||||
formatted heading which is also inserted before the first scene of a chapter.
|
||||
|
||||
|
||||
.. _a_manuscript_settings_head_hard:
|
||||
.. _docs_ui_manuscript_head_hard_soft:
|
||||
|
||||
Hard and Soft Scenes
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -136,18 +188,20 @@ If you wish to distinguish between so-called soft and hard scene breaks, you can
|
||||
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.
|
||||
See :ref:`docs_usage_headings_levels` for more info on how to format alternative scene headings in
|
||||
your text.
|
||||
|
||||
|
||||
Output Settings
|
||||
---------------
|
||||
|
||||
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.
|
||||
The **Formatting** sections of the **Manuscript Build Settings** dialog control a number of other
|
||||
settings for the output. This includes formatting, but also what content is included. You can for
|
||||
instance select to include comments, synopsis. tags and reference, and even exclude the body text
|
||||
itself.
|
||||
|
||||
|
||||
.. _a_manuscript_build:
|
||||
.. _docs_ui_manuscript_build:
|
||||
|
||||
Building Manuscript Documents
|
||||
=============================
|
||||
@@ -172,14 +226,14 @@ show the build progress, but for small projects it may pass very fast.
|
||||
File Formats
|
||||
------------
|
||||
|
||||
Currently, four document formats are supported.
|
||||
The following document formats are supported:
|
||||
|
||||
Open Document Format
|
||||
Open Document
|
||||
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 only a few the latter.
|
||||
|
||||
Microsoft Word Document Format
|
||||
Microsoft Word Document
|
||||
The Microsoft Word Document format writes a single ``.docx`` file. It uses a fairly basic format
|
||||
that should be compatible with most rich text editors.
|
||||
|
||||
@@ -213,8 +267,7 @@ Additional Formats
|
||||
------------------
|
||||
|
||||
In addition to the above document formats, the novelWriter HTML and Markup formats can also be
|
||||
wrapped in a JSON file. These files will have a meta data entry and a body entry. For HTML, also
|
||||
the accompanying CSS styles used by the preview are included.
|
||||
wrapped in a JSON file. These files will have a meta data entry and a body entry.
|
||||
|
||||
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
|
||||
@@ -224,7 +277,7 @@ These files are mainly intended for scripted post-processing for those who want
|
||||
file can be imported directly into a Python dict object or a PHP array, to mentions a few options.
|
||||
|
||||
|
||||
.. _a_manuscript_print:
|
||||
.. _docs_ui_manuscript_print:
|
||||
|
||||
Printing
|
||||
========
|
||||
@@ -235,5 +288,5 @@ 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 **Print Preview** dialog.
|
||||
The paper format should default to whatever your system default is. If you want to change it,
|
||||
you have to select it from the **Print Preview** dialog.
|
||||
@@ -0,0 +1,146 @@
|
||||
.. _docs_ui_projects:
|
||||
|
||||
*****************
|
||||
Managing Projects
|
||||
*****************
|
||||
|
||||
Your text in novelWriter is organised into projects. Each project is meant to contain one novel
|
||||
and associated notes. If you have multiple novels in a series, with the same characters and shared
|
||||
notes, it is also possible to keep all of them in the same project by creating multiple **Novel**
|
||||
root folders. See :ref:`docs_usage_project_roots` for more details.
|
||||
|
||||
|
||||
.. _docs_ui_projects_new:
|
||||
|
||||
Creating A New Project
|
||||
======================
|
||||
|
||||
You can create a new project 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 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 of how projects are stored, you can have a look at the section
|
||||
:ref:`docs_technical_storage`.
|
||||
|
||||
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 **Welcome** dialog.
|
||||
|
||||
Project-specific settings are available in **Project Settings** in the **Project** menu. See
|
||||
further details below in the :ref:`docs_ui_projects_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.
|
||||
|
||||
|
||||
Template Projects
|
||||
-----------------
|
||||
|
||||
From the Welcome dialog you can also create a new from another existing project. If you have a
|
||||
specific structure you want to use for all your new projects, you can create a dedicated project to
|
||||
be used as a template, and select to copy an existing project from the "Prefill Project" option
|
||||
from the **New Project** form.
|
||||
|
||||
|
||||
.. _docs_ui_projects_settings:
|
||||
|
||||
Project Settings
|
||||
================
|
||||
|
||||
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.
|
||||
|
||||
|
||||
General Settings
|
||||
----------------
|
||||
|
||||
The **Settings** tab holds the project name, author, and language settings.
|
||||
|
||||
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 **Author** 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 **Tools**
|
||||
menu.
|
||||
|
||||
You can also override the automatic backup setting for the project if you wish.
|
||||
|
||||
|
||||
.. _docs_ui_projects_settings_status:
|
||||
|
||||
Status and Importance
|
||||
---------------------
|
||||
|
||||
Each document or folder of type **Novel** can be given a "Status" label accompanied by a coloured
|
||||
icon with an optional shape selected from a list of pre-defined shapes. Each document or folder of
|
||||
the remaining types can be given an "Importance" label with the same customisation options.
|
||||
|
||||
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
|
||||
intended for, but you can make them whatever you want.
|
||||
|
||||
Both status and importance labels can be exported and imported so you can share them between
|
||||
projects, or define a standard set for all your writing projects. When you import labels to a
|
||||
project, they are always added as *new* labels.
|
||||
|
||||
See also :ref:`docs_usage_project_status`.
|
||||
|
||||
.. note::
|
||||
|
||||
Status or importance level currently in use cannot be deleted, but they can be edited.
|
||||
|
||||
|
||||
Text Auto-Replace
|
||||
-----------------
|
||||
|
||||
A set of automatically replaced keywords can be added in this tab. The keywords in the left column
|
||||
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 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.
|
||||
|
||||
.. note::
|
||||
|
||||
A keyword cannot contain spaces. The angle brackets are added by default, and when used in the
|
||||
text are a part of the keyword to be replaced. This is to ensure that parts of the text aren't
|
||||
unintentionally replaced by the content of the list.
|
||||
|
||||
|
||||
.. _docs_ui_projects_backup:
|
||||
|
||||
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 **Preferences**. The path defaults to a
|
||||
folder named "Backups" in your home directory.
|
||||
|
||||
Backups can 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 **Project Name**
|
||||
defined in :ref:`docs_ui_projects_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 **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.
|
||||
@@ -0,0 +1,48 @@
|
||||
.. _docs_ui_split_merge:
|
||||
|
||||
*************************
|
||||
Split and Merge Documents
|
||||
*************************
|
||||
|
||||
Under the **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 **Split Document** dialog.
|
||||
|
||||
The **Split Document by Headings** option will open a dialog that allows you to split the selected
|
||||
document into multiple new documents based on the headings it contains. You can select at which
|
||||
heading level the split is to be performed from the dropdown box. The list box will preview which
|
||||
headings will be split into new documents.
|
||||
|
||||
You are given the option to create a folder for these new documents, and whether or not to create a
|
||||
hierarchy of documents. That is, put sections under scenes, and scenes under chapters.
|
||||
|
||||
The source document *is not* deleted in the process, but you have the option to let the tool move
|
||||
the source document to the **Trash** folder.
|
||||
|
||||
|
||||
Merging Documents
|
||||
=================
|
||||
|
||||
.. figure:: images/fig_project_merge_tool.png
|
||||
|
||||
The **Merge Documents** dialog.
|
||||
|
||||
You have two options for merging documents that are child elements of another document. You can
|
||||
either **Merge Child Items into Self** and **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, only the latter option is possible, so only the choice
|
||||
**Merge Documents in Folder** is available.
|
||||
|
||||
In either case, the **Merge Documents** dialog will let you exclude documents you don't want to
|
||||
include, and it also lets you reorder them if you wish.
|
||||
@@ -0,0 +1,39 @@
|
||||
.. _docs_ui_statistics:
|
||||
|
||||
******************
|
||||
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. For more details
|
||||
about the log file itself, see :ref:`docs_technical_storage`.
|
||||
|
||||
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
|
||||
application like for instance Libre Office Calc or Excel.
|
||||
|
||||
|
||||
Idle Time
|
||||
=========
|
||||
|
||||
The log file 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. You can change the number of minutes in **Preferences**.
|
||||
|
||||
|
||||
Session Timer
|
||||
=============
|
||||
|
||||
A session timer is by default visible in the status bar. The icon will show you a clock icon when
|
||||
you are active, and a pause icon when you are considered "idle" per the criteria mentioned above.
|
||||
|
||||
If you do not wish to see the timer, you can click on it once to hide it. The icon will still be
|
||||
visible. Click the icon once more to display the timer again.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
|
||||
As of version 2.6, clicking the timer text or icon in the status bar will toggle its visibility.
|
||||
Reference in New Issue
Block a user