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

Complete the usage section

Browse Source
This commit is contained in:
Veronica Berglyd Olsen
2025-05-24 19:35:58 +02:00
parent 60973954ef
commit d0c838450d
7 changed files with 608 additions and 326 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/usage/advanced_formatting.rst
+146 -1
View File
@@ -1,5 +1,150 @@
.. _docs_usage_shortcodes:
.. _docs_usage_formatting:
*******************
Advanced Formatting
*******************
Markdown formatting is somewhat limited by default, so novelWriter has some additional formatting
codes for common use cases. These codes are all based on brackets, and some allow an additional
value 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`.
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 overlap and intersect.
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."
"``[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 building the project. To add additional space between paragraphs, add the text
``[vspace]`` on a line of its own, and the **Manuscript** 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.
: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 has 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"
:widths: 40, 60
: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. The Word Count uses a "field" shortcode to insert a count of all words in text paragraphs
on the cover page.
.. code-block:: md
Jane Smith[br]
42 Main Street[br]
1234 Capital City <<
[vspace:5]
#! Example
>> **By Jane Smith** <<
>> Word Count: [field:textWords] <<
docs/source/usage/alignment_and_indent.rst
+73
View File
@@ -3,3 +3,76 @@
*************************
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
docs/source/usage/comments.rst
+158
View File
@@ -3,3 +3,161 @@
******************
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 sue
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 chose 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 count, 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 only be used 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 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 completely ignored.
This text is a regular paragraph.
docs/source/usage/organising_project.rst
+8 -8
View File
@@ -45,7 +45,7 @@ however you want.
Root Folder Types
-----------------
**Novel**
**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.
@@ -53,35 +53,35 @@ Root Folder Types
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**
**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**
**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**
**Locations** (Notes)
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**
**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**
**Objects** (Notes)
Important objects in the story, for instance physical objects that change hands often, can be
tracked here.
**Entities**
**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**
**Custom** (Notes)
The custom root folder type can be used for tracking anything else not covered by the above
options.
docs/source/usage/tags_and_references.rst
+223
View File
@@ -3,3 +3,226 @@
*******************
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_headers` for more details. Therefore, metadata is
also associated with headings, and not the documents directly.
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 | 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.
``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 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 chapter 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 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 these 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 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 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 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. New references can be created by right-clicking on them and selecting **Create Note for
Tag** from the menu.
.. versionadded:: 2.2
docs/source/usage_breakdown.rst
-39
View File
@@ -178,45 +178,6 @@ for the mouse or touchpad.
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 titles.
* **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:
docs/source/usage_format.rst
-278
View File
@@ -4,44 +4,11 @@
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
@@ -63,287 +30,42 @@ Text Emphasis with Markdown
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.