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

Update usage documentation and incorporate last usage file from old doc

Browse Source
This commit is contained in:
Veronica Berglyd Olsen
2025-05-25 15:08:55 +02:00
parent b7a8664cf9
commit d3fa06dccc
13 changed files with 176 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/images/screenshot_dark.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 516 KiB

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

Before

Width:  |  Height:  |  Size: 535 KiB

docs/source/index.rst
+3 -3
View File
@@ -34,10 +34,9 @@ storage for robustness.
Main Page <self>
More Documents <https://novelwriter.io/more/>
howto
.. toctree::
:caption: Using novelWriter
:caption: Getting Started
:hidden:
usage/introduction
@@ -48,12 +47,13 @@ storage for robustness.
usage/tags_and_references
usage/alignment_and_indent
usage/advanced_formatting
usage/front_back_matter
usage/howto
.. toctree::
:caption: The User Interface
:hidden:
user_interface/introduction
user_interface/projects
user_interface/editor_viewer
user_interface/split_and_merge
docs/source/project_structure.rst
-156
View File
@@ -1,156 +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.
.. 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
a_references for more details.
The syntax for the four basic heading types, and the three special types, is listed in section
:ref:`docs_usage_headers_levels`. 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:`docs_usage_headers_levels`.
**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:`docs_usage_headers_levels`. 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:`docs_usage_formatting_breaks`.
.. 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:`docs_ui_manuscript` page for more details.
.. _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:`docs_usage_formatting_breaks`.
.. _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:`docs_ui_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
docs/source/usage/basic_formatting.rst
+1 -1
View File
@@ -25,7 +25,7 @@ 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
applied to text paragraphs in the :ref:`Manuscript Tool <docs_ui_manuscript>` depends on paragraphs
being separated by blank lines.
:bdg-success:`Correct`
docs/source/usage/chapters_and_scenes.rst
+14 -5
View File
@@ -30,7 +30,10 @@ Heading Levels
An illustration of how heading levels correspond to the novel structure.
Four levels of headings are understood for novel documents:
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.
``# Title Text``
This is a heading level one. This heading indicates the start of a new partition. Partitions are
@@ -40,7 +43,7 @@ Four levels of headings are understood for novel documents:
``## 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.
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
@@ -72,13 +75,19 @@ may want to keep the use cases in mind while writing.
``###! 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.
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_manuscript>`, which is covered in a separate part of the documentation.
: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 syntax highlighter 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.
docs/source/usage/comments.rst
+1 -1
View File
@@ -158,6 +158,6 @@ on your keyboard with your cursor somewhere in the paragraph.
### Scene
%~ This text is completely ignored.
%~ This text is ignored.
This text is a regular paragraph.
docs/source/usage/front_back_matter.rst
+77
View File
@@ -0,0 +1,77 @@
.. _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.
.. _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
docs/source/howto.rst → docs/source/usage/howto.rst
+1 -1
View File
@@ -1,4 +1,4 @@
.. _docs_more_howto:
.. _docs_usage_howto:
*************
Tips & Tricks
docs/source/usage/images/fig_heading_levels.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 26 KiB

docs/source/usage/organising_project.rst
+35 -11
View File
@@ -85,6 +85,10 @@ Root Folder Types
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
@@ -120,21 +124,41 @@ documents.
.. _docs_usage_project_documents:
Project Documents
=================
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 add documents anywhere you want in your project structure. You can even add documents as
child items of other documents, just like 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.
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.
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.
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:`docs_ui_split_merge` for more details on
the latter two.
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_headers` for more details about 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 the types are allowed. You can also
convert folders into documents, which may sometimes be convenient.
Another convenient feature is that documents can be split into sub-documents by its containing
headings, or multiple documents merged into one. This is particularly convenient if you start out
with larger structural documents, like one containing all chapters and scenes in an act, and then
split those. See :ref:`docs_ui_split_merge` for more details.
.. _docs_usage_project_documents_templates:
Document Templates
------------------
docs/source/user_interface/introduction.rst
-10
View File
@@ -1,10 +0,0 @@
.. _docs_manuscript:
************
Introduction
************
.. _docs_manuscript_numbers:
Automatic Numbering
===================
docs/source/user_interface/manuscript.rst
+44 -1
View File
@@ -110,10 +110,53 @@ 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 also allows you to automatically insert chapter and scene numbers into your
heading formats. The automatic chapter number counter will skip all chapter headings marked as
unnumbered using the heading format described in :ref:`docs_usage_headers_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 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
^^^^^^^^^^^^^^^^
@@ -127,7 +170,7 @@ the desired separator text as the format. If the format is any piece of static t
be treated as a separator.
.. _docs_ui_manuscript_head_hard:
.. _docs_ui_manuscript_head_hard_soft:
Hard and Soft Scenes
^^^^^^^^^^^^^^^^^^^^