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

Update docs and add menu entries for special titles (#850)

Browse Source 
* Update Introduction chapter
* Update User Interface chapter
* Update Novel Projects chapter
* Update Novel Structure chapter
* Update Exporting Projects chapter
* Drop the asterisk notation for unnumbered chapters
* Add menu entries and tests for Novel Title and Unnumbered Chapter block formats
This commit is contained in:
Veronica Berglyd Olsen
2021-08-15 23:30:11 +02:00
committed by GitHub
parent 669f013c96
commit 460b350d85
11 changed files with 203 additions and 183 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/int_introduction.rst
+15 -15
View File
@@ -11,16 +11,16 @@ projects are structured is covered in :ref:`a_struct`.
In addition, the project can contain notes on the various plot elements, characters, locations,
etc, that make up the story. These notes are organised in a set of category-specific top-level
folders referred to as "root" folders, and each entry can be tagged and cross-referenced from
folders referred to as "root folders", and each entry can be tagged and cross-referenced from
within the novel documents and notes. These tags make it possible to inter-link documents, and
generate an overview of the entire novel project and how the various documents and plot elements
are interconnected. The tag and reference syntax is covered in :ref:`a_proj` and :ref:`a_notes`.
These additional features are not standard in markdown, but are available through special meta
keywords described in :ref:`a_struct_tags`. Syntax highlighting is provided to make it easier to
verify that the markdown tags are used correctly.
These features are available through special meta keywords described in :ref:`a_struct_tags`.
Syntax highlighting is provided to make it easier to verify that the markdown tags are used
correctly.
An overview of the supported markdown syntax is covered in :ref:`a_ui`.
An overview of the supported formatting syntax is covered in :ref:`a_ui`.
.. _a_intro_design:
@@ -34,32 +34,32 @@ at the same time provide a complete set of features needed for writing a novel.
.. note::
novelWriter is not intended to be a full office type word processor. It doesn't support images,
links, tables, and other complex structures and objects often needed for such documents.
Formatting is limited to headers, and bold, italicised and strikethrough text.
Formatting is limited to headers, emphasis, text alignment, and a few other simple features.
.. tip::
If you do need to align information in rows and columns in your notes, you can achieve this with
tabs and line breaks. The tab stop width can be specified in :guilabel:`Preferences`.
The main window does not have a toolbar like many other applications do. This reduces clutter, and
since the documents are formatted with markdown tags, is more or less redundant. However, all
since the documents are formatted with style tags, is more or less redundant. However, all
formatting features supported are available through convenient keyboard shortcuts. They are also
available in the main menu so you don't have to look up the syntax every time until you've
memorised it. A full list of shortcuts can be found in the :ref:`a_kb` section.
available in the main menu so you don't have to look up formatting codes every time you need them,
before you've memorised them. A full list of shortcuts can be found in the :ref:`a_kb` section.
In addition, novelWriter has a :guilabel:`Focus Mode` where all the user interface elements other
than the document editor itself are hidden away.
The colour scheme of the user interface defaults to that of the host operating system. In addition,
other light and dark themes are provided, and can be enabled in :guilabel:`Preferences` from the
The colour scheme of the user interface defaults to that of the host operating system. Some other
light and dark colour themes are provided, and can be enabled in :guilabel:`Preferences` from the
:guilabel:`Tools` menu. A number of syntax highlighting themes are also available in
:guilabel:`Preferences`. A set of icon themes in colour and greyscale are also offered. The icons
are based on the Typicons_ icon set designed by Stephen Hutchings.
The main window is split in two, or optionally three, panels. The left-most panel contains the
project tree and all the documents in your project. The second panel is the document editor, and
the optional third panel is a document viewer which can view any document in your project
independently of the document editor. It is not intended as a preview window, although you can use
it for this, but for viewing your notes next to your editor while you're writing.
project tree and all the documents in your project. The second panel is the document editor. An
optional third panel is a document viewer which can view any document in your project independently
of the document editor. It is not intended as a preview window, although you can use it for this,
but for viewing your notes next to your editor while you're writing.
A second tab is also available on the main window. This is the :guilabel:`Outline` tab where the
entire novel structure can be displayed, with all the tags and references listed. Depending on how
docs/source/usage_export.rst
+5 -7
View File
@@ -23,10 +23,9 @@ a series of keyword–replace steps. They are all on the format ``%keyword%``.
``%ch%``
This will be replaced by a chapter number. The number is incremented by one each time the build
tool sees a new heading of level two in a document with layout :guilabel:`Chapter`. If the
document has layout :guilabel:`Unnumbered`, the counter is *not* incremented. The latter is
useful for for instance Prologue and Epilogue chapters. Adding an asterisk (``*``) in front of
the title text of a level two heading will also disable the chapter counter for that heading.
tool sees a new heading of level two in a document, unless the heading formatting code has the
added ``!``. In the latter case, the counter is *not* incremented. This is useful for for
instance Prologue and Epilogue chapters.
``%chw%``
Behaves like ``%ch%``, but the number is represented as a number word.
@@ -97,9 +96,8 @@ exclude the body text itself.
If you need to exclude specific documents from your exports, like draft documents or documents you
want to take out of your manuscript, but don't want to delete, you can un-check the
:guilabel:`Include when building project` option for each document in the project tree. An included
document has a checkmark after the status icon in the :guilabel:`Flags` column. The
:guilabel:`Build Novel Project` tool has a switch to ignore this flag if you need to collectively
override these settings.
document has a checkmark after in the third column of the project tree. The :guilabel:`Build Novel
Project` tool has a switch to ignore this flag if you need to collectively override these settings.
.. _a_export_print:
docs/source/usage_interface.rst
+59 -33
View File
@@ -16,29 +16,28 @@ The Project Tree
The main window contains a project tree in the left-most panel. It shows the entire structure of
the project. It has four columns:
:guilabel:`Label`
**Column 1**
The first column shows the item icon and its label. The labels can be edited from the
:guilabel:`Project` menu, or by pressing :kbd:`F2` or :kbd:`Ctrl`:kbd:`E`. The label is not the
same as the title you set inside the document, but it will appear in the header above the
document text itself.
:guilabel:`Words`
**Column 2**
The second column shows the word count of the document, or the sum of words of the child items
if it is a folder. If the counts seem incorrect, they can be updated by rebuilding the project
index from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`.
for folders. If the counts seem incorrect, they can be updated by rebuilding the project index
from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`.
:guilabel:`Inc`
**Column 3**
The third column indicates whether the document is included in the final project build or not.
You may want to filter out documents that you no longer want to keep in the final manuscript,
but want to keep in the project for reference.
:guilabel:`Flags`
The fourth column shows various meta data flags for the item. The first is an icon indicating
the importance or status of the document. These are colour coded status levels that you control
and define yourself. They can be changed in :guilabel:`Project Settings` from the
:guilabel:`Project` menu. The first character after the icon indicates the class of the item,
that is ``N`` for **Novel**, ``C`` for **Character**, etc (see :ref:`a_struct_tags`). The
characters after the dot indicate the document layout type (see :ref:`a_proj_roots`).
**Column 4**
The fourth column shows the user-defined status or importance labels you've assigned to each
project item. By default, both the icon and the label text is shown, but you can turn off the
text label from :guilabel:`Preferences`. If the text label is off, the text will instead appear
in a tooltip when you hover your mouse over the icon. They status and importance values can be
changed in :guilabel:`Project Settings`.
Right-clicking an item in the project tree will open a context menu under the cursor, displaying
a selection of actions that can be performed on the selected item.
@@ -112,9 +111,9 @@ Editing and Viewing Documents
To edit a document, double-click it in the project tree, or press the :kbd:`Return` key while
having it selected. This will open the document in the document editor. The editor uses a
simplified markdown format. The format is described in the :ref:`a_ui_md` section below. The editor
has a maximise button (toggles the :guilabel:`Focus Mode`) and a close button in the top-right
corner.
markdown-like syntax for some features, and a novelWriter-specific syntax for others. The syntax
format is described in the :ref:`a_ui_md` section below. The editor has a maximise button (toggles
the :guilabel:`Focus Mode`) and a close button in the top-right corner.
Any document in the project tree can also be viewed in parallel in a right hand side document
viewer. To view a document, press :kbd:`Ctrl`:kbd:`R`, or select :guilabel:`View Document` in the
@@ -214,7 +213,8 @@ Markdown editor. It supports basic formatting like emphasis (italic), strong imp
and strikethrough text, as well as four levels of headings.
In addition to formatting codes, novelWriter allows for comments, a synopsis tag, and a set of
keyword and value sets used for tags and references.
keyword and value sets used for tags and references. There are also some codes that apply two whole
paragraphs. See :ref:`a_ui_md_text` below for more details.
.. _a_ui_md_head:
@@ -222,36 +222,43 @@ keyword and value sets used for tags and references.
Headings
--------
Four levels of headings are allowed. For documents of layout ``Note``, they are free to be used as
you see fit, but for all other layouts used for the novel text itself, they indicate the structural
level of the novel. See :ref:`a_struct_heads` for more details.
Four levels of headings are allowed. For project notes they are free to be used as you see fit.
However, for novel documents they indicate the structural level of the novel. See
:ref:`a_struct_heads` for more details.
``# Title``
``# Title Text``
Heading level one. If the document is a novel file, the header level indicates the start of a
new partition. This heading level can also be used for the title page's novel title.
new partition.
``## Title``
``## Title Text``
Heading level two. If the document is a novel file, the header level indicates the start of a
new chapter. Chapter numbers can be inserted automatically when exporting the manuscript.
``### Title``
``### Title Text``
Heading level three. If the document is a novel file, the header level indicates the start of a
new scene. Scene numbers or scene separators can be inserted automatically when exporting the
manuscript, so you can use the title field as a working title for your scenes if you wish.
``#### Title``
``#### Title Text``
Heading level four. If the document is a novel file, the header level indicates the start of a
new section. Section titles can be replaced by separators or removed when exporting the
manuscript, so you can use the title field as a working title for your sections if you wish.
.. note::
The space after the ``#`` characters is mandatory. The syntax highlighter will change colour and
font size when the heading is correctly formatted.
For header level one and two, adding a ``!`` modifies the behaviour of the heading slightly:
.. tip::
If you do use the automatic numbering feature for exports, you can tell the export tool to skip
assigning a number to a specific chapter by adding a ``*`` as the first character of the title
itself. See :ref:`a_struct_heads_unnum` for more details.
``#! Title Text``
This tells the build tool that the level one heading is intended to be used for the novel's
main title, like for instance on the front page. When exporting, this will use a different
styling and will exclude the title from for instance a Table of Contents in Libre Office.
``##! 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 a prologue for instance. See
:ref:`a_struct_heads_unnum` for more details.
.. note::
The space after the ``#`` or ``!`` characters is mandatory. The syntax highlighter will change
colour and font size when the heading is correctly formatted.
.. _a_ui_md_text:
@@ -281,13 +288,32 @@ background, depending on the selected theme.
it prevents the line wrapping algorithms from adding line breaks where it shouldn't.
.. _a_ui_md_break:
Vertical Space and Page Breaks
------------------------------
Adding more than one line break between paragraphs will *not* increase the space between those
paragraphs when exporting 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 number. For instance, writing ``[VSPACE:3]`` will
insert three blank paragraphs.
Normally, the build tool will insert a page break before all headers of level one and for all
headers of level two for novel documents, i.e. chapters, but not for project notes.
If you need to add a page break somewhere else, put the text ``[NEW PAGE]`` on a line by itself
before the text you wish to start on a new page.
.. _a_ui_md_align:
Paragraphs Alignment and Indentation
------------------------------------
Aside from Title Page and Partition which by default have its text centred, all document layouts
have the text by default aligned to the left ot justified, depending on your Preferences.
All documents have the text by default aligned to the left or justified, depending on your
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
docs/source/usage_projects.rst
+5 -4
View File
@@ -194,9 +194,10 @@ Settings` dialog where the document label and various other settings can be chan
can also be opened again later from either the :guilabel:`Project` menu, selecting :guilabel:`Edit
Project Item`, or by pressing :kbd:`Ctrl`:kbd:`E` or :kbd:`F2` with the item selected.
The layout of the document is also defined here. For Novel documents, the full list of layout
options are available. For non-Novel documents, only :guilabel:`Note` is available. See
:ref:`a_struct_layout` for more details.
The layout of the document is also defined here. The two options available are :guilabel:`Novel
Document` and :guilabel:`Project Note`. These behave slightly differently when the project is
built. A project note is never treated as part of the novel, no matter where in the project it is
located. See :ref:`a_struct_layout` for more details.
You can also select whether the document is by default included when building the project. This
setting can be overridden in the :guilabel:`Build Novel Project` tool if you wish to include them
@@ -214,7 +215,7 @@ of a document following a header. The word count, and change of words in the cur
displayed in the footer of any document open in the editor, and all stats are shown in the details
panel below the project tree for any document selected in the project or novel tree.
The word counts are not updated in real time, but run in the background every five seconds for as
The word counts are not updated in real time, but run in the background every few seconds for as
long as the document is being actively edited.
A total project word count is displayed in the status bar. The total count depends on the sum of
docs/source/usage_structure.rst
+47 -111
View File
@@ -31,9 +31,8 @@ The different header levels are interpreted as specific section types of the nov
way:
``# Header1``
Header level one signifies that the text refers to either the novel title or the name of a top
level partition. The latter is useful when you want to split the manuscript up into books,
parts, or acts.
Header level one signifies that the text refers to a top level partition. This is useful when
you want to split the manuscript up into books, parts, or acts.
``## Header2``
Header level two signifies a chapter level partition. Each time you want to start a new chapter,
@@ -60,26 +59,43 @@ way:
them in a draft manuscript. See the :ref:`a_export` 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 your project with the novel title as
the first line. You should modify the header format code with an ``!`` in order to render it as a
document title that is excluded from any automatic Table of Content in an exported document, like
so:
``#! My Novel``
The title is by default centred on the page. You can add more text to the page as you wish.
If you want an additional page inserted 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
when the project is exported.
.. _a_struct_heads_unnum:
Unnumbered Chapter Headings
---------------------------
If you use layout types for your documents, the automatic numbering feature for your chapters is
controlled by whether you use the :guilabel:`Chapter` or :guilabel:`Unnumbered` layout type for
your document. However, if you have a different document layout where this isn't practical, you can
also switch off chapter numbering for a chapter by making the first character of the chapter title
an asterisk (``*``). Like so:
If you use the automatic numbering feature for your chapters, but you want to keep some special
chapters separate from this, you cam add a ``!`` to the header formatting code to tell the build
tool to skip these chapters.
``## *Unnumbered Chapter Title``
``##! Unnumbered Chapter Title``
The leading asterisk is only considered by the :guilabel:`Build Novel Project` tool, and will be
removed before the title is inserted at the location of the ``%title%`` label. See the
:ref:`a_export` page for more details.
There is a separate formatting feature for such chapters in the :guilabel:`Build Novel Project`
tool as well. See the :ref:`a_export` page for more details.
.. note::
If you need the first character of the title to be an actual asterisk, you must escape it:
``\*``.
.. Note::
Previously, you could also disable the automatic numbering of a chapter by adding an ``*`` as
the first character if the chapter title itself. This feature has been dropped in favour of the
current format. Please update your chapter headings if you've used this syntax.
.. _a_struct_tags:
@@ -147,104 +163,24 @@ the index for a document is regenerated when it is saved, so this shouldn't norm
.. _a_struct_layout:
Novel Document Layout
=====================
Document Layout
===============
All documents in the project can have a layout format set. These layouts are important when the
project is exported as they indicate how to treat the content in terms of text formatting,
headings, and page breaks. The layout for each document is indicated as the last set of characters
in the :guilabel:`Flags` column of the project tree.
All documents in the project can have a layout format set. Previously, there were multiple layouts
available to change how the documents where formatted on export. These have now been reduced to
just two layouts: :guilabel:`Novel Document` and :guilabel:`Project Note`.
Not all layout types are actually treated differently, they also help to indicate what each
document is intended for in your project. The :guilabel:`Book` layout is a generic novel document
layout that is formatted identically to :guilabel:`Chapter` and :guilabel:`Scene` layout documents,
but may help to indicate what each document does in your project.
Novel documents can only live in the :guilabel:`Novel` root folder. You can also move them to
:guilabel:`Outtakes` and :guilabel:`Trash` of course. Project notes can be added anywhere in the
project.
You can for instance lay out your project using :guilabel:`Book` documents for each act, and then
later split those into chapter or scene documents by using the :guilabel:`Split Document` tool.
Scenes can also be contained within :guilabel:`Chapter` type documents, but you lose the drag and
drop feature that comes with having them in separate documents if you organise them this way.
Some layouts *do* have implications on how the project is exported. Documents with layout
:guilabel:`Title Page` and :guilabel:`Partition` have all headings and text centred, while the
:guilabel:`Unnumbered` layout disables the automatic chapter numbering feature for everything
contained within it. The latter is convenient for Prologue and Epilogue type chapters.
The above layout formats are only usable in the Novel root folder. Documents that are not a part of
the novel itself should have the :guilabel:`Note` layout. These documents are not getting any
special formatting, and it is possible to collectively filter them out during export. Notes can be
used anywhere in the project, also in the :guilabel:`Novel` root folder.
Below is an overview of all available layout formats.
:guilabel:`Title Page`
The title page layout. The title should be formatted as a heading level one. All text is centred
on export.
:guilabel:`Plain Page`
A plain page layout useful for instance for front matter pages. Heading levels are ignored for
this layout format, and so are formatting options like :guilabel:`Justify Text`. The page is
exported with a page break before it.
:guilabel:`Book`
This is the generic novel format that in principle can be used for all novel documents. Since
the internal structure of the novel is controlled by the heading levels, this layout will
produce the same result as a collection of :guilabel:`Partition`, :guilabel:`Chapter` and
:guilabel:`Scene` layout documents. However, it does not provide the functionality of the
:guilabel:`Unnumbered` layout format by default, but this can still be achieved by prefixing the
chapter title with an asterisk (``*``). See :ref:`a_struct_heads_unnum` for more details.
:guilabel:`Partition`
A partition can be used to split the novel into parts. Partition titles are indicated with a
level one heading. You can also add text and meta data to the page. The :guilabel:`Partition`
layout will in addition force a page break before the heading, and centre all content on the
page.
:guilabel:`Chapter`
Signifies the start of a new chapter. If the text itself is contained in scene documents, these
documents should only contain the title, comments, synopsis, and tag references for characters,
plot, etc. The heading for chapters should be level two. If you need an opening text, like a
quote or other leading text before the first scene, this is also where you'd want to add this
text.
:guilabel:`Unnumbered`
Same as :guilabel:`Chapter`, but when exporting the project, and automatic chapter numbering is
enabled, documents with this layout will not increment and apply a chapter number. It also has a
separate title formatting setting. This makes the layout suitable for Prologue and Epilogue type
chapters.
:guilabel:`Scene`
Used for scenes. This document should have a header of level three. Further sections can have
headers of level four, but there are no layout specifically for sections.
:guilabel:`Note`
A generic document that is optionally ignored when the novel project is exported. Use this
layout for descriptions of content in the supporting root folders. Notes can also be added to
the :guilabel:`Novel` root folder if you need to insert notes there. Note headers receive no
special formatting when building the project. They are always exported as-is.
.. note::
The layout granularity is entirely optional. In principle, you can write the entire novel in a
single document with layout :guilabel:`Book`. You can also have a single document per chapter if
that suits you better. The :guilabel:`Outline` will show your structure of chapters and scenes
regardless of how your documents are organised. So will the novel tree.
Depending on which icon theme you're using, the project tree can distinguish between the different
layouts and header levels of the documents to help indicate which are project notes and which are
novel documents containing a partition, chapter, or scene. If the icon theme you've selected
doesn't show a difference, you can still see the layout description in the details panel below the
project tree.
.. tip::
You can always start writing with a coarse layout with one or a few documents, and then later
use the split tool to automatically split the documents into separate chapter and scene
documents. The split tool will try to select the correct layout for each of the new documents.
.. _a_struct_layout_auto:
Novel Layout Automation
-----------------------
When a document is saved from the document editor, novelWriter will check if the level of the first
header of the document matches the selected document layout. If the header level is inconsistent
with the layout, the layout will automatically be corrected if it can be unambiguously determined.
This means that for instance saving a document with header level three, when the layout is set to
:guilabel:`Chapter`, the layout will automatically be changed to :guilabel:`Scene`. If, however,
the layout was set to :guilabel:`Book`, no change will be made because the :guilabel:`Book` layout
is not associated with a specific header level.
You can always start writing with a coarse setup with one or a few documents, and then later use
the split tool to automatically split the documents into separate chapter and scene documents.
You can split a document on any of the four header levels.