diff --git a/docs/source/int_customise.rst b/docs/source/int_customise.rst index 7124b3a9..7b93249f 100644 --- a/docs/source/int_customise.rst +++ b/docs/source/int_customise.rst @@ -36,7 +36,8 @@ and add dictionaries yourself. A small tool to assist with this can be found under :guilabel:`Tools > Add Dictionaries`. It will import spell checking dictionaries from Free Office or Libre Office extensions. The dictionaries -are then installed in the install location for the Enchant library. +are then installed in the install location for the Enchant library and should thus work for any +application that uses Enchant for spell checking. **Manual Install** @@ -139,10 +140,10 @@ In the Main section you must at least define the ``name`` and ``icontheme`` sett ``typicons_light`` or ``typicons_dark``, or to an icon theme in your custom icons directory. The setting must match the icon theme's folder name. -The Palette values correspond to the Qt enum values for QPalette::ColorRole, see the +The Palette values correspond to the Qt enum values for ``QPalette::ColorRole``, see the `Qt documentation `_ for more details. The -colour values are RGB numbers on the format ``r, g, b`` where each is an integer from to 255. -Omitted values are not loaded and will use default values. +colour values are RGB numbers on the format ``r, g, b`` where each is an integer from ``0`` to +``255``. Omitted values are not loaded and will use default values. Custom Syntax Theme @@ -181,13 +182,13 @@ A syntax theme ``.conf`` file consists of the following settings: modifier = 0, 0, 0 In the Main section, you must define at least the ``name`` setting. The Syntax colour values are -RGB numbers of the format ``r, g, b`` where each is an integer from to 255. Omitted values default -to black, except ``background`` which defaults to white, +RGB(A) numbers of the format ``r, g, b, a`` where each is an integer ``0`` from to ``255``. The +fourth value is the alpha channel (transparency), which can be omitted. + +Omitted syntax colours default to black, except ``background`` which defaults to white. .. versionadded:: 2.2 - The `shortcode` syntax colour entry was added, so you need to update your custom themes if you - made any before version 2.2. + The `shortcode` syntax colour entry was added. .. versionadded:: 2.3 - The `optional` syntax colour entry was added, so you need to update your custom themes if you - made any before version 2.3. + The `optional` syntax colour entry was added. diff --git a/docs/source/int_glossary.rst b/docs/source/int_glossary.rst index 2cead9cf..7e9bd509 100644 --- a/docs/source/int_glossary.rst +++ b/docs/source/int_glossary.rst @@ -50,7 +50,7 @@ Glossary Headings Each level of headings in :term:`Novel Documents` have a specific meaning in terms of the structure of the story. That is, they determine what novelWriter considers a partition, a - chapter, a scene or a text section. For :term:`Project Notes`, the header levels don't + chapter, a scene or a text section. For :term:`Project Notes`, the heading levels don't matter. For more details on headings in novel documents, see :ref:`a_struct_heads`. Keyword diff --git a/docs/source/int_howto.rst b/docs/source/int_howto.rst index d3633f73..43f28601 100644 --- a/docs/source/int_howto.rst +++ b/docs/source/int_howto.rst @@ -25,7 +25,7 @@ Managing the Project :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. See :ref:`a_ui_tree_split_merge` for more details. + can rearrange them here of you wish. See :ref:`a_ui_tree_split_merge` for more details. Layout Tricks @@ -42,7 +42,7 @@ Layout Tricks 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. + to match. Especially if you don't use the same font in your manuscript as in the editor. Organising Your Text @@ -56,7 +56,9 @@ Organising Your Text 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). + documents of the chapter. + + .. versionadded:: 2.0 .. dropdown:: Distinguishing Soft and Hard Scene Breaks :animate: fade-in-slide-down @@ -64,12 +66,15 @@ 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 the scene heading for hard scene breaks and section headings + 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. + Other Tools =========== diff --git a/docs/source/int_introduction.rst b/docs/source/int_introduction.rst index 9bc89145..a23810bd 100644 --- a/docs/source/int_introduction.rst +++ b/docs/source/int_introduction.rst @@ -8,9 +8,18 @@ Key Features .. _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 is designed for writing fiction, so the -formatting features available are limited to those relevant for this purpose. It is *not* suitable -for technical writing, and it is *not* a full-featured Markdown editor. +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. + +.. admonition:: Limitations + + novelWriter is designed for writing fiction, so the formatting features available are limited to + 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 + 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 @@ -20,10 +29,10 @@ There are two kinds of documents in your project: :term:`Novel Documents` are do 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 +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 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 scenes by their headers. +one per act for instance, and later effortlessly split these up into chapters or scenes. Below are some key features of novelWriter. @@ -45,15 +54,15 @@ Below are some key features of novelWriter. build the project into a manuscript, 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 of the project tree. You can also start out with a few documents and then - later split them into multiple documents based on their headers. + drag-and-drop feature of the project tree. You can also start out with fewer documents and then + later split them into multiple documents based on chapter and scene headings. **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. + 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** +**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. @@ -69,10 +78,10 @@ Below are some key features of novelWriter. **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 when you don't need it - to free up space. + on which categories you are using in your story. This panel can be hidden to free up space when + you don't need it. -**Building your manuscript** +**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 do so. The tool lets you select what information you want to include in the generated document, diff --git a/docs/source/int_overview.rst b/docs/source/int_overview.rst index 69202c22..e83dcd58 100644 --- a/docs/source/int_overview.rst +++ b/docs/source/int_overview.rst @@ -11,9 +11,9 @@ Overview :width: 220 novelWriter is built as a cross-platform application using `Python 3 `_ as -the programming language, and `Qt 5 `_ for the user interface. +the programming language, and `Qt 5 `_ framework for the user interface. -novelWriter is built for Linux first, and this is where it works best. However, it also runs fine +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. @@ -22,7 +22,7 @@ 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, see :ref:`a_started`. +For install instructions for novelWriter, see :ref:`a_started`. Using novelWriter @@ -58,12 +58,6 @@ read on. your language, and other special characters. If you use any symbols aside from these, their intended use is explained here. -:ref:`a_prjfmt` – Optional - This chapter is more technical and has an overview of changes made to the way your project data - is stored. The format has changed a bit from time to time, and sometimes the changes require - that you make small modifications to your project. Everything you need to know is listed in this - chapter. - Organising Your Projects ======================== @@ -90,3 +84,11 @@ meta data for it to extract. :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. + + +Additional Details & Technical Topics +===================================== + +The Additional Details and the Technical Topics sections contain more in-depth information about +how various bits of novelWriter works. This information is not essential to getting started using +novelWriter. diff --git a/docs/source/int_started.rst b/docs/source/int_started.rst index e83c0a42..d53b68cb 100644 --- a/docs/source/int_started.rst +++ b/docs/source/int_started.rst @@ -6,7 +6,7 @@ Getting Started .. _Enchant: https://abiword.github.io/enchant/ .. _GitHub: https://github.com/vkbo/novelWriter -.. _main website: https://novelwriter.io +.. _Downloads page: https://download.novelwriter.io .. _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/ @@ -15,9 +15,10 @@ Getting Started .. _AppImage: https://appimage.org/ Ready-made packages and installers for novelWriter are available for all major platforms, including -Linux, Windows and MacOS. See below for install instructions for each platform. +Linux, Windows and MacOS, from the `Downloads page`_. See below for install instructions for each +platform. -You can also install novelWriter from the Python Package Index (PyPi). See :ref:`a_started_pip`. +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 the command line. @@ -32,7 +33,7 @@ Installing on Windows ===================== You can install novelWriter with both Python and library dependencies embedded using the Windows -Installer (setup.exe) file from the `main website`_, or from the Releases_ page on GitHub_. +Installer (setup.exe) file from the `Downloads page`_, or from the Releases_ page on GitHub_. Installing it should be straightforward. If you have any issues, try uninstalling the previous version and making a fresh install. If you @@ -51,8 +52,8 @@ multiple installations has been known to cause problems. Installing 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, at least. +A Debian package can be downloaded from the `Downloads page`_, or from the Releases_ page on +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. @@ -112,8 +113,8 @@ completely standalone images for the app that include the necessary environment They can of course be run on any Linux distro, if you prefer this to native packages. .. note:: - novelWriter generally don't support Python versions that have reached end of life. If your Linux - distro still uses older Python versions and novelWriter won't run, you may want to try the + novelWriter generally doesn't support Python versions that have reached end of life. If your + Linux distro still uses older Python versions and novelWriter won't run, you may want to try the AppImage instead. @@ -123,14 +124,14 @@ Installing on MacOS =================== You can install novelWriter with both its Python and library dependencies embedded using the DMG -application image file from the `main website`_, or from the Releases_ page on GitHub_. Installing -it should be straightforward. +application image file from the `Downloads page`_, or from the Releases_ page on GitHub_. +Installing it should be straightforward. * Download the DMG file and open it. Then drag the novelWriter icon to the :guilabel:`Applications` folder on the right. This will install it into your :guilabel:`Applications`. * The first time you try to launch it, it will say that the bundle cannot be verified, simply press the :guilabel:`Open` button to add an exception. -* If you are not presented with an :guilabel:`Open` button in the dialog launch the application +* If you are not presented with an :guilabel:`Open` button in the dialog, launch the application again by right clicking on the application in Finder and selecting :guilabel:`Open` from the context menu. @@ -149,7 +150,7 @@ Installing from PyPi ==================== novelWriter is also available on the Python Package Index, or PyPi_. This install method works on -all supported operating systems. +all supported operating systems with a suitable Python environment. To install from PyPi you must first have the ``python`` and ``pip`` commands available on your system. You can download Python from `python.org`_. It is recommended that you install the latest