Update the introduction section

docs/source/index.rst

@@ -17,14 +17,12 @@ storage for robustness.
    :width: 500
 
 The project storage is suitable for version control software, and also well suited for file
-synchronisation tools. All text is saved as plain text files with a meta data header. The core
+synchronisation tools. All text is saved as plain text files, and your project data as standard
-project structure is stored in a single project XML file. Other meta data is saved as JSON files.
+data formats in XML and JSON. See :ref:`a_tech_overview` for more details.
-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
+Any operating system that has Python 3 and the Qt 5 libraries should be able to run novelWriter.
-novelWriter. It runs fine on Linux, Windows and MacOS, and users have tested it on other platforms
+It runs fine on Linux, Windows and MacOS, and users have tested it on other platforms as well.
-as well. novelWriter can be run directly from the Python source, or installed from packages or with
+See :ref:`a_started` for more details.
-pip. See :ref:`a_started` for more details.
 
 **Useful Links**
 
@@ -53,7 +51,6 @@ pip. See :ref:`a_started` for more details.
    int_overview
    int_started
    int_howto
-   int_customise
    int_glossary
 
 .. toctree::
@@ -83,6 +80,7 @@ pip. See :ref:`a_started` for more details.
    :caption: Additional Details
    :hidden:
 
+   more_customise
    more_projectformat
    more_counting
 
@@ -91,6 +89,7 @@ pip. See :ref:`a_started` for more details.
    :caption: Technical Topics
    :hidden:
 
+   tech_overview
    tech_locations
    tech_storage
    tech_source

docs/source/int_howto.rst

@@ -19,9 +19,9 @@ Managing the Project
 .. dropdown:: Merge Multiple Documents Into One
    :animate: fade-in-slide-down
 
-   If you need to merge a set of documents in your project into a single document, you can achieve
+   If you need to merge a selection of documents in your project into a single document, you can
-   this by first making a new folder for just that purpose, and drag all the files you want merged
+   achieve this by first making a new folder for just that purpose, and drag all the files you want
-   into this folder. Then you can right click the folder, select :guilabel:`Transform` and
+   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
@@ -36,7 +36,7 @@ Layout Tricks
 
    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`.
+   set the width of a tab in **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.
@@ -66,18 +66,13 @@ Organising Your Text
    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 a scene heading for hard scene breaks and a section heading
+   In such cases you may want to use different scene headings for hard and soft scene breaks. The
-   for soft scene breaks. The :guilabel:`Build Manuscript` tool will let you add separate
+   **Build Manuscript** tool will let you define a different format for scenes using the ``###``
-   formatting for the two when you generate your manuscript. You can for instance add the common
+   and ``###!`` heading codes when you generate your manuscript. You can for instance add the
-   "``* * *``" for hard breaks and select to hide section breaks, which will just insert an empty
+   common "``* * *``" for hard breaks and select to soft scene breaks, which will just insert an
-   paragraph in their place. See :ref:`a_manuscript_settings` for more details.
+   empty paragraph in their place. See :ref:`a_manuscript_settings` for more details.
-
-   Keep in mind that this is not what the section heading is intended for, so the app will not
-   understand the section heading as a scene, but it will be formatted correctly in the manuscript.
 
    .. versionadded:: 2.4
-      You can now distinguish between soft and hard scene breaks with a modified scene header. See
-      :ref:`a_manuscript_settings_head_hard` for more details.
 
 
 Other Tools

docs/source/int_introduction.rst

@@ -1,15 +1,21 @@
 .. _a_intro:
 
-************
+********
-Key Features
+Overview
-************
+********
 
 .. _Snowflake: https://www.advancedfictionwriting.com/articles/snowflake-method/
 .. _Markdown: https://en.wikipedia.org/wiki/Markdown
 
-At its core, novelWriter is a multi-document plain text editor. It uses a markup syntax inspired by
+At its core, novelWriter is a multi-document plain text editor. The idea is to let you edit your
-Markdown_ to apply simple formatting to the text. It also allows for some extended formatting codes
+text without having to deal with formatting until you generate a draft document or manuscript.
-using a shortcode format. See :ref:`a_fmt_shortcodes` for more details.
+Instead, you can focus on the writing right from the start.
+
+Of course, you probably need *some* formatting for your text. At the very least you need emphasis.
+Most people are familiar with adding emphasis using underscores and asterisks. This formatting
+standard comes from Markdown_ and is supported by novelWriter. It also uses Markdown formatting for
+defining document headings. If you need more specialised formatting, additional formatting options
+are available using a shortcode format. See :ref:`a_fmt_shortcodes` for more details.
 
 .. admonition:: Limitations
 
@@ -17,22 +23,28 @@ using a shortcode format. See :ref:`a_fmt_shortcodes` for more details.
    those relevant for this purpose. It is **not** suitable for technical writing, and it is **not**
    a full-featured Markdown editor.
 
-   It is also not intended as a tool to organise research for writing, and therefore lacks
+   It is also not intended as a tool for organising research for writing, and therefore lacks
    formatting features you may need for this purpose. The notes feature in novelWriter is mainly
    intended for character profiles and plot outlines.
 
-Your novel project is organised as a collection of separate plain text documents instead of a
+Your novel project in novelWriter is organised as a collection of separate plain text documents
-single, large document. The idea is to make it easier to reorganise your project structure without
+instead of a single, large document. The idea is to make it easier to reorganise your project
-having to cut and paste text between chapters.
+structure without having to cut and paste text between chapters and scenes.
 
 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 headings up into multiple documents,
-or merge multiple documents into single documents. This makes it easier to use variations of the
+or merge multiple documents into a single document. This makes it easier to use variations of the
 Snowflake_ method for writing. You can start by writing larger structure-focused documents, like
-one per act for instance, and later effortlessly split these up into chapters or scenes.
+for instance one document per act, and later effortlessly split these up into chapters or scenes.
+
+
+.. _a_intro_features:
+
+Key Features
+============
 
 Below are some key features of novelWriter.
 
@@ -40,12 +52,12 @@ Below are some key features of novelWriter.
    The aim of the user interface is to let you 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 panel itself is
+   switch the editor into **Focus Mode** where only the text editor panel itself is visible, and
-   visible, and the project structure view is hidden away.
+   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
+   The main window can optionally show a document viewer to the right of the editor. The viewer
-   panel is intended for displaying another scene document, your character notes, plot notes, or any
+   is intended for displaying another scene document, your character notes, plot notes, or any
    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.
 
@@ -58,32 +70,35 @@ Below are some key features of novelWriter.
    later split them into multiple documents based on chapter and scene headings.
 
 **Multi-novel project support**
-   You can have multiple Novel type root folders in a project. This allows you to keep a series of
+   The main parts of your project is split up into top level special folders called "Root" folders.
-   individual novels with the same characters and world building in the same project, and create
+   Your main story text lives in the "Novel" root folder. You can have multiple such folders in a
-   manuscripts for them individually.
+   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 story elements**
-   All notes in your project can be assigned a :term:`tag` that you can :term:`reference` from any
+   All notes in your project can be assigned a :term:`tag` that you can then :term:`reference` from
-   other document or note. In fact, you can add a new tag under each heading of a note if you need
+   any other document or note. In fact, you can add a new tag under each heading of a note if you
-   to be able to reference specific sections of it.
+   need to be able to reference specific sections of it.
 
 **Get an overview of your story**
-   In the :guilabel:`Outline View` on the main window you can see an outline of all the chapters,
+   It is not the documents themselves that define the chapters and scenes of your story, but the
-   scenes, and sections of your project. If they have any references in them, these are listed in
+   headings that separate them. In the **Outline View** on the main window you can see an outline
-   additional columns. You can also add a synopsis to each chapter or scene, which can be listed
+   of all the chapter and scene headings of your project. If they have any references in them, like
-   here as well. You have the option to add or remove columns of information from this outline. A
+   which character is in what chapter and scene, these are listed in additional columns.
-   subset of the outline information is also available in the :guilabel:`Novel View` as an
+
-   alternative view to the project tree.
+   You can also add a synopsis to each chapter or scene, 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 **Novel View** as an alternative view to the project tree.
 
 **Get an overview of your story elements**
-   Under the document viewer panel you will find a series of tabs that shows the different story
+   Under the document viewer panel you will find a series of tabs that show the different story
-   elements you have created tags for. The tabs are sorted into Characters, Plots, etc, depending
+   elements you have created tags for. The tabs are sorted into **Characters**, **Plots**, etc,
-   on which categories you are using in your story. This panel can be hidden to free up space when
+   depending on which categories you are using in your story. This panel can be hidden to free up
-   you don't need it.
+   space when you don't need it.
 
 **Assembling your manuscript**
    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
+   your chapters and scenes with a synopsis included, you can use the **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
@@ -95,7 +110,7 @@ Below are some key features of novelWriter.
 Screenshots
 ===========
 
-.. figure:: images/screenshot_default.png
+.. figure:: images/screenshot_light.png
    :class: dark-light
 
    novelWriter with light colour theme

docs/source/int_overview.rst

@@ -1,28 +1,22 @@
-.. _a_overview:
+.. _a_reading:
 
-********
+******************
-Overview
+What to Read First
-********
+******************
 
-.. only:: html
+The documentation of novelWriter is quite extensive. There are a lot of features to get used to,
+but you don't need all of them to get started.
 
-   .. image:: images/python_powered.png
+The chapters below labelled "Essential Information" are the ones you need to know to use the
-      :align: right
+application correctly. By "correctly", it is meant: in a way so novelWriter understands the basic
-      :width: 220
+structure of your text. It collects a lot of information from your text and uses it to display the
+structure of it in various ways to help you get an overview of your project.
 
-novelWriter is built as a cross-platform application using `Python 3 <https://www.python.org/>`_ as
+The chapters labelled "Recommended Reading" includes additional information on how the different
-the programming language, and `Qt 5 <https://www.qt.io/>`_ framework for the user interface.
+parts if the application work and what the features do. 
 
-novelWriter is built for Linux first, so this is where it works best. However, it also runs fine
+The "Optional" and "Lookup" chapters contain additional information or lookup tables that are not
-on Windows and MacOS due to the cross-platform framework it's built on. The author of the
+essential for using the application.
-application doesn't own a Mac, so on-going Mac support is dependent on user feedback and user
-contributions.
-
-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 install spell checking languages.
-
-For install instructions for novelWriter, see :ref:`a_started`.
 
 
 Using novelWriter
@@ -82,8 +76,8 @@ meta data for it to extract.
    the application interface.
 
 :ref:`a_manuscript` - Recommended Reading
-   This chapter explains how the :guilabel:`Manuscript Build` tool works, how you can control the
+   This chapter explains how the **Manuscript Build** tool works, how you can control the way
-   way chapter titles are formatted, and how scene and section breaks are handled.
+   chapter titles are formatted, and how scene and section breaks are handled.
 
 
 Additional Details & Technical Topics

docs/source/int_started.rst

@@ -1,8 +1,8 @@
 .. _a_started:
 
-***************
+**********************
-Getting Started
+Setup and Installation
-***************
+**********************
 
 .. _Enchant: https://abiword.github.io/enchant/
 .. _GitHub: https://github.com/vkbo/novelWriter
@@ -15,8 +15,8 @@ Getting Started
 .. _AppImage: https://appimage.org/
 
 Ready-made packages and installers for novelWriter are available for all major platforms, including
-Linux, Windows and MacOS, from the `Downloads page`_. See below for install instructions for each
+Linux, Windows and MacOS, from the `Downloads page`_. See below for install additional instructions
-platform.
+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,
@@ -44,7 +44,7 @@ multiple installations has been known to cause problems.
    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.
+   see an additional warning about this when you download and run the installer.
 
 
 .. _a_started_linux:
@@ -56,6 +56,7 @@ A Debian package can be downloaded from the `Downloads page`_, or from the Relea
 GitHub_. This package should work on both Debian, Ubuntu and Linux Mint, at least.
 
 If you prefer, you can also add the novelWriter repository on Launchpad to your package manager.
+The Launchpad packages `are signed by the author <https://launchpad.net/~vkbo>`__.
 
 
 Ubuntu

docs/source/tech_overview.rst

@@ -0,0 +1,20 @@
+.. _a_tech_overview:
+
+******************
+Technical Overview
+******************
+
+
+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/>`_ framework for the user interface.
+
+novelWriter is built for Linux first, so this is where it works best. However, it also runs fine
+on Windows and MacOS due to the cross-platform framework it's built on. The author of the
+application doesn't own a Mac, so on-going Mac support is dependent on user feedback and user
+contributions.
+
+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 install spell checking languages.
+
+For install instructions for novelWriter, see :ref:`a_started`.