Complete the usage section
This commit is contained in:
Veronica Berglyd Olsen
@@ -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] <<
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user