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

Move and expand text into usage section

Browse Source
This commit is contained in:
Veronica Berglyd Olsen
2025-05-24 18:09:34 +02:00
parent 8018edb183
commit 60973954ef
15 changed files with 561 additions and 225 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/_outtakes.rst
+10
View File
@@ -0,0 +1,10 @@
From Index
----------
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.
docs/source/features/breaks_and_spaces.rst
+24
View File
@@ -0,0 +1,24 @@
.. _docs_features_breaks_spaces:
**********************
Page Breaks and Spaces
**********************
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:`docs_features_shortcuts`.
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.
docs/source/features/introduction.rst
+20
View File
@@ -0,0 +1,20 @@
.. _docs_features:
************
Introduction
************
.. _docs_features_scene_breaks:
Soft and Hard Scene Breaks
==========================
.. _docs_features_active:
Active and Inactive Documents
=============================
.. _docs_features_status:
Document Status Labels
======================
docs/source/features/shortcuts.rst
+189
View File
@@ -0,0 +1,189 @@
.. _docs_features_shortcuts:
******************
Keyboard Shortcuts
******************
Most features in novelWriter are available as keyboard shortcuts. This is a reference list of those
shortcuts. Most of them are also listed in the application's user interface.
.. note::
On MacOS, replace :kbd:`Ctrl` with :kbd:`Cmd`.
Main Window Shortcuts
=====================
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`F1`", "Open the online user manual"
":kbd:`F5`", "Open the **Build Manuscript** tool"
":kbd:`F6`", "Open the **Writing Statistics** tool"
":kbd:`F8`", "Toggle **Focus Mode**"
":kbd:`F9`", "Re-build the project's index"
":kbd:`F11`", "Toggle full screen mode"
":kbd:`Ctrl+,`", "Open the **Preferences** dialog"
":kbd:`Ctrl+E`", "Switch or toggle focus for the editor or viewer"
":kbd:`Ctrl+T`", "Switch or toggle focus for the project tree or novel view"
":kbd:`Ctrl+Q`", "Exit novelWriter"
":kbd:`Ctrl+Shift+,`", "Open the **Project Settings** dialog"
":kbd:`Ctrl+Shift+O`", "Open the Welcome dialog to open or create a project"
":kbd:`Ctrl+Shift+S`", "Save the current project"
":kbd:`Ctrl+Shift+T`", "Switch focus to the outline view"
":kbd:`Ctrl+Shift+W`", "Close the current project"
":kbd:`Shift+F1`", "Open the local user manual (PDF) if it is available"
":kbd:`Shift+F6`", "Open the **Project Details** dialog"
Project Tree Shortcuts
======================
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`F2`", "Edit the label of the selected item"
":kbd:`Return`", "Open the selected document in the editor"
":kbd:`Alt+Up`", "Jump or go to the previous item at same level in the tree"
":kbd:`Alt+Down`", "Jump or go to the next item at same level in the tree"
":kbd:`Alt+Left`", "Jump to the parent item in the tree"
":kbd:`Alt+Right`", "Jump to the first child item in the project tree"
":kbd:`Ctrl+.`", "Open the context menu on the selected item"
":kbd:`Ctrl+L`", "Open the **Quick Links** menu"
":kbd:`Ctrl+N`", "Open the **Create New Item** menu"
":kbd:`Ctrl+O`", "Open the selected document in the editor"
":kbd:`Ctrl+R`", "Open the selected document in the viewer"
":kbd:`Ctrl+Up`", "Move selected item one step up in the tree"
":kbd:`Ctrl+Down`", "Move selected item one step down in the tree"
":kbd:`Ctrl+Shift+Del`", "Move the selected item to Trash"
Document Editor Shortcuts
=========================
Text Search Shortcuts
---------------------
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`F3`", "Find the next occurrence of the search word"
":kbd:`Ctrl+F`", "Open search and look for the selected word"
":kbd:`Ctrl+G`", "Find the next occurrence of the search word"
":kbd:`Ctrl+H`", "Open replace and look for the selected word (Mac :kbd:`Cmd+=`)"
":kbd:`Ctrl+Shift+1`", "Replace selected occurrence, and move to the next"
":kbd:`Ctrl+Shift+G`", "Find the previous occurrence of the search word"
":kbd:`Ctrl+Shift+F`", "Open project search and look for the selected word"
":kbd:`Shift+F3`", "Find the previous occurrence of the search word"
Text Formatting Shortcuts
-------------------------
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`Ctrl+'`", "Wrap selected text, or word under cursor, in single quotes"
":kbd:`Ctrl+""`", "Wrap selected text, or word under cursor, in double quotes"
":kbd:`Ctrl+/`", "Toggle comment format for block or selected text"
":kbd:`Ctrl+0`", "Remove format for block or selected text"
":kbd:`Ctrl+1`", "Change block format to heading level 1"
":kbd:`Ctrl+2`", "Change block format to heading level 2"
":kbd:`Ctrl+3`", "Change block format to heading level 3"
":kbd:`Ctrl+4`", "Change block format to heading level 4"
":kbd:`Ctrl+5`", "Change block alignment to left-aligned"
":kbd:`Ctrl+6`", "Change block alignment to centred"
":kbd:`Ctrl+7`", "Change block alignment to right-aligned"
":kbd:`Ctrl+8`", "Add a left margin to the block"
":kbd:`Ctrl+9`", "Add a right margin to the block"
":kbd:`Ctrl+B`", "Format selected text, or word under cursor, with bold"
":kbd:`Ctrl+D`", "Format selected text, or word under cursor, with strike through"
":kbd:`Ctrl+I`", "Format selected text, or word under cursor, with italic"
":kbd:`Ctrl+Shift+/`", "Remove format for block or selected text"
":kbd:`Ctrl+Shift+D`", "Toggle ignored text format for block or selected text"
Other Editor Shortcuts
----------------------
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`F7`", "Re-run the spell checker on the document"
":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+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"
":kbd:`Ctrl+W`", "Close the current document"
":kbd:`Ctrl+X`", "Cut selected text to clipboard"
":kbd:`Ctrl+Y`", "Redo latest undo"
":kbd:`Ctrl+Z`", "Undo latest changes"
":kbd:`Ctrl+Backspace`", "Delete the word before the cursor"
":kbd:`Ctrl+Del`", "Delete the word after the cursor"
":kbd:`Ctrl+F7`", "Toggle spell checking"
":kbd:`Ctrl+Return`", "Open the tag or reference under the cursor in the viewer"
":kbd:`Ctrl+Shift+A`", "Select all text in the current paragraph"
Insert Shortcuts
----------------
A set of insert features are also available through shortcuts, but they require a double
combination of key sequences. The insert feature is activated with :kbd:`Ctrl+K`, followed by
a key or key combination for the inserted content.
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`Ctrl+K`, :kbd:`Space`", "Insert a non-breaking space"
":kbd:`Ctrl+K`, :kbd:`_`", "Insert a long dash (em dash)"
":kbd:`Ctrl+K`, :kbd:`.`", "Insert an ellipsis"
":kbd:`Ctrl+K`, :kbd:`'`", "Insert a modifier apostrophe"
":kbd:`Ctrl+K`, :kbd:`*`", "Insert a list bullet"
":kbd:`Ctrl+K`, :kbd:`%`", "Insert a per mille symbol"
":kbd:`Ctrl+K`, :kbd:`~`", "Insert a figure dash (same width as a number)"
":kbd:`Ctrl+K`, :kbd:`−`", "Insert a short dash (en dash)"
":kbd:`Ctrl+K`, :kbd:`1`", "Insert a left single quote"
":kbd:`Ctrl+K`, :kbd:`2`", "Insert a right single quote"
":kbd:`Ctrl+K`, :kbd:`3`", "Insert a left double quote"
":kbd:`Ctrl+K`, :kbd:`4`", "Insert a right double quote"
":kbd:`Ctrl+K`, :kbd:`C`", "Insert a ``@char`` keyword"
":kbd:`Ctrl+K`, :kbd:`E`", "Insert an ``@entity`` keyword"
":kbd:`Ctrl+K`, :kbd:`F`", "Insert a ``@focus`` keyword"
":kbd:`Ctrl+K`, :kbd:`G`", "Insert a ``@tag`` keyword"
":kbd:`Ctrl+K`, :kbd:`H`", "Insert a short description comment"
":kbd:`Ctrl+K`, :kbd:`L`", "Insert a ``@location`` keyword"
":kbd:`Ctrl+K`, :kbd:`M`", "Insert a ``@mention`` keyword"
":kbd:`Ctrl+K`, :kbd:`O`", "Insert an ``@object`` keyword"
":kbd:`Ctrl+K`, :kbd:`P`", "Insert a ``@plot`` keyword"
":kbd:`Ctrl+K`, :kbd:`S`", "Insert a synopsis comment"
":kbd:`Ctrl+K`, :kbd:`T`", "Insert a ``@time`` keyword"
":kbd:`Ctrl+K`, :kbd:`V`", "Insert a ``@pov`` keyword"
":kbd:`Ctrl+K`, :kbd:`X`", "Insert a ``@custom`` keyword"
":kbd:`Ctrl+K`, :kbd:`Ctrl+Space`", "Insert a thin non-breaking space"
":kbd:`Ctrl+K`, :kbd:`Ctrl+_`", "Insert a horizontal bar (quotation dash)"
":kbd:`Ctrl+K`, :kbd:`Ctrl+'`", "Insert a prime"
":kbd:`Ctrl+K`, :kbd:`Ctrl+""`", "Insert a double prime"
":kbd:`Ctrl+K`, :kbd:`Ctrl+*`", "Insert a flower mark (alternative bullet)"
":kbd:`Ctrl+K`, :kbd:`Ctrl+−`", "Insert a hyphen bullet (alternative bullet)"
":kbd:`Ctrl+K`, :kbd:`Ctrl+D`", "Insert a division sign"
":kbd:`Ctrl+K`, :kbd:`Ctrl+O`", "Insert a degree symbol"
":kbd:`Ctrl+K`, :kbd:`Ctrl+X`", "Insert a times sign"
":kbd:`Ctrl+K`, :kbd:`Shift+Space`", "Insert a thin space"
Document Viewer Shortcuts
=========================
.. csv-table::
:header: "Shortcut", "Description"
":kbd:`Alt+Left`", "Move backward in the view history"
":kbd:`Alt+Right`", "Move forward in the view history"
":kbd:`Ctrl+C`", "Copy selected text to clipboard"
":kbd:`Ctrl+Shift+A`", "Select all text in the current paragraph"
":kbd:`Ctrl+Shift+R`", "Close the document viewer"
docs/source/index.rst
+16 -1
View File
@@ -40,12 +40,27 @@ storage for robustness.
:hidden:
usage/introduction
usage/folders_and_documents
usage/organising_project
usage/chapters_and_scenes
usage/basic_formatting
usage/comments
usage/tags_and_references
usage/alignment_and_indent
usage/advanced_formatting
.. toctree::
:caption: The Manuscript Tool
:hidden:
manuscript/introduction
.. toctree::
:caption: Additional Features
:hidden:
features/introduction
features/shortcuts
features/breaks_and_spaces
.. toctree::
:maxdepth: 1
docs/source/manuscript/introduction.rst
+10
View File
@@ -0,0 +1,10 @@
.. _docs_manuscript:
************
Introduction
************
.. _docs_manuscript_numbers:
Automatic Numbering
===================
docs/source/project_overview.rst
-98
View File
@@ -50,82 +50,6 @@ option from the **New Project** form.
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:
@@ -145,34 +69,12 @@ A document or a folder can be moved to trash from the **Project** menu, or by pr
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:
docs/source/usage/advanced_formatting.rst
+5
View File
@@ -0,0 +1,5 @@
.. _docs_usage_shortcodes:
*******************
Advanced Formatting
*******************
docs/source/usage/basic_formatting.rst
+90
View File
@@ -3,3 +3,93 @@
****************
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.
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_manuscript>` depends 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 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.
docs/source/usage/chapters_and_scenes.rst
+79
View File
@@ -3,3 +3,82 @@
*******************
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 it is a Chapter or a Scene document.
The formatting of headings is based on Markdown_, and a heading is indicated by a line starting
with the ``#`` character. It accepts from one two 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 headings for your notes in the other root folders, but they aren't
treated as chapters or scenes, so you are free to use them as you want.
.. _docs_usage_headers_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:
``# 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.
``## 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_manuscript_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 to 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.
``##! 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.
``###! 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_features_scene_breaks` for more
details.
The formatting of these headings can be customised quite extensively in the
:ref:`Manuscript Tool <docs_manuscript>`, which is covered in a separate part of the documentation.
.. note::
The space after the ``#`` or ``!`` character is mandatory. The syntax highlighter will change
colour and font size when the heading is correctly formatted.
docs/source/usage/folders_and_documents.rst
-5
View File
@@ -1,5 +0,0 @@
.. _docs_usage_dirs_docs:
*********************
Folders and Documents
*********************
docs/source/usage/images/fig_heading_levels.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

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

After

Width:  |  Height:  |  Size: 259 KiB

docs/source/usage/organising_project.rst
+118
View File
@@ -0,0 +1,118 @@
.. _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 label of each item, its word count (or alternatively
character count), an active/inactive icon (see :ref:`docs_features_active`), and a custom status
icon (see :ref:`docs_features_status`).
You can add, view and edit the 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.
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 the application on what you put in them. You can use them
however you want.
Root Folder Types
-----------------
**Novel**
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_headers`.
**Plot**
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**
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**
The locations where your story takes place can be documented here. This, together with Plot and
Characters are the particularly useful story elements to track, and to reference from your
chapter and scene documents.
**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.
**Objects**
Important objects in the story, for instance physical objects that change hands often, can be
tracked here.
**Entities**
Does your plot have many powerful organisations or companies? Or other entities that are part of
the plot? They can be organised here.
**Custom**
The custom root folder type can be used for tracking anything else not covered by the above
options.
**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 folders are closely tied to the tags and reference system. Each folder type except
**Archive** and **Trash** 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
===============
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.
docs/source/usage_format.rst
-121
View File
@@ -47,137 +47,16 @@ can select them from **Preferences**.
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: