diff --git a/docs/source/index.rst b/docs/source/index.rst index e3e25614..70392df7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -28,21 +28,25 @@ novelWriter |release| **Last Updated:** |today| -novelWriter is a markdown-like text editor designed for writing novels and larger projects of many -smaller plain text documents. It uses its own flavour of markdown that supports a meta data syntax -for comments, synopsis and cross-referencing between documents. The idea is to have a simple text -editor which allows for easy organisation of text documents and notes, built on a plain text file -project repository for robustness. +novelWriter is a plain text editor designed for writing novels assembled from many smaller text +documents. It uses a minimal formatting syntax inspired by Markdown, and adds a meta data syntax +for comments, synopsis, and cross-referencing. It is designed to be a simple text editor that +allows for easy organisation of text and notes, using human readable text files as storage for +robustness. -The plain text storage is suitable for version control software, and also well suited for file -synchronisation tools. The core project structure is stored in a single project XML file. Other -meta data is primarily saved as JSON files. +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 primarily saved as +JSON files. See also the :ref:`a_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, or installed from the pip tool or via -the provided setup script. See :ref:`a_started`, or one or the setup instructions for your -operating system for further details. +too. novelWriter can be run directly from the Python source, installed from the pip tool. + +You can also download a minimal archive package of novelWriter tailored for your operating system. +This package can be extracted anywhere on your computer, and a setup script can be run to create +the necessary icons and file associations. See :ref:`a_started`, or one or the setup instructions +for your operating system for further details. **Useful Links** @@ -68,17 +72,24 @@ operating system for further details. .. toctree:: :maxdepth: 2 - :caption: Usage + :caption: Using novelWriter usage_interface + usage_format usage_shortcuts - usage_projects - usage_structure - usage_notes - usage_export usage_typography +.. toctree:: + :maxdepth: 2 + :caption: Organising Your Project + + project_overview + project_structure + project_notes + project_export + + .. toctree:: :maxdepth: 2 :caption: Under the Hood diff --git a/docs/source/int_introduction.rst b/docs/source/int_introduction.rst index 0759c3bc..4b66092e 100644 --- a/docs/source/int_introduction.rst +++ b/docs/source/int_introduction.rst @@ -4,17 +4,35 @@ Introduction ************ -novelWriter is a simple, multi-document plain text editor using a modified markdown syntax to apply -simple formatting to the text. It is designed for writing novels, and allows for the component -documents to be ordered freely to create the desired structure of the novel. More details about how -projects are structured is covered in :ref:`a_struct`. +novelWriter is a simple, 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. -In addition, the project can contain notes on the various plot elements, characters, locations, -etc, that make up the story. These notes are organised in a set of category-specific top-level -folders referred to as "root folders", and each entry can be tagged and cross-referenced from -within the novel documents and notes. These tags make it possible to inter-link documents, and -generate an overview of the entire novel project and how the various documents and plot elements -are interconnected. The tag and reference syntax is covered in :ref:`a_proj` and :ref:`a_notes`. +The idea is to let the user focus on writing instead of spending time messing with the formatting +of headers and text. Therefore you cannot change the look of the text in the editor window. +Instead, you provide formatting tags where they're needed, like for instance which text is a +header, where you want text bolded or italicised, and what alignment you want for paragraphs. The +actual formatting is then added to the text when you run the :guilabel:`Build Novel Project` tool. + +A document viewer to the right of the editor can also show a renderred version of any document if +you want to inspect the result, or just want to keep a second document open for reference when +you're writing. + +You can split your novel project up into as many individual files as you want to. The files are +glued together when you build the project, in the top-to-bottom order in which they appear in the +project tree. Splitting the project up into chapter and scene files means you can easily reorder +them using the drag and drop feature. More details about how projects are structured is covered in +:ref:`a_struct`. + +In addition to novel text documents, the project can contain notes on the various plot elements, +characters, locations, etc, that make up the story. These notes are organised in a set of +category-specific top-level folders referred to as *Root Folders*. Each note can be assigned one or +more tags (one tag is allowed for each heading in the note), and these tags can be referenced from +within the novel documents and other notes. + +These tags make it possible to inter-link documents, and you can also generate an overview of the +entire novel project and how the various documents and plot elements are interconnected. The tag +and reference syntax is covered in :ref:`a_proj` and :ref:`a_notes`. These features are available through special meta keywords described in :ref:`a_struct_tags`. Syntax highlighting is provided to make it easier to verify that the markdown tags are used @@ -41,10 +59,10 @@ at the same time provide a complete set of features needed for writing a novel. tabs and line breaks. The tab stop width can be specified in :guilabel:`Preferences`. The main window does not have a toolbar like many other applications do. This reduces clutter, and -since the documents are formatted with style tags, is more or less redundant. However, all +since the documents are formatted with style tags, is more or less redundant. However, most formatting features supported are available through convenient keyboard shortcuts. They are also -available in the main menu so you don't have to look up formatting codes every time you need them, -before you've memorised them. A full list of shortcuts can be found in the :ref:`a_kb` section. +available in the main menu so you don't have to look up formatting codes every time you need them. +A full list of shortcuts can be found in the :ref:`a_kb` section. In addition, novelWriter has a :guilabel:`Focus Mode` where all the user interface elements other than the document editor itself are hidden away. @@ -58,14 +76,15 @@ are based on the Typicons_ icon set designed by Stephen Hutchings. The main window is split in two, or optionally three, panels. The left-most panel contains the project tree and all the documents in your project. The second panel is the document editor. An optional third panel is a document viewer which can view any document in your project independently -of the document editor. It is not intended as a preview window, although you can use it for this, -but for viewing your notes next to your editor while you're writing. +of what is open in the document editor. It is not intended as a preview window, although you can +use it for this. The main purpose of the viewer is for viewing your notes next to your editor +while you're writing. A second tab is also available on the main window. This is the :guilabel:`Outline` tab where the entire novel structure can be displayed, with all the tags and references listed. Depending on how you structure your novel documents, this outline can be quite different from your project tree. Your project tree lists individual documents, your Outline tree lists the structure of the novel -itself in terms of partitions, chapters and scenes as it appears in the text of the documents. +itself in terms of partitions, chapters and scenes as it appears in the text of those documents. .. _Typicons: https://github.com/stephenhutchings/typicons.font @@ -105,11 +124,13 @@ The HTML5 export format is suitable for conversion by a number of other tools li importing into word processors if the Open Document format isn't suitable. In addition, printing and printing to PDF is also possible. -It is also possible to export the content of the project to a JSON file. This is useful if you want -to write your own processing script in for instance Python as the entire novel can be read into a -Python dictionary with a couple of lines of code. +You can also export the content of the project to a JSON file. This is useful if you want to write +your own processing script in for instance Python as the entire novel can be read into a Python +dictionary with a couple of lines of code. The JSON file can be populated either with HTML +formatted text, or with the raw text as typed into the novel documents. See :ref:`a_export_options` +for more details. -A number of filter options can be applied to the produced document, allowing you to export a draft +A number of filter options can be applied to the Build tool, allowing you to export a draft manuscript, a reference document of notes, an outline based on chapter and scene titles with a synopsis each, and so on. See :ref:`a_export` for more details on export features and formats. diff --git a/docs/source/int_started.rst b/docs/source/int_started.rst index 031284c7..cf48a76b 100644 --- a/docs/source/int_started.rst +++ b/docs/source/int_started.rst @@ -54,6 +54,10 @@ back to using the internal ``difflib`` of Python to check spelling. This is a sl sophisticated spell checker than the full spell checking libaries. The spell check library must be at least 3.0 to work with Windows. On Linux, 2.0 also works fine. +If you do use the internal spell checker, you also have to provide a text file with a list of all +words correctly spelled. One word on each line. Dictionary files for English is included with +novelWriter. For other languages, you will need to add more files yourself. + If you install from PyPi, these dependencies should be installed automatically. If you install from source, dependencies can still be installed from PyPi with: @@ -64,16 +68,18 @@ source, dependencies can still be installed from PyPi with: .. _a_started_install: -Installing via PyPi -=================== +Installing from Source or PyPi +============================== -The application is written in Python 3 using Qt5 via PyQt5. It is developed on Linux, but it should -in principle work fine on other operating systems as long as dependencies are met. +You can download the latest version of novelWriter from the source repository on GitHub_. You can +also install novelWriter from PyPi_. -You can download the latest version of novelWriter from the source repository on GitHub_. -novelWriter is also hosted on PyPi_, and can be installed on all operating systems that support Qt5 -and Python 3. It is regularly tested on Linux, Windows and macOS. The latest version of novelWriter -is |release|. +If you're running novelWriter from source, the main setup script has a number of options that may +be useful to you. You can list them by running: + +.. code-block:: console + + python setup.py --help To install from PyPi you must first have the ``python`` and ``pip`` commands available on your system. If you don't, see specific instructions for your operating system in this documentation. @@ -120,8 +126,8 @@ needed package is called `qttools5-dev-tools`. .. note:: If you want to improve novelWriter with translation files for another language, or update an - existing translation, instructions for how to contribute can be found in the README file in the - ``i18n`` folder of the source code. + existing translation, instructions for how to contribute can be found in the README.md file in + the ``i18n`` folder of the source code. .. _a_started_docs: @@ -129,7 +135,7 @@ needed package is called `qttools5-dev-tools`. Building the Documentation ========================== -If you installed novelWriter from a package, the documentation should be bre-built and included. If +If you installed novelWriter from a package, the documentation should be pre-built and included. If you're running novelWriter from the source code, a local copy of this documentation can be generated. It requires the following Python packages on Debian and Ubuntu. diff --git a/docs/source/usage_export.rst b/docs/source/project_export.rst similarity index 80% rename from docs/source/usage_export.rst rename to docs/source/project_export.rst index 169e4310..5fc22cf3 100644 --- a/docs/source/usage_export.rst +++ b/docs/source/project_export.rst @@ -28,13 +28,14 @@ a series of keyword–replace steps. They are all on the format ``%keyword%``. instance Prologue and Epilogue chapters. ``%chw%`` - Behaves like ``%ch%``, but the number is represented as a number word. + Behaves like ``%ch%``, but the number is represented as a number word. You can select between a + number of different languages. ``%chi%`` - Begaves like ``%ch%``, but the number is represented as a lower case Roman number. + Begaves like ``%ch%``, but represented as a lower case Roman number from 1 to 4999. ``%chI%`` - Behaves like ``%ch%``, but the number is represented as an upper case Roman number. + Behaves like ``%ch%``, but represented as an upper case Roman number from 1 to 4999. ``%sc%`` This is the number counter equivalent for scenes. These are incremented each time a heading of @@ -49,9 +50,7 @@ a series of keyword–replace steps. They are all on the format ``%keyword%``. This inserts a line break within the title. .. note:: - Header formatting only applies to novel documents. Headings in notes will be left as-is on - export. However, heading levels 1 through 4 are converted to the correct heading level in the - respective output formats. + Header formatting only applies to novel documents. Headings in notes will be left as-is. **Example** @@ -67,7 +66,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. +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 @@ -80,10 +79,9 @@ 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 select any document -that isn't classified as a note. The switch for :guilabel:`Include note files` will select any -document that *is* a note. This allows for exporting just the novel, just your notes, or both, as -you see fit. +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. @@ -95,9 +93,10 @@ exclude the body text itself. 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 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. +: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. .. _a_export_print: @@ -106,8 +105,8 @@ Printing ======== The print button allows you to print the content in the preview window. You can either print to one -of your system's printers, or print directly to file. You can also print to file from the regular -print dialog. The direct to file option is just a shortcut. +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. .. _a_export_formats: @@ -119,7 +118,8 @@ Currently, six formats are supported for exporting. 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. + 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 @@ -134,7 +134,7 @@ novelWriter Markdown 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 of strikethrough text, which is not supported + 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. diff --git a/docs/source/usage_notes.rst b/docs/source/project_notes.rst similarity index 100% rename from docs/source/usage_notes.rst rename to docs/source/project_notes.rst diff --git a/docs/source/usage_projects.rst b/docs/source/project_overview.rst similarity index 86% rename from docs/source/usage_projects.rst rename to docs/source/project_overview.rst index e26611f1..95562407 100644 --- a/docs/source/usage_projects.rst +++ b/docs/source/project_overview.rst @@ -4,11 +4,11 @@ Novel Projects ************** -A new project can be created from the :guilabel:`Project` menu by selecting -:guilabel:`New Project`. This will open the :guilabel:`New Project Wizard` that will assist you in -creating a barebone project suited to your needs. A novelWriter project requires a dedicated folder -for storing its files on the local file system. See :ref:`a_tech` for further details on how files -are organised. +New projects can be created from the :guilabel:`Project` menu by selecting :guilabel:`New Project`. +This will open the :guilabel:`New Project Wizard` that will assist you in creating a barebone +project suited to your needs. A novelWriter project requires a dedicated folder for storing its +files on the local file system. See :ref:`a_storage` for further details on how files are +organised. A list of recently opened projects is maintained, and displayed in the :guilabel:`Open Project` dialog. A project can be removed from this list by selecting it and pressing the :kbd:`Del` key or @@ -25,18 +25,20 @@ including word counts, and a table of contents with word and page counts, is ava Project Roots ============= -Projects are structured into a set of top level folders called *root folders*. They are visible in +Projects are structured into a set of top level folders called "Root Folders". They are visible in the project tree at the left side of the main window. -The core novel documents go into a root folder of type :guilabel:`Novel`. Other supporting -documents go into the other root folders. These other root folder types are intended for your notes -on the various elements of your story. Using them is of course entirely optional. +The novel documents go into a root folder of type :guilabel:`Novel`. Project notes go into the +other root folders. These other root folder types are intended for your notes on the various +elements of your story. Using them is of course entirely optional. A new project may not have all of the root folders present, but you can add the ones you want from :guilabel:`Create Root Folder` in the :guilabel:`Project` menu. -The root folders are intended for the following use, but aside from the :guilabel:`Novel` folder, -no restrictions are enforced by the application. You can use them however you want. +Each root folder has one or more reference keyword associated with it that can be used to reference +content in your notes from other documents and notes. The intended usage of each type of root +folder is listed below. However, aside from the :guilabel:`Novel` folder, no restrictions are +applied by the application. You can use them however you want. :guilabel:`Novel` This is the root folder of all text that goes into the final novel. This class of documents have @@ -45,7 +47,7 @@ no restrictions are enforced by the application. You can use them however you wa :guilabel:`Plot` This is the root folder where main plots can be outlined. It is optional, but adding at least - dummy notes can be useful in order to tag plot elements for the Outline view. Tags in this + brief notes can be useful in order to tag plot elements for the Outline view. Tags in this folder can be references using the ``@plot`` keyword. :guilabel:`Characters` @@ -81,9 +83,8 @@ The root folders correspond to the categories of tags that can be used to refere information about the tags listed, see :ref:`a_struct_tags`. .. tip:: - You can rename root folders to whatever you want. The first character in the :guilabel:`Flags` - column in the project tree will still indicate what type they are, and so will the icon if you - are using one of the optional icon sets. + You can rename root folders to whatever you want. However, this doesn't change the reference + keyword. .. _a_proj_roots_del: @@ -127,7 +128,7 @@ file synchronisation tool that runs out of sync, there may be files in the proje aren't tracked in the core project file. These files, when discovered, are recovered and added back into the project if possible. -The discovered files are scanned for meta information that gives clues as to where the document may +The discovered files are scanned for meta information that give clues as to where the document may previously have been located in the project. The project loading routines will try to put them back as close as possible to this location, if it still exists. Generally, it will be appended to the end of the folder where it previously was located. If that folder doesn't exist, it will try to add @@ -180,7 +181,7 @@ documents. .. tip:: You can use folders to sort your scene documents into chapters. You will still need to add a chapter document as the first item of your chapter folder, and the scene documents as the - following items. Another way to use folders is to make a folder for each act. + following items. Other ways to use folders is to make a folder for each act or part. .. _a_proj_files: @@ -192,12 +193,12 @@ New documents can be created from the :guilabel:`Document` menu, or by pressing while in the project tree. This will create a new, empty document, and open the :guilabel:`Item Settings` dialog where the document label and various other settings can be changed. This dialog can also be opened again later from either the :guilabel:`Project` menu, selecting :guilabel:`Edit -Project Item`, or by pressing :kbd:`Ctrl`:kbd:`E` or :kbd:`F2` with the item selected. +Project Item`, or by pressing :kbd:`F2` with the item selected. The layout of the document is also defined here. The two options available are :guilabel:`Novel -Document` and :guilabel:`Project Note`. These behave slightly differently when the project is -built. A project note is never treated as part of the novel, no matter where in the project it is -located. See :ref:`a_struct_layout` for more details. +Document` and :guilabel:`Project Note`. These behave differently when the project is built. A +project note is never treated as part of the novel, no matter where in the project it is located. +See :ref:`a_struct_layout` for more details. You can also select whether the document is by default included when building the project. This setting can be overridden in the :guilabel:`Build Novel Project` tool if you wish to include them @@ -245,8 +246,8 @@ Title` should remain unchanged throughout the project, otherwise the name of exp backup files may change too. The :guilabel:`Book Title` and :guilabel:`Book Authors` settings are currently not used for -anything, so setting then is just for the benefit of the author. Future features may be using them, -and they are exported on some export formats in the :guilabel:`Build Novel Project` tool. +anything, so setting them is just for the benefit of the author. Future features may use them, and +they are exported on some export formats in the :guilabel:`Build Novel Project` tool. If your project is in a different language than your main spell checking is set to, you can override the default spell checking language here. You can also override the automatic backup @@ -304,7 +305,7 @@ are stored in a subfolder of the backup path. The subfolder will have the same n :guilabel:`Working Title` set in :ref:`a_proj_settings`. The backup feature, when configured, can also be run manually from the :guilabel:`Tools` menu. -It is also possible to disable automated backup for a given project in :guilabel:`Project +It is also possible to disable automated backups for a given project in :guilabel:`Project Settings`. .. note:: @@ -326,11 +327,11 @@ file in the ``meta`` folder in the directory where you saved your project. The f A tool to view the content of this file is available in the :guilabel:`Tools` menu under :guilabel:`Writing Statistics`. You can also launch it by pressing :kbd:`F6`. -The tool will show a list of all your sessions, and a set of filters to apply to it. You can also -export the filtered data to a JSON file or to a CSV file that can be opened by a spreadsheet +The tool will show a list of all your sessions, and a set of filters to apply to the data. You can +also export the filtered data to a JSON file or to a CSV file that can be opened by a spreadsheet application like for instance Libre Office Calc. As of version 1.2, the log file also stores how much of the session time was spent idle. The -definition of idle here is that the novelWriter main window loses focus, and the user hasn't made +definition of idle here is that the novelWriter main window loses focus, or the user hasn't made any changes to the currently open document in five minutes. The number of minutes can be altered in :guilabel:`Preferences`. diff --git a/docs/source/usage_structure.rst b/docs/source/project_structure.rst similarity index 76% rename from docs/source/usage_structure.rst rename to docs/source/project_structure.rst index a5dccc98..48981341 100644 --- a/docs/source/usage_structure.rst +++ b/docs/source/project_structure.rst @@ -19,7 +19,7 @@ Subfolders under root folders have no impact on the structure of the novel itsel instead dictated by the heading level of the headers within the documents. Four levels of headings are supported, signified by the number of hashes (``#``) preceding the -title. See also the :ref:`a_ui_md` section for more details about the markdown syntax. +title. See also the :ref:`a_fmt` section for more details about the markdown syntax. .. note:: The header levels are not only important when generating the exported novel file, they are also @@ -27,28 +27,30 @@ title. See also the :ref:`a_ui_md` section for more details about the markdown s :guilabel:`Novel` tab of the project tree. Each heading also starts a new region where new references and tags can be defined. -The different header levels are interpreted as specific section types of the novel in the following -way: +The syntax for the four basic header types, and the two special header types, is listed in section +:ref:`a_fmt_head`. The meaning of the four levels for the structure of your novel is as follows: -``# Header1`` - Header level one signifies that the text refers to a top level partition. This is useful when - you want to split the manuscript up into books, parts, or acts. +**Header Level 1** + This header level signifies that the text refers to a top level partition. This is useful when + you want to split the manuscript up into books, parts, or acts. These headings are not required. + The novel title itself should use the special header level one code explained in + :ref:`a_fmt_head`. -``## Header2`` - Header level two signifies a chapter level partition. Each time you want to start a new chapter, - you must add such a heading. If you choose to split your manuscript up into one document per - scene, you need a single chapter document with just the heading. You can of course also add a - synopsis and reference keywords to the chapter document. If you want to open the chapter with a - quote or other introductory text that isn't part of a scene, this is also where you'd put that - text. +**Header Level 2** + This header level signifies a chapter level partition. Each time you want to start a new + chapter, you must add such a heading. If you choose to split your manuscript up into one + document per scene, you need a single chapter document with just the heading. You can of course + also add a synopsis and reference keywords to the chapter document. If you want to open the + chapter with a quote or other introductory text that isn't part of a scene, this is also where + you'd put that text. -``### Header3`` - Header level three signifies a scene level partition. You must provide a title text, but the +**Header Level 3** + This header level signifies a scene level partition. You must provide a title text, but the title text can be replaced with a scene separator or just skipped entirely when you export your manuscript. -``#### Header4`` - Header level four signifies a sub-scene level partition, usually called a "section" in the +**Header Level 4** + This header level signifies a sub-scene level partition, usually called a "section" in the documentation and the user interface. These can be useful if you want to change tag references mid-scene, like if you change the point-of-view character. You are free to use sections as you wish, and can filter them out of the final manuscript just like with scene titles. @@ -65,13 +67,14 @@ Novel Title and Front Matter ---------------------------- It is recommended that you add a document at the very top of your project with the novel title as -the first line. You should modify the header format code with an ``!`` in order to render it as a -document title that is excluded from any automatic Table of Content in an exported document, like -so: +the first line. You should modify the level 1 header format code with an ``!`` in order to render +it as a document title that is excluded from any automatic Table of Content in an exported +document, like so: ``#! My Novel`` -The title is by default centred on the page. You can add more text to the page as you wish. +The title is by default centred on the page when exported. You can add more text to the page as you +wish, like for instance the author's name and details. If you want an additional page inserted after the title page, starting on a fresh page, you can add ``[NEW PAGE]`` on a line by itself, and continue the text after it. This will insert a page break @@ -84,8 +87,8 @@ Unnumbered Chapter Headings --------------------------- If you use the automatic numbering feature for your chapters, but you want to keep some special -chapters separate from this, you cam add a ``!`` to the header formatting code to tell the build -tool to skip these chapters. +chapters separate from this, you cam add a ``!`` to the level 2 header formatting code to tell the +build tool to skip these chapters. ``##! Unnumbered Chapter Title`` @@ -94,8 +97,9 @@ tool as well. See the :ref:`a_export` page for more details. .. Note:: Previously, you could also disable the automatic numbering of a chapter by adding an ``*`` as - the first character if the chapter title itself. This feature has been dropped in favour of the - current format. Please update your chapter headings if you've used this syntax. + the first character of the chapter title itself. This feature has been dropped in favour of the + current format in order to keep level 1 and 2 headers consistent. Please update your chapter + headings if you've used this syntax. .. _a_struct_tags: @@ -151,7 +155,8 @@ allow multiple values. ``@custom`` Custom references in the current section. The target must be a note tag in a :guilabel:`Custom` - type root folder. + type root folder. You can add more than one Custom folder, but they all use the same reference + keyword. The syntax highlighter will alert the user that the tags and references are used correctly, and that the tags referenced exist. diff --git a/docs/source/setup_linux.rst b/docs/source/setup_linux.rst index cf3ee580..bdef783f 100644 --- a/docs/source/setup_linux.rst +++ b/docs/source/setup_linux.rst @@ -46,8 +46,8 @@ You can install novelWriter to the default location for Python packages using `` step is optional as you can also just put the novelWriter program folder wherever you like yourself. For instance in ``/opt/novelWriter``, and then run Step 3 to set up icons and launcher. -To install novelWriter to the default location, it requires that you have ``setuptools`` installed -on your system. If you don't have it installed, it can usually be installed from your distro's +To install novelWriter to the default location requires that you have ``setuptools`` installed on +your system. If you don't have it installed, it can usually be installed from your distro's repository. For Debian and Ubuntu this is achieved with: .. code-block:: console diff --git a/docs/source/tech_technical.rst b/docs/source/tech_technical.rst index 7b74def1..4486ef3d 100644 --- a/docs/source/tech_technical.rst +++ b/docs/source/tech_technical.rst @@ -1,8 +1,8 @@ -.. _a_tech: +.. _a_storage: -********************* -Technical Information -********************* +****************** +How Data is Stored +****************** This section contains details of how novelWriter stores and handles the project data. @@ -31,13 +31,13 @@ your own backup solution. .. tip:: The novelWriter project folder is structured so that it can easily be added to a version control - system like git. If so, you may want to add a `.gitignore` file to exclude files with the + system like git. If you do so, you may want to add a `.gitignore` file to exclude files with the extensions `.json` as JSON files are used to cache the index and various run-time settings and are generally large files that change often. You'd also want to exclude the ``cache`` folder. The project XML file is indent-formatted, suitable for diff tools and version control since most of -the file will stay static, although a timesetamp is set in the meta section on line 2 each time the -file is saved, and various meta data entries are incremented on each save. +the file will stay static, although a timesetamp is set in the meta section on line 2, and various +meta data entries incremented, on each save. Project Documents @@ -45,8 +45,8 @@ Project Documents All the project documents are saved in a folder in the main project folder named ``content``. Each document has a file handle taken from the first 13 characters of a SHA256 hash of the system time -when the document was first created. The documents are saved with a filename assembled from this -hash and the file extension ``.nwd``. +plus an incremented number when the document was first created. The documents are saved with a +filename assembled from this hash and the file extension ``.nwd``. If you wish to find the file system location of a document in the project, you can either look it up in the project XML file, select :guilabel:`Show File Details` from the :guilabel:`Document` menu @@ -63,6 +63,11 @@ principle be edited in any text editor, and is suitable for diffing and version desired. Just make sure the file remains in utf-8 encoding, otherwise unicode chatracters may become mangled when the file is opened in novelWriter again. +Editing these files is generally not recommended outside of special circumstances, whatever they +may be. The reason for this is that the index will not be automatically updated when doing so, +which means novelWriter doesn't know you've altered the file. If you do edit a file in this manner, +you should rebuild the index when you next open the project in novelWriter. + The first lines of the file may contain some meta data starting with the characters ``%%~``. These lines are mainly there to restore some information if it is lost from the project file, and the information may be helpful if you do open the file in an external editor as it contains the @@ -75,7 +80,7 @@ The File Saving Process ----------------------- When saving the project file, or any of the documents, the data is first saved to a temporary file. -If successful, the old data file is removed, and the temporary file becomes the new file. This +If successful, the old data file is then removed, and the temporary file becomes the new file. This ensures that the previously saved data is only replaced when the new data has been successfully saved to the storage medium. diff --git a/docs/source/usage_format.rst b/docs/source/usage_format.rst new file mode 100644 index 00000000..be83fdb4 --- /dev/null +++ b/docs/source/usage_format.rst @@ -0,0 +1,220 @@ +.. _a_fmt: + +******************** +Formatting Your Text +******************** + +The editor itself is a plain text editor that uses formatting codes for setting meta data values +and allowing for some text formatting. The syntax is based on Markdown, but novelWriter is *not* a +Markdown editor. It supports basic formatting like emphasis (italic), strong importance (bold) +and strikethrough text, as well as four levels of headings. + +In addition to formatting codes, novelWriter allows for comments, a synopsis tag, and a set of +keyword and value sets used for tags and references. There are also some codes that apply two whole +paragraphs. See :ref:`a_fmt_text` below for more details. + + +.. _a_fmt_head: + +Headings +======== + +Four levels of headings are allowed. For project notes they are free to be used as you see fit. +That is, novelWriter doesn't assign the different headings any importance. However, for novel +documents they indicate the structural level of the novel and must be used correctly to produce the +intended result. See :ref:`a_struct_heads` for more details. + +``# Title Text`` + Heading level one. For novel documents, the header level indicates the start of a new partition. + +``## Title Text`` + Heading level two. For novel documents, the header level indicates the start of a new chapter. + Chapter numbers can be inserted automatically when exporting the manuscript. + +``### Title Text`` + Heading level three. For novel documents, the header level indicates the start of a new scene. + Scene numbers or scene separators can be inserted automatically when exporting the manuscript, + so you can use the title field as a working title for your scenes if you wish. + +``#### Title Text`` + Heading level four. For novel documents, the header level indicates the start of a new section. + Section titles can be replaced by separators or removed completely when exporting the + manuscript. + +For headers level one and two, adding a ``!`` modifies the behaviour of the heading: + +``#! Title Text`` + This tells the build tool that the level one heading is intended to be used for the novel's + main title, like for instance on the front page. When exporting, this will use a different + styling and will exclude the title from for instance a Table of Contents in Libre Office. + +``##! Title Text`` + This tells the build tool to not assign a chapter number to this chapter title if automatic + chapter numbers are being used. Such titles are useful for a prologue for instance. See + :ref:`a_struct_heads_unnum` for more details. + +.. note:: + The space after the ``#`` or ``!`` character is mandatory. The syntax highlighter will change + colour and font size when the heading is correctly formatted. + + +.. _a_fmt_text: + +Text Paragraphs +=============== + +A text paragraph is indicated by a blank line. That is, you need two line breaks to separate two +fragments of text into two paragraphs. Single line breaks are treated as line breaks within a +paragraph. + +In addition, the editor supports a few additional types of whitespaces: + +* A non-breaking space can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Space`. +* Thin spaces are also supported, and can be inserted with :kbd:`Ctrl`:kbd:`K`, + :kbd:`Shift`:kbd:`Space`. +* Non-breaking thin space can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`Space`. + +These are all insert features, and the :guilabel:`Insert` menu has more. They are also listed +in :ref:`a_kb_ins`. + +Non-breaking spaces are highlighted by the syntax highlighter with an alternate coloured +background, depending on the selected theme. + +.. tip:: + Non-breaking spaces are the correct type of space to separate a number from its unit. Generally, + it prevents the line wrapping algorithms from adding line breaks where it shouldn't. + + +.. _a_fmt_emph: + +Text Emphasis +============= + +A minimal set of text emphasis styles are supported. + +``_text_`` + The text is rendered as emphasised text (italicised). + +``**text**`` + The text is rendered as strongly important text (bold). + +``~~text~~`` + Strikethrough text. + +In markdown guides it is often recommended to differentiate between strong importance and emphasis +by using ``**`` for strong and ``_`` for emphasis, although markdown generally also supports ``__`` +for strong and ``*`` for emphasis. However, since the differentiation makes the highlighting and +conversion significantly simpler and faster, in novelWriter this is a rule, not just a +recommendation. + +In addition, the following rules apply: + +1. The emphasis and strikethrough formatting tags do not allow spaces between the words and the tag + itself. That is, ``**text**`` is valid, ``**text **`` is not. +2. More generally, the delimiters must be on the outer edge of words. That is, ``some **text in + bold** here`` is valid, ``some** text in bold** here`` is not. +3. If using both ``**`` and ``_`` to wrap the same text, the underscore must be the inner wrapper. + This is due to the underscore also being a valid word character, so if they are on the outside, + they violate rule 2. +4. Text emphasis does not span past line breaks. If you need to add emphasis to multiple lines or + paragraphs, you must apply it to each of them in turn. + + +.. _a_fmt_comm: + +Comments and Synopsis +===================== + +In addition to these standard markdown features, novelWriter also allows for comments in documents. +The text of a comment is ignored by the word counter. The text can also be filtered out when +exporting or viewing the document. + +If the first word of a comment is ``Synopsis:`` (with the colon included), the comment is treated +specially and will show up in the :ref:`a_ui_outline` in a dedicated column. The word ``synopsis`` +is not case sensitive. If it is correctly formatted, the syntax highlighter will indicate this by +altering the colour of the word. + +``% text...`` + This is a comment. The text is not exported by default (this can be overridden), seen in the + document viewer, or counted towards word counts. + +``% Synopsis: text...`` + This is a synopsis comment. It is generally treated in the same way as a regular comment, except + that it is also captured by the indexing algorithm and displayed in the :ref:`a_ui_outline`. It + can also be filtered separately when exporting the project to for instance generate an outline + document of the whole project. + +.. note:: + Only one comment can be flagged as a synopsis comment for each heading. If multiple comments are + flagged as synopsis comments, the last one will be used and the rest ignored. + + +.. _a_fmt_tags: + +Tags and References +=================== + +The document editor supports a minimal set of keywords used for setting tags, and making references +between documents. The tags and references can be set once per section defined by a heading. Using +them multiple times under the same heading will just override the previous setting. + +``@keyword: value`` + A keyword argument followed by a value, or a comma separated list of values. + +The available tag and reference keywords are listed in the :ref:`a_struct_tags` section. They can +also be inserted at the cursor position in the editor via the :guilabel:`Insert` menu. + + +.. _a_fmt_align: + +Paragraphs Alignment and Indentation +==================================== + +All documents have the text by default aligned to the left or justified, depending on your +Preferences. + +You can override the default text alignment on individual paragraphs by specifying alignment tags. +These tags are double angle brackets. Either ``>>`` or ``<<``. You put them either before or after +the paragraph, and they will "push" the text towards the edge the brackets point towards. This +should be fairly intuitive. + +Indentation uses a similar syntax. But here you use a single ``>`` or ``<`` to push the text away +from the edge. + +Examples: + +.. csv-table:: Text Alignment and Indentation + :header: "Syntax", "Description" + :widths: 40, 60 + :class: "tight-table" + + "``>> Right aligned text``", "The text paragraph is right-aligned." + "``Left aligned text <<``", "The text paragraph is left-aligned." + "``>> Centred text <<``", "The text paragraph is centred." + "``> Indented text``", "The text has an increased left margin." + "``Indented text <``", "The text has an increased right margin." + "``> Indented text <``", "The text has an both margins increased." + +.. note:: + The text editor will not show the alignment and indentation live. But the viewer will show them + when you open the document there. It will of course also be reflected in the document generated + from the build tool as long as the format supports paragraph alignment. + + +.. _a_fmt_break: + +Vertical Space and Page Breaks +============================== + +Adding more than one line break between paragraphs will *not* increase the space between those +paragraphs when exporting the project. To add additional space between paragraphs, add the text +``[VSPACE]`` on a line of its own, and the build tool will insert a blank paragraph in its place. + +If you need multiple blank paragraphs just add a colon and a number to the above code. For +instance, writing ``[VSPACE:3]`` will insert three blank paragraphs. + +Normally, the build tool will insert a page break before all headers of level one and for all +headers of level two for novel documents, i.e. chapters, but not for project notes. + +If you need to add a page break somewhere else, put the text ``[NEW PAGE]`` on a line by itself +before the text you wish to start on a new page. diff --git a/docs/source/usage_interface.rst b/docs/source/usage_interface.rst index dd608407..832379ce 100644 --- a/docs/source/usage_interface.rst +++ b/docs/source/usage_interface.rst @@ -1,8 +1,8 @@ .. _a_ui: -************** -User Interface -************** +*********************** +User Interface Overview +*********************** The user interface is kept as simple as possible to avoid distractions when writing. This page lists all the main GUI elements, and explains what they do. @@ -17,10 +17,10 @@ The main window contains a project tree in the left-most panel. It shows the ent the project. It has four columns: **Column 1** - The first column shows the item icon and its label. The labels can be edited from the - :guilabel:`Project` menu, or by pressing :kbd:`F2` or :kbd:`Ctrl`:kbd:`E`. The label is not the - same as the title you set inside the document, but it will appear in the header above the - document text itself. + The first column shows the icon and label of each folder, document, or note in your project. The + label is not the same as the title you set inside the document. However, the document's label + will appear in the header above the document text itself so you know where in the project an + open document belongs. **Column 2** The second column shows the word count of the document, or the sum of words of the child items @@ -34,14 +34,18 @@ the project. It has four columns: **Column 4** The fourth column shows the user-defined status or importance labels you've assigned to each - project item. By default, both the icon and the label text is shown, but you can turn off the - text label from :guilabel:`Preferences`. If the text label is off, the text will instead appear - in a tooltip when you hover your mouse over the icon. They status and importance values can be - changed in :guilabel:`Project Settings`. + project item. See :ref:`a_ui_tree_status` for more details. By default, both the icon and the + label text is shown, but you can turn off the text label from :guilabel:`Preferences`. If the + text label is off, the text will instead appear in a tooltip when you hover your mouse over the + icon. Right-clicking an item in the project tree will open a context menu under the cursor, displaying a selection of actions that can be performed on the selected item. +The label, status or importance setting, the layout, and the include flag can all be edited using +the :guilabel:`Item Settings` dialog box. The dialog can be opened from the :guilabel:`Project` +menu, or by pressing :kbd:`F2` with the item selected. + Below the project tree you will find a small details panel showing the full information of the currently selected item. This panel also includes the latest paragraph and character counts in addition to the word count. @@ -58,8 +62,8 @@ the view in the :guilabel:`Outline`. It is convenient when you want to browse th story itself rather than the document files. .. note:: - You cannot reorganise the entries in the novel tree as that would imply restructuring the - content of the document files. + You cannot reorganise the entries in the novel tree, or add any new ones, as that would imply + restructuring the content of the document files. .. _a_ui_tree_status: @@ -68,10 +72,12 @@ Document Importance and Status ------------------------------ Each document or folder in your project can have either a "Status" or "Importance" flag set. These -are flags that you control and define in their respective tabs in :guilabel:`Project Settings`. The -"Status" flag is intended to tag a Novel document as for instance a draft or as completed, and the -"Importance" flag is intended to tag character notes, or other notes, as for instance a main, major -or minor character. +are flags that you control and define yourself. To modify the labels, go to their respective tabs +in :guilabel:`Project Settings`. + +The "Status" flag is intended to tag a Novel document as for instance a draft or as completed, and +the "Importance" flag is intended to tag character notes, or other notes, as for instance a main, +major or minor character. Whether a document uses a "Status" or "Importance" flag depends on which root folder it lives in. If it's in the :guilabel:`Novel` folder, it uses the "Status" flag, otherwise it uses an @@ -84,10 +90,12 @@ Project Tree Drag & Drop ------------------------ The project tree allows drag & drop to a certain extent. This feature is primarily intended for -rearranging the order of your documents within each root folder, and has only limited support for -moving documents elsewhere in the project tree. In general, bulk actions are not allowed. This is -deliberate to avoid accidentally messing up your project. If you make a mistake, the last move -action can be undone by pressing :kbd:`Ctrl`:kbd:`Shift`:kbd:`Z`. +reordering your documents within each root folder. Moving a document in the project tree will also +put it in a different place when you build the novel project. + +Drag & drop has only limited support for moving documents. In general, bulk actions are not +allowed. This is deliberate to avoid accidentally messing up your project. If you make a mistake, +the last move action can be undone by pressing :kbd:`Ctrl`:kbd:`Shift`:kbd:`Z`. Documents and their folders can be rearranged freely within their root folders. Novel documents cannot be moved out of the :guilabel:`Novel` folder, except to :guilabel:`Trash` and the @@ -98,7 +106,7 @@ default "Status" setting. See :ref:`a_ui_tree_status`. Folders cannot be moved at all outside their root tree. Neither can a folder containing documents be deleted. You must first delete the containing documents. -Root folders in the project tree cannot be dragged and dropped at all. If you want to reorder them, +Root folders in the project tree cannot be dragged & dropped at all. If you want to reorder them, you can move them up or down with respect to eachother from the :guilabel:`Project` menu, the right-click context menu, or by pressing :kbd:`Ctrl`:kbd:`Shift` and the :kbd:`Up` or :kbd:`Down` key. @@ -112,30 +120,33 @@ Editing and Viewing Documents To edit a document, double-click it in the project tree, or press the :kbd:`Return` key while having it selected. This will open the document in the document editor. The editor uses a markdown-like syntax for some features, and a novelWriter-specific syntax for others. The syntax -format is described in the :ref:`a_ui_md` section below. The editor has a maximise button (toggles -the :guilabel:`Focus Mode`) and a close button in the top-right corner. +format is described in the :ref:`a_fmt` section below. The editor has a maximise button (toggles +the :guilabel:`Focus Mode`) and a close button in the top–right corner. On the top–left side you +will find an edit button that opens the :guilabel:`Item Settings` dialog for the currently open +document, and a search button to open the search dialog. Any document in the project tree can also be viewed in parallel in a right hand side document viewer. To view a document, press :kbd:`Ctrl`:kbd:`R`, or select :guilabel:`View Document` in the menu. If you have a middle mouse button, middle-clicking on the document will also open it in the -viewer. The document viewed does not have to be the same document currently being edited. However, -If you *are* viewing the same document, pressing :kbd:`Ctrl`:kbd:`R` again will update the document -with your latest changes. You can also press the reload button in the top-right corner of the view -panel next to the close button to achieve the same thing. +viewer. The document viewed does not have to be the same document as currently being edited. +However, If you *are* viewing the same document, pressing :kbd:`Ctrl`:kbd:`R` again will update the +document with your latest changes. You can also press the reload button in the top–right corner of +the view panel, next to the close button, to achieve the same thing. Both the document editor and viewer will show the label of the document in the header at the top of the edit or view panel. Optionally, the full project path to the document can be shown. This can be -set in :guilabel:`Preferences` from the :guilabel:`Tools` menu. Clicking on the document title bar -will select and reveal its location in the project tree, making it easier to locate in a large -project. +set in :guilabel:`Preferences`. Clicking on the document title bar will select and reveal its +location in the project tree, making it easier to locate in a large project. Any tag reference in the editor can be opened in the viewer by moving the cursor to the label and pressing :kbd:`Ctrl`:kbd:`Return`. You can also control-click them with your mouse. In the viewer, the references become clickable links. Clicking them will replace the content of the viewer with -the content of the document the reference points to. The document viewer keeps a history of viewed -documents, which you can navigate with the arrow buttons in the top-left corner of the viewer. If -your mouse has back and forward navigation buttons, these can be used as well. They work just like -the backward and forward features in a browser. +the content of the document the reference points to. + +The document viewer keeps a history of viewed documents, which you can navigate through with the +arrow buttons in the top–left corner of the viewer. If your mouse has back and forward navigation +buttons, these can be used as well. They work just like the backward and forward features in a +browser. At the bottom of the view panel there is a :guilabel:`References` panel. (If it is hidden, click the icon to reveal it.) This panel will show links to all documents referring back to the one @@ -156,15 +167,15 @@ convenient if you want to quickly look through all documents in the list in the Search & Replace ---------------- -The document editor has a search and replace bar that can be activated with :kbd:`Ctrl`:kbd:`F` for -search mode or :kbd:`Ctrl`:kbd:`H` for search/replace mode. +The document editor has a search and replace tool that can be activated with :kbd:`Ctrl`:kbd:`F` +for search mode or :kbd:`Ctrl`:kbd:`H` for search and replace mode. Pressing :kbd:`Return` while in the search box will search for the next occurrence of the word, and :kbd:`Shift`:kbd:`Return` for the previous. Pressing :kbd:`Return` in the replace box, will replace -the highlighted text and move to the next word. +the highlighted text and move to the next result. -There are a number of settings for the search bar available as toggle switches above the search -box. They allows you to search for, in order:,: matched case only, whole word results only, search +There are a number of settings for the search tool available as toggle switches above the search +box. They allows you to search for, in order: matched case only, whole word results only, search using regular expressions, loop search when reaching the end of the document, and move to the next document when reaching the end. There is also a switch that will try to match the case of the word when the replacement is made. That is, it will try to keep the word upper, lower, or capitalised to @@ -194,7 +205,7 @@ The editor is able to replace two and three hyphens with short and long dashes, ellipsis, and replace straight single and double quotes with user-defined quote symbols. It will also try to determine whether to use the opening or closing symbol, although this feature isn't always accurate. Especially distinguishing between closing single quote and apostrophe can be -tricky for languages that use the same symbol for these. +tricky for languages that use the same symbol for these, like English does. .. tip:: If the auto-replace feature changes a symbol when you did not want it to change, pressing @@ -202,227 +213,6 @@ tricky for languages that use the same symbol for these. character you typed. -.. _a_ui_md: - -The Markdown-Like Format -======================== - -The editor itself is a plaintext editor that uses formatting codes for setting meta data values and -allowing for some text formatting. The syntax is based on Markdown, but novelWriter is *not* a -Markdown editor. It supports basic formatting like emphasis (italic), strong importance (bold) -and strikethrough text, as well as four levels of headings. - -In addition to formatting codes, novelWriter allows for comments, a synopsis tag, and a set of -keyword and value sets used for tags and references. There are also some codes that apply two whole -paragraphs. See :ref:`a_ui_md_text` below for more details. - - -.. _a_ui_md_head: - -Headings --------- - -Four levels of headings are allowed. For project notes they are free to be used as you see fit. -However, for novel documents they indicate the structural level of the novel. See -:ref:`a_struct_heads` for more details. - -``# Title Text`` - Heading level one. If the document is a novel file, the header level indicates the start of a - new partition. - -``## Title Text`` - Heading level two. If the document is a novel file, the header level indicates the start of a - new chapter. Chapter numbers can be inserted automatically when exporting the manuscript. - -``### Title Text`` - Heading level three. If the document is a novel file, the header level indicates the start of a - new scene. Scene numbers or scene separators can be inserted automatically when exporting the - manuscript, so you can use the title field as a working title for your scenes if you wish. - -``#### Title Text`` - Heading level four. If the document is a novel file, the header level indicates the start of a - new section. Section titles can be replaced by separators or removed when exporting the - manuscript, so you can use the title field as a working title for your sections if you wish. - -For header level one and two, adding a ``!`` modifies the behaviour of the heading slightly: - -``#! Title Text`` - This tells the build tool that the level one heading is intended to be used for the novel's - main title, like for instance on the front page. When exporting, this will use a different - styling and will exclude the title from for instance a Table of Contents in Libre Office. - -``##! Title Text`` - This tells the build tool to not assign a chapter number to this chapter title if automatic - chapter numbers are being used. Such titles are useful for a prologue for instance. See - :ref:`a_struct_heads_unnum` for more details. - -.. note:: - The space after the ``#`` or ``!`` characters is mandatory. The syntax highlighter will change - colour and font size when the heading is correctly formatted. - - -.. _a_ui_md_text: - -Text Paragraphs ---------------- - -A text paragraph is indicated by a blank line. That is, you need two line breaks to separate two -fragments of text into two paragraphs. Single line breaks are treated as line breaks within a -paragraph. - -In addition, the editor supports a few additional types of whitespaces. - -* A non-breaking space can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Space`. -* Thin spaces are also supported, and can be inserted with :kbd:`Ctrl`:kbd:`K`, - :kbd:`Shift`:kbd:`Space`. -* Non-breaking thin space can be inserted with :kbd:`Ctrl`:kbd:`K`, :kbd:`Ctrl`:kbd:`Space`. - -These are all insert features, and the :guilabel:`Insert` menu has more. They are also listed -in :ref:`a_kb_ins`. - -Non-breaking spaces are highlighted by the syntax highlighter with an alternate coloured -background, depending on the selected theme. - -.. tip:: - Non-breaking spaces are the correct type of space to separate a number from its unit. Generally, - it prevents the line wrapping algorithms from adding line breaks where it shouldn't. - - -.. _a_ui_md_break: - -Vertical Space and Page Breaks ------------------------------- - -Adding more than one line break between paragraphs will *not* increase the space between those -paragraphs when exporting the project. To add additional space between paragraphs, add the text -``[VSPACE]`` on a line of its own, and the build tool will insert a blank paragraph in its place. - -If you need multiple blank paragraphs just add a number. For instance, writing ``[VSPACE:3]`` will -insert three blank paragraphs. - -Normally, the build tool will insert a page break before all headers of level one and for all -headers of level two for novel documents, i.e. chapters, but not for project notes. - -If you need to add a page break somewhere else, put the text ``[NEW PAGE]`` on a line by itself -before the text you wish to start on a new page. - - -.. _a_ui_md_align: - -Paragraphs Alignment and Indentation ------------------------------------- - -All documents have the text by default aligned to the left or justified, depending on your -Preferences. - -You can override the default text alignment on individual paragraphs by specifying alignment tags. -These tags are double angle brackets. Either ``>>`` or ``<<``. You put them either before or after -the paragraph, and they will "push" the text towards the edge the brackets point towards. This -should be fairly intuitive. - -Indentation uses a similar syntax. But here you use a single ``>`` or ``<`` to push the text away -from the edge. - -Examples: - -.. csv-table:: Text Alignment and Indentation - :header: "Syntax", "Description" - :widths: 40, 60 - :class: "tight-table" - - "``>> Right aligned text``", "The text paragraph is right-aligned." - "``Left aligned text <<``", "The text paragraph is left-aligned." - "``>> Centred text <<``", "The text paragraph is centred." - "``> Indented text``", "The text has an increased left margin." - "``Indented text <``", "The text has an increased right margin." - "``> Indented text <``", "The text has an both margins increased." - -.. note:: - The text editor will not show the alignment and indentation live. But the viewer will show them - when you open the document in the viewer. It will of course also be reflected in the document - generated from the build tool. - - -.. _a_ui_md_emph: - -Text Emphasis -------------- - -A minimal set of text emphasis styles are supported. - -``_text_`` - The text is rendered as emphasised text (italicised). - -``**text**`` - The text is rendered as strongly important text (bold). - -``~~text~~`` - Strikethrough text. - -In markdown guides it is often recommended to differentiate between strong importance and emphasis -by using ``**`` for strong and ``_`` for emphasis, although markdown generally also supports ``__`` -for strong and ``*`` for emphasis. However, since the differentiation makes the highlighting and -conversion significantly simpler and faster, in novelWriter this is a rule, not just a -recommendation. - -In addition, the following rules apply: - -1. The emphasis and strikethrough formatting tags do not allow spaces between the words and the tag - itself. That is, ``**text**`` is valid, ``**text **`` is not. -2. More generally, the delimiters must be on the outer edge of words. That is, ``some **text in - bold** here`` is valid, ``some** text in bold** here`` is not. -3. If using both ``**`` and ``_`` to wrap the same text, the underscore must be the inner wrapper. - This is due to the underscore also being a valid word character, so if they are on the outside, - they violate rule 2. -4. Text emphasis does not span past line breaks. If you need to add emphasis to multiple lines or - paragraphs, you must apply it to each of them in turn. - - -.. _a_ui_md_comm: - -Comments and Synopsis ---------------------- - -In addition to these standard markdown features, novelWriter also allows for comments in documents. -The text of a comment is ignored by the word counter. The text can also be filtered out when -exporting or viewing the document. - -If the first word of a comment is ``Synopsis:`` (with the colon included), the comment is treated -specially and will show up in the :ref:`a_ui_outline` in a dedicated column. The word ``synopsis`` -is not case sensitive. If it is correctly formatted, the syntax highlighter will indicate this by -altering the colour of the word. - -``% text...`` - This is a comment. The text is not exported by default (this can be overridden), seen in the - document viewer, or counted towards word counts. - -``% Synopsis: text...`` - This is a synopsis comment. It is generally treated in the same way as a regular comment, except - that it is also captured by the indexing algorithm and displayed in the :ref:`a_ui_outline`. It - can also be filtered separately when exporting the project to for instance generate an outline - document of the whole project. - -.. note:: - Only one comment can be flagged as a synopsis comment for each heading. If multiple comments are - flagged as synopsis comments, the last one will be used and the rest ignored. - - -.. _a_ui_md_tags: - -Tags and References -------------------- - -The document editor supports a minimal set of keywords used for setting tags, and making references -between documents. The tags and references can be set once per section defined by a heading. Using -them multiple times under the same heading will just override the previous setting. - -``@keyword: value`` - A keyword argument followed by a value, or a comma separated list of values. - -The available tag and reference keywords are listed in the :ref:`a_struct_tags` section. They can -also be inserted at the cursor position in the editor via the :guilabel:`Insert` menu. - - .. _a_ui_outline: Project Outline View @@ -460,4 +250,4 @@ and the :guilabel:`Outline` tab is active. You may want to disable this feature very large, The :guilabel:`Synopsis` column of the outline view takes its information from a specially -formatted comment. See :ref:`a_ui_md_comm`. +formatted comment. See :ref:`a_fmt_comm`. diff --git a/docs/source/usage_typography.rst b/docs/source/usage_typography.rst index 00d15cf4..2a9d768f 100644 --- a/docs/source/usage_typography.rst +++ b/docs/source/usage_typography.rst @@ -29,8 +29,8 @@ always be reverted with the undo command :kbd:`Ctrl`:kbd:`Z`, reverting the text before the automatic replacement occurred. In addition, "Figure Dash" is available. The Figure Dash is a dash that has the same width as the -numbers of the same font, for most fonts. It helps to align numbers align nicely in columns when -you need to use a dash in them. +numbers of the same font, for most fonts. It helps to align numbers nicely in columns when you need +to use a dash in them. Single and Double Quotes @@ -44,10 +44,10 @@ Ordinarily, text wrapped in quotes are highlighted by the editor. This is meant for highlighting dialogue between characters. This feature can be disabled in :guilabel:`Preferences` if this feature isn't wanted. -The editor distinguishes between text wrapped in regular straight quotes and with the user-selected -double quote symbols. This is to help the writer recognise which parts of the text are not using -the chosen quote symbols. Two convenience functions in the :guilabel:`Format` menu can be used to -re-format a selected section of text with the correct quote symbols. +The editor distinguishes between text wrapped in regular straight double quotes and the +user-selected double quote symbols. This is to help the writer recognise which parts of the text +are not using the chosen quote symbols. Two convenience functions in the :guilabel:`Format` menu +can be used to re-format a selected section of text with the correct quote symbols. .. _Quotation Mark: https://en.wikipedia.org/wiki/Quotation_mark