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

Updated the introduction section of the docs

Browse Source
This commit is contained in:
Veronica K. B. Olsen
2021-01-01 18:37:11 +01:00
parent 176c25004c
commit 92f44f0aaa
5 changed files with 191 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/index.rst
+10 -8
View File
@@ -30,18 +30,19 @@ novelWriter |release|
novelWriter is a markdown-like text editor designed for writing novels and larger projects of many novelWriter is a markdown-like text editor designed for writing novels and larger projects of many
smaller plain text documents. It uses its own flavour of markdown that supports a meta data syntax smaller plain text documents. It uses its own flavour of markdown that supports a meta data syntax
for comments, synopsis and cross-referencing between files. The idea is to have a simple text editor for comments, synopsis and cross-referencing between files. The idea is to have a simple text
which allows for easy organisation of text files and notes, built on a plain text file project editor which allows for easy organisation of text files and notes, built on a plain text file
repository for robustness. project repository for robustness.
The plain text storage is suitable for version control software, and also well suited for file The plain text storage is suitable for version control software, and also well suited for file
synchronisation tools. The core project structure is stored in a project XML file. Other meta data synchronisation tools. The core project structure is stored in a single project XML file. Other
is primarily saved as JSON files. meta data is primarily saved as JSON files.
Any operating system that can run Python 3 and has the Qt 5 libraries should be able to run 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 already, and users have tested it on other novelWriter. It runs fine on Linux, Windows and macOS, and users have tested it on other platforms
platforms too. Since novelWriter is still under development, it is easier to run it if you are too. novelWriter can be run directly from the Python source, or installed from the pip tool or via
already familiar with how to run Python applications on your platform. the provided setup script. A setup.exe is provided for Windows. See :ref:`a_started` for further
details.
**Useful Links** **Useful Links**
@@ -50,6 +51,7 @@ already familiar with how to run Python applications on your platform.
* Source Code: https://github.com/vkbo/novelWriter * Source Code: https://github.com/vkbo/novelWriter
* Source Releases: https://github.com/vkbo/novelWriter/releases * Source Releases: https://github.com/vkbo/novelWriter/releases
* Issue Tracker: https://github.com/vkbo/novelWriter/issues * Issue Tracker: https://github.com/vkbo/novelWriter/issues
* Feature Discussions: https://github.com/vkbo/novelWriter/discussions
* PyPi Project: https://pypi.org/project/novelWriter * PyPi Project: https://pypi.org/project/novelWriter
docs/source/int_interface.rst
+64 -61
View File
@@ -4,21 +4,22 @@
User Interface User Interface
************** **************
The user interface is kept as simple as possible to avoid distractions when writing. This page lists The user interface is kept as simple as possible to avoid distractions when writing. This page
all the main GUI elements, and explains what they do. lists all the main GUI elements, and explains what they do.
.. _a_ui_tree: .. _a_ui_tree:
The Project Tree The Project Tree
================ ================
The main window contains a project tree in the left-most panel. It shows the entire structure of the The main window contains a project tree in the left-most panel. It shows the entire structure of
project. It has four columns: the project. It has four columns:
:guilabel:`Label` :guilabel:`Label`
The first column shows the item icon and its label. The labels can be edited from the menu, or by The first column shows the item icon and its label. The labels can be edited from the menu
pressing :kbd:`F2` or :kbd:`Ctrl`:kbd:`E`. The label is not the same as the title you set inside :guilabel:`Project` menu, or by pressing :kbd:`F2` or :kbd:`Ctrl`:kbd:`E`. The label is not the
the document, but it will appear in the header above the document text itself. same as the title you set inside the document, but it will appear in the header above the
document text itself.
:guilabel:`Words` :guilabel:`Words`
The second column shows the word count of the file, or the sum of words in the child items if it The second column shows the word count of the file, or the sum of words in the child items if it
@@ -27,42 +28,46 @@ project. It has four columns:
:guilabel:`Inc` :guilabel:`Inc`
The third column indicates whether the file is included in the final project build or not. You The third column indicates whether the file is included in the final project build or not. You
may want to filter out files that you no longer want to keep in the final manuscript, but want to may want to filter out files that you no longer want to keep in the final manuscript, but want
keep in the project for reference. to keep in the project for reference.
:guilabel:`Flags` :guilabel:`Flags`
The fourth column shows various meta data flags for the item. The first is an icon indicating the The fourth column shows various meta data flags for the item. The first is an icon indicating
importance or status of the file. These are colour coded status levels that you control and the importance or status of the file. These are colour coded status levels that you control and
define yourself. They can be changed in :guilabel:`Project Settings` from the :guilabel:`Project` define yourself. They can be changed in :guilabel:`Project Settings` from the
menu. The first character after the icon indicates the class of the item, that is ``N`` for :guilabel:`Project` menu. The first character after the icon indicates the class of the item,
**Novel**, ``C`` for **Character**, etc (see :ref:`a_struct_tags`. The second character indicates that is ``N`` for **Novel**, ``C`` for **Character**, etc (see :ref:`a_struct_tags`). The second
the file layout type (see :ref:`a_proj_roots`). character indicates the file layout type (see :ref:`a_proj_roots`).
Below the project tree you will find a small details panel showing the full information of the 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 currently selected item. This panel also includes the latest paragraph and character counts in
addition to the word count. addition to the word count.
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.
.. _a_ui_tree_dnd: .. _a_ui_tree_dnd:
Project Tree Drag and Drop Project Tree Drag and Drop
-------------------------- --------------------------
The project tree allows dragging and drop to a certain extent. This feature is primarily intended The project tree allows drag and drop to a certain extent. This feature is primarily intended for
for rearranging the order of your files within each root folder, and has only limited support for rearranging the order of your files within each root folder, and has only limited support for
moving files elsewhere in the project tree. In general, bulk actions are not allowed. This is moving files elsewhere in the project tree. In general, bulk actions are not allowed. This is
deliberate to avoid accidentally messing up your project. The project tree has no undo function. deliberate to avoid accidentally messing up your project. The project tree has no undo function.
Document files and their folders can be rearranged freely within their root folders. Novel files Document files and their folders can be rearranged freely within their root folders. Novel files
cannot be moved out of the :guilabel:`Novel` folder, except to :guilabel:`Trash` and the cannot be moved out of the :guilabel:`Novel` folder, except to :guilabel:`Trash` and the
:guilabel:`Outtakes` folder. Note files can be moved freely anywhere. :guilabel:`Outtakes` folder. Note files can be moved freely between root folders.
Folders cannot be moved at all outside their root tree. Neither can a folder containing files be Folders cannot be moved at all outside their root tree. Neither can a folder containing files be
deleted. You must first delete the files. deleted. You must first delete the files.
Root folders in the project tree cannot be dragged and dropped at all. However, if you want to Root folders in the project tree cannot be dragged and dropped at all. If you want to reorder them,
reorder them, you can move them up or down with respect to eachother from the :guilabel:`Tools` you can move them up or down with respect to eachother from the :guilabel:`Tools` menu or the
menu, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down` key. right-click context menu, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down`
key.
.. _a_ui_edit: .. _a_ui_edit:
@@ -75,11 +80,12 @@ having it selected. This will open the file in the document editor. The editor u
markdown format. The format is described in the :ref:`a_ui_md` section below. The editor has a markdown format. The format is described in the :ref:`a_ui_md` section below. The editor has a
maximise button (activates :guilabel:`Focus Mode`) and a close button in the top-right corner. maximise button (activates :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. Any document in the project tree can also be viewed in parallel in a right hand side document
To view a document, press :kbd:`Ctrl`:kbd:`R`, or select :guilabel:`View Document` in the menu. The viewer. To view a document, press :kbd:`Ctrl`:kbd:`R`, or select :guilabel:`View Document` in the
document viewed does not have to be the same document currently being edited. However, If you *are* menu. If you have a middle mouse button, middle-clicking on the document will also open it in the
viewing the same document, pressing :kbd:`Ctrl`:kbd:`R` again will update the document with your viewer. The document viewed does not have to be the same document currently being edited. However,
latest changes. You can also press the little reload button in the top-right corner of the view 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. 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 Both the document editor and viewer will show the label of the document in the header at the top of
@@ -91,11 +97,13 @@ location of the file in a large project.
Any reference to a tag in the editor can be opened in the viewer by moving the cursor to the label Any reference to a tag in the editor can be opened in the viewer by moving the cursor to the label
and pressing :kbd:`Ctrl`:kbd:`Return`. In the viewer, the references become clickable links. and pressing :kbd:`Ctrl`:kbd:`Return`. In the viewer, the references become clickable links.
Clicking them will replace the content of the viewer with the content of the document the reference Clicking them will replace the content of the viewer with the content of the document the reference
points to. points to. The document viewer keeps a history of viewed documents that you can navigate with the
arrow buttons in the top-left corner of the viewer. If your mouse has navigation buttons, these can
be used as well.
At the bottom of the view panel there is a :guilabel:`References` panel. (If it is hidden, click the At the bottom of the view panel there is a :guilabel:`References` panel. (If it is hidden, click
icon to reveal it.) This panel will show links to all documents referring back to it, if any has the icon to reveal it.) This panel will show links to all documents referring back to it, if any
been defined. The :guilabel:`Sticky` button will freeze the content of the panel to the current has been defined. The :guilabel:`Sticky` button will freeze the content of the panel to the current
document, even if you navigate to another document. This is convenient if you want to quickly look document, even if you navigate to another document. This is convenient if you want to quickly look
through all documents in the list in the :guilabel:`References` panel. through all documents in the list in the :guilabel:`References` panel.
@@ -187,13 +195,11 @@ A minimal set of text emphasis styles are supported.
Strikethrough text. Strikethrough text.
In markdown guides it is often recommended to differentiate between strong importance and emphasis In markdown guides it is often recommended to differentiate between strong importance and emphasis
by using ``**`` for strong and ``_`` for emphasis, although markdown generally supports also ``__`` 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 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 conversion significantly simpler and faster, in novelWriter this is a rule, not just a
recommendation. The following is therefore the only supported formatting syntax: recommendation. The following is therefore the only supported formatting syntax:
There are also some additional rules:
1. The emphasis and strikethrough formatting tags do not allow spaces between the words and the tag 1. The emphasis and strikethrough formatting tags do not allow spaces between the words and the tag
itself. That is, ``**text**`` is valid, ``**text **`` is not. itself. That is, ``**text**`` is valid, ``**text **`` is not.
2. More generally, the delimiters must be on the outer edge of words. That is, ``some **text in 2. More generally, the delimiters must be on the outer edge of words. That is, ``some **text in
@@ -201,6 +207,8 @@ There are also some additional rules:
3. If using both ``**`` and ``_`` to wrap the same text, the underscore must be the inner wrapper. 3. If using both ``**`` and ``_`` to wrap the same text, the underscore must be the inner wrapper.
This is due to the underscore also being a valid word character, so if they are on the outside, This is due to the underscore also being a valid word character, so if they are on the outside,
they violate rule 2. they violate rule 2.
4. Text emphasis does not span past line breaks. If you need to add emphasis to multiple lines or
paragraphs, you must apply it to each of them in turn.
.. _a_ui_md_comm: .. _a_ui_md_comm:
@@ -211,17 +219,23 @@ Comments and Synopsis
In addition to these standard markdown features, novelWriter also allows for comments in the text In addition to these standard markdown features, novelWriter also allows for comments in the text
files. The text of the comment is ignored by the word counter and not exported or, optionally, files. The text of the comment is ignored by the word counter and not exported or, optionally,
hidden when viewing the document. If the first word of a comment is ``Synopsis:`` (with the colon), hidden when viewing the document. If the first word of a comment is ``Synopsis:`` (with the colon),
the comment is treated specially, and will show up in the :ref:`a_ui_outline` in a dedicated column. the comment is treated specially and will show up in the :ref:`a_ui_outline` in a dedicated column.
The word ``synopsis`` is not case sensitive. If it is correctly formatted, the syntax highlighter
will indicate this by altering the colour of the word.
``% text...`` ``% text...``
A comment. The text is not exported by default (this can be overridden), seen in the Viewer, or A comment. The text is not exported by default (this can be overridden), seen in the Viewer, or
counted towards word counts. counted towards word counts.
``% Synopsis: text...`` ``% Synopsis: text...``
A synopsis comment. It is generally treated in the same way as regular comments, except that it A synopsis comment. It is generally treated in the same way as a regular comment, except that it
is captured by the indexing algorithm and displayed in the :ref:`a_ui_outline`. It can also be is also captured by the indexing algorithm and displayed in the :ref:`a_ui_outline`. It can also
filtered separately when exporting the project to for instance generate an outline document of be filtered separately when exporting the project to for instance generate an outline document
the whole project. of the whole project.
.. note::
Only one comment can be flagged as a synopsis comment for each heading. If multiple comments are
flagged as synopsis comments, the last one will be used.
.. _a_ui_md_tags: .. _a_ui_md_tags:
@@ -236,7 +250,8 @@ multiple times under the same heading will just override the previous setting.
``@keyword: value`` ``@keyword: value``
A keyword argument followed by a value, or a comma separated list of values. A keyword argument followed by a value, or a comma separated list of values.
The available tag and reference keywords are listed in the :ref:`a_struct_tags` section. The available tag and reference keywords are listed in the :ref:`a_struct_tags` section. They can
also be inserted at the cursor position in the editor via the :guilabel:`Insert` menu.
.. _a_ui_md_add: .. _a_ui_md_add:
@@ -248,10 +263,11 @@ The editor and viewer also supports markdown standard hard line breaks, and pres
spaces if running with Qt 5.9 or higher. For older versions, the non-breaking spaces are lost when spaces if running with Qt 5.9 or higher. For older versions, the non-breaking spaces are lost when
the file is saved. This is unfortunately hard-coded in the Qt text editor. the file is saved. This is unfortunately hard-coded in the Qt text editor.
* A hard line break is achieved by leaving two or more spaces at the end of the line. Alternatively, * A hard line break is achieved by leaving two or more spaces at the end of the line.
the user can press :kbd:`Ctrl`:kbd:`K`, :kbd:`Return` to insert this. Alternatively, the user can press :kbd:`Ctrl`:kbd:`K`, :kbd:`Return` to insert this.
* A non-breaking space is inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Space`. * A non-breaking space is inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Space`.
* Thin spaces are also supported, and can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Shift`:kbd:`Space`. * Thin spaces are also supported, and can be inserted with :kbd:`Ctrl`:kbd:`K`,
:kbd:`Shift`:kbd:`Space`.
* Non-breaking thin space can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`Space`. * Non-breaking thin space can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`Space`.
These are all insert features, and the :guilabel:`Insert` menu has more. They are also listed These are all insert features, and the :guilabel:`Insert` menu has more. They are also listed
@@ -276,7 +292,7 @@ editor.
.. note:: .. note::
Since the internal structure of the novel does not depend on the file structure of the project Since the internal structure of the novel does not depend on the file structure of the project
tree, these will not necessarily look the same, depending how you chose to organise your files. tree, these will not necessarily look the same, depending how you choose to organise your files.
See the :ref:`a_struct` page for more details. 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. Various meta data and information extracted from tags can be displayed in columns in the outline.
@@ -296,21 +312,8 @@ updating in the :guilabel:`Tools` menu, which will trigger an update whenever th
and the :guilabel:`Outline` tab is active. You may want to disable this feature if your project is and the :guilabel:`Outline` tab is active. You may want to disable this feature if your project is
very large, very large,
The :guilabel:`Synopsis` column of the outline view takes its information from a specially
.. _a_ui_outline_synopsis: formatted comment. See :ref:`a_ui_md_comm`.
Synopsis Column
---------------
The :guilabel:`Synopsis` column of the outline view takes its information from a specially formatted
comment. See :ref:`a_ui_md_comm`. In order to flag a comment as a synopsis, add the word
``Synopsis:`` as the first word of the comment. The ``:`` is required, and the word ``synopsis`` is
not case sensitive. If it is correctly formatted, the syntax highlighter will indicate this by
altering the colour of the word.
.. note::
Only one comment can be flagged as a synopsis comment for each heading. If multiple comments are
flagged as a synopsis comment, the last one will be used.
.. _a_ui_shortcuts: .. _a_ui_shortcuts:
@@ -401,9 +404,9 @@ Most features are available as keyboard shortcuts. These are as follows:
Insert Shortcuts Insert Shortcuts
---------------- ----------------
A set of insert features are also available through shortcuts, but they require a double combination A set of insert features are also available through shortcuts, but they require a double
of key sequences. The insert feature is activated with :kbd:`Ctrl-K`, followed by a key or combination of key sequences. The insert feature is activated with :kbd:`Ctrl-K`, followed by a key
combination for the inserted character or punctuation. or combination for the inserted character or punctuation.
.. csv-table:: Keyboard Shortcuts .. csv-table:: Keyboard Shortcuts
:header: "Shortcut", "Description" :header: "Shortcut", "Description"
docs/source/int_introduction.rst
+28 -25
View File
@@ -5,20 +5,22 @@ Introduction
************ ************
novelWriter is a simple, multi-document plain text editor using a modified markdown syntax to apply novelWriter is a simple, multi-document plain text editor using a modified markdown syntax to apply
simple formatting. It is designed for writing novels, and allows for the component documents to be simple formatting to the text. It is designed for writing novels, and allows for the component
ordered freely to create the desired structure of the novel. More details about how projects are documents to be ordered freely to create the desired structure of the novel. More details about how
structured is covered on the :ref:`a_struct` page. projects are structured is covered on the :ref:`a_struct` page.
In addition, the project can contain notes on the various plot elements, characters, locations, etc, In addition, the project can contain notes on the various plot elements, characters, locations,
that make up the story. These notes are organised in a set of category-specific top-level folders, etc, that make up the story. These notes are organised in a set of category-specific top-level
and each entry can be tagged and cross-referenced from within the novel files and other notes. These folders (root folders), and each entry can be tagged and cross-referenced from within the novel
tags make it possible to inter-link documents, and generate an overview of the entire novel project files and other note files. These tags make it possible to inter-link documents, and generate an
and how the various files and plot elements are interconnected. This is covered on the :ref:`a_proj` overview of the entire novel project and how the various files and plot elements are
and :ref:`a_notes` pages. interconnected. This is covered on the :ref:`a_proj` and :ref:`a_notes` pages.
These additional features are not standard in markdown, but are available through special meta These additional features are not standard in markdown, but are available through special meta
keywords. Syntax highlighting is provided to make it easier to verify that the markdown tags are keywords described on :ref:`a_struct_tags`. Syntax highlighting is provided to make it easier to
used correctly. The syntax is covered on the :ref:`a_ui` page. verify that the markdown tags are used correctly.
An overview of the extended markdown syntax is covered on the :ref:`a_ui` page.
.. _a_intro_design: .. _a_intro_design:
@@ -31,8 +33,8 @@ at the same time provide a complete set of features needed for writing a novel.
.. note:: .. note::
novelWriter is not intended to be a full office type word processor. It doesn't support images, novelWriter is not intended to be a full office type word processor. It doesn't support images,
links, tables, and other complex structure and objects often needed for such document. Formatting links, tables, and other complex structure and objects often needed for such document.
is limited to headers, and bold, italicised and strikethrough text. Formatting is limited to headers, and bold, italicised and strikethrough text.
The main window does not have a toolbar like most other applications do. This reduces clutter, and The main window does not have a toolbar like most 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 markdown tags, is more or less redundant. However, all
@@ -40,14 +42,14 @@ formatting features supported are available through convenient keyboard shortcut
available in the main menu. A full list of shortcuts can be found in the :ref:`a_ui_shortcuts` available in the main menu. A full list of shortcuts can be found in the :ref:`a_ui_shortcuts`
section. section.
In addition, novelWriter offers a :guilabel:`Focus Mode` where all the user interface elements other In addition, novelWriter offers a :guilabel:`Distraction Free Mode` where all the user interface
than the document editor itself are hidden away. 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, The colour scheme of the user interface defaults to that of the host operating system. In addition,
a dark theme is provided, and can be enabled in :guilabel:`Preferences` from the :guilabel:`Tools` a dark theme is 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 menu. A number of syntax highlighting themes are also available in :guilabel:`Preferences`. A set
icon themes in colour and greyscale are also offered. The icons are based on the Typicons_ icon set of icon themes in colour and greyscale are also offered. The icons are based on the Typicons_ icon
designed by Stephen Hutchings. set designed by Stephen Hutchings.
The main window is split in two, or optionally three, panels. The left-most contains the project The main window is split in two, or optionally three, panels. The left-most contains the project
tree and all the files in your project. The second panel is the document editor, and the optional tree and all the files in your project. The second panel is the document editor, and the optional
@@ -55,7 +57,7 @@ third panel is a document viewer which can view any document in your project.
A second tab is also available on the main window. This is the :guilabel:`Outline` tab where the 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 entire novel structure can be displayed, with all the tags and references listed. Depending on how
you structure your novel project files, this outline can be quite different than your project tree. you structure your novel project files, this outline can be quite different from your project tree.
Your project tree lists files, your Outline tree lists the structure of the novel itself. Your project tree lists files, your Outline tree lists the structure of the novel itself.
.. _Typicons: https://github.com/stephenhutchings/typicons.font .. _Typicons: https://github.com/stephenhutchings/typicons.font
@@ -79,7 +81,7 @@ The four heading levels (**H1** to **H4**) are treated as follows:
* **H4** is for section titles within scenes, if such granularity is needed. * **H4** is for section titles within scenes, if such granularity is needed.
This header level structure is only taken into account for novel files. For the files designated as This header level structure is only taken into account for novel files. For the files designated as
project notes, the header levels imply no structural meaning, and the user is free to do whatever project notes, the header levels have no structural meaning, and the user is free to do whatever
they want. See the :ref:`a_struct` page for more details. they want. See the :ref:`a_struct` page for more details.
@@ -88,9 +90,10 @@ they want. See the :ref:`a_struct` page for more details.
Project Export Project Export
============== ==============
The project can at any time be exported to a range of different formats. Natively, novelWriter The project can at any time be exported to a range of different formats through the
supports export to plain text file, HTML document, novelWriter flavoured markdown, standard :guilabel:`Build Novel Project` tool. Natively, novelWriter supports export to plain text file,
markdown (requires Qt 5.14), and to a basic Open Document. HTML document, novelWriter flavoured markdown, standard markdown (requires Qt 5.14), and to a basic
Open Document format.
In addition, printing and printing to PDF is also possible. The best supported export format is In addition, printing and printing to PDF is also possible. The best supported export format is
HTML, which can be imported or converted by a number of other tools like Pandoc, or simply imported HTML, which can be imported or converted by a number of other tools like Pandoc, or simply imported
@@ -108,8 +111,8 @@ formats.
.. _a_intro_screenshots: .. _a_intro_screenshots:
Screenshot Screenshots
========== ===========
**novelWriter with default system theme:** **novelWriter with default system theme:**
docs/source/int_started.rst
+73 -34
View File
@@ -4,13 +4,19 @@
Getting Started Getting Started
*************** ***************
This is a brief guide to how you can get novelWriter running on your computer. These are the methods This is a brief guide to how you can get novelWriter running on your computer. These are the
currently supported by the developer. Packages may also be available in other package managers, but methods currently supported by the developer. Packages may also be available in other package
those are not managed by me. managers, but those are not managed by the developer. A Windows installer file is also provided on
the GitHub page and main website.
As novelWriter matures, more options for how to install it and get it running will be added. At the As novelWriter matures, more options for how to install it and get it running will be added. For
present time, the process is best suited for people used to working with Python projects from command non-Windows users the install process is at the present time best suited for people used to working
line. with the command line.
.. note::
The text below assumes the command ``python`` corresponds to a Python 3 executable. For
operating systems with both Python 2 and 3, the command ``python3`` may be needed instead. On
Linux, the scripts can also be made executable and run without the ``python`` command.
.. _a_started_install: .. _a_started_install:
@@ -28,6 +34,46 @@ Latest version of novelWriter is |release|.
.. _PyPi: https://pypi.org/project/novelWriter/ .. _PyPi: https://pypi.org/project/novelWriter/
.. _a_started_install_win:
Windows Installer
-----------------
You can run novelWriter directly from source on Windows, but a Windows installer is also provided
for 64-bit Windows on the `main website`_ and GitHub_ page. This installer bundles all that is
needed for novelWriter to run, including Python and the xml and Qt libraries.
.. _main website: https://novelwriter.io
.. note::
While the majority of virus scanners have no warnings, some scanners will flag the installer.
This is caused by the ``pyinstaller`` tool being used to create the package. The ``pyinstaller``
binaries bundled with the installer are from the official PyPi repository.
.. _a_started_install_source:
Install from Source on Linux
----------------------------
For Linux systems, novelWriter can be installed from source with the provided ``setup.py`` script.
To install novelWriter into the system's default Python install locations, run:
.. code-block:: console
python setup.py install
To set up the novelWriter desktop launcher, the icons and the project file association, run:
.. code-block:: console
python setup.py xdg-install
By default, these commands installs novelWriter and its icons for the current user only. To install
for all users, run the script with the ``sudo`` command. Other options are also available. Run
``python setup.py help`` for a full list of install options.
.. _a_started_depend: .. _a_started_depend:
Dependencies Dependencies
@@ -68,11 +114,9 @@ You can of course also install these packages from your operating system's packa
PyQt/Qt should be at least 5.2.1, but ideally 5.10 or higher for nearly all features to work. PyQt/Qt should be at least 5.2.1, but ideally 5.10 or higher for nearly all features to work.
Exporting to standard Markdown, for instance, requires PyQt/Qt 5.14. Searching using regular Exporting to standard Markdown, for instance, requires PyQt/Qt 5.14. Searching using regular
expressions requires 5.3, and for full Unicode support, 5.13. expressions requires 5.3, and for full Unicode support, 5.13. There is no known minimum version
requirement for package ``lxml``, but the code was originally written with 4.2, which is therefore
There is no known minimum version requirement for package ``lxml``, but the code was originally set as the minimum. It may work on lower versions. You have to test it.
written with 4.2, which is therefore set as the minimum. It may work on lower versions. You have to
test it.
The spell checking extension is optional, but recommended: The spell checking extension is optional, but recommended:
@@ -87,9 +131,9 @@ works fine.
Building the Documentation Building the Documentation
-------------------------- --------------------------
If you installed novelWriter from a package, the documentation should be included. If you're running If you installed novelWriter from a package, the documentation should be included. If you're
novelWriter from the source code, a local copy of this documentation can be generated. It requires running novelWriter from the source code, a local copy of this documentation can be generated. It
the following Python packages on Debian and Ubuntu. requires the following Python packages on Debian and Ubuntu.
* ``python3-sphinx`` * ``python3-sphinx``
* ``python3-sphinxcontrib.qthelp`` * ``python3-sphinxcontrib.qthelp``
@@ -100,13 +144,20 @@ Or from PyPi:
pip install sphinx sphinxcontrib-qthelp pip install sphinx sphinxcontrib-qthelp
To build the help packages from the documentation source, run The documentation can then be built from the ``docs`` folder in the source code by running:
.. code-block:: console .. code-block:: console
./setup.py qthelp make html
from the root source folder. If successful, the documentation should then be available in the ``docs/build/html`` folder.
The documentation can also be built for the Qt Assistant. To build the help packages from the
documentation source, run the following from the root source folder:
.. code-block:: console
python setup.py qthelp
The setup script will copy the generated files into the ``nw/assets/help`` folder, and novelWriter The setup script will copy the generated files into the ``nw/assets/help`` folder, and novelWriter
will detect the presence of the files and redirect the menu help entry to open help locally instead will detect the presence of the files and redirect the menu help entry to open help locally instead
@@ -121,17 +172,14 @@ locally first, then send you to the website as a fallback.
.. _a_started_running: .. _a_started_running:
Running novelWriter Running from Source
=================== ===================
If all the required dependencies are met, you can run novelWriter from the command line in one of If all the required dependencies are met, you can run novelWriter from the command line:
the following ways:
.. code-block:: console .. code-block:: console
python novelWriter.py python novelWriter.py
python3 novelWriter.py
./novelWriter.py
A few switches are supported from the command line, mostly to assist in debugging if an error is A few switches are supported from the command line, mostly to assist in debugging if an error is
encountered. To list all options, run: encountered. To list all options, run:
@@ -140,10 +188,6 @@ encountered. To list all options, run:
python novelWriter.py --help python novelWriter.py --help
There are also a couple of install scripts in the setup folder which will assist in setting up a
launch icon and the novelWriter project file mimetype for Gnome desktops on Linux. Currently,
there's one script for Debian and one for Ubuntu.
.. _a_started_standalone: .. _a_started_standalone:
@@ -151,15 +195,10 @@ Building a Standalone Executable
================================ ================================
A standalone executable can be built with ``pyinstaller``, using the provided python script A standalone executable can be built with ``pyinstaller``, using the provided python script
``install.py`` in the source folder. This script will automatically try to install all dependencies ``make.py`` in the source folder. This script can install dependencies, build a standalone
and build the standalone executable of novelWriter. You can run the script by typing the following executable of novelWriter, or build a ``setup.exe`` file with Inno Setup.
into your command prompt:
.. code-block:: console For a full list of the script's options, run ``python make.py help``.
python install.py
If successful, the executable will be in the "dist" folder.
.. _a_started_standalone_win: .. _a_started_standalone_win:
docs/source/int_typography.rst
+15 -15
View File
@@ -4,10 +4,10 @@
Typographical Notes Typographical Notes
******************* *******************
novelWriter has some support for typographical symbols that are not usually easily available in many novelWriter has some support for typographical symbols that are not usually easily available in
text editors. This includes for instance the proper unicode quotation marks, dashes, ellipsis, thin many text editors. This includes for instance the proper unicode quotation marks, dashes, ellipsis,
spaces, etc. All these symbols are available from the :guilabel:`Insert` menu, and via keyboard thin spaces, etc. All these symbols are available from the :guilabel:`Insert` menu, and via
shortcuts. See :ref:`a_ui_shortcuts_ins`. keyboard shortcuts. See :ref:`a_ui_shortcuts_ins`.
This chapter provides some additional information on how novelWriter handles these symbols. This chapter provides some additional information on how novelWriter handles these symbols.
@@ -24,9 +24,9 @@ Dashes and Ellipsis
------------------- -------------------
With the auto-replace feature enabled (see :ref:`a_ui_edit_auto`), multiple hyphens are converted With the auto-replace feature enabled (see :ref:`a_ui_edit_auto`), multiple hyphens are converted
automatically to short and long dashes, and three dots to ellipsis. The last auto-replace can always automatically to short and long dashes, and three dots to ellipsis. The last auto-replace can
be reverted with the undo command :kbd:`Ctrl`:kbd:`Z`, reverting the text to what you typed before always be reverted with the undo command :kbd:`Ctrl`:kbd:`Z`, reverting the text to what you typed
the automatic replacement occurred. before the automatic replacement occurred.
Single and Double Quotes Single and Double Quotes
@@ -36,14 +36,14 @@ All the different quotation marks listed on the `Quotation Mark`_ Wikipedia page
can be selected as auto-replaced symbols for straight single and double quote key strokes. The can be selected as auto-replaced symbols for straight single and double quote key strokes. The
settings can be found in the :guilabel:`Preferences`. settings can be found in the :guilabel:`Preferences`.
Ordinarily, text wrapped in quotes are highlighted by the editor. This is meant as a convenience for Ordinarily, text wrapped in quotes are highlighted by the editor. This is meant as a convenience
highlighting dialogue between characters. This feature can be disabled in the for highlighting dialogue between characters. This feature can be disabled in the
:guilabel:`Preferences` if this feature isn't wanted. :guilabel:`Preferences` if this feature isn't wanted.
The editor distinguishes between text wrapped in straight quotes and with the user-selected double The editor distinguishes between text wrapped in straight quotes and with the user-selected double
quote symbols. This is to help the writer recognise which parts of the text are not using the chosen quote symbols. This is to help the writer recognise which parts of the text are not using the
quote symbols. Two convenience functions in the :guilabel:`Format` menu can be used to re-format a chosen quote symbols. Two convenience functions in the :guilabel:`Format` menu can be used to
selected section of text with the correct quote symbols. re-format a selected section of text with the correct quote symbols.
.. _Quotation Mark: https://en.wikipedia.org/wiki/Quotation_mark .. _Quotation Mark: https://en.wikipedia.org/wiki/Quotation_mark
@@ -76,10 +76,10 @@ separate a number from its unit is with a `thin space`_. It is usually 2/3 the w
space. For numbers and units, this should in addition be a non-breaking space, that is, the text space. For numbers and units, this should in addition be a non-breaking space, that is, the text
wrapping should not add a line break on this particular space. wrapping should not add a line break on this particular space.
A regular space can also be made into a non-breaking space. A regular space can also be made into a non-breaking space if needed.
All non-breaking spaces are highlighted with a differently coloured packground. The colour will All non-breaking spaces are highlighted with a differently coloured background to make it easier to
depend on the selected colour theme. spot them in the text. The colour will depend on the selected colour theme.
The thin and non-breaking spaces are converted to their corresponding HTML codes on export to HTML The thin and non-breaking spaces are converted to their corresponding HTML codes on export to HTML
format. For plain text, they are exported as regular spaces. format. For plain text, they are exported as regular spaces.