diff --git a/docs/source/images/python_powered.png b/docs/source/images/python_powered.png deleted file mode 100644 index d51df248..00000000 Binary files a/docs/source/images/python_powered.png and /dev/null differ diff --git a/docs/source/images/screenshot_dark.png b/docs/source/images/screenshot_dark.png index 7f581b72..03433a38 100644 Binary files a/docs/source/images/screenshot_dark.png and b/docs/source/images/screenshot_dark.png differ diff --git a/docs/source/images/screenshot_default.png b/docs/source/images/screenshot_default.png deleted file mode 100644 index 93ba2ac8..00000000 Binary files a/docs/source/images/screenshot_default.png and /dev/null differ diff --git a/docs/source/images/screenshot_light.png b/docs/source/images/screenshot_light.png new file mode 100644 index 00000000..bb7e22c7 Binary files /dev/null and b/docs/source/images/screenshot_light.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index b0020fc6..51c1226d 100644 --- a/docs/source/index.rst +++ b/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 -project structure is stored in a single project XML file. Other meta data is saved as JSON files. -See the :ref:`a_breakdown_storage` section for more details. +synchronisation tools. All text is saved as plain text files, and your project data as standard +data formats in XML and JSON. See :ref:`a_tech_overview` 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 -as well. novelWriter can be run directly from the Python source, or installed from packages or with -pip. See :ref:`a_started` for more details. +Any operating system that has Python 3 and 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 as well. +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 diff --git a/docs/source/int_howto.rst b/docs/source/int_howto.rst index fe5b22fa..bab60b39 100644 --- a/docs/source/int_howto.rst +++ b/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 - 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 + If you need to merge a selection 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 @@ -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 - 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. 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. + In such cases you may want to use different scene headings for hard and soft scene breaks. The + **Build Manuscript** tool will let you define a different format for scenes using the ``###`` + and ``###!`` heading codes when you generate your manuscript. You can for instance add the + common "``* * *``" for hard breaks and select to soft scene breaks, which will just insert an + empty paragraph in their place. See :ref:`a_manuscript_settings` for more details. .. 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 diff --git a/docs/source/int_introduction.rst b/docs/source/int_introduction.rst index a23810bd..c67588e7 100644 --- a/docs/source/int_introduction.rst +++ b/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 -Markdown_ to apply simple formatting to the text. It also allows for some extended formatting codes -using a shortcode format. See :ref:`a_fmt_shortcodes` for more details. +At its core, novelWriter is a multi-document plain text editor. The idea is to let you edit your +text without having to deal with formatting until you generate a draft document or manuscript. +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 -single, large document. The idea is to make it easier to reorganise your project structure without -having to cut and paste text between chapters. +Your novel project in novelWriter is organised as a collection of separate plain text documents +instead of a single, large document. The idea is to make it easier to reorganise your project +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 - visible, and the project structure view is hidden away. + switch the editor into **Focus Mode** where only the text editor panel itself is visible, 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, your character notes, plot notes, or any + The main window can optionally show a document viewer to the right of the editor. The viewer + 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 - individual novels with the same characters and world building in the same project, and create - manuscripts for them individually. + The main parts of your project is split up into top level special folders called "Root" folders. + Your main story text lives in the "Novel" root folder. You can have multiple such 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 story elements** - 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 of it. + All notes in your project can be assigned a :term:`tag` that you can then :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 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, - 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 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 :guilabel:`Novel View` as an - alternative view to the project tree. + It is not the documents themselves that define the chapters and scenes of your story, but the + headings that separate them. In the **Outline View** on the main window you can see an outline + of all the chapter and scene headings of your project. If they have any references in them, like + which character is in what chapter and scene, these are listed in additional columns. + + 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 - elements you have created tags for. The tabs are sorted into Characters, Plots, etc, depending - on which categories you are using in your story. This panel can be hidden to free up space when - you don't need it. + 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 on which categories you are using in your story. This panel can be hidden to free up + 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 diff --git a/docs/source/int_overview.rst b/docs/source/int_overview.rst index e83dcd58..96c938b7 100644 --- a/docs/source/int_overview.rst +++ b/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 - :align: right - :width: 220 +The chapters below labelled "Essential Information" are the ones you need to know to use the +application correctly. By "correctly", it is meant: in a way so novelWriter understands the basic +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 `_ as -the programming language, and `Qt 5 `_ framework for the user interface. +The chapters labelled "Recommended Reading" includes additional information on how the different +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 -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 `_. 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`. +The "Optional" and "Lookup" chapters contain additional information or lookup tables that are not +essential for using the application. 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 - way chapter titles are formatted, and how scene and section breaks are handled. + This chapter explains how the **Manuscript Build** tool works, how you can control the way + chapter titles are formatted, and how scene and section breaks are handled. Additional Details & Technical Topics diff --git a/docs/source/int_started.rst b/docs/source/int_started.rst index d53b68cb..d361de2f 100644 --- a/docs/source/int_started.rst +++ b/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 -platform. +Linux, Windows and MacOS, from the `Downloads page`_. See below for install additional 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, @@ -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 `__. Ubuntu diff --git a/docs/source/int_customise.rst b/docs/source/more_customise.rst similarity index 100% rename from docs/source/int_customise.rst rename to docs/source/more_customise.rst diff --git a/docs/source/tech_overview.rst b/docs/source/tech_overview.rst new file mode 100644 index 00000000..b6851333 --- /dev/null +++ b/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 `_ as +the programming language, and `Qt 5 `_ 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 `_. 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`.