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

Update the introduction section of the docs

Browse Source
This commit is contained in:
Veronica Berglyd Olsen
2023-10-08 18:50:33 +02:00
parent 976f73c41c
commit a3fdb3cfc4
9 changed files with 124 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/conf.py
+1 -1
View File
@@ -35,7 +35,7 @@ os.environ["TZ"] = "Europe/Oslo"
time.tzset()
needs_sphinx = "5.0"
extensions = []
extensions = ["sphinx_design"]
templates_path = ["_templates"]
source_suffix = ".rst"
master_doc = "index"
docs/source/images/python_win_install.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 96 KiB

docs/source/int_customise.rst
+7 -5
View File
@@ -17,14 +17,14 @@ Spell Check Dictionaries
========================
novelWriter uses Enchant_ as the spell checking tool. Depending on your operating system, it may or
may not load installed spell check dictionaries.
may not load installed spell check dictionaries automatically.
Linux and MacOS
---------------
On Linux and MacOS, you generally only have to install hunspell or aspell dictionaries on your
system like you do for other applications. See your distro or OS documentation for how to do this.
These dictionaries should then show up as available spell check languages in novelWriter.
These dictionaries should show up as available spell check languages in novelWriter.
Windows
-------
@@ -54,8 +54,9 @@ not exist, so you may need to create them.
Syntax and GUI Themes
=====================
Adding your own GUI and syntax themes is relatively easy. The themes are defined by simple plain
text config files with meta data and colour settings.
Adding your own GUI and syntax themes is relatively easy altough requires that you manually edit
config files with colour values. The themes are defined by simple plain text config files with meta
data and colour settings.
In order to make your own versions, first copy one of the existing files to your local computer and
modify it as you like.
@@ -81,7 +82,8 @@ set as ``name`` inside the file.
.. note::
In novelWriter 2.0 the ``icontheme`` value was added to GUI themes. Make sure you set this value
in existing custom themes. Otherwise it defaults to ``typicons_light``, which may not match your
theme colour scheme.
theme colour scheme. Otherwise, novelWriter will try to guess your icon theme, and may not pick
the most suitable one.
Gustom GUI and Icons Theme
docs/source/int_howto.rst
+44 -86
View File
@@ -9,117 +9,75 @@ Tips & Tricks
This is a list of hopefully helpful little tips on how to get the most out of novelWriter.
.. note::
This section will be expanded over time, and if you would like to have something added, feel
free to contribute, or start a discussion on the project's `Discussions Page`_
Overview
========
**Managing the Project**
* :ref:`a_howto_merge_documents`
**Layout Tricks**
* :ref:`a_howto_simple_table`
**Organising Your Text**
* :ref:`a_howto_chapter_intro`
* :ref:`a_howto_soft_hard_breaks`
**Other Tools**
* :ref:`a_howto_convert_ywriter`
How-Tos
=======
This section will be expanded over time, and if you would like to have something added, feel
free to contribute, or start a discussion on the project's `Discussions Page`_.
Managing the Project
--------------------
====================
.. dropdown:: Merge Multiple Documents Into One
:animate: fade-in-slide-down
.. _a_howto_merge_documents:
If you need to merge a set of documents in your project into a single document, you can achieve
this by first making a new folder for just that purpose, and drag all the files you want merged
into this folder. Then you can right click the folder, select :guilabel:`Transform` and
:guilabel:`Merge Documents in Folder`.
Merge Multiple Documents Into One
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you need to merge a set of documents in your project into a single document, you can achieve
this by first making a new folder for just that purpose, and drag all the files you want merged
into this folder. Then you can right click the folder, select :guilabel:`Transform` and
:guilabel:`Merge Documents in Folder`.
In the dialog that pops up, the documents will be in the same order as in the folder, but you can
also rearrange them here of you wish.
In the dialog that pops up, the documents will be in the same order as in the folder, but you
can also rearrange them here of you wish.
Layout Tricks
-------------
=============
.. dropdown:: Create a Simple Table
:animate: fade-in-slide-down
.. _a_howto_simple_table:
The formatting tools available in novelWriter don't allow for complex structures like tables.
However, the editor does render tabs in a similar way that regular word processors do. You can
set the width of a tab in :guilabel:`Preferences`.
Create a Simple Table
^^^^^^^^^^^^^^^^^^^^^
The tab key should have the same distance in the editor as in the viewer, so you can align text
in columns using the tab key, and it should look the same when viewed next to the editor.
The formatting tools available in novelWriter don't allow for complex structures like tables.
However, the editor does render tabs in a similar way to regular word processors. You can set the
width of a tab in :guilabel:`Preferences`.
The tab key should have the same distance in the editor as in the viewer, so you can align text in
columns using the tab key, and it should look the same when viewed next to the editor.
This is most suitable for your notes, as the result in exported documents cannot be guaranteed to
match.
This is most suitable for your notes, as the result in exported documents cannot be guaranteed
to match.
Organising Your Text
--------------------
====================
.. dropdown:: Add Introductory Text to Chapters
:animate: fade-in-slide-down
.. _a_howto_chapter_intro:
Sometimes chapters have a short preface, like a brief piece of text or a quote to set the stage
before the first scene begins.
Add Introductory Text to Chapters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you add separate files for chapters and scenes, the chapter file is the perfect place to add
such text. Separating chapter and scene files also allows you to make scene files child
documents of the chapter (added in novelWriter 2.0).
Sometimes chapters have a short preface, like a brief piece of text or a quote to set the stage
before the first scene -- Some text that may not be a part of the actual following scene.
.. dropdown:: Distinguishing Soft and Hard Scene Breaks
:animate: fade-in-slide-down
If you add separate files for chapters and scenes, this is the perfect place to add such text.
Separating chapter and scene files also allows you to set meta data for the whole chapter. Like
list all characters present in the chapter, etc.
Depending on your writing style, you may need to separate between soft and hard scene breaks
within chapters. Like for instance if you switch point-of-view character often.
.. _a_howto_soft_hard_breaks:
Distinguishing Soft and Hard Scene Breaks
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Depending on your writing style, you may need to separate between soft and hard scene breaks within
chapters. Like for instance if you switch point-of-view character often.
In such cases you may want to use the scene heading for hard scene breaks and section headings for
soft scene breaks. the :guilabel:`Project Build Tool` will let you add separate formatting for the
two when you generate your manuscript. You can for instance add the common "``* * *``" for hard
breaks and select to hide section breaks, which will just insert an empty paragraph in their place.
In such cases you may want to use the scene heading for hard scene breaks and section headings
for soft scene breaks. the :guilabel:`Build Manuscript` tool will let you add separate
formatting for the two when you generate your manuscript. You can for instance add the common
"``* * *``" for hard breaks and select to hide section breaks, which will just insert an empty
paragraph in their place.
Other Tools
-----------
===========
.. dropdown:: Convert Project to/from yWriter Format
:animate: fade-in-slide-down
.. _a_howto_convert_ywriter:
There is a tool available that lets you convert a `yWriter <http://spacejock.com/yWriter7.html>`_
project to a novelWriter project, and vice versa.
Convert Project to/from yWriter Format
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _yWriter: http://spacejock.com/yWriter7.html
There is a tool available that lets you convert a yWriter_ project to a novelWriter project, and
vice versa.
The tool is available at `peter88213.github.io/yw2nw <https://peter88213.github.io/yw2nw/>`__
The tool is available at `peter88213.github.io/yw2nw <https://peter88213.github.io/yw2nw/>`__
docs/source/int_introduction.rst
+35 -23
View File
@@ -4,19 +4,26 @@
Key Features
************
.. _Snowflake : https://www.advancedfictionwriting.com/articles/snowflake-method/
.. _Snowflake: https://www.advancedfictionwriting.com/articles/snowflake-method/
.. _Markdown: https://en.wikipedia.org/wiki/Markdown
At the core, novelWriter is a multi-document plain text editor. It uses a markup syntax inspired by
Markdown to apply simple formatting to the text. It is designed for writing fiction, so the
Markdown_ to apply simple formatting to the text. It is designed for writing fiction, so the
formatting features are limited to those relevant for this purpose. It is not suitable for
technical writing.
technical writing, and it is *not* a full feature Markdown editor.
Your novel project is organised as a collection of separate plain text documents instead of a
single, large document. The idea here is to make it easier to reorganise your project structure
without having to cut and paste text.
without having to cut and paste text between chapters.
You can at any point split documents by their header, or merge multiple documents into single
documents. This makes it easier to use variations of the popular Snowflake_ method for writing.
There are two kinds of documents in your project: :term:`Novel Documents` are documents that are
part of your story. The other kind of documents are :term:`Project Notes`. These are intended for
your notes about your characters, your world building, and so on.
You can at any point split the individual documents by their headers up into multiple documents, or
merge multiple documents into single documents. This makes it easier to use variations of the
popular Snowflake_ method for writing. You can focus on writing larger structure-focused documents,
like one per act for instance, and later effortlessly split these up into scenes by their headers.
Below are some key features of novelWriter.
@@ -24,43 +31,48 @@ Below are some key features of novelWriter.
The aim of the user interface is to let the user focus on writing instead of spending time
formatting text. Formatting is therefore limited to a small set of formatting tags for simple
things like text emphasis and paragraph alignment. When you really want to focus on just
writing, you can switch the editor into :guilabel:`Focus Mode` where only the text editor window
itself is vissible.
writing, you can switch the editor into :guilabel:`Focus Mode` where only the text editor panel
itself is vissible, and the project structure view is hidden away.
**Keep an eye on your notes**
The main window can optionally show a document viewer to the right of the editor. This view
panel is intended for displaying another scene document, you character notes, plot notes, or any
other document you may need to reference while writing.
other document you may need to reference while writing. It is not intended as a preview panel
for the document you're editing, but if you wish, you can also use it for this purpose.
**Organise your documents how you like**
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. You
can start out with a few documents and then later split the document into multiple documents
based on its headers.
can start out with a few documents and then later split them into multiple documents based on
their headers.
**Multi-novel project support**
As of novelWriter 2.0, you can have multiple Novel type root folders in a project. This allows
you to keep a series of individual novels with the same characters and world building in the
same project, and create manuscripts for them individually.
**Keep track of your plot elements**
All notes in your project can be assigned a *tag* you can *reference* from any other document or
note. In fact, you can add a new tag under each heading of a note if you need to be able to
reference a specific section. Note tags are organised into categories with specific reference
keywords.
All notes in your project can be assigned a :term:`tag` that you can :term:`reference` from any
other document or note. In fact, you can add a new tag under each heading of a note if you need
to be able to reference specific sections.
**Get an overview of your plot elements**
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
additional columns. You can also add a synopsis to each document, which can be listed here as
well. You have the option to add or remove columns of information from this outline. A subset of
the outline information is also available in the :guilabel:`Novel View` as a replacement for the
main project tree.
the outline information is also available in the :guilabel:`Novel View` as an alternative view
to the project tree.
**Building your manuscript**
Whether you want to compile a manuscript, or export all your notes, or generate an outline of
your chapters and scenes with a synopsis, you can use the :guilabel:`Build Novel Project` tool.
The tool lets you select what information you want to include in the generated document, and how
it is formatted. You can send the result to a printer, a PDF, or to an Open Document file that
can be opened by most office type word processors. You can also generate the result as HTML, or
Markdown, both suitable for further conversion to other formats.
Whether you want to assemble a manuscript, or export all your notes, or generate an outline of
your chapters and scenes with a synopsis, you can use the :guilabel:`Build Manuscript` tool to
do so. The tool lets you select what information you want to include in the generated document,
and how it is formatted. You can send the result to a printer, a PDF, or to an Open Document
file that can be opened by most office type word processors. You can also generate the result
as HTML, or Markdown, both suitable for further conversion to other formats.
.. _a_intro_screenshots:
docs/source/int_overview.rst
+9 -13
View File
@@ -10,23 +10,19 @@ Overview
:align: right
:width: 220
novelWriter is built on `Python 3 <https://www.python.org/>`_, a cross platform programming
language that doesn't require a compiler to build and run. That means that the code can run on your
computer right out of the box, or from a zip file.
novelWriter is built as a cross-platform application using `Python 3 <https://www.python.org/>`_ as
the programming language, and `Qt 5 <https://www.qt.io/>`_ for the user interface.
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 support for mac is dependant on user feedback and
contributions.
novelWriter is built for Linux first, and this is where it works best. However, it also runs fine
on Windows and MacOS due to being built with cross-platform tools. The author of the application
doesn't own a Mac, so on-going Mac support is dependant on user feedback and user contributions.
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
applications. It also uses a third party XML package. If you want spell checking, you also need the
spell check package Enchant developed for AbiWord
Spell checking in novelWriter is provided by a third party library called
`Enchant <https://abiword.github.io/enchant/>`_. Please see the section on :ref:`a_custom_dict` for
how to handle spell checking in different languages.
For install instructions, see :ref:`a_started`.
For information on how to add spell check dictionaries, see :ref:`a_custom_dict`.
Using novelWriter
=================
@@ -45,7 +41,7 @@ read on.
:ref:`a_fmt` – Essential Information
This section covers how you should format your text. The editor is plain text, so text
formatting requires some basic markup. The structure of your novel is also inferred by how you
use headings. Tags and references are implemented by simple codes.
use headings. Tags and references are implemented by special keywords.
:ref:`a_kb` – Optional / Lookup
This section lists all the keyboard shortcuts in novelWriter and what they do. Most of the
docs/source/int_started.rst
+25 -43
View File
@@ -10,7 +10,7 @@ Getting Started
.. _PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter
.. _Pre-Release PPA: https://launchpad.net/~vkbo/+archive/ubuntu/novelwriter-pre
.. _PyPi: https://pypi.org/project/novelWriter/
.. _python.org: https://www.python.org/downloads/windows
.. _python.org: https://www.python.org/downloads/
.. _Releases: https://github.com/vkbo/novelWriter/releases
.. _AppImage: https://appimage.org/
@@ -19,7 +19,7 @@ below for install instructions for each platform.
You can also install novelWriter from the Python Package Index (PyPi). See :ref:`a_started_pip`.
Installing from PyPi does not set up icon launchers, so you will either have to do this yourself,
or start novelWriter from command line.
or start novelWriter from the command line.
Spell checking in novelWriter is provided by a third party library called Enchant_. Generally, it
should pull dictionaries from your operating system automatically. However, on Windows they must be
@@ -36,7 +36,14 @@ Installer (setup.exe) file from the `main website`_, or from the Releases_ page
Installing it should be straightforward.
If you have any issues, try uninstalling the previous version and making a fresh install. If you
already had a version installed via a different method, you should uninstall that first.
already had a version installed via a different method, you should uninstall that first as having
multiple installations has been known to cause issues.
.. note::
The novelWriter installer is not signed because Microsoft doesn't currently provide a way for
non-profit open source projects to properly sign their installers. The novelWriter project
doesn't have the funding to pay for commercial software signing certificates. You will therefore
see an additional warning about this when you download the installer.
.. _a_started_linux:
@@ -68,7 +75,7 @@ Debian and Mint
---------------
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.
Mint. However, the above command will fail to add the signing key, as it is Ubuntu-specific.
Instead, run the following commands to add the repository and key:
@@ -85,12 +92,10 @@ Then run the update and install commands as for Ubuntu:
sudo apt install novelwriter
.. note::
You may need to use the Ubuntu 20.04 (focal) packages for Debian 11 or earlier. The newer Ubuntu
packages use a different compression algorithm that may not be supported.
.. tip::
If you get an error message like ``gpg: failed to create temporary file`` when importing the key
from the Ubuntu keyserver, try creating the folder it fails on, and import the key again:
@@ -106,6 +111,11 @@ For other Linux distros than the ones mentioned above, the primary option is App
completely standalone images for the app that include the necessary environment to run novelWriter.
They can of course be run on any Linux distro, if you prefer this to native packages.
.. note::
novelWriter generally stops supporting Python versions that have reached end of life. If your
Linux distro still uses older Python versions, you may want to try the AppImage instead.
.. _a_started_macos:
@@ -127,6 +137,11 @@ it should be straightforward.
The context menu can also be accessed by option-clicking if you have a one button mouse. This is
done by holding down the option key on your keyboard and clicking on the application in Finder.
.. note::
The novelWriter DMG is not signed because Apple doesn't currently provide a way for non-profit
open source projects to properly sign their installers. The novelWriter project doesn't have the
funding to pay for commercial software signing certificates.
.. _a_started_pip:
@@ -137,8 +152,9 @@ novelWriter is also available on the Python Package Index, or PyPi_. This instal
all supported operating systems.
To install from PyPi you must first have the ``python`` and ``pip`` commands available on your
system. If you are on Windows, and don't have Python installed, see :ref:`a_started_win_py` for
help.
system. You can download Python from `python.org`_. It is recommended that you install the latest
version. If you are on Windows, also make sure to select the "Add Python to PATH" option during
installation.
To install novelWriter from PyPi, use the following command:
@@ -159,38 +175,4 @@ When installing via pip, novelWriter can be launched from command line with:
novelwriter
Make sure the install location for pip is in your PATH variable. This is not always the case by
default.
.. note::
On systems with both Python 2 and 3, you may have to replace the ``pip`` command with ``pip3``.
.. _a_started_win_py:
Installing Python on Windows
----------------------------
In order to run novelWriter from source, or install from PyPi, you need to have Python set up on
your system. Unlike Linux and MacOS, Windows does not come with Python pre-installed.
You can download Python from `python.org`_. Python 3.8 or higher is required for running
novelWriter, but it is recommended that you install the latest version.
Make sure you select the "Add Python to PATH" option during installation, otherwise the ``python``
command will not work in the command line window.
.. figure:: images/python_win_install.png
:align: center
:width: 500
Screenshot of the Python installer on Windows.
When Python is installed, you should be able to run Python commands from the Command Prompt or
from PowerShell. You can verify this by running:
.. code-block:: bash
python --version
This should print out the version number of the Python installation.
default, and then you may get a "Not Found" error when running the ``novelwriter`` command.
docs/source/requirements.txt
+1
View File
@@ -1,5 +1,6 @@
sphinx-book-theme
sphinx>=5.0
sphinx-favicon
sphinx-design
pygments>=2.7
docutils>=0.17.1
docs/source/int_source.rst → docs/source/tech_source.rst
+2 -2
View File
@@ -13,8 +13,8 @@ to build the various components like the translation files and documentation.
.. note::
The text below assumes the command ``python`` corresponds to a Python 3 executable. Python 2 is
now deprecated, but many systems still have both Python 2 and 3. For such systems, the command
``python3`` may be needed instead. Likewise, ``pip`` may need to be replaced with ``pip3``.
now deprecated, but on many systems the command ``python3`` may be needed instead. Likewise,
``pip`` may need to be replaced with ``pip3``.
Most of the custom commands for building packages of novelWriter, or building assets, are contained
in the ``pkgutils.py`` script in the root of the source code. You can list the available commands