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

Update docs for 2.0 (#1248)

Browse Source
This commit is contained in:
Veronica Berglyd Olsen
2022-11-16 23:07:30 +01:00
committed by GitHub
parent 444c168da5 308a1649a5
commit 18c3e9851e
20 changed files with 702 additions and 583 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/conf.py
+1 -1
View File
@@ -42,7 +42,7 @@ templates_path = ["_templates"]
source_suffix = ".rst"
master_doc = "index"
today_fmt = "%A, %d %B %Y at %H:%M"
language = None
language = "en"
exclude_patterns = []
pygments_style = "sphinx"
pygments_dark_style = "monokai"
docs/source/index.rst
+2 -2
View File
@@ -27,8 +27,8 @@ JSON files. See the :ref:`a_breakdown_storage` section for more details.
Any operating system that can run Python 3 and has the Qt 5 libraries should be able to run
novelWriter. It runs fine on Linux, Windows and macOS, and users have tested it on other platforms
too. novelWriter can be run directly from the Python source, installed from the pip tool. See
:ref:`a_started` for more details.
too. novelWriter can be run directly from the Python source, or installed from packages or the pip
tool. See :ref:`a_started` for more details.
.. note::
Version 1.5 introduced a few changes that will require you to make a few minor modifications to
docs/source/int_customise.rst
-15
View File
@@ -58,18 +58,3 @@ For novelWriter to be able to locate the custom theme files, you must copy them
Once the files are copied there, they should show up in :guilabel:`Preferences` with the label you
set as ``name`` inside the file.
Theme CSS Files
---------------
If you wish, you can also modify the CSS styles of the GUI in addition to change colour settings.
This is only available for GUI themes, and you do this by creating a file with the exact same file
name as the ``.conf`` file with colour settings and give it the ``.qss`` extension.
On Windows, file extensions may not be visible by default, so make sure you only have one file
extension, and don't end up with two.
The QSS files are Qt Style Sheet files. See Qt's
`The Style Sheet Syntax <https://doc.qt.io/qt-5/stylesheet-syntax.html>`_ documentation for more
details.
docs/source/int_introduction.rst
+10 -7
View File
@@ -4,10 +4,10 @@
Key Features
************
novelWriter is a multi-document plain text editor using a markup syntax inspired by markdown to
novelWriter is a multi-document plain text editor using a markup syntax inspired by Markdown to
apply simple formatting to the text. It is designed for writing novels, so the formatting features
are limited. Your novel project is organised as a collection of separate plain text documents
instead of a single, large document.
are limited to those relevant for this purpose. Your novel project is organised as a collection of
separate plain text documents instead of a single, large document.
Below are some key features of novelWriter.
@@ -27,7 +27,9 @@ Below are some key features of novelWriter.
You can split your novel project up into as many individual documents as you want to. When you
build the project, they are all glued together in the top-to-bottom order in which they appear
in the project tree. You can use as few text documents as you like, but splitting the project up
into chapters and scenes means you can easily reorder them using the drag and drop feature.
into chapters and scenes means you can easily reorder them using the drag and drop feature. You
can start out with a few documents and then later split the document into multiple documents
based on its headers.
**Keep track of your plot elements**
All notes in your project can be assigned a *tag* you can *reference* from any other document or
@@ -36,11 +38,12 @@ Below are some key features of novelWriter.
keywords.
**Get an overview of your plot elements**
In the :guilabel:`Outline` tab on the main window you can see an outline of all the chapter and
scene sections of your project. If they have any references in them, these are listed in
In the :guilabel:`Outline View` on the main window you can see an outline of all the chapters,
scenes, and sections of your project. If they have any references in them, these are listed in
columns. You can also add a synopsis to each document, which can be listed here. You have the
option to add or remove columns of information from the outline. A subset of the outline
information is also available in the :guilabel:`Novel` tab under the main project tree.
information is also available in the :guilabel:`Novel View` as a replacement for the main
project tree.
**Building your manuscript**
Whether you want to compile a manuscript, or export all your notes, or generate an outline of
docs/source/int_overview.rst
+2 -2
View File
@@ -15,7 +15,7 @@ language that doesn't require a compiler to build and run. That means that the c
computer right out of the box, or from a zip file.
While it is developed for Linux primarily, it runs just fine on Windows as well. It also works fine
on macOS, but the author is not a mac user so less attention is paid to that platform.
on macOS, but the author is not a mac user, so less attention is paid to that platform.
In order to run novelWriter, you also need a few additional packages. The user interface is built
with `Qt 5 <https://www.qt.io/>`_, a cross platform library for building graphical user interface
@@ -86,5 +86,5 @@ meta data for it to extract.
them for tags you've set so that it knows which file to open when you click on a reference.
:ref:`a_export` - Recommended Reading
This section explains in more detail how the export tool works. In particular how you can
This section explains in more detail how the build tool works. In particular how you can
control the way chapter titles are formatted, and how scene and section breaks are handled.
docs/source/int_source.rst
+13
View File
@@ -110,6 +110,19 @@ needed package is called `qttools5-dev-tools`.
the ``i18n`` folder of the source code.
.. _a_source_sample:
Building the Example Project
============================
In order to be able to create new projects from example files, you need a ``sample.zip`` file in
the ``assets`` folder of the source. This file can be built from setup script by running:
.. code-block:: bash
python setup.py sample
.. _a_source_docs:
Building the Documentation
docs/source/int_started.rst
+18 -9
View File
@@ -15,6 +15,7 @@ Getting Started
.. _python.org: https://www.python.org/downloads/windows
.. _Releases: https://github.com/vkbo/novelWriter/releases
.. _RPM: https://github.com/vkbo/novelWriter/issues/907
.. _AppImage: https://appimage.org/
If you are using Windows or a Debian-based Linux distribtuion, you can install novelWriter from
package installers. If you are on macOS, you have the option to run novelWriter from a standalone
@@ -46,10 +47,10 @@ If you have any issues, try uninstalling the previous version and making a fresh
already had a version installed via a different method, you should uninstall that first.
.. _a_started_debian:
.. _a_started_linux:
Install on Debian/Ubuntu/Mint
=============================
Install on Linux
================
A Debian package can be downloaded from the `main website`_, or from the Releases_ page on GitHub.
This package should work on both Debian, Ubuntu and Linux Mint.
@@ -57,8 +58,8 @@ This package should work on both Debian, Ubuntu and Linux Mint.
If you prefer, you can also add the novelWriter repository on Launchpad to your package manager.
Ubuntu and Mint
---------------
Ubuntu
------
You can add the Ubuntu PPA_ and install novelWriter with the following commands.
@@ -71,11 +72,11 @@ You can add the Ubuntu PPA_ and install novelWriter with the following commands.
If you want pre-releases, add the ``ppa:vkbo/novelwriter-pre`` repository instead.
Debian
------
Debian and Mint
---------------
Since this is a pure Python package, the Launchpad PPA can in principle also be used on Debian.
However, the above command will fail to add the signing key.
Since this is a pure Python package, the Launchpad PPA can in principle also be used on Debian or
Mint. However, the above command will fail to add the signing key.
Instead, run the following commands to add the repository and key:
@@ -97,6 +98,14 @@ Then run the update and install commands as for Ubuntu:
different compression algorithm that Debian doesn't currently support.
Other Distros
-------------
For other Linux distros than the ones mentioned above, the primary option is AppImage_. These are
completely standalone images for the app that include the necessary environment to run novelWriter.
They can be run on any Linux distro.
.. _a_started_minimal:
Minimal Package Install
docs/source/project_export.rst
+30 -31
View File
@@ -1,11 +1,12 @@
.. _a_export:
******************
Exporting Projects
******************
***********************
Building the Manuscript
***********************
The novelWriter project can be exported in various formats using the build tool available from
:guilabel:`Build Novel Project` in the :guilabel:`Tools` menu, or by pressing :kbd:`F5`.
You can at any time build a manuscript, an outline of your notes, or any other type of document
from the text in your project. All of this is handled by the :guilabel:`Build Novel Project` tool.
You can activate it from the sidebar, the :guilabel:`Tools` menu, or by pressing :kbd:`F5`.
.. _a_export_headers:
@@ -66,7 +67,7 @@ Scene Separators
If you don't want any titles for your scenes (or for your sections if you have them), you can leave
the formatting boxes empty. If so, an empty paragraph will be inserted between the scenes or
sections instead resulting in a gap in the text.
sections instead, resulting in a gap in the text.
Alternatively, if you want a separator between them, like the common ``* * *``, you can enter the
desired separator text in the formatting box. In fact, if the format is a piece of static text, it
@@ -78,13 +79,9 @@ will always be treated as a separator.
File Selection
==============
Which documents and notes are selected for export can be controlled from the options on the left
side of the dialog window. The switch for :guilabel:`Include novel files` will enable or disable
inclusion of novel documents, and the switch for :guilabel:`Include note files` will do the same
for project notes. This allows for exporting just the novel, just your notes, or both, as you wish.
In addition, you can select to export the synopsis comments, regular comments, keywords, and even
exclude the body text itself.
Which documents and notes are selected for the build can be controlled from the options on the left
side of the dialog window. In addition, you can select to include the synopsis comments, regular
comments, keywords, and even exclude the body text itself if you just want an outline.
.. tip::
If you for instance want to export a document with an outline of the novel, you can enable
@@ -92,11 +89,9 @@ exclude the body text itself.
followed by the tags and references and the synopsis.
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 such document in the project tree. An
included 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.
want to take out of your manuscript, but don't want to delete, you can set the documents as
"inactive" in the project tree. :guilabel:`Build Novel Project` tool has a switch to collectively
exclude inactive documents.
.. _a_export_print:
@@ -108,13 +103,17 @@ The print button allows you to print the content in the preview window. You can
of your system's printers, or print directly to a file as PDF. You can also print to file from the
regular print dialog. The direct to file option is just a shortcut.
.. note::
The paper format should in all cases default to whatever your system default is. Of you want to
change it, you have to select it from the :guilabel:`Print Preview`` dialog.
.. _a_export_formats:
Export Formats
==============
Currently, six formats are supported for exporting.
Currently, six formats are supported.
Open Document Format
The Build tool can produce either an ``.odt`` file, or an ``.fodt`` file. The latter is just a
@@ -122,9 +121,9 @@ Open Document Format
former, and a few the latter.
novelWriter HTML
The HTML export format writes a single ``.htm`` file with minimal style formatting. The exported
HTML document is suitable for further processing by document conversion tools like Pandoc, for
importing in word processors, or for printing from browser.
The HTML format writes a single ``.htm`` file with minimal style formatting. The HTML document
is suitable for further processing by document conversion tools like Pandoc, for importing in
word processors, or for printing from browser.
novelWriter Markdown
This is simply a concatenation of the project documents selected by the filters. The documents
@@ -133,23 +132,23 @@ novelWriter Markdown
import back into novelWriter.
Standard/GitHub Markdown
The Markdown export format comes in both Standard and GitHub flavour. The *only* difference in
terms of novelWriter functionality is the support for strikethrough text, which is not supported
by the Standard flavour, but *is* supported by the GitHub flavour.
The Markdown format comes in both Standard and GitHub flavour. The *only* difference in terms of
novelWriter functionality is the support for strikethrough text, which is not supported by the
Standard flavour, but *is* supported by the GitHub flavour.
.. _a_export_options:
Additional Export Options
=========================
Additional Formats
==================
In addition to the above document formats, the novelWriter HTML and Markdown formats can also be
wrapped in a JSON file. These files will have a meta data entry and a body entry. For HTML, also
the accompanying css styles are exported.
the accompanying css styles are included.
The text body is saved in a two-level list. The outer list contains one entry per exported
document, in the order they appear in the project tree. Each document is then split up into a list
as well, with one entry per paragraph it contains.
The text body is saved in a two-level list. The outer list contains one entry per document, in the
order they appear in the project tree. Each document is then split up into a list as well, with one
entry per paragraph it contains.
These files are mainly intended for scripted post-processing for those who want that option. A JSON
file can be imported directly into a Python dict object or a PHP array, to mentions a few options.
docs/source/project_notes.rst
+29 -7
View File
@@ -25,9 +25,9 @@ Tags in Notes
Each new heading in a note can have a tag associated with it. The format of a tag is
``@tag: tagname``, where tagname is a unique identifier. Tags can then be referenced in the novel
documents, or cross-referenced in other notes, and will show up in the outline view and in the
back-reference panel when a document is being viewed. See :ref:`a_struct_tags` for how to reference
notes.
documents, or cross-referenced in other notes, and will show up in the Outline View and in the
back-reference panel when a document is opened in the viewer. See :ref:`a_struct_tags` for how to
reference notes.
The syntax highlighter will alert the user that the keyword is correctly used and that the tag is
allowed, that is, the tag is unique. Duplicate tags should be detected as long as the index is up
@@ -36,15 +36,37 @@ colour that valid tags do.
The tag is the only part of these notes that the application uses. The rest of the document content
is there for the writer to use in whatever way they wish. Of course, the content of the documents
can be exported if you want to compile a single document of all your notes, or include them in an
outline.
can be added to the manuscript, or an outline document. If you want to compile a single document of
all your notes, you can do this from the :guilabel:`Build Novel Project` tool.
A note can also reference other notes in the same way novel documents do. When the note is opened
in the view panel, the references become clickable links, making it easier to follow connections in
the plot. Notes don't show up in the outline view though, so referencing between notes is only
meaningful if you want to be able to click-navigate between them.
the plot. Notes don't show up in the Outline View though, 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
:guilabel:`Build Novel Project` tool, the cross-references become clickable links in the
exported HTML document.
Example of a project note with two headers, with separate tags, and with references to other notes:
.. code-block:: none
:linenos:
# Main Characters
## Jane Doe
@tag: Jane
@location: Earth
Something about Jane ...
## John Doh
@tag: John
@location: Mars
Something about John ...
docs/source/project_overview.rst
+67 -50
View File
@@ -33,12 +33,14 @@ other root folders. These other root folder types are intended for your notes on
elements of your story. Using them is of course entirely optional.
A new project may not have all of the root folders present, but you can add the ones you want from
:guilabel:`Create Root Folder` in the :guilabel:`Project` menu.
the project tree.
Each root folder has one or more reference keyword associated with it that can be used to reference
content in your notes from other documents and notes. The intended usage of each type of root
folder is listed below. However, aside from the :guilabel:`Novel` folder, no restrictions are
applied by the application. You can use them however you want.
tags in your notes from other documents and notes. The intended usage of each type of root folder
is listed below. However, aside from the :guilabel:`Novel` folder, no restrictions are applied by
the application. You can use them however you want.
You can make multiple root folders of each kind.
:guilabel:`Novel`
This is the root folder of all text that goes into the final novel. This class of documents have
@@ -51,9 +53,9 @@ applied by the application. You can use them however you want.
folder can be references using the ``@plot`` keyword.
:guilabel:`Characters`
Character notes go in this root folder. These are especially important if one wants to use the
Outline view to see which character appears where, and which part of the story is told from a
specific character's point-of-view or focusing on a particular character's storyline. Tags in
Character notes go in this root folder. These are especially important if you want to use the
Outline View to see which character appears where, and which part of the story is told from a
specific character's point-of-view, or focusing on a particular character's storyline. Tags in
this folder can be referenced using the ``@pov`` keyword for point-of-view characters,
``@focus`` for a focus character, or the ``@char`` keyword for any other characters.
@@ -86,6 +88,28 @@ information about the tags listed, see :ref:`a_struct_tags`.
You can rename root folders to whatever you want. However, this doesn't change the reference
keyword.
Example of a character note:
.. code-block:: none
:linenos:
# Jane Doe
@tag: Jane
Some information about the character Jane Doe.
Example of a novel scene referencing the above character:
.. code-block:: none
:linenos:
### Chapter 1, Scene 1
@pov: Jane
When Jane woke up that morning ...
.. _a_proj_roots_del:
@@ -97,9 +121,8 @@ trash folder can then be deleted permanently, either individually, or by emptyin
the menu. Documents in the trash folder are removed from the project index and cannot be
referenced.
Folders and root folders can only be deleted when they are empty. Recursive deletion is not
supported. A document or a folder can be deleted from the :guilabel:`Project` menu, or by pressing
:kbd:`Ctrl`:kbd:`Shift`:kbd:`Del`.
A document or a folder can be deleted from the :guilabel:`Project` menu, or by pressing
:kbd:`Ctrl`:kbd:`Shift`:kbd:`Del`. Root folders can only be deleted when they are empty.
.. _a_proj_roots_out:
@@ -109,9 +132,7 @@ Archived Documents
If you don't want to delete a document, or put it in the :guilabel:`Trash` folder where it may be
deleted, but still want it out of your main project tree, you can create an :guilabel:`Archive`
root folder from the :guilabel:`Project` menu. You are not allowed to move entire folders to this
root folder, only documents. If you need folders in it to organise your documents, you can of
course create new ones there.
root folder.
You can drag any document to this folder and preserve its settings. The document will always be
excluded from the :guilabel:`Build Novel Project` builds. It is also removed from the project
@@ -179,9 +200,10 @@ and to be able to collapse and hide them in the project tree when you're not wor
documents.
.. tip::
You can use folders to sort your scene documents into chapters. You will still need to add a
chapter document as the first item of your chapter folder, and the scene documents as the
following items. Other ways to use folders is to make a folder for each act or part.
You can add child documents to other documents. This is particularly useful when you create
chapters and scenes. If you add separate scene documents, you should also add separate chapter
documents, even if they only contain a chapter heading. You can then add scene documents as
child items to the chapters.
.. _a_proj_files:
@@ -189,21 +211,15 @@ documents.
Project Documents
=================
New documents can be created from the :guilabel:`Document` menu, or by pressing :kbd:`Ctrl`:kbd:`N`
while in the project tree. This will create a new, empty document, and open the :guilabel:`Item
Settings` dialog where the document label and various other settings can be changed. This dialog
can also be opened again later from either the :guilabel:`Project` menu, selecting :guilabel:`Edit
Project Item`, or by pressing :kbd:`F2` with the item selected.
New documents can be created from tool bar in the Project Tree, or by pressing :kbd:`Ctrl`:kbd:`N`.
This will open the create new item menu and let you choose between a number of pre-defined
documents and folders. You will be prompted for a label for the new item. You can always rename an
item by selecting :guilabel:`Rename Item` from the :guilabel:`Project` menu, or by pressing
:kbd:`F2`.
The layout of the document is also defined here. The two options available are :guilabel:`Novel
Document` and :guilabel:`Project Note`. These behave 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
anyway. This is covered in the :ref:`a_export_files` section. You can also toggle the included
state of a document from the right-click context menu.
Other settings for project items are available from the context menu that you can activate by
right-clicking on them inb the Project Tree. The :guilabel:`Transform` submenu includes options for
converting, splitting, or merging items.
.. _a_proj_files_counts:
@@ -237,17 +253,16 @@ The :guilabel:`Project Settings` can be accessed from the :guilabel:`Project` me
Settings Tab
------------
The :guilabel:`Settings` tab holds the project title and author settings.
The :guilabel:`Settings` tab holds the project name, title, and author settings.
The :guilabel:`Working Title` can be set to a different title than the :guilabel:`Book Title`. The
difference between them is simply that the :guilabel:`Working Title` is used for the GUI (main
window title) and for generating the backup files. The intention is that the :guilabel:`Working
Title` should remain unchanged throughout the project, otherwise the name of exported files and
The :guilabel:`Project Name` can be set to a different value than the :guilabel:`Novel Title`. The
difference between them is simply that the :guilabel:`Project Name` is used for the GUI (main
window title) and for generating the backup files. The intention is that the :guilabel:`Project
Name` should remain unchanged throughout the project, otherwise the name of exported files and
backup files may change too.
The :guilabel:`Book Title` and :guilabel:`Book Authors` settings are currently not used for
anything, so setting them is just for the benefit of the author. Future features may use them, and
they are exported on some export formats in the :guilabel:`Build Novel Project` tool.
The :guilabel:`Novel Title` and :guilabel:`Authors` settings are used when building the manuscript,
for some formats.
If your project is in a different language than your main spell checking is set to, you can
override the default spell checking language here. You can also override the automatic backup
@@ -257,14 +272,14 @@ setting.
Status and Importance Tabs
--------------------------
Each document or folder of type :guilabel:`Novel` can be given a status level, signified by a
coloured icon, and each document or folder of the remaining types can be given an importance level.
These are colour coded icons and labels that can be applied to each document or folder.
Each document or folder of type :guilabel:`Novel` can be given a _Status_ label accompanied by a
coloured icon, and each document or folder of the remaining types can be given an _Importance_
label.
These are purely there for the user's convenience, and you are not required to use them for any
other features to work. No other part of novelWriter accesses this information. The intention is to
use these to indicate at what stage of completion each novel document is, or how important the
content of a note is to the plot. You don't have to use them this way, that's just what they were
content of a note is to the story. You don't have to use them this way, that's just what they were
intended for, but you can make them whatever you want.
See also :ref:`a_ui_tree_status`.
@@ -279,7 +294,7 @@ Auto-Replace Tab
A set of automatically replaced keywords can be added in this tab. The keywords in the left column
will be replaced by the text in the right column when documents are opened in the viewer. They will
also be applied to exports.
also be applied to manuscript builds.
The auto-replace feature will replace text in angle brackets that are in this list. The syntax
highlighter will add an alternate colour to text marching the syntax, but it doesn't check if the
@@ -300,16 +315,17 @@ An automatic backup system is built into novelWriter. In order to use it, a back
the backup files are to be stored must be provided in :guilabel:`Preferences`.
Backups can be run automatically when a project is closed, which also implies it is run when the
application itself is closed. Backups are date stamped zip files of the entire project folder, and
are stored in a subfolder of the backup path. The subfolder will have the same name as the project
:guilabel:`Working Title` set in :ref:`a_proj_settings`.
application itself is closed. Backups are date stamped zip files of the project files in the
project folder (files not strictly a part of the project are ignored). The zip archives are stored
in a subfolder of the backup path. The subfolder will have the same name as the
:guilabel:`Project Name` as defined in :ref:`a_proj_settings`.
The backup feature, when configured, can also be run manually from the :guilabel:`Tools` menu.
It is also possible to disable automated backups for a given project in :guilabel:`Project
Settings`.
It is also possible to disable automated backups for a given project in
:guilabel:`Project Settings`.
.. note::
For the backup to be able to run, the :guilabel:`Working Title` must be set in
For the backup to be able to run, the :guilabel:`Project Name` must be set in
:guilabel:`Project Settings`. This value is used to generate the folder name for the zip files.
Without it, the backup will not run at all, but it will produce a warning message.
@@ -320,7 +336,8 @@ Writing Statistics
==================
When you work on a project, a log file records when you opened it, when you closed it, and the
total word counts of your novel documents and notes at the end of the session. You can view this
total word counts of your novel documents and notes at the end of the session provided that the
session lasted either more than 5 minutes, or that the total word count changed. You can view this
file in the ``meta`` folder in the directory where you saved your project. The file is named
``sessionStats.log``.
docs/source/project_structure.rst
+42 -31
View File
@@ -22,10 +22,9 @@ Four levels of headings are supported, signified by the number of hashes (``#``)
title. See also the :ref:`a_fmt` section for more details about the markdown syntax.
.. note::
The header levels are not only important when generating the exported novel file, they are also
used by the indexer when building the outline tree in the :guilabel:`Outline` tab as well as the
:guilabel:`Novel` tab of the project tree. Each heading also starts a new region where new
references and tags can be defined.
The header levels are not only important when generating the manuscript, they are also used by
the indexer when building the outline tree in the Outline as well as the Novel Tree. Each
heading also starts a new region where new references and tags can be defined.
The syntax for the four basic header types, and the two special header types, is listed in section
:ref:`a_fmt_head`. The meaning of the four levels for the structure of your novel is as follows:
@@ -33,8 +32,7 @@ The syntax for the four basic header types, and the two special header types, is
**Header Level 1: Partition**
This header level 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. These headings are not required.
The novel title itself should use the special header level one code explained in
:ref:`a_fmt_head`.
The novel title itself should use the special header level explained in :ref:`a_fmt_head`.
**Header Level 2: Chapter**
This header level signifies a chapter level partition. Each time you want to start a new
@@ -46,7 +44,7 @@ The syntax for the four basic header types, and the two special header types, is
**Header Level 3: Scene**
This header level signifies a scene level partition. You must provide a title text, but the
title text can be replaced with a scene separator or just skipped entirely when you export your
title text can be replaced with a scene separator or just skipped entirely when you build your
manuscript.
**Header Level 4: Section**
@@ -55,12 +53,12 @@ The syntax for the four basic header types, and the two special header types, is
mid-scene, like if you change the point-of-view character. You are free to use sections as you
wish, and can filter them out of the final manuscript just like with scene titles.
Page breaks are automatically added before level 1 and 2 headers when you export your project to a
Page breaks are automatically added before level 1 and 2 headers when you build your project to a
format that supports page breaks, or when you print the document directly from the build tool. If
you want page breaks in other places, you have to specify them manually. See :ref:`a_fmt_break`.
.. tip::
There are multiple options of how to process novel titles when exporting the manuscript. For
There are multiple options of how to process novel titles when building the manuscript. For
instance, chapter numbers can be applied automatically, and so can scene numbers if you want
them in a draft manuscript. See the :ref:`a_export` page for more details.
@@ -70,19 +68,19 @@ you want page breaks in other places, you have to specify them manually. See :re
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 level 1 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:
It is recommended that you add a document at the very top of each Novel root folder with the novel
title as the first line. You should modify the level 1 header format code with an ``!`` in order to
render it as a document title that is excluded from any automatic Table of Content in a manuscript
build document, like so:
``#! My Novel``
The title is by default centred on the page when exported. You can add more text to the page as you
wish, like for instance the author's name and details.
The title is by default centred on the page. You can add more text to the page as you wish, like
for instance the author's name and details.
If you want an additional page of text after the title page, starting on a fresh page, you can add
``[NEW PAGE]`` on a line by itself, and continue the text after it. This will insert a page break
when the project is exported.
before the text.
.. _a_struct_heads_unnum:
@@ -97,9 +95,9 @@ build tool to skip these chapters.
``##! Unnumbered Chapter Title``
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. When exporting to a format that
supports page breaks, also unnumbered chapters will have a page break added just like for normal
chapters.
tool as well. See the :ref:`a_export` page for more details. When building a document of a format
that supports page breaks, also unnumbered chapters will have a page break added just like for
normal chapters.
.. Note::
Previously, you could also disable the automatic numbering of a chapter by adding an ``*`` as
@@ -110,14 +108,13 @@ chapters.
.. _a_struct_tags:
Tag References
==============
Note References
===============
Each text partition, indicated by a heading of any level, can contain references to tags set in the
supporting notes of the project. The references are gathered by the indexer and used to generate an
outline view on the :guilabel:`Outline` tab of how the different parts of the novel are connected.
This section covers how to set references to tags. See :ref:`a_notes_tags` for how to define tags
the references can point to.
project notes of the project. The references are gathered by the indexer and used to generate the
Outline View. This section covers how to make references to tags. See :ref:`a_notes_tags` for how
to define tags the references can point to.
References and tags are also clickable in the document editor and viewer, making it easy to
navigate between reference notes while writing. Clicked links are always opened in the view panel.
@@ -171,6 +168,22 @@ The highlighter may be mistaken if the index of defined tags is out of date. If
to regenerate it, or select :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu. In general,
the index for a document is regenerated when it is saved, so this shouldn't normally be necessary.
Example of a novel document with references to characters and plots:
.. code-block:: none
:linenos:
## Chapter 1
@pov: Jane
### Scene 1
@char: John, Sam
@plot: Main
Once upon a time ...
.. _a_struct_layout:
@@ -181,15 +194,13 @@ All documents in the project can have a layout format set. Previously, there wer
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`.
Novel documents can only live in the :guilabel:`Novel` root folder. You can also move them to
Novel documents can only live in a :guilabel:`Novel` type root folder. You can also move them to
:guilabel:`Archive` and :guilabel:`Trash` of course. Project notes can be added anywhere in the
project.
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.
The project tree can distinguish between the different layouts and header levels of the documents
using coloured icons, and optionally add emphasis on the label (See the :guilabel:`Preferences`.)
For novel documents, the heading level of the first heading is recorded, and indicated by the icon.
.. tip::
You can always start writing with a coarse setup with one or a few documents, and then later use
docs/source/requirements.txt
+2 -2
View File
@@ -1,4 +1,4 @@
furo
sphinx~=4.0
pygments~=2.7
sphinx>=4.0
pygments>=2.7
docutils==0.17.1
docs/source/usage_breakdown.rst
+78 -41
View File
@@ -8,7 +8,7 @@ How it Works
The main features of novelWriter are listed in the :ref:`a_intro` section. Here, we go into some
more details on how they are implemented. Later on in this documentation, these features will be
covered in more detail.
covered in even more detail.
.. _a_breakdown_design:
@@ -19,52 +19,80 @@ GUI Layout and Design
The user interface of novelWriter is intended to be as minimalistic as practically possible, while
at the same time provide a complete set of features needed for writing a novel.
The main window does not have a toolbar like many other applications do. This reduces clutter, and
since the documents are formatted with style tags, is more or less redundant. However, most
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 formatting codes every time you need them.
However, a list of all shortcuts can be found in the :ref:`a_kb` section.
The main window does not have an editor toolbar like many other applications do. This reduces
clutter, and since the documents are formatted with style tags, is more or less redundant. However,
most formatting features supported are available through convenient keyboard shortcuts. They are
alsoavailable in the main menu so you don't have to look up formatting codes every time you need
them. However, a list of all shortcuts can be found in the :ref:`a_kb` section.
.. 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, emphasis, text alignment, and a few other simple features.
On the left edge of the main window, you will find a sidebar. This bar has buttons for the standard
views you can switch between, a quick link to the :guilabel:`Build Novel Project` tool, and a set
of project-related tools as well as quick access to settings at the bottom.
Window Tabs and Areas
---------------------
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. An
optional third panel is a document viewer which can view any document in your project independently
of what is open in the document editor. It is not intended as a preview window, although you can
use it for this as well as it will apply the formatting tags you have specified. The main purpose
of the viewer is for viewing your notes next to your editor while you're writing.
Project Tree View
-----------------
When in :guilabel:`Project Tree View` mode, the main work area of 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. An optional third panel is a document viewer
which can view any document in your project independently of what is open in the document editor.
It is not intended as a preview window, although you can use it for this as well as it will apply
the formatting tags you have specified. The main purpose of the viewer is for viewing your notes
next to your editor while you're writing.
The editor also has a :guilabel:`Focus Mode` you can toggle either from the menu, or from the icon
in the editor header. When :guilabel:`Focus Mode` is enabled, all the user interface elements other
than the document editor itself are hidden away.
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
you structure your novel documents, this outline can be quite different from your project tree.
Your project tree lists individual documents, your Outline tree lists the structure of the novel
itself in terms of partitions, chapters and scenes as it appears in the text of those documents.
Novel Tree View
---------------
When in :guilabel:`Novel Tree View` mode, the project tree is replaces by an overview of your novel
structure. Instead of showing individual documents, the tree shows all headings of your novel text.
Each heading is indented according to the heading level. You can open and edit your novel documents
from this view as well. All headings contained in the currently open document should be highlighted
in the view.
If you have multiple Novel root folders, you can switch between them from the dropdown menu from
the buttons at the top of the tree view. You can also select to view an extra column of data. To
select its content, see the menu icon button.
If you click the arrow to the right of each item, a tooltip will pop up showing you all the meta
data collected for that heading entry.
Novel Outline View
------------------
When in :guilabel:`Novel Outline View` mode, the tree, editor and viewer will be replaced by a
large table that shows the entire novel structure with all the tags and references listed. Pretty
much all collected meta data is available here in different columns.
You can select which novel root folder to display from the dropdown box, and you can select which
columns to show or hide from the menu button. You can also rearrange the columns by drag and drop.
Colour Themes
-------------
The colour theme 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`. Icon themes for light and dark GUIs are also available. The icons are
based on the Typicons_ icon set designed by Stephen Hutchings.
The default colour theme of the user interface is the default theme from the Qt library. There is a
standard dark theme provided as well, which is similar to the default Qt theme. Some other light
and dark colour themes are also provided. You can select which one you prefer from in
:guilabel:`Preferences` from :guilabel:`Settings` or the :guilabel:`Tools` menu.
A number of syntax highlighting themes are also available in :guilabel:`Preferences`. These are
separate settings because there are a lot more options for syntax highlighting.
.. note::
The GUI colour theme and the syntax highlighting theme are separate settings in
:guilabel:`Preferences`. If you switch to dark mode on the GUI, you should also switch the icon
theme and syntax highlighting theme.
If you switch to dark mode on the GUI, you should also switch the icon theme and syntax
highlighting theme, otherwise icons may be hard to see.
.. _a_breakdown_project:
@@ -75,10 +103,11 @@ Project Layout
This is a brief introduction to how you structure your writing projects. All of this will be
covered in more detail later.
The main point is that you are free to organise your project documents as you wish into subfolders,
and split the text between 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.
The main point of novelWriter is that you are free to organise your project documents as you wish
into subfolders or subdocuments, 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.
The four heading levels (**H1** to **H4**) are treated as follows:
@@ -87,33 +116,40 @@ The four heading levels (**H1** to **H4**) are treated as follows:
* **H3** is used for scene titles – optionally replaced by separators.
* **H4** 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 header level structure is only taken into account for novel documents. For the project notes,
the header levels have no structural meaning, and the user is free to do whatever they want. See
:ref:`a_struct` and :ref:`a_notes` for more details.
.. note::
You can add documents as child items of other documents if you wish. This is often more useful
than adding folders, since you may want to have the chapter heading in a separate document from
your individual scene documents.
.. _a_breakdown_export:
Project Export
==============
Building the Manuscript
=======================
The project can at any time be exported to a range of different formats through the
:guilabel:`Build Novel Project` tool. Natively, novelWriter supports export to Open Document,
HTML5, and various flavours of Markdown.
The project can at any time be assembled into a range of different formats through the
:guilabel:`Build Novel Project` tool. Natively, novelWriter supports Open Document, HTML5, and
various flavours of Markdown.
The HTML5 export format is suitable for conversion by a number of other tools like Pandoc, or for
The HTML5 format is suitable for conversion by a number of other tools like Pandoc, or for
importing into word processors if the Open Document format isn't suitable. In addition, printing
and printing to PDF is also possible.
You can also export the content of the project to a JSON file. This is useful if you want to write
your own processing script in for instance Python as the entire novel can be read into a Python
your own processing script in for instance Python, as the entire novel can be read into a Python
dictionary with a couple of lines of code. The JSON file can be populated either with HTML
formatted text, or with the raw text as typed into the novel documents. See :ref:`a_export_options`
for more details.
A number of filter options can be applied to the :guilabel:`Build Novel Project` tool, allowing you
to export a draft manuscript, a reference document of notes, an outline based on chapter and scene
titles with a synopsis each, and so on. See :ref:`a_export` for more details on export features and
to make a draft manuscript, a reference document of notes, an outline based on chapter and scene
titles with a synopsis each, and so on. See :ref:`a_export` for more details on build features and
formats.
@@ -132,7 +168,8 @@ project is saved directly to your project folder in separate files. Only the pro
the text you are currently editing is stored in memory at any given time. Secondly, having multiple
small files means it is very easy to sync them between computers with standard file synchronisation
tools. Thirdly, if you use version control software to track the changes to your project, the file
formats used for the files are well suited. Also the JSON documents have line breaks and indents.
formats used for the files are well suited. Also the JSON documents have line breaks and indents,
which makes it easier to track them with version control software.
.. note::
docs/source/usage_format.rst
+22 -21
View File
@@ -37,34 +37,34 @@ can select them for :guilabel:`Preferences`.
Headings
========
Four levels of headings are allowed. For project notes they are free to be used as you see fit.
That is, novelWriter doesn't assign the different headings any meaning. However, for novel
documents they indicate the structural level of the novel and must be used correctly to produce the
intended result. See :ref:`a_struct_heads` for more details.
Four levels of headings are allowed. For project notes, they are free to be used as you see fit.
That is, novelWriter doesn't assign the different headings any particular meaning. However, for
novel documents they indicate the structural level of the novel and must be used correctly to
produce the intended result. See :ref:`a_struct_heads` for more details.
``# Title Text``
Heading level one. For novel documents, the header level indicates the start of a new partition.
``## Title Text``
Heading level two. For novel documents, the header level indicates the start of a new chapter.
Chapter numbers can be inserted automatically when exporting the manuscript.
Chapter numbers can be inserted automatically when building the manuscript.
``### Title Text``
Heading level three. For novel documents, the header level indicates the start of a new scene.
Scene numbers or scene separators can be inserted automatically when exporting the manuscript,
Scene numbers or scene separators can be inserted automatically when building the manuscript,
so you can use the title field as a working title for your scenes if you wish.
``#### Title Text``
Heading level four. For novel documents, the header level indicates the start of a new section.
Section titles can be replaced by separators or removed completely when exporting the
manuscript.
Section titles can be replaced by separators or removed completely when building the manuscript.
For headers level one and two, adding a ``!`` modifies the behaviour of the heading:
``#! 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.
main title, like for instance on the front page. When building the manuscript, 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
@@ -121,7 +121,7 @@ A minimal set of text emphasis styles are supported.
Strikethrough text.
In markdown guides it is often recommended to differentiate between strong importance and emphasis
by using ``**`` for strong and ``_`` for emphasis, although markdown generally also supports ``__``
by using ``**`` for strong and ``_`` for emphasis, although Markdown generally also supports ``__``
for strong and ``*`` for emphasis. However, since the differentiation makes the highlighting and
conversion significantly simpler and faster, in novelWriter this is a rule, not just a
recommendation.
@@ -144,9 +144,9 @@ In addition, the following rules apply:
Comments and Synopsis
=====================
In addition to these standard markdown features, novelWriter also allows for comments in documents.
In addition to these standard Markdown features, novelWriter also allows for comments in documents.
The text of a comment is ignored by the word counter. The text can also be filtered out when
exporting or viewing the document.
building the manuscript or viewing the document.
If the first word of a comment is ``Synopsis:`` (with the colon included), the comment is treated
specially and will show up in the :ref:`a_ui_outline` in a dedicated column. The word ``synopsis``
@@ -154,13 +154,13 @@ is not case sensitive. If it is correctly formatted, the syntax highlighter will
altering the colour of the word.
``% text...``
This is a comment. The text is not exported by default (this can be overridden), seen in the
This is a comment. The text is not renderred by default (this can be overridden), seen in the
document viewer, or counted towards word counts.
``% 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 exporting the project to for instance generate an outline
can also be filtered separately when building the project to for instance generate an outline
document of the whole project.
.. note::
@@ -174,8 +174,9 @@ Tags and References
===================
The document editor supports a minimal set of keywords used for setting tags, and making references
between documents. The tags and references can be set once per section defined by a heading. Using
them multiple times under the same heading will just override the previous setting.
between documents. 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. References can be set
anywhere within a section, and are collected according to their category.
``@keyword: value``
A keyword argument followed by a value, or a comma separated list of values.
@@ -226,7 +227,7 @@ 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
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
@@ -242,6 +243,6 @@ Page breaks are automatically added to partition, chapter and unnumbered chapter
documents. If you want such breaks for scenes and sections, you must add them manually.
.. note::
The page break code is applied to the text that follows. 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 will not result in a page break.
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.
docs/source/usage_interface.rst
+62 -45
View File
@@ -22,7 +22,8 @@ the project, and has four columns:
The first column shows the icon and label of each folder, document, or note in your project. The
label is not the same as the title you set inside the document. However, the document's label
will appear in the header above the document text itself so you know where in the project an
open document belongs.
open document belongs. The icon is selected based on the type of item, and for novel documents,
the level of the first header in the document text.
**Column 2**
The second column shows the word count of the document, or the sum of words of the child items
@@ -30,20 +31,34 @@ the project, and has four columns:
from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`.
**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 tree for reference.
The third column indicates whether the document is considered active or inactive in the project.
You can use this flag to indicate that a document is still in the project, but should not be
considered an active part of it. When you run the :guilabel:`Build Novel Project` tool, you can
filter based on this flag. You can change this value from the context menu.
**Column 4**
The fourth column shows the user-defined status or importance labels you've assigned to each
project item. See :ref:`a_ui_tree_status` for more details.
project item. See :ref:`a_ui_tree_status` for more details. You can change these labels from the
context menu.
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.
The label, status or importance setting, the layout, and the include flag can all be edited using
the :guilabel:`Item Settings` dialog box. The dialog can be opened from the :guilabel:`Project`
menu, or by pressing :kbd:`F2` with the item selected.
At the top of the tree, you will find a set of buttons.
* The first button is a quick links button that will show you a dropdown menu of all the root
folders in your project. Selecting one will scroll to that position in the tree. You can also
activate this menu by pressing :kbd:`Ctrl`:kbd:`L`.
* The next buttons can be used to move items up and down in the project tree. This is the only way
to move root folders.
* The next button opens a dropdown menu for adding new items to the tree. This includes root
folders. You can also activate this dropdown menu by pressing :kbd:`Ctrl`:kbd:`N`.
* The last button is a menu of further actions on the entire project tree.
.. tip::
Under the :guilabel:`Transform` submenu in the context menu of an item, you will find several
options on how to change a document or folder. This includes changing between document and note,
splitting them into multiple documents, or merging child items into a single document.
Below the project tree you will find a small details panel showing the full information of the
currently selected item. This panel also includes the latest paragraph and character counts in
@@ -56,13 +71,15 @@ The Novel Tree
--------------
An alternative way to view the project structure is the novel tree. You can switch to this view by
selecting the :guilabel:`Novel` tab under the project tree. This view is a simplified version of
the view in the :guilabel:`Outline`. It is convenient when you want to browse the structure of the
story itself rather than the document files.
selecting the :guilabel:`Novel Tree View` button in the sidebar. This view is a simplified version
of the view in the :guilabel:`Outline`. It is convenient when you want to browse the structure of
the story itself rather than the document files.
.. note::
You cannot reorganise the entries in the novel tree, or add any new ones, as that would imply
restructuring the content of the document files. Any editing must be done in the project tree.
You cannot reorganise the entries in the novel tree, or add any new documents, as that would
imply restructuring the content of the document files. Any editing must be done in the project
tree. However, you can add new headings to existing documents, which will be updated in this
view.
.. _a_ui_tree_status:
@@ -96,19 +113,15 @@ Drag & drop has only limited support for moving documents. In general, bulk acti
allowed. This is deliberate to avoid accidentally messing up your project. If you make a mistake,
the last move action can be undone by pressing :kbd:`Ctrl`:kbd:`Shift`:kbd:`Z`.
Documents and their folders can be rearranged freely within their root folders. Novel documents
cannot be moved out of the :guilabel:`Novel` folder, except to :guilabel:`Trash` and the
:guilabel:`Archive` folders. Notes can be moved freely between all root folders, but keep in mind
that if you move a note into a :guilabel:`Novel`, its "Importance" setting will be reset to the
default "Status" setting. See :ref:`a_ui_tree_status`.
Folders cannot be moved at all outside their root tree. Neither can a folder containing documents
be deleted. You must first delete the containing documents.
Documents and their folders can be rearranged freely within their root folders. If you move a Novel
documents out of a Novel folder, it will be converted to a project note. Notes can be moved freely
between all root folders, but keep in mind that if you move a note into a :guilabel:`Novel`, its
"Importance" setting will be switched with a "Status" setting. See :ref:`a_ui_tree_status`. The old
value will not be overwritten though, and should be restored if you move it back.
Root folders in the project tree cannot be dragged & dropped at all. If you want to reorder them,
you can move them up or down with respect to eachother from the :guilabel:`Project` menu, the
right-click context menu, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down`
key.
you can move them up or down with respect to eachother from the arrow buttons at the top of the
project tree, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down` key.
.. _a_ui_edit:
@@ -118,19 +131,23 @@ 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
markdown-like syntax for some features, and a novelWriter-specific syntax for others. The syntax
format is described in the :ref:`a_fmt` section. The editor has a maximise button (toggles the
:guilabel:`Focus Mode`) and a close button in the top–right corner. On the top–left side you will
find an edit button that opens the :guilabel:`Item Settings` dialog for the currently open
document, and a search button to open the search dialog.
Markdown-like syntax for some features, and a novelWriter-specific syntax for others. The syntax
format is described in the :ref:`a_fmt` section.
The editor has a maximise button (toggles the :guilabel:`Focus Mode`) and a close button in the
top–right corner. On the top–left side you will find an edit button that opens the
:guilabel:`Item Label` dialog for the currently open document, and a search button to open the
search dialog.
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
menu. If you have a middle mouse button, middle-clicking on the document will also open it in the
viewer. The document viewed does not have to be the same document as currently being edited.
However, If you *are* viewing the same document, pressing :kbd:`Ctrl`:kbd:`R` again will update the
document with your latest changes. You can also press the reload button in the top–right corner of
the view panel, next to the close button, to achieve the same thing.
menu or context menu. If you have a middle mouse button, middle-clicking on the document will also
open it in the viewer.
The document viewed does not have to be the same document as currently being edited. However, If
you *are* viewing the same document, pressing :kbd:`Ctrl`:kbd:`R` again will update the document
with your latest changes. You can also press the reload button in the top–right corner of the view
panel, next to the close button, to achieve the same thing.
Both the document editor and viewer will show the label of the document in the header at the top of
the edit or view panel. Optionally, the full project path to the document can be shown. This can be
@@ -218,24 +235,26 @@ tricky for languages that use the same symbol for these, like English does.
Project Outline View
====================
The project's Outline view is available as the second tab on the right hand side of the main window
labelled :guilabel:`Outline`. The outline provides an overview of the novel structure, displaying a
tree hierarchy of the elements of the novel, that is, the level 1 to 4 headings representing
partitions, chapters, scenes and sections.
The project's Outline view is available as another view option from the views bar. The outline
provides an overview of the novel structure, displaying a tree hierarchy of the elements of the
novel, that is, the level 1 to 4 headings representing partitions, chapters, scenes and sections.
The document containing the heading can also be displayed as a separate column, as well as the line
number where it occurs. Double-clicking an entry will open the corresponding document in the
editor.
You can select which novel folder to display from the dropdown menu. You can optionally also choose
to show a combination of all novel folders.
.. note::
Since the internal structure of the novel does not depend directly on the folder and document
structure of the project tree, these will not necessarily look the same, depending on how you
choose to organise your documents. See the :ref:`a_struct` page for more details.
Various meta data and information extracted from tags can be displayed in columns in the outline.
A default set of such columns is visible, but you can turn on or off more columns by right clicking
the header and selecting the columns you want to show. The order of the columns can also be
rearranged by dragging them to a different position.
A default set of such columns is visible, but you can turn on or off more columns from the menu
button in the toolbar. The order of the columns can also be rearranged by dragging them to a
different position.
.. note::
The :guilabel:`Title` column cannot be disabled or moved.
@@ -244,10 +263,8 @@ The information viewed in the outline is based on the project's main index. Whil
its best to keep the index up to date when contents change, you can always rebuild it manually by
pressing :kbd:`F9` if something isn't right.
The outline view itself can be regenerated by pressing :kbd:`F10`. You can also enable automatic
updating in the :guilabel:`Tools` menu, which will trigger an update whenever the index is updated
and the :guilabel:`Outline` tab is active. You may want to disable this feature if your project is
very large,
The outline view itself can be regenerated by pressing the refresh button. By default, the content
is refreshed each time you switch to this view.
The :guilabel:`Synopsis` column of the outline view takes its information from a specially
formatted comment. See :ref:`a_fmt_comm`.
docs/source/usage_projectformat.rst
+16 -11
View File
@@ -19,12 +19,27 @@ applicable.
have the option to decline the upgrade.
.. _a_prjfmt_1_5:
Format 1.5 Changes
==================
This project format was introduced in novelWriter version 2.0.
This is a modification of the 1.4 format. It makes the XML more consistent in that meta data have
been moved to the section nodes, and key/value settings now have a consistent format. Logical flags
are saved as yes/no instead of Python True/False, and the main heading of the document is now saved
to the item rather than in the index.
.. _a_prjfmt_1_4:
Format 1.4 Changes
==================
This project format was introduced in novelWriter version 1.7.
This project format was introduced in novelWriter version 2.0 RC 1. Since this was a release
candidate, it is unlikely that your project uses it, but it may be the case if you've installed a
pre-release.
This format changes the way project items (folders, documents and notes) are stored. It is a more
compact format that is simpler and faster to parse, and easier to extend. The conversion is done
@@ -77,10 +92,6 @@ Format 1.2 Changes
This project format was introduced in novelWriter version 0.10.
With this format, the way auto-replace entries were stored in the main project XML file changed.
Opening an old project automatically converts the storage format up to and including version 1.1.1.
Format 1.2 projects can be opened without loss of information up until version 1.1.1, and if the
auto-replace is not being used, can still be opened in novelWriter as of version |release|.
.. _a_prjfmt_1_1:
@@ -96,9 +107,6 @@ novelWriter documents were saved in a series of folders numbered from ``data_0``
It also reduces the number of meta data and cache files. These files are automatically deleted if
an old project is opened. This was also when the Table of Contents file was introduced.
Format 1.1 projects can be opened without loss of information up until version 1.1.1, and if the
auto-replace is not being used, can still be opened in novelWriter as of version |release|.
.. _a_prjfmt_1_0:
@@ -106,6 +114,3 @@ Format 1.0 Changes
==================
This is the original file format and project structure. It was in use up to version 0.6.3.
Format 1.0 projects can be opened without loss of information up until version 1.1.1, and if the
auto-replace is not being used, can still be opened in novelWriter as of version |release|.
i18n/nw_base.ts
+298 -298
View File
File diff suppressed because it is too large Load Diff
novelwriter/gui/__init__.py
+2 -2
View File
@@ -28,7 +28,7 @@ from novelwriter.gui.outline import GuiOutlineView
from novelwriter.gui.projtree import GuiProjectView
from novelwriter.gui.statusbar import GuiMainStatus
from novelwriter.gui.theme import GuiTheme
from novelwriter.gui.viewsbar import GuiViewsBar
from novelwriter.gui.sidebar import GuiSideBar
__all__ = [
"GuiDocEditor",
@@ -41,5 +41,5 @@ __all__ = [
"GuiOutlineView",
"GuiProjectView",
"GuiTheme",
"GuiViewsBar",
"GuiSideBar",
]
novelwriter/gui/viewsbar.py → novelwriter/gui/sidebar.py
+6 -6
View File
@@ -1,7 +1,7 @@
"""
novelWriter – GUI Main Window Views ToolBar
novelWriter – GUI Main Window SideBar
===========================================
GUI class for the main window "Views" toolbar
GUI class for the main window side bar
File History:
Created: 2022-05-10 [1.7b1]
@@ -36,14 +36,14 @@ from novelwriter.enum import nwView
logger = logging.getLogger(__name__)
class GuiViewsBar(QToolBar):
class GuiSideBar(QToolBar):
viewChangeRequested = pyqtSignal(nwView)
def __init__(self, mainGui):
super().__init__(parent=mainGui)
logger.debug("Initialising GuiViewsBar ...")
logger.debug("Initialising GuiSideBar ...")
self.mainConf = novelwriter.CONFIG
self.mainGui = mainGui
@@ -123,7 +123,7 @@ class GuiViewsBar(QToolBar):
self.updateTheme()
logger.debug("GuiViewsBar initialisation complete")
logger.debug("GuiSideBar initialisation complete")
return
@@ -142,4 +142,4 @@ class GuiViewsBar(QToolBar):
return
# END Class GuiViewsBar
# END Class GuiSideBar
novelwriter/guimain.py
+2 -2
View File
@@ -41,7 +41,7 @@ from PyQt5.QtWidgets import (
from novelwriter.gui import (
GuiDocEditor, GuiDocViewDetails, GuiDocViewer, GuiItemDetails, GuiMainMenu,
GuiMainStatus, GuiNovelView, GuiOutlineView, GuiProjectView, GuiTheme,
GuiViewsBar
GuiSideBar
)
from novelwriter.dialogs import (
GuiAbout, GuiPreferences, GuiProjectDetails, GuiProjectLoad,
@@ -118,7 +118,7 @@ class GuiMain(QMainWindow):
self.itemDetails = GuiItemDetails(self)
self.outlineView = GuiOutlineView(self)
self.mainMenu = GuiMainMenu(self)
self.viewsBar = GuiViewsBar(self)
self.viewsBar = GuiSideBar(self)
# Project Tree Stack
self.projStack = QStackedWidget()