Update docs for 2.0 (#1248)

Author: vkbo

docs/source/conf.py

@@ -42,7 +42,7 @@
 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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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,19 +47,19 @@ 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.
 
 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

@@ -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,25 +79,19 @@ 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
    keywords and synopsis export and disable body text, thus getting a document with each heading
    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,23 +103,27 @@ 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
    flat version of the document format as a single XML file. Most rich text editors support the
    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

@@ -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 ...