diff --git a/docs/requirements.txt b/docs/requirements.txt index 4ccbc91e..767647e7 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,6 +1,7 @@ docutils>=0.17.1 pygments>=2.7 sphinx-book-theme +sphinx-copybutton sphinx-design sphinx-favicon sphinx-intl diff --git a/docs/source/conf.py b/docs/source/conf.py index 4791c0e4..b3d3d41f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -40,7 +40,7 @@ os.environ["TZ"] = "Europe/Oslo" time.tzset() needs_sphinx = "5.0" -extensions = ["sphinx_design"] +extensions = ["sphinx_design", "sphinx_copybutton"] templates_path = ["_templates"] source_suffix = ".rst" master_doc = "index" diff --git a/docs/source/features/dialogue.rst b/docs/source/features/dialogue.rst new file mode 100644 index 00000000..829b7ba6 --- /dev/null +++ b/docs/source/features/dialogue.rst @@ -0,0 +1,92 @@ +.. _docs_features_dialogue: + +********************* +Dialogue Highlighting +********************* + +Dialogue recognition and colour highlighting is available both while you're writing and in +generated manuscript documents. + +The default language settings in novelWriter are for English. That includes the dialogue +highlighting settings. But many dialogue styles are supported. You can tune a number of settings +to fit your language and style preferences in the "Text Highlighting" section in **Preferences**. +You can mix and match these settings. + +.. figure:: images/fig_dialogue_highlighting.png + + The **Text Highlighting** section of **Preferences**. + + +Quoted Dialogue +=============== + +By default, dialogue highlighting is enabled for the double quote symbols you have defined in the +**Quotation Style** section of **Preferences**. + +.. figure:: images/fig_dialogue_quote_styles.png + + The **Quotation Style** section of **Preferences**. + +You can change which quote symbols are highlighted by selecting one of "None", "Single", "Double", +or "Both" from the "Highlight dialogue" setting under **Text Highlighting**. + +You can also enable or disable the "Allow open-ended dialogue" setting to allow for the style where +multi-paragraph dialogue is not closed until the last paragraph. + +.. admonition:: Limitations + + Dialogue highlighting for single quotes is difficult to process when the same single quote + symbol is also used for apostrophes. There isn't a good solution to this. Your best option in + the cases where the highlighting is wrong is to insert an alternative apostrophe symbol instead. + See :ref:`docs_more_typographical_symbols_apostrophe` for more details. + + +Alternative Dialogue +==================== + +You can use the "Alternative dialogue symbols" setting for custom dialogue wrapper symbols. These +are highlighted in a different colour than regular dialogue. + +The intended use case here is if you use an alternative style to distinguish a different style of +communication. The feature idea came from a science fiction series where mind-to-mind communication +used a different quotation style. + + +Dialogue Line Symbols +===================== + +In some languages, a single symbol at the start of a paragraph can indicate that the whole +paragraph is dialogue. For instance, this symbol can be a short dash (en dash). + +.. figure:: images/fig_dialogue_line.png + + An example of dialogue starting with a short dash. + +You can enable this feature by adding the symbols to the "Dialogue line symbols" setting. Multiple +symbols are allowed. + + +Dialogue with Narrator Break +============================ + +The dialogue symbol setting will not detect if the dialogue ends in the paragraph. In some styles +there is no way to actually indicate the switch from dialogue to narration; in others there are. +These a narrator break symbols are usually dashes. You can select one of the supported dash symbols +for narrator breaks. These can be used with any of the above dialogue recognition settings. + +.. figure:: images/fig_dialogue_narrator_break.png + + An example of dialogue starting with a short dash and a long dash narrator break. + + +Alternating Dialogue and Narration +================================== + +The alternating dialogue and narration style is supported with the "Alternating dialogue/narration +symbol" setting. It can be set to one of the supported dashes. This style will switch into dialogue +mode when it first encounters the selected dash in a paragraph, and switch back out when it sees +the next one, and so forth. + +.. figure:: images/fig_dialogue_alternating.png + + An example of alternating dialogue and narration using a long dash. diff --git a/docs/source/features/images/fig_dialogue_alternating.png b/docs/source/features/images/fig_dialogue_alternating.png new file mode 100644 index 00000000..6020dbc3 Binary files /dev/null and b/docs/source/features/images/fig_dialogue_alternating.png differ diff --git a/docs/source/features/images/fig_dialogue_highlighting.png b/docs/source/features/images/fig_dialogue_highlighting.png new file mode 100644 index 00000000..08fcb6c0 Binary files /dev/null and b/docs/source/features/images/fig_dialogue_highlighting.png differ diff --git a/docs/source/features/images/fig_dialogue_line.png b/docs/source/features/images/fig_dialogue_line.png new file mode 100644 index 00000000..63013b15 Binary files /dev/null and b/docs/source/features/images/fig_dialogue_line.png differ diff --git a/docs/source/features/images/fig_dialogue_narrator_break.png b/docs/source/features/images/fig_dialogue_narrator_break.png new file mode 100644 index 00000000..1eb1ab4f Binary files /dev/null and b/docs/source/features/images/fig_dialogue_narrator_break.png differ diff --git a/docs/source/features/images/fig_dialogue_quote_styles.png b/docs/source/features/images/fig_dialogue_quote_styles.png new file mode 100644 index 00000000..39cb8a72 Binary files /dev/null and b/docs/source/features/images/fig_dialogue_quote_styles.png differ diff --git a/docs/source/images/fig_story_structure_manuscript.png b/docs/source/features/images/fig_story_structure_manuscript.png similarity index 100% rename from docs/source/images/fig_story_structure_manuscript.png rename to docs/source/features/images/fig_story_structure_manuscript.png diff --git a/docs/source/usage_shortcuts.rst b/docs/source/features/shortcuts.rst similarity index 98% rename from docs/source/usage_shortcuts.rst rename to docs/source/features/shortcuts.rst index 8aa93e72..0a29927b 100644 --- a/docs/source/usage_shortcuts.rst +++ b/docs/source/features/shortcuts.rst @@ -1,4 +1,4 @@ -.. _a_kb: +.. _docs_features_shortcuts: ****************** Keyboard Shortcuts @@ -8,11 +8,10 @@ Most features in novelWriter are available as keyboard shortcuts. This is a refe shortcuts. Most of them are also listed in the application's user interface. .. note:: + On MacOS, replace :kbd:`Ctrl` with :kbd:`Cmd`. -.. _a_kb_main: - Main Window Shortcuts ===================== @@ -38,8 +37,6 @@ Main Window Shortcuts ":kbd:`Shift+F6`", "Open the **Project Details** dialog" -.. _a_kb_tree: - Project Tree Shortcuts ====================== @@ -62,8 +59,6 @@ Project Tree Shortcuts ":kbd:`Ctrl+Shift+Del`", "Move the selected item to Trash" -.. _a_kb_editor: - Document Editor Shortcuts ========================= @@ -120,7 +115,7 @@ Other Editor Shortcuts ":kbd:`Ctrl+.`", "Open the context menu at the current cursor location" ":kbd:`Ctrl+A`", "Select all text in the document" ":kbd:`Ctrl+C`", "Copy selected text to clipboard" - ":kbd:`Ctrl+K`", "Activate the insert commands (see list in :ref:`a_kb_ins`)" + ":kbd:`Ctrl+K`", "Activate the insert commands (see list in :ref:`docs_features_shortcuts_insert`)" ":kbd:`Ctrl+R`", "Open or reload the current document in the viewer" ":kbd:`Ctrl+S`", "Save the current document" ":kbd:`Ctrl+V`", "Paste text from clipboard to cursor position" @@ -135,7 +130,7 @@ Other Editor Shortcuts ":kbd:`Ctrl+Shift+A`", "Select all text in the current paragraph" -.. _a_kb_ins: +.. _docs_features_shortcuts_insert: Insert Shortcuts ---------------- @@ -184,8 +179,6 @@ a key or key combination for the inserted content. ":kbd:`Ctrl+K`, :kbd:`Shift+Space`", "Insert a thin space" -.. _a_kb_viewer: - Document Viewer Shortcuts ========================= diff --git a/docs/source/writing_story.rst b/docs/source/features/story_comments.rst similarity index 58% rename from docs/source/writing_story.rst rename to docs/source/features/story_comments.rst index ba6b9641..994643a0 100644 --- a/docs/source/writing_story.rst +++ b/docs/source/features/story_comments.rst @@ -1,25 +1,26 @@ -.. _a_story_structure: +.. _docs_features_story: -************************ -Story Structure Comments -************************ +************** +Story Comments +************** - -As of version 2.7, story structure annotations using the ``%story`` style of comment is supported. -To use the feature, make the first word of a comment ``story``, followed by a period, a structure -term, a colon, a space and the text for that term. - -Here's an example: - -.. code-block:: md - - %story.term: text +A special set of comment styles allow for annotating your text with structure information. There +are two styles of comments available. They are an extension to regular comments as described in +:ref:`docs_usage_comments`. .. versionadded:: 2.7 +Story Structure Comments +======================== + +You can annotate story structure by using the ``%Story`` style of comment. To use the feature, +make the first word of a comment ``Story``, followed by a period, a structure term, a colon, a +space and the text for that term. + + Usage -===== +----- The story term can be anything that you want to track in the manuscript. This construct is intended to make it easier to extract metadata from a work to perform a structural analysis of the story. @@ -33,6 +34,8 @@ story is composed of "beats", and that each beat has an inciting incident, a com crisis, and a resolution. One might capture these elements of a beat where a character overcomes their fear of giving a speech as: +:bdg-info:`Example` + .. code-block:: md ### Scene @@ -56,7 +59,7 @@ fast-paced scenes without a break that readers might become fatigued or over-sti Output -====== +------ The story structure comments can be included in the manuscript, and are formatted similarly to the synopsis comments: @@ -67,3 +70,41 @@ the synopsis comments: When you export your project data from the Outline View, all story structure terms are added as columns to the exported file, which can then be opened in the spread sheet software of your choice. + + +Story Notes +=========== + +Story notes are similar to story structure comments, but have no predefined meaning. Essentially +they are a generalisation of the story structure comment, and the only point of having this +additional format is to allow you do filter them in and out of your manuscript independently. + +You can annotate story notes by using the ``%Note`` style of comment. To use the feature, +make the first word of a comment ``Note``, followed by a period, a term, a colon, a space and the +text for the note. + + +Usage +----- + +These notes are free form, but one intended use case is to add consistency annotations to your text +to remind yourself where you have described something that must be checked against other parts of +your text later on. + +:bdg-info:`Example` + +.. code-block:: md + + ### Scene + + %Synopsis: Carol overcomes her fear of giving a speech. + + %Note.consistency: This is the first time in the story Carol gives a speech. + + +Output +------ + +Story notes are included in the manuscript in exactly the same way story structure comments are, +but has a separate inclusion setting in the build settings. They are also included in CSV exports +from the **Outline View**. diff --git a/docs/source/images/fig_build_build.png b/docs/source/images/fig_build_build.png deleted file mode 100644 index 8c509d57..00000000 Binary files a/docs/source/images/fig_build_build.png and /dev/null differ diff --git a/docs/source/images/fig_build_settings_selections.png b/docs/source/images/fig_build_settings_selections.png deleted file mode 100644 index b92e7a96..00000000 Binary files a/docs/source/images/fig_build_settings_selections.png and /dev/null differ diff --git a/docs/source/images/fig_header_levels.png b/docs/source/images/fig_header_levels.png deleted file mode 100644 index e427e3a2..00000000 Binary files a/docs/source/images/fig_header_levels.png and /dev/null differ diff --git a/docs/source/images/fig_project_tree_detailed.png b/docs/source/images/fig_project_tree_detailed.png deleted file mode 100644 index ec451ccc..00000000 Binary files a/docs/source/images/fig_project_tree_detailed.png and /dev/null differ diff --git a/docs/source/images/fig_references.png b/docs/source/images/fig_references.png deleted file mode 100644 index 3ffb9afa..00000000 Binary files a/docs/source/images/fig_references.png and /dev/null differ diff --git a/docs/source/images/screenshot_dark.png b/docs/source/images/screenshot_dark.png deleted file mode 100644 index dd2cbf84..00000000 Binary files a/docs/source/images/screenshot_dark.png and /dev/null differ diff --git a/docs/source/images/screenshot_light.png b/docs/source/images/screenshot_light.png deleted file mode 100644 index 51ce2f7f..00000000 Binary files a/docs/source/images/screenshot_light.png and /dev/null differ diff --git a/docs/source/index.rst b/docs/source/index.rst index 3cefdc4e..8e863ff8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -16,14 +16,6 @@ storage for robustness. :align: center :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, and your project data as standard -data formats in XML and JSON. See :ref:`a_storage` for more details. - -Any operating system that has Python 3 and the Qt 6 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** * Website: https://novelwriter.io @@ -40,64 +32,58 @@ See :ref:`a_started` for more details. .. toctree:: :hidden: - Main Page + self More Documents .. toctree:: - :maxdepth: 1 - :caption: Introduction + :caption: Getting Started :hidden: - int_introduction - int_overview - int_started - int_howto - int_glossary + usage/introduction + usage/organising_project + usage/chapters_and_scenes + usage/basic_formatting + usage/comments + usage/tags_and_references + usage/alignment_and_indent + usage/advanced_formatting + usage/front_back_matter + usage/howto .. toctree:: - :maxdepth: 1 - :caption: Using novelWriter + :caption: The User Interface :hidden: - usage_breakdown - usage_project - usage_writing - usage_format - usage_shortcuts - usage_typography + user_interface/main_window + user_interface/projects + user_interface/editor_viewer + user_interface/split_and_merge + user_interface/manuscript + user_interface/statistics .. toctree:: - :maxdepth: 1 - :caption: Organising Your Project + :caption: Other Features :hidden: - project_overview - project_structure - project_references - project_manuscript + features/dialogue + features/story_comments + features/shortcuts .. toctree:: - :maxdepth: 1 - :caption: Writing Aids + :caption: In-Depth Topics :hidden: - writing_story + more/counting + more/typography + more/customise + more/handling_errors + more/project_format .. toctree:: - :maxdepth: 1 - :caption: Additional Details - :hidden: - - more_customise - more_projectformat - more_counting - -.. toctree:: - :maxdepth: 1 :caption: Technical Topics :hidden: - tech_locations - tech_storage - tech_source - tech_tests + technical/locations + technical/storage + technical/source + technical/tests diff --git a/docs/source/int_glossary.rst b/docs/source/int_glossary.rst deleted file mode 100644 index c8777923..00000000 --- a/docs/source/int_glossary.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _a_glossary: - -******** -Glossary -******** - -.. glossary:: - :sorted: - - Root Folder - A "Root Folder" is a top level folder of the project tree in novelWriter. Each type of root - folder has a specific icon to identify it. For an overview of available root folder types, - see :ref:`a_proj_roots`. - - Novel Documents - These are documents that are created under a "Novel" :term:`Root Folder`. They behave - differently than :term:`Project Notes`, and have some more restrictions. For instance, they - can not exist in folders intended only for project notes. See the :ref:`a_struct` chapter for - more details. - - Project Notes - Project Notes are unrestricted documents that can be placed anywhere in your project. You - should not use these documents for story elements, only for notes. Project notes are the - source files used by the Tags and References system. See the :ref:`a_references` chapter for - more details on how to use them. - - Tag - A tag is a user defined value assigned as a tag to a section of your :term:`Project Notes`. - It is optional, and can be defined once per heading. It is set using the :term:`keyword` - syntax ``@tag: value``, where ``value`` is the user defined part. Each tag can be referenced - in another file using one of the :term:`reference` keywords. See :ref:`a_references` chapter - for more details. - - Reference - A reference is one of a set of :term:`keywords` that can be used to link to a - :term:`tag` in another document. The reference keywords are specific to the different - :term:`root folder` types. A full overview is available in the :ref:`a_references` chapter. - - Project Index - The project index is a record of all headings in a project, with all their meta data like - synopsis comments, :term:`tags` and :term:`references`. The project index is - kept up to date automatically, but can also be regenerated manually from the - :guilabel:`Tools` menu or by pressing :kbd:`F9`. - - Context Menu - A context menu is a menu that pops up when you right click something in the user interface. - In novelWriter, you can often also open a context menu by pressing the keyboard shortcut - :kbd:`Ctrl+.`. - - 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 heading levels don't - matter. For more details on headings in novel documents, see :ref:`a_struct_heads`. - - Keyword - A keyword in novelWriter is a special command you put in the text of your documents. They are - not standard Markdown, but are used in novelWriter to add information that is interpreted by - the application. For instance, keywords are used for :term:`tags` and - :term:`references`. - - Keywords must always be on their own line, and the first character of the line must always be - the ``@`` character. The keyword must also always be followed by a ``:`` character, and the - values passed to the command are added after this, separated by commas. diff --git a/docs/source/int_introduction.rst b/docs/source/int_introduction.rst deleted file mode 100644 index ab50a55b..00000000 --- a/docs/source/int_introduction.rst +++ /dev/null @@ -1,129 +0,0 @@ -.. _a_intro: - -******** -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. 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 - - 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 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 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`, which 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 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 -for instance one document per act, and later effortlessly split these up into individual chapter or -scene documents. - - -.. _a_intro_features: - -Key Features -============ - -Below are some key features of novelWriter. - -**Focus on writing** - 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. Additional shortcodes are available for special - formatting cases when you need them. - - When you really want to focus on just writing, you can 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. 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. - -**Organise your documents how you like** - You can split your novel project up into as many individual documents as you want to. When you - 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 fewer documents and then - later split them into multiple documents based on chapter and scene headings. - -**Multi-novel project support** - 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, and rename them to whatever you want. 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 separately. - -**Keep track of your story elements** - All documents 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, or you want to keep several topics or - scenes in the same document. - -**Get an overview of your story** - It is not the documents themselves that define the chapters and scenes of your story, but the - headings within them. In the **Outline View** on the main window you can see an outline of all - the chapter and scene headings of each novel root folder in 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 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 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, or generate an Open Document or - Word Document file that can be opened by most office type word processors. You can also generate - the result as HTML, or Markdown, both suitable for further conversion to other formats. - - -.. _a_intro_screenshots: - -Screenshots -=========== - -.. figure:: images/screenshot_light.png - :class: dark-light - - novelWriter with light colour theme - -.. figure:: images/screenshot_dark.png - :class: dark-light - - novelWriter with dark colour theme diff --git a/docs/source/int_overview.rst b/docs/source/int_overview.rst deleted file mode 100644 index 96f5e410..00000000 --- a/docs/source/int_overview.rst +++ /dev/null @@ -1,100 +0,0 @@ -.. _a_reading: - -****************** -What to Read First -****************** - -The documentation of novelWriter is quite extensive. There are a lot of features to get used to, -but you don't need to know all of them to get started. - -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 writing. - -The chapters labelled "Recommended Reading" includes additional information on how the different -parts if the application work and what the features do. - -The "Optional" and "Lookup" chapters contain additional information or lookup tables that are not -essential for using the application. - - -Using novelWriter -================= - -In order to use novelWriter effectively, you need to know the basics of how it works. The following -chapters will explain the main principles. They start with the basics, and get more detailed as you -read on. - -:ref:`a_breakdown` -- Essential Information - This chapter explains the basics of how the application works and what it can and cannot do. - -:ref:`a_ui_project` -- Recommended Reading - This chapter will give you a more detailed explanation of how you can use the user interface - components to organise and view your project work. - -:ref:`a_ui_writing` -- Recommended Reading - This chapter will give you a more detailed explanation of how the text editor and viewer work. - -:ref:`a_fmt` -- Essential Information - This chapter covers how you should format your text. The editor is plain text, so text - formatting requires some basic markup. The structure of your novel is also inferred from how you - use headings. Tags and references are implemented by special keywords. - -:ref:`a_kb` -- Optional / Lookup - This chapter lists all the keyboard shortcuts in novelWriter and what they do. Most of the - shortcuts are also listed next to their menu entries inside the app, or in tool tips. This - chapter is mostly for reference. - -:ref:`a_typ` -- Optional - This chapter gives you an overview of the special typographical symbols available in - novelWriter. The auto-replace feature can handle the insertion of standard quote symbols for - your language, and other special characters. If you use any symbols aside from these, their - intended use is explained here. - - -Organising Your Projects -======================== - -In addition to managing a collection of plain text files, novelWriter can interpret and map the -structure of your novel and show you additional information about its flow and content. In order -to take advantage of these features, you must structure your text in a specific way and add some -meta data for it to extract. - -:ref:`a_proj` -- Essential Information - This chapter explains how you organise the content of your project, and how to set up automated - backups of your work. - -:ref:`a_struct` -- Essential Information - This chapter covers the way your novel's structure is encoded into the text documents. It - explains how the different levels of headings are used, and some special formatting for - different kinds of headings. - -:ref:`a_references` -- Recommended Reading - This chapter explains how you organise your notes, and how the Tags and References system works. - This system lets you cross-link your documents in your project, and display these references in - the application interface. - -:ref:`a_manuscript` -- Recommended Reading - 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. - - -Writing Aids -============ - -We are in the process of adding tools to novelWriter that can be used to track more information -about your project to assist in your writing. These tools are entirely optional and will not be in -your way if you choose to not use them. - -:ref:`a_story_structure` -- Writing Tools - Story structure comments are a way to add meta data that can be used to analyse the structure of - your writing. These comments can be exported to spreadsheets for analysis. - - -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 deleted file mode 100644 index fe2502ae..00000000 --- a/docs/source/int_started.rst +++ /dev/null @@ -1,170 +0,0 @@ -.. _a_started: - -********************** -Setup and Installation -********************** - -.. _Enchant: http://rrthomas.github.io/enchant/ -.. _GitHub: https://github.com/vkbo/novelWriter -.. _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/ -.. _python.org: https://www.python.org/downloads/ -.. _Releases: https://github.com/vkbo/novelWriter/releases -.. _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 additional install 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, -or start novelWriter from the command line. - -Spell checking in novelWriter is provided by a third party library called Enchant_. Generally, it -should pull dictionaries from your operating system automatically. However, on Windows they must be -installed manually. See :ref:`a_custom_dict` for more details. - - -.. _a_started_windows: - -Installing on Windows -===================== - -You can install novelWriter with both Python and library dependencies embedded using the Windows -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 -already had a version installed via a different method, you should uninstall that first as having -multiple installations has been known to cause problems. - - -.. _a_started_linux: - -Installing on Linux -=================== - -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. -The Launchpad packages `are signed by the author `__. - - -Ubuntu ------- - -You can add the Ubuntu PPA_ and install novelWriter with the following commands. - -.. code-block:: bash - - sudo add-apt-repository ppa:vkbo/novelwriter - sudo apt update - sudo apt install novelwriter - -If you want the `Pre-Release PPA`_ instead, add the ``ppa:vkbo/novelwriter-pre`` repository. - - -Debian and Mint ---------------- - -Since this is a pure Python package, the Launchpad PPA can in principle also be used on Debian or -Mint. However, the above command will fail to add the signing key, as it is Ubuntu-specific. - -Instead, run the following commands to add the repository and key: - -.. code-block:: bash - - sudo gpg --no-default-keyring --keyring /usr/share/keyrings/novelwriter-ppa-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys F19F1FCE50043114 - echo "deb [signed-by=/usr/share/keyrings/novelwriter-ppa-keyring.gpg] http://ppa.launchpad.net/vkbo/novelwriter/ubuntu noble main" | sudo tee /etc/apt/sources.list.d/novelwriter.list - -Then run the update and install commands as for Ubuntu: - -.. code-block:: bash - - sudo apt update - sudo apt install novelwriter - -.. tip:: - If you get an error message like ``gpg: failed to create temporary file`` when importing the key - from the Ubuntu keyserver, try creating the folder it fails on, and import the key again: - - .. code-block:: bash - - sudo mkdir /root/.gnupg/ - - -AppImage Releases ------------------ - -For other Linux distros than the ones mentioned above, the primary option is AppImage_. These are -completely standalone images for the app that include the necessary environment to run novelWriter. -They can of course be run on any Linux distro, if you prefer this to native packages. - -.. note:: - 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. - - -.. _a_started_macos: - -Installing on MacOS -=================== - -You can install novelWriter with both its Python and library dependencies embedded using the DMG -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 - again by right clicking on the application in Finder and selecting :guilabel:`Open` from the - context menu. - -The context menu can also be accessed by option-clicking if you have a one button mouse. This is -done by holding down the option key on your keyboard and clicking on the application in Finder. - -.. note:: - The novelWriter DMG is not signed because Apple 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 a commercial software signing certificate. - - -.. _a_started_pip: - -Installing from PyPi -==================== - -novelWriter is also available on the Python Package Index, or PyPi_. This install method works on -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 -version. If you are on Windows, also make sure to select the "Add Python to PATH" option during -installation. - -To install novelWriter from PyPi, use the following command: - -.. code-block:: bash - - pip install novelwriter - -To upgrade an existing installation, use: - -.. code-block:: bash - - pip install --upgrade novelwriter - -When installing via pip, novelWriter can be launched from command line with: - -.. code-block:: bash - - novelwriter - -Make sure the install location for pip is in your PATH variable. This is not always the case by -default, and then you may get a "Not Found" error when running the ``novelwriter`` command. diff --git a/docs/source/more_counting.rst b/docs/source/more/counting.rst similarity index 95% rename from docs/source/more_counting.rst rename to docs/source/more/counting.rst index 7272c9fc..d2ec5667 100644 --- a/docs/source/more_counting.rst +++ b/docs/source/more/counting.rst @@ -1,13 +1,13 @@ -.. _a_counting: +.. _docs_more_counting: ******************** Word and Text Counts ******************** This is an overview of how words and other counts of your text are performed. The counting rules -should be relatively standard, and are compared to Libre Office Writer rules. +should be relatively standard, and are comparable to Libre Office Writer rules. -The counts provided in the app on the raw text is meant to be approximate. For more accurate +The counts provided in the app on the raw text are meant to be approximate. For more accurate counts, you need to build your manuscript in the **Manuscript Tool** and check the counts on the generated preview. diff --git a/docs/source/more_customise.rst b/docs/source/more/customise.rst similarity index 84% rename from docs/source/more_customise.rst rename to docs/source/more/customise.rst index 924a0ef7..80aa1201 100644 --- a/docs/source/more_customise.rst +++ b/docs/source/more/customise.rst @@ -1,4 +1,4 @@ -.. _a_custom: +.. _docs_more_custom: ************** Customisations @@ -11,7 +11,7 @@ There are a few ways you can customise novelWriter yourself. Currently, you can your own syntax themes, and install additional dictionaries. -.. _a_custom_dict: +.. _docs_more_custom_dict: Spell Check Dictionaries ======================== @@ -19,6 +19,7 @@ Spell Check Dictionaries novelWriter uses Enchant_ as the spell checking tool. Depending on your operating system, it may or may not load all installed spell check dictionaries automatically. + Linux and MacOS --------------- @@ -26,6 +27,7 @@ On Linux and MacOS, you generally only have to install hunspell, aspell or myspe your system like you do for other applications. See your distro or OS documentation for how to do this. These dictionaries should show up as available spell check languages in novelWriter. + Windows ------- @@ -61,7 +63,7 @@ You can find the various dictionaries on the `Free Desktop`_ website. each line and download that. -.. _a_custom_theme: +.. _docs_more_custom_theme: Syntax and GUI Themes ===================== @@ -84,17 +86,17 @@ Remember to also change the name of your theme by modifying the ``name`` setting file, otherwise you may not be able to distinguish them in **Preferences**. For novelWriter to be able to locate the custom theme files, you must copy them to the -:ref:`a_locations_data` location in your home or user area. There should be a folder there named +:ref:`docs_technical_locations_data` location in your home or user area. There should be a folder there named ``syntax`` for syntax themes, just ``themes`` for GUI themes, and ``icons`` for icon themes. These folders are created the first time you start novelWriter. Once the files are copied there, they should show up in **Preferences** with the label you set as ``name`` inside the file. -.. versionadded:: 2.0 - The ``icontheme`` value was added to GUI themes. Make sure you set this value in existing custom - themes. Otherwise, novelWriter will try to guess your icon theme, and may not pick the most - suitable one. +.. note:: + + The theme file formats change regularly in new releases. It is up to you to keep custom theme + files up to date. Custom GUI and Icons Theme @@ -112,7 +114,26 @@ A GUI theme ``.conf`` file consists of the following settings: url = https://example.com license = CC BY-SA 4.0 licenseurl = https://creativecommons.org/licenses/by-sa/4.0/ - icontheme = typicons_light + + [Icons] + default = 100, 100, 100 + faded = 100, 100, 100 + red = 255, 0, 0 + orange = 255, 128, 0 + yellow = 255, 255, 0 + green = 0, 255, 0 + aqua = 0, 255, 255 + blue = 0, 0, 255 + purple = 255, 0, 255 + + [Project] + root = 0, 255, 255 + folder = 255, 255, 0 + file = 100, 100, 100 + title = 0, 255, 0 + chapter = 255, 0, 0 + scene = 0, 0, 255 + note = 255, 255, 0 [Palette] window = 100, 100, 100 @@ -134,24 +155,23 @@ A GUI theme ``.conf`` file consists of the following settings: helptext = 0, 0, 0 fadedtext = 128, 128, 128 errortext = 255, 0, 0 - statusnone = 120, 120, 120 - statussaved = 2, 133, 37 - statusunsaved = 200, 15, 39 -In the Main section you must at least define the ``name`` and ``icontheme`` settings. The -``icontheme`` settings should correspond to one of the internal icon themes, either -``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. +In the Main section you must at least define the ``name`` settings. 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 ``0`` to ``255``. Omitted values are not loaded and will use default values. If the ``helptext`` colour is not defined, it is computed as a colour between the ``window`` and ``windowtext`` colour. +Additional shades of some of the colours are also computed. These are mainly used for 3D effects. .. versionadded:: 2.5 The ``fadedtext`` and ``errortext`` theme colour entries were added. +.. versionadded:: 2.7 + The ``icontheme`` setting was dropped as the icon theme is now its own setting. + The ``[Icons]`` and ``[Project]`` sections were added, and the ``status*`` settings removed. + Custom Syntax Theme ------------------- diff --git a/docs/source/more/handling_errors.rst b/docs/source/more/handling_errors.rst new file mode 100644 index 00000000..9c244e52 --- /dev/null +++ b/docs/source/more/handling_errors.rst @@ -0,0 +1,62 @@ +.. _docs_more_errors: + +*************** +Handling Errors +*************** + +In case something goes wrong, novelWriter has a few built-in features to reduce the chance your +work is lost. In case of a crash, it will also try to save whatever changes you have made before +exiting, if this is at all possible. + +The storage solution is designed to save each text document independently, so only the document +you're working on is actually at a risk of losing data in the event of a crash. + + +.. _docs_more_errors_orphaned: + +Recovered Documents +=================== + +If novelWriter crashes or otherwise exits without saving the project state, or if you're using a +file synchronisation tool that runs out of sync, there may be files in the project storage folder +that aren't tracked in the core project file. These files, when discovered, are recovered and added +back into the project when a project is opened. + +The discovered files are scanned for metadata that give clues as to where the document may +previously have been located in the project. The project loading routine 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 +it to the correct root folder type. If it cannot figure out which root folder is correct, the +document will be added to the **Novel** root folder. Finally, if a **Novel** does not exist, one +will be created. + +If the title of the document can be recovered, the word "Recovered:" will be added as a prefix to +indicate that it may need further attention. If the title cannot be determined, the document will +be named after its internal key, which is a string of characters and numbers. + + +.. _docs_more_errors_lock: + +Project Lockfile +================ + +To prevent data loss caused by file conflicts when novelWriter projects are synchronised via file +synchronisation tools, a project lockfile is written to the project storage folder when a project +is open. If you try to open a project that already has such a file present, you will be presented +with a warning, and some information about where else novelWriter thinks the project is also open. +You will be given the option to ignore this warning, and continue opening the project at your own +risk. + +.. note:: + + If, for some reason, novelWriter or your computer crashes, the lock file may remain even if + there are no other instances keeping the project open. In such a case it is safe to ignore the + lock file warning when re-opening the project. + +.. warning:: + + If you choose to ignore the warning and continue opening the project, and multiple instances of + the project are in fact open, you are likely to cause inconsistencies and create diverging + project files, potentially resulting in loss of data and orphaned files. You are not likely to + lose any actual text unless both instances have the same document open in the editor, and + novelWriter will try to resolve project inconsistencies the next time you open the project. diff --git a/docs/source/more_projectformat.rst b/docs/source/more/project_format.rst similarity index 87% rename from docs/source/more_projectformat.rst rename to docs/source/more/project_format.rst index 0648a453..da80370b 100644 --- a/docs/source/more_projectformat.rst +++ b/docs/source/more/project_format.rst @@ -1,12 +1,9 @@ -.. _a_prjfmt: +.. _docs_more_project_formats: ********************** Project Format Changes ********************** -.. _File Format Spec 1.5: _static/fileformatspec15.pdf -.. _documentation: https://docs.novelwriter.io/ - Most of the changes to the file formats over the history of novelWriter have no impact on the user side of things. The project files are generally updated automatically. However, some of the changes require minor actions from the user. @@ -17,13 +14,14 @@ where applicable. A full project file format specification is available under "More Documents". .. caution:: + When you update a project from one format version to the next, the project can no longer be opened by a version of novelWriter prior to the version where the new file format was introduced. You will get a notification about any updates to your project file format and will have the option to decline the upgrade. -.. _a_prjfmt_1_5: +.. _docs_more_project_formats_1_5: Format 1.5 Changes ================== @@ -37,7 +35,7 @@ heading of the document is now saved to the item rather than in the index. The c automatically the first time a project is loaded. No user action is required. -.. _a_prjfmt_1_4: +.. _docs_more_project_formats_1_4: Format 1.4 Changes ================== @@ -51,7 +49,7 @@ compact format that is simpler and faster to parse, and easier to extend. The co automatically the first time a project is loaded. No user action is required. -.. _a_prjfmt_1_3: +.. _docs_more_project_formats_1_3: Format 1.3 Changes ================== @@ -71,25 +69,26 @@ should be used only a few places in any given project. These are as follows: **Title Pages** * The formatting of the level one title on the title page must be changed from ``# Title Text`` to - ``#! Title Text`` in order to retain the previous functionality. See :ref:`a_fmt_head`. + ``#! Title Text`` in order to retain the previous functionality. + See :ref:`docs_usage_headings_levels`. * Any text that was previously centred on the page must be manually centred using the text - alignment feature. See :ref:`a_fmt_align`. + alignment feature. See :ref:`docs_usage_align_indent`. **Unnumbered Chapters** * Since the specific layout for unnumbered chapters has been dropped, such chapters must all use the ``##! Chapter Name`` formatting code instead of ``## Chapter Name``. This also includes chapters marked by an asterisk: ``## *Chapter Name``, as this feature has also been dropped. - See :ref:`a_fmt_head`. + See :ref:`docs_usage_headings_levels`. **Plain Pages** * The layout named "Plain Page" has also been removed. The only feature of this layout was that it ensured that the content always started on a fresh page. In the new format, fresh pages can be - set anywhere in the text with the ``[NEW PAGE]`` code. See :ref:`a_fmt_break`. + set anywhere in the text with the ``[new page]`` code. See :ref:`docs_usage_formatting_breaks`. -.. _a_prjfmt_1_2: +.. _docs_more_project_formats_1_2: Format 1.2 Changes ================== @@ -97,9 +96,10 @@ Format 1.2 Changes This project format was introduced in novelWriter version 0.10. With this format, the way auto-replace entries were stored in the main project XML file changed. +Conversion from this format is done automatically. -.. _a_prjfmt_1_1: +.. _docs_more_project_formats_1_1: Format 1.1 Changes ================== @@ -110,10 +110,11 @@ With this format, the ``content`` folder was introduced in the project storage. novelWriter documents were saved in a series of folders numbered from ``data_0`` to ``data_f``. It also reduces the number of meta data and cache files. These files are automatically deleted if -an old project is opened. This was also when the Table of Contents file was introduced. +an old project is opened. This was also when the Table of Contents file was introduced. Conversion +from this format is done automatically. -.. _a_prjfmt_1_0: +.. _docs_more_project_formats_1_0: Format 1.0 Changes ================== diff --git a/docs/source/usage_typography.rst b/docs/source/more/typography.rst similarity index 68% rename from docs/source/usage_typography.rst rename to docs/source/more/typography.rst index 189e0dd1..eb64c8b4 100644 --- a/docs/source/usage_typography.rst +++ b/docs/source/more/typography.rst @@ -1,4 +1,4 @@ -.. _a_typ: +.. _docs_more_typographical: ******************* Typographical Notes @@ -12,26 +12,22 @@ Typographical Notes novelWriter has some support for typographical symbols that are not usually easily available in many text editors. This includes for instance the proper unicode quotation marks, dashes, ellipsis, thin spaces, etc. All these symbols are available from the **Insert** menu, and via -keyboard shortcuts. See :ref:`a_kb_ins`. +keyboard shortcuts. See :ref:`docs_features_shortcuts_insert`. This chapter provides some additional information on how novelWriter handles these symbols. -.. _a_typ_notes: - -Special Notes on Symbols -======================== - -This section contains additional notes on the available special symbols. - - Dashes and Ellipsis -------------------- +=================== -With the auto-replace feature enabled (see :ref:`a_ui_edit_auto`), multiple hyphens are converted -automatically to short and long dashes, and three dots to ellipsis. The last auto-replace can -always be reverted with the undo command :kbd:`Ctrl+Z`, reverting the text to what you typed before -the automatic replacement occurred. +With the auto-replace feature enabled (see :ref:`docs_ui_edit_view_auto`), two and three hyphens +are converted automatically to short and long dashes, four hyphens to a horizontal bar, and three +dots to ellipsis. + +.. tip:: + + The last auto-replace can always be reverted with the undo command :kbd:`Ctrl+Z`, reverting the + text to what you typed 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 nicely in columns when you need @@ -39,24 +35,22 @@ to use a dash in them. Single and Double Quotes ------------------------- +======================== All the different quotation marks listed on the `Quotation Mark`_ Wikipedia page are available, and can be selected as auto-replaced symbols for straight single and double quote key strokes. The settings can be found in **Preferences**. -Ordinarily, text wrapped in quotes are highlighted by the editor. This is meant as a convenience -for highlighting dialogue between characters. This feature can be disabled in -**Preferences** if this feature isn't wanted. +If your text contains straight single and double quotes, there are two convenience functions in the +**Format** menu that 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 **Format** menu -can be used to re-format a selected section of text with the correct quote symbols. +You can enable dialogue recognition and colour highlighting for novel documents. +See :ref:`docs_features_dialogue` for more details. Single and Double Prime ------------------------- +======================= Both single and double prime symbols are available in the **Insert** menu. These symbols are the correct symbols to use for unit symbols for feet, inches, minutes, and seconds. The usage @@ -66,8 +60,10 @@ codes. Using these correctly will also prevent the auto-replace and dialogue hig misunderstanding their meaning in the text. +.. _docs_more_typographical_symbols_apostrophe: + Modifier Letter Apostrophe --------------------------- +========================== The auto-replace feature will consider any right-facing single straight quote as a quote symbol, even if it is intended as an apostrophe. This also includes the syntax highlighter, which may @@ -79,13 +75,15 @@ right single quotation marks, depending on the font. There is a Wikipedia articl `Modifier letter apostrophe`_ with more details. .. note:: + On export with the **Build Manuscript** tool, these apostrophes will be replaced automatically with the corresponding right hand single quote symbol as is generally recommended. - Therefore it doesn't really matter if you only use them to correct syntax highlighting. + Therefore it doesn't really matter if you only use them to correct syntax highlighting in some + places, and not others. -Special Space Symbols ---------------------- +White Space Symbols +=================== A few variations of the regular space character is supported. The correct typographical way to separate a number from its unit is with a `thin space`_. It is usually 2/3 the width of a regular @@ -97,5 +95,11 @@ A regular space can also be made into a non-breaking space if needed. All non-breaking spaces are highlighted with a differently coloured background to make it easier to spot them in the text. The colour will depend on the selected colour theme. -The thin and non-breaking spaces are converted to their corresponding HTML codes on export to HTML -format. +You can insert these spaces in your text using the following keyboard combinations: + +* A non-breaking space can be inserted with :kbd:`Ctrl+K`, :kbd:`Space`. +* Thin spaces are also supported, and can be inserted with :kbd:`Ctrl+K`, :kbd:`Shift+Space`. +* Non-breaking thin space can be inserted with :kbd:`Ctrl+K`, :kbd:`Ctrl+Space`. + +These are all insert features, and the **Insert** menu has more. The keyboard shortcuts for them +are also listed in :ref:`docs_features_shortcuts`. diff --git a/docs/source/project_overview.rst b/docs/source/project_overview.rst deleted file mode 100644 index 0fe08327..00000000 --- a/docs/source/project_overview.rst +++ /dev/null @@ -1,409 +0,0 @@ -.. _a_proj: - -***************** -Managing Projects -***************** - -Your text in novelWriter is organised into projects. Each project is meant to contain one novel -and associated notes. If you have multiple novels in a series, with the same characters and shared -notes, it is also possible to keep all of them in the same project. - -.. _a_proj_new: - -Creating Project -================ - -New projects can be created from the **Project** menu by selecting **Create or Open Project**. This -will open the **Welcome** dialog, where you can select the :guilabel:`New` button that will assist -you in creating a new project. This dialog is also displayed when you start novelWriter. - -A novelWriter project requires a dedicated folder for storing its files on the local file system. -If you're interested in the details, you can have a look at the chapter :ref:`a_storage`. - -A list of recently opened projects is maintained, and displayed in the **Welcome** dialog. A -project can be removed from this list by selecting it and pressing the :kbd:`Del` key or by -right-clicking it and selecting the **Remove Project** option. - -.. figure:: images/fig_welcome.jpg - - The project list (left) and new project form (right) of the :guilabel:`Welcome` dialog. - -Project-specific settings are available in **Project Settings** in the **Project** menu. See -further details below in the :ref:`a_proj_settings` section. - -Details about the project's novel text, including word counts, and a table of contents with word -and page counts, is available through the **Novel Details** dialog. Statistics about the project -is also available in the **Manuscript Build** tool. - - -Template Projects ------------------ - -From the Welcome dialog you can also create a new from another existing project. If you have a -specific structure you want to use for all your new projects, you can create a dedicated project to -be used as a template, and select to copy an existing project from the :guilabel:"Prefill Project" -option from the **New Project** form. - - -.. _a_proj_roots: - -Project Structure -================= - -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 :term:`novel documents` go into a root folder of type **Novel**. :term:`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 -the project tree tool bar. - -Each root folder has one or more :term:`reference` :term:`keyword` associated with it that is used -to reference them from other documents and notes. The intended usage of each type of root folder is -listed below. However, aside from the **Novel** folder, no restrictions are applied by the -application on what you put in them. You can use them however you want. - -The root folder system is closely connected to how the Tags and References system works. For more -details, see the :ref:`a_references` chapter. - - -Root Folder Types ------------------ - -**Novel** - This is the root folder type for text that goes into the final novel or novels. This class of - documents have other rules and features than the project notes. See :ref:`a_struct` for more - details. - -**Plot** - This is the root folder type where main plots can be outlined. It is optional, but adding at - least 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. - -**Characters** - Character notes go in this root folder type. These are especially important if you want to use - the **Outline View** to see which character appears where, which part of the story is told from - a specific character's point-of-view, or focusing on a particular character's storyline. - - The character names can also be inserted into for instance chapter titles when you create your - manuscript. Tags in this type of folder can be referenced using the ``@pov`` keyword for - point-of-view characters, ``@focus`` for a focus character, or the ``@char`` keyword for any - other character present. - -**Locations** - The locations folder type is for various scene locations that you want to track. Tags in this - folder can be references using the ``@location`` keyword. - -**Timeline** - If the story has multiple plot timelines or jumps in time within the same plot, this folder type - can be used to track this. Tags in this type of folder can be references using the ``@time`` - keyword. - -**Objects** - Important objects in the story, for instance physical objects that change hands often, can be - tracked here. Tags in this type of folder can be references using the ``@object`` keyword. - -**Entities** - Does your plot have many powerful organisations or companies? Or other entities that are part of - the plot? They can be organised here. Tags in this type of folder can be references using the - ``@entity`` keyword. - -**Custom** - The custom root folder type can be used for tracking anything else not covered by the above - options. Tags in this folder type can be references using the ``@custom`` keyword. - -The root folders are closely tied to the tags and reference system. Each folder type corresponds to -categories of tags that can be used to reference them. For more information about the tags listed, -see :ref:`a_references_references`. - -There is also a ``@mention`` keyword that can be used to reference any tag. -See :ref:`a_references_references` for more details. - -.. note:: - - You can rename root folders to whatever you want. However, this doesn't change the reference - keyword or what they do. - - -.. _a_proj_roots_del: - -Deleted Documents ------------------ - -Deleted documents are moved into a special **Trash** root folder. Documents in the trash folder can -then be deleted permanently, either individually, or by emptying the trash from the menu. Documents -in the trash folder are removed from the :term:`project index` and cannot be referenced. - -A document or a folder can be moved to trash from the **Project** menu, or by pressing -:kbd:`Ctrl+Shift+Del`. Root folders can only be removed when they are empty. - - -.. _a_proj_roots_out: - -Archived Documents ------------------- - -If you don't want to delete a document, or put it in the **Trash** folder where it may be deleted -accidentally, but still want it out of your main project tree, you can create an **Archive** root -folder instead and move it there. It has the same effect as moving it to **Trash**, but it is safe -from deletion. - -You can drag any document to this folder and preserve its settings. The document will always be -excluded from the **Build Manuscript** tool. It is also removed from the :term:`project index`, so -the tags and references defined in it will not show up anywhere else. - - -.. _a_proj_roots_dirs: - -Using Folders in the Project Tree ---------------------------------- - -Regular folders, those that are not root folders, have no structural significance to the project. -When novelWriter is processing the documents in a project, like for instance when you create a -manuscript from it, these folders are ignored. Only the order of the documents themselves matter. - -The folders are there purely as a way for you to organise the documents in meaningful sections and -to be able to collapse and hide them in the project tree when you're not working on those -documents. - -In addition to using folders. it is also possible to add child documents to other documents. This -is particularly useful when you create chapters and scenes. If you add separate scene documents, -you should also add separate chapter documents, even if they only contain a chapter heading. You -can then add scene documents as child items to the chapters. - - -.. _a_proj_roots_orphaned: - -Recovered Documents -------------------- - -If novelWriter crashes or otherwise exits without saving the project state, or if you're using a -file synchronisation tool that runs out of sync, there may be files in the project storage folder -that aren't tracked in the core project file. These files, when discovered, are recovered and added -back into the project when a project is opened. - -The discovered files are scanned for metadata that give clues as to where the document may -previously have been located in the project. The project loading routine 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 -it to the correct root folder type. If it cannot figure out which root folder is correct, the -document will be added to the **Novel** root folder. Finally, if a **Novel** does not exist, one -will be created. - -If the title of the document can be recovered, the word "Recovered:" will be added as a prefix to -indicate that it may need further attention. If the title cannot be determined, the document will -be named after its internal key, which is a string of characters and numbers. - - -.. _a_proj_roots_lock: - -Project Lockfile ----------------- - -To prevent data loss caused by file conflicts when novelWriter projects are synchronised via file -synchronisation tools, a project lockfile is written to the project storage folder when a project -is open. If you try to open a project which already has such a file present, you will be presented -with a warning, and some information about where else novelWriter thinks the project is also open. -You will be given the option to ignore this warning, and continue opening the project at your own -risk. - -.. note:: - - If, for some reason, novelWriter or your computer crashes, the lock file may remain even if - there are no other instances keeping the project open. In such a case it is safe to ignore the - lock file warning when re-opening the project. - -.. warning:: - - If you choose to ignore the warning and continue opening the project, and multiple instances of - the project are in fact open, you are likely to cause inconsistencies and create diverging - project files, potentially resulting in loss of data and orphaned files. You are not likely to - lose any actual text unless both instances have the same document open in the editor, and - novelWriter will try to resolve project inconsistencies the next time you open the project. - - -.. _a_proj_files: - -Project Documents -================= - -New documents can be created from the toolbar in the project tree, or by pressing :kbd:`Ctrl+N`. -This will open the create new item menu and let you choose between a number of pre-defined -documents and folders. You will be prompted for a label for the new item. - -You can always rename an item by selecting **Rename Item** from the **Project** menu, or by -pressing :kbd:`F2` when a document or folder is selected. - -Other settings for project documents and folders are available from the context menu that you can -activate by right-clicking on an it in the tree. The **Transform** submenu includes options for -converting, splitting, or merging documents. See :ref:`a_ui_tree_split_merge` for more details on -the latter two. - - -Document Templates ------------------- - -If you wish to create template documents to be used when creating new project documents, like for -instance a character note template, you can add a **Templates** root folder to your project. Any -document added to this root folder will show up in the **Add Item** menu in the project tree -toolbar. When selected, a new document is created with its content copied from the chosen template. - -.. versionadded:: 2.3 - - -.. _a_proj_files_counts: - -Word Counts ------------ - -A character, word and paragraph count is maintained for each document, as well as for each section -of a document following a :term:`heading`. The word count and change of words in the -current session is displayed in the footer of any document open in the editor, and all stats are -shown in the details panel below the project tree for any document selected in the project or novel -trees. - -The word counts are not updated in real time, but run in the background every few seconds for as -long as the document is being actively edited. - -A total project word count is displayed in the status bar. The total count depends on the sum of -the values in the project tree, which again depend on an up to date :term:`project index`. If the -counts seem wrong, a full project word recount can be initiated by rebuilding the project's index. -Either from the **Tools** menu, or by pressing :kbd:`F9`. - -The rules for how the counts are made is covered in more detail in :ref:`a_counting`. - - -.. _a_proj_settings: - -Project Settings -================ - -The **Project Settings** can be accessed from the **Project** menu, or by pressing -:kbd:`Ctrl+Shift+,`. This will open a dialog box, with a set of tabs. - - -Settings Tab ------------- - -The **Settings** tab holds the project name, author, and language settings. - -The **Project Name** can be edited here. It is used for the main window title and for generating -backup files. So keep in mind that if you do change this setting, the backup file names will change -too. - -You can also change the **Authors** and **Project Language** setting. These are only used when -building the manuscript, for some formats. The language setting is also used when inserting text -into documents in the viewer, like for instance labels for keywords and special comments. - -If your project is in a different language than your main spell checking language is set to, you -can override the default setting here. The project language can also be changed from the **Tools** -menu. - -You can also override the automatic backup setting for the project if you wish. - - -Status and Importance Tabs --------------------------- - -Each document or folder of type **Novel** can be given a "Status" label accompanied by a coloured -icon with an optional shape selected from a list of pre-defined shapes. Each document or folder of -the remaining types can be given an "Importance" label with the same customisation options. - -These labels are there purely for your convenience, and you are not required to use them for any -other features to work. No other part of novelWriter accesses this information. The intention is to -use these to indicate at what stage of completion each novel document is, or how important the -content of a note is to the story. You don't have to use them this way, that's just what they were -intended for, but you can make them whatever you want. - -Both status and importance labels can be exported and imported so you can share them between -projects, or define a standard set for all your writing projects. When you import labels to a -project, they are always added as *new* labels. - -See also :ref:`a_ui_tree_status`. - -.. note:: - - The status or importance level currently in use by one or more documents cannot be deleted, but - they can be edited. - - -Auto-Replace Tab ----------------- - -A set of automatically replaced keywords can be added in this tab. The keywords in the left column -will be replaced by the text in the right column when documents are opened in the viewer. They will -also be applied to manuscript builds. - -The auto-replace feature will replace text in angle brackets that is in this list. The syntax -highlighter will add an alternate colour to text matching the syntax, but it doesn't check if the -text is in this list. - -.. note:: - A keyword cannot contain spaces. The angle brackets are added by default, and when used in the - text are a part of the keyword to be replaced. This is to ensure that parts of the text aren't - unintentionally replaced by the content of the list. - - -.. _a_proj_backup: - -Backup -====== - -An automatic backup system is built into novelWriter. In order to use it, a backup path to where -the backup files are to be stored must be provided in **Preferences**. The path defaults to a -folder named "Backups" in your home directory. - -Backups can be run automatically when a project is closed, which also implies it is run when the -application itself is closed. Backups are date stamped zip files of the project files in the -project folder (files not strictly a part of the project are ignored). The zip archives are stored -in a subfolder of the backup path. The subfolder will have the same name as the **Project Name** as -defined in :ref:`a_proj_settings`. - -The backup feature, when configured, can also be run manually from the **Tools** menu. It is also -possible to disable automated backups for a given project in **Project Settings**. - -.. note:: - For the backup to be able to run, the **Project Name** must be set in **Project Settings**. This - value is used to generate the name and path of the backups. Without it, the backup will not run - at all, but it will produce a warning message. - - -.. _a_proj_stats: - -Writing Statistics -================== - -When you work on a project, a log file records when you opened it, when you closed it, and the -total word counts of your novel documents and notes at the end of the session, provided that the -session lasted either more than 5 minutes, or that the total word count changed. For more details -about the log file, see :ref:`a_storage`. - -A tool to view the content of the log file is available in the **Tools** menu under **Writing -Statistics**. You can also launch it by pressing :kbd:`F6`, or find it on the sidebar. - -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 or Excel. - -.. versionadded:: 1.2 - - 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, or the user hasn't made - any changes to the currently open document in five minutes. The number of minutes can be altered - in **Preferences**. - - -Session Timer -------------- - -A session timer is by default visible in the status bar. The icon will show you a clock icon when -you are active, and a pause icon when you are considered "idle" per the criteria mentioned above. - -If you do not wish to see the timer, you can click on it once to hide it. The icon will still be -visible. Click the icon once more to display the timer again. - -.. versionadded:: 2.6 - - As of version 2.6, clicking the timer text or icon in the status bar will toggle its visibility. diff --git a/docs/source/project_references.rst b/docs/source/project_references.rst deleted file mode 100644 index 1bea77b2..00000000 --- a/docs/source/project_references.rst +++ /dev/null @@ -1,244 +0,0 @@ -.. _a_references: - -******************* -Tags and References -******************* - -In novelWriter there are no forms or tables to fill in to define characters, locations or other -elements of your story. Instead, you create :term:`project notes` which you can mark as -representing these story elements by creating a :term:`tag`. Whenever you want to link a piece of -your story to a note defining a story element, like a character, you create a :term:`reference` -back to that tag. You can also cross-link your project notes in the same way. - -This is perhaps one of the features that makes novelWriter different from other, similar -applications. It is therefore not always obvious to new users how this is supposed to work, so -this chapter hopes to explain in more detail how to use this tags and references system. - -.. tip:: - - If you find the Tags and Reference system difficult to follow just from reading this chapter, - you can create a new project in the **Welcome** dialog's New project form and select "Create an - example project" from the "Pre-fill project" option. The example project contains several - examples of tags and references. - - -.. _a_references_metadata: - -Metadata in novelWriter -======================= - -The structure of your novelWriter project is inferred from the :term:`headings` within the -documents, not the documents themselves. See :ref:`a_struct_heads` for more details. Therefore, -metadata is also associated with headings, and not the documents directly. - -If you split your project into separate documents for each scene, this distinction may not matter. -However, there are several benefits to using documents at a larger structural scale when first -starting your project. For instance, it may make more sense to define all your scenes, and even -chapters, in a single document at first, or perhaps a document per act. You can later split these -documents up using the document split feature. See :ref:`a_ui_tree_split_merge` for more details. - -You can do the same with your notes. You can treat each heading as an independent element of your -notes that can be referenced somewhere else. That way you can collect all your minor or background -characters in a single note file, and still be able to reference them individually by separating -them with headings and assigning each a tag. Or, you can lay out your plot in a single document and -have a tag for each plot stage under separate headings. - - -.. _a_references_tags: - -How to Use Tags -=============== - -A "tag" in novelWriter is a word or phrase that you define as belonging to a heading. Tags are set -by using the ``@tag`` :term:`keyword`. - -The basic format of a tag is ``@tag: tagName``. - -An alternative format of a tag is ``@tag: tagName | displayName``. - -``tagName`` (Required) - This is a unique identifier of your choosing. It is the value you use later for making - references back to this document, or section of the document. - -``displayName`` (Optional) - This is an optional display name used for the tag. When you build your manuscript, you can for - instance insert the point of view character name directly into chapter headings. By default, the - ``tagName`` value is used in such headings, but if you use a shortened format internally in your - project, you can use this to specify a more suitable format for your manuscript headings. - -You can only set **one** tag per heading, and the tag has to be unique across **all** documents in -the project. - -After a tag has been defined, it can be referenced in novel documents, or cross-referenced in other -notes. Tags will also show up in the **Outline View** and in the references panel under the -document viewer when a document is open in the viewer. - -The syntax highlighter will indicate to you that the keyword is correctly used and that the tag is -allowed, that is, the tag is unique. Duplicate tags should be detected as long as the index is up -to date. An invalid tag should have a green wiggly line under it, and will not receive the colour -that valid tags do. - -The tag is the only part of these notes that novelWriter uses. The rest of the document content is -there for you to use in whatever way you wish. Of course, the content of the documents can be added -to the manuscript, or an outline document. If you want to compile a single document of all your -notes, you can do this from the **Manuscript Build** tool. - -.. versionadded:: 2.2 - - Tags are no longer case sensitive. The tags are by default displayed with the capitalisation you - use when defining the tag, but you don't have to use the same capitalisation when referencing - it later. - -.. versionadded:: 2.3 - - Tags can have an optional display name for manuscript builds. - -.. versionadded:: 2.6 - - You can now add tags also to Novel Documents. These can be used for cross-referencing between - chapters and scenes, and also from notes if desired. - -Example of a heading with a tag for a character of the story: - -.. code-block:: md - - # Character: Jane Doe - - @tag: Jane | Jane Doe - - Some information about the character Jane Doe. - -When this is done in a document in a :term:`Root Folder` of type "Characters", the tag is -automatically treated as an available character in your project with the value "Jane", and you will -be able to reference it in any of your other documents using the reference keywords for characters. -It will also show up in the Character tab in the Reference panel below the document viewer, and in -the reference auto-completer menu in the editor when you fill in references. See :ref:`a_ui_view` -and :ref:`a_references_completer`. - -It is the root folder type that defines what category of story elements the tag is indexed under. -See the :ref:`a_proj_roots` section for an overview of available root folder types. They are also -covered in the next section. - - -.. _a_references_references: - -How to Use References -===================== - -Each heading of any level in your project can contain references to tags set in project notes. The -references are gathered by the indexer and used to generate the **Outline View**, among other -things. - -References are set as a :term:`keyword` and a list of corresponding tags. The valid keywords are -listed below. The format of a reference line is ``@keyword: value1, [value2] ... [valueN]``. All -reference keywords allow multiple values. - -``@pov`` - The point-of-view character for the current section. The target must be a note tag in a - **Character** type root folder. - -``@focus`` - The character that has the focus for the current section. This can be used in cases where the - focus is not a point-of-view character. The target must be a note tag in a **Character** type - root folder. - -``@char`` - Other characters in the current section. The target must be a note tag in a **Character** type - root folder. This should not include the point-of-view or focus character if those references - are used. - -``@plot`` - The plot or subplot advanced in the current section. The target must be a note tag in a **Plot** - type root folder. - -``@time`` - The timelines touched by the current section. The target must be a note tag in a **Timeline** - type root folder. - -``@location`` - The location the current section takes place in. The target must be a note tag in a - **Locations** type root folder. - -``@object`` - Objects present in the current section. The target must be a note tag in a **Object** type root - folder. - -``@entity`` - Entities present in the current section. The target must be a note tag in an **Entities** type - root folder. - -``@custom`` - Custom references in the current section. The target must be a note tag in a **Custom** type - root folder. The custom folder are for any other category of notes you may want to use. - -``@mention`` - Anything mentioned, but not present in the current section. It is intended for those cases where - you reveal details about a character or place in a scene without it being otherwise a part of - it. This can be useful when checking for consistency later. Any tag in any root note folder can - be listed under mentions. - -``@story`` - This is used when referencing a Novel Document, like a scene or chapter, from somewhere else in - your project. - -The syntax highlighter will alert the user that the tags and references are used correctly, and -that the tags referenced exist. - -.. note:: - - The highlighter may be mistaken if the index of defined tags is out of date. If so, press - :kbd:`F9` to regenerate it, or select **Rebuild Index** from the **Tools** menu. In general, the - index for a document is regenerated when it is saved, so this shouldn't normally be necessary. - -.. tip:: - - If you add a reference in the editor to a tag that doesn't yet exist, you can right-click it and - select **Create Note for Tag**. This will generate a new project note automatically with the new - tag defined. In order for this to be possible, a root folder for that category of references - must already exist. - -One note can also reference another note in the same way novel documents do. When the note is -opened in the document viewer, the references become clickable links, making it easier to follow -connections in the plot. You can follow links in the document editor by clicking them with the -mouse while holding down the :kbd:`Ctrl` key. Clicked links are always opened in the view panel. - -Project notes don't show up in the **Outline View**, so referencing between notes is only -meaningful if you want to be able to click-navigate between them, or of course if you just want to -highlight that two notes are related. - -.. tip:: - - If you cross-reference between notes and export your project as an HTML document using the - **Manuscript Build** tool, the cross-references become clickable links in the exported HTML - document as well. - -Example of a novel document with references to characters and plots: - -.. code-block:: md - - ## Chapter 1 - - @pov: Jane - - ### Scene 1 - - @char: John, Sam - @plot: Main - - Once upon a time ... - - -.. _a_references_completer: - -The References Auto-Completer ------------------------------ - -An auto-completer context menu will show up automatically in the document editor when you type the -character ``@`` on a new line. It will first suggest tag or reference keywords for you to add, and -after the ``:`` has been added, suggest references from the list of tags you have already defined. - -You can use the auto-completer to add multiple references with a ``,`` between them, and even type -new ones. New references can be created by right-clicking on them and selecting **Create Note for -Tag** from the menu. - -.. versionadded:: 2.2 diff --git a/docs/source/project_structure.rst b/docs/source/project_structure.rst deleted file mode 100644 index ea78cc4a..00000000 --- a/docs/source/project_structure.rst +++ /dev/null @@ -1,163 +0,0 @@ -.. _a_struct: - -*************** -Novel Structure -*************** - -This chapter covers the structure of a novel project. - -There are two different types of documents in a project, **Novel Documents** and **Project Notes**. -Active novel documents can only live in a **Novel** type root folder. You can also move them to -**Archive** and **Trash** of course, where they become inactive. - -The project tree can distinguish between the different heading levels of the novel documents using -coloured icons, and optionally add emphasis on the label. Emphasis can be enabled in -**Preferences**. - - -.. _a_struct_heads: - -Importance of Headings -====================== - -Subfolders under root folders have no impact on the structure of the novel itself. The structure is -instead dictated by the heading level of the headings within the documents. - -Four levels of headings are supported, signified by the number of hashes (``#``) preceding the -title. See also the :ref:`a_fmt` section for more details about the markup syntax. - -.. note:: - - The heading levels are not only important when generating the manuscript, they are also used by - the indexer when building the outline tree in the **Outline View** as well as in the **Novel - Tree**. Each heading also starts a new region where new Tags and References can be defined. See - :ref:`a_references` for more details. - -The syntax for the four basic heading types, and the three special types, is listed in section -:ref:`a_fmt_head`. The meaning of the four levels for the structure of your novel is as follows: - -**Heading Level 1: Partition** - This heading level signifies that the text refers to a top level heading. 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 heading level ``#!`` covered in :ref:`a_fmt_head`. - -**Heading Level 2: Chapter** - This heading level signifies a chapter. 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. - -**Heading Level 3: Scene** - This heading level signifies a scene. You must provide a title text, but the title text can be - replaced with a scene separator or just skipped entirely when you build your manuscript. If you - need to distinguish between hard and soft scene breaks, there is an alternative format for - scenes you can use for this distinction. The formatting is covered in :ref:`a_fmt_head`. See - also :ref:`a_struct_heads_scenes`. - -**Heading Level 4: Section** - This heading level can be used to split up a scene, usually called a "section" in the - documentation and the user interface. These can be useful if you want to change references - mid-scene, like if you change the point-of-view character. You are free to use sections as you - wish, and you can filter them out of the final manuscript. - -Page breaks can be automatically added before titles, partition, chapter and scene headings from -the **Manuscript Build** tool when you build your project to a format that supports page breaks. If -you want page breaks in other places, you have to specify them manually. See :ref:`a_fmt_break`. - -.. tip:: - - There are multiple options of how to process novel headings when building the manuscript. For - instance, chapter numbers can be applied automatically, and so can scene numbers if you want - them in a draft manuscript. You can also insert point-of-view character names in chapter titles. - See the :ref:`a_manuscript` page for more details. - -.. note:: - - As of 2.6, the heading levels internally in novelWriter do not map directly to heading levels in - manuscript documents. In manuscript documents, chapters are considered the top level heading, - and partitions become plain text paragraphs with a larger font. - - .. versionadded:: 2.6 - - -.. _a_struct_heads_title: - -Novel Title and Front Matter ----------------------------- - -It is recommended that you add a document at the very top of each **Novel** root folder with the -novel title in it. You should modify the level 1 heading format code with an ``!`` in order to -render it as a document title that is excluded from any automatic Table of Content in a manuscript -build document. - -You can also add the author name and address above this if this is required by the manuscript -format you use, and additional space added before the title. - -This is the title page novelWriter generates automatically for a new project as of version 2.6: - -.. code-block:: md - - Jane Doe[br] - Address 1[br] - Address 2 << - - [vspace:5] - - #! My Novel - - >> **By Jane Doe** << - - >> Word Count: [field:textWords] << - -The title is by default centred on the page. 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 of text 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 -before the text. See also :ref:`a_fmt_break`. - - -.. _a_struct_heads_unnum: - -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 can add an ``!`` to the level 2 heading formatting code to tell -the build tool to skip these chapters when adding numbers. - -.. code-block:: md - - ##! Unnumbered Chapter Title - - Chapter Text - -There is a separate formatting feature for such chapter titles in the **Manuscript Build** tool as -well. See the :ref:`a_manuscript` page for more details. When building a document of a format that -supports page breaks, also unnumbered chapters can have a page break added just like for normal -chapters. - - -.. _a_struct_heads_scenes: - -Hard and Soft Scene Breaks --------------------------- - -If you need two different ways to style scenes in your manuscript, like if you want to insert -different scene separators for soft and hard scene breaks, there is an alternative scene format -available for scene headings with a ``!`` added to the formatting code. - -.. code-block:: md - - ### Soft Scene Transition - - A soft scene break. - - ###! Hard Scene Transition - - A hard scene break. - -There is a separate formatting feature for these titles in the **Manuscript Build** tool. - -.. versionadded:: 2.4 diff --git a/docs/source/tech_locations.rst b/docs/source/technical/locations.rst similarity index 93% rename from docs/source/tech_locations.rst rename to docs/source/technical/locations.rst index cc4b612e..cbc8a5d0 100644 --- a/docs/source/tech_locations.rst +++ b/docs/source/technical/locations.rst @@ -1,4 +1,4 @@ -.. _a_locations: +.. _docs_technical_locations: ************** File Locations @@ -10,7 +10,7 @@ novelWriter will create a few files on your system outside of the application fo file locations are described in this chapter. -.. _a_locations_conf: +.. _docs_technical_locations_conf: Configuration ============= @@ -33,7 +33,7 @@ user's username on Windows. different way, these locations may also be different. -.. _a_locations_data: +.. _docs_technical_locations_data: Application Data ================ @@ -62,4 +62,4 @@ The Application Data location also holds several folders: ``icons``, ``syntax`` and ``themes`` These folders are empty by default, but this is where the user can store custom theme files. - See :ref:`a_custom` for more details. + See :ref:`docs_more_custom` for more details. diff --git a/docs/source/tech_source.rst b/docs/source/technical/source.rst similarity index 95% rename from docs/source/tech_source.rst rename to docs/source/technical/source.rst index 6e0fc62b..6b69b491 100644 --- a/docs/source/tech_source.rst +++ b/docs/source/technical/source.rst @@ -1,4 +1,4 @@ -.. _a_source: +.. _docs_technical_source: ******************* Running from Source @@ -12,6 +12,7 @@ This chapter describes various ways of running novelWriter directly from the sou to build the various components like the translation files and documentation. .. note:: + The text below assumes the command ``python`` corresponds to a Python 3 executable. Python 2 is now deprecated, but on many systems the command ``python3`` may be needed instead. Likewise, ``pip`` may need to be replaced with ``pip3``. @@ -22,10 +23,10 @@ by running: .. code-block:: bash - python pkgutils.py help + python pkgutils.py --help -.. _a_source_depend: +.. _docs_technical_source_depend: Dependencies ============ @@ -50,13 +51,14 @@ source, dependencies can still be installed from PyPi with: pip install -r requirements.txt .. note:: + On Linux distros, the Qt library is usually split up into multiple packages. In some cases, secondary dependencies may not be installed automatically. For novelWriter, the library files for rendering the SVG icons may be left out and needs to be installed manually. This is the case on for instance Arch Linux. -.. _a_source_install: +.. _docs_technical_source_install: Build and Install from Source ============================= @@ -89,7 +91,7 @@ different: pip install --user dist/novelWriter-2.0.7-py3-none-any.whl -.. _a_source_i18n: +.. _docs_technical_source_i18n: Building the Translation Files ============================== @@ -109,12 +111,13 @@ This requires that the Qt Linguist tool is installed on your system. On Ubuntu a 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.md`` file in the ``i18n`` folder of the source code. -.. _a_source_sample: +.. _docs_technical_source_sample: Building the Example Project ============================ @@ -128,7 +131,7 @@ running: python pkgutils.py sample -.. _a_source_docs: +.. _docs_technical_source_docs: Building the Documentation ========================== diff --git a/docs/source/tech_storage.rst b/docs/source/technical/storage.rst similarity index 77% rename from docs/source/tech_storage.rst rename to docs/source/technical/storage.rst index fac04949..4d0ceeaa 100644 --- a/docs/source/tech_storage.rst +++ b/docs/source/technical/storage.rst @@ -1,12 +1,54 @@ -.. _a_storage: +.. _docs_technical_storage: ****************** How Data is Stored ****************** +.. _version control: https://en.wikipedia.org/wiki/Version_control + This chapter contains details of how novelWriter stores and handles the project data. +Overview +======== + +The files of a novelWriter project are stored in a dedicated project folder. The project structure +is kept in a file at the root of this folder called ``nwProject.nwx``. All the document files and +associated meta data are stored in other folders below the project folder. + +This way of storing data was chosen for several reasons. + +Firstly, all the text you add to your project is saved directly to your project folder in separate +files. Only the project structure and the text you are currently editing is stored in memory at any +given time, which means there is a smaller risk of losing data if the application or your computer +crashes. + +Secondly, having multiple small files means it is very easy to synchronise them between computers +with standard file synchronisation tools. + +Thirdly, if you use `version control`_ software to track the changes to your project, the file +formats used for the files are well suited. All the JSON documents have line breaks and indents as +well, which makes it easier to track them with version control software. + +.. note:: + + Since novelWriter has to keep track of a bunch of files and folders when a project is open, it + may not run well on some virtual file systems. A file or folder must be accessible with exactly + the path it was saved or created with. An example where this is not the case is the way Google + Drive is mapped on Linux Gnome desktops using gvfs/gio. + +.. caution:: + + You should not add additional files to the project folder yourself. Nor should you, as a rule, + manually edit files within it. If you really must manually edit the text files, e.g. with some + automated task you want to perform, you need to rebuild the Project Index when you open + the project again. + + Editing text files in the ``content`` folder is less risky as these are just plain text. Editing + the main project XML file, however, may make the project file unreadable and you may crash + novelWriter and lose project structure information and project settings. + + Project Structure ================= diff --git a/docs/source/tech_tests.rst b/docs/source/technical/tests.rst similarity index 99% rename from docs/source/tech_tests.rst rename to docs/source/technical/tests.rst index f4502594..56623ff4 100644 --- a/docs/source/tech_tests.rst +++ b/docs/source/technical/tests.rst @@ -1,4 +1,4 @@ -.. _a_pytest: +.. _docs_technical_pytest: ************* Running Tests diff --git a/docs/source/usage/advanced_formatting.rst b/docs/source/usage/advanced_formatting.rst new file mode 100644 index 00000000..557db1a7 --- /dev/null +++ b/docs/source/usage/advanced_formatting.rst @@ -0,0 +1,149 @@ +.. _docs_usage_formatting: + +******************* +Advanced Formatting +******************* + +Standard Markdown formatting is somewhat limited, so novelWriter has some additional formatting +codes for special use cases. These codes are all based on brackets, and some allow an additional +value to be set after a colon. + +This section covers all these formatting codes. + + +.. _docs_usage_formatting_shortcodes: + +Formatting with Shortcodes +========================== + +For basic formatting, like emphasis, you should use the standard Markdown style formatting tags +descried in :ref:`docs_usage_basics_emphasis` whenever possible. + +For additional formatting options, you can use shortcodes. Shortcodes is a form of in-line codes +that wrap the section of text to be formatted. Shortcodes can be nested to apply multiple formats +to the same piece of text. + +These shortcodes are intended for special formatting cases, or more complex cases that cannot be +solved with simple Markdown-like formatting codes. Available shortcodes are listed below. + +.. csv-table:: Shortcodes Formats + :header: "Syntax", "Description" + :widths: 40, 60 + :class: "tight-table" + + "``[b]text[/b]``", "Text is displayed as bold text." + "``[i]text[/i]``", "Text is displayed as italicised text." + "``[s]text[/s]``", "Text is displayed as strike through text." + "``[u]text[/u]``", "Text is displayed as underlined text." + "``[m]text[/m]``", "Text is displayed as highlighted text." + "``[sup]text[/sup]``", "Text is displayed as superscript text." + "``[sub]text[/sub]``", "Text is displayed as subscript text." + "``[footnote:key]``", "A reference to a :ref:`footnote comment `." + +Unlike Markdown style codes, these can be used anywhere within a paragraph. Even in the middle of a +word if you need to. You can also freely combine them to form more complex formatting. + +The shortcodes are available from the **Format** menu and in the editor toolbar, which can be +activated by clicking the left-most icon button in the editor header. + +.. note:: + + Shortcodes are not processed until you generate a preview or generate a manuscript document. So + there is no highlighting of the text between the formatting markers. There is also no check that + your markers make sense. You must ensure that you have both the opening and closing formatting + markers where you want them. + +.. versionadded:: 2.2 + + +.. _docs_usage_formatting_breaks: + +Vertical Space and Page Breaks +============================== + +You can apply page breaks to partition, chapter and scene headings for novel documents from the +**Manuscript Build** tool. If you need to add a page break or additional vertical spacing in other +places, there are special codes available for this purpose. + +Adding more than one line break between paragraphs will **not** increase the space between those +paragraphs when generating a manuscript document. To add additional space between paragraphs, add +the text ``[vspace]`` on a line of its own, and the **Manuscript 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. + +If you need to add a page break somewhere, put the text ``[new page]`` on a line by itself before +the text you wish to start on a new page. + +.. note:: + + The page break code is applied to the text that follows it. It adds a "page break before" mark + to the text when exporting to HTML or Open Document. This means that a ``[new page]`` code which + has no text following it will not result in a page break. + +:bdg-info:`Example` + +.. code-block:: md + + This is a text paragraph. + + [vspace:2] + + This is another text paragraph, but there will be two empty paragraphs + between them. + + [new page] + + This text will start on a new page if the build format supports pages. + + +.. _docs_usage_formatting_counts: + +Inserting Word Counts in the Text +================================= + +The cover page of a manuscript normally has the word count stated on it. Any statistics value +collected by novelWriter can be inserted into any document using a special shortcode. You can +insert the code for any of the available statistics values from the **Insert** menu under +**Word/Character Count**. + +The value inserted is the actual count for your entire manuscript, so it is not populated until you +run the **Manuscript Build** tool. Until then they will show up as "0" in the viewer panel. + +The available codes are: + +.. csv-table:: Stats Shortcodes + :header: "Code", "Description" + :class: "tight-table" + + "``[field:allChars]``", "Characters" + "``[field:textChars]``", "Characters in Text" + "``[field:titleChars]``", "Characters in Headings" + "``[field:paragraphCount]``", "Paragraphs" + "``[field:titleCount]``", "Headings" + "``[field:allWordChars]``", "Characters, No Spaces" + "``[field:textWordChars]``", "Characters in Text, No Spaces" + "``[field:titleWordChars]``", "Characters in Headings, No Spaces" + "``[field:allWords]``", "Words" + "``[field:textWords]``", "Words in Text" + "``[field:titleWords]``", "Words in Headings" + +:bdg-info:`Example` + +This is an example cover page. A similar page is automatically generated when you create a new +project. + +.. code-block:: md + + Jane Smith[br] + 42 Main Street[br] + 1234 Capital City << + + [vspace:5] + + #! Example + + >> **By Jane Smith** << + + >> Word Count: [field:textWords] << diff --git a/docs/source/usage/alignment_and_indent.rst b/docs/source/usage/alignment_and_indent.rst new file mode 100644 index 00000000..2494ea32 --- /dev/null +++ b/docs/source/usage/alignment_and_indent.rst @@ -0,0 +1,78 @@ +.. _docs_usage_align_indent: + +************************* +Alignment and Indentation +************************* + +The Markdown standard doesn't have commands for aligning text, so novelWriter adds its own syntax +for this. It also has syntax for indentation, which is similar to Markdown block quotes. + + +Paragraph Alignment and Indentation +=================================== + +All documents have the text by default aligned to the left or justified, depending on your setting +in **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. + +:bdg-info:`Example` + +.. 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." + "``> Left indented text``", "The text has an increased left margin." + "``Right indented text <``", "The text has an increased right margin." + "``> Left/right indented text <``", "The text has 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 **Manuscript Build** tool as long as the format supports paragraph alignment. + + +Alignment with Line Breaks +========================== + +If you have line breaks in the paragraph, the markers for all the lines are combined and used for +the entire paragraph. For the following text, all lines will be centred: + +:bdg-info:`Example` + +.. code-block:: md + + >> I am the very model of a modern Major-General + I've information vegetable, animal, and mineral + I know the kings of England, and I quote the fights historical + From Marathon to Waterloo, in order categorical << + + +Alignment with First Line Indent +================================ + +If you have first line indent enabled in your manuscript build settings, you probably want to +disable it for text in verses. Adding any alignment tags will cause the first line indent to be +switched off for that paragraph. + +:bdg-info:`Example` + +The following text will always be aligned against the left margin: + +.. code-block:: md + + I am the very model of a modern Major-General << + I've information vegetable, animal, and mineral + I know the kings of England, and I quote the fights historical + From Marathon to Waterloo, in order categorical diff --git a/docs/source/usage/basic_formatting.rst b/docs/source/usage/basic_formatting.rst new file mode 100644 index 00000000..8a5d59c6 --- /dev/null +++ b/docs/source/usage/basic_formatting.rst @@ -0,0 +1,95 @@ +.. _docs_usage_basics: + +**************** +Basic Formatting +**************** + +.. _Markdown: https://en.wikipedia.org/wiki/Markdown + +The basic text formatting syntax of novelWriter is based on Markdown_. It is only a subset of the +Markdown syntax though. Lists, images, and links are not supported. + +That said, URLs in the text should automatically be highlighted and become clickable. However, only +URLs starting with "http" or "https" are recognised. In the editor, you must hold down the +:kbd:`Ctrl` key when clicking a URL to follow it. + + +.. _docs_usage_basics_paragraphs: + +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. + +It is important that you actually follow this rule. You should not, for instance, mimic indented +paragraphs manually in the editor. This, and a lot of other formatting options that can be +applied to text paragraphs in the :ref:`Manuscript Tool ` depend on paragraphs +being separated by blank lines. + +:bdg-success:`Correct` + +.. code-block:: md + + ### Scene + + This is a text paragraph. + + This is another text paragraph. + +:bdg-danger:`Incorrect` + +.. code-block:: md + + ### Scene + + This is a text paragraph. + This is meant to be another text paragraph. + +If you do as shown in the "Incorrect" example, novelWriter will understand this as a single +paragraph with two lines. + + +.. _docs_usage_basics_emphasis: + +Text Emphasis with Markdown +=========================== + +A minimal set of Markdown text emphasis styles are supported for text paragraphs. + +``_text_`` + The text is rendered as emphasised text (italicised). + +``**text**`` + The text is rendered as strongly emphasised text (bold). + +``~~text~~`` + Strike through text. + +In Markdown guides it is often recommended to differentiate between strong emphasis 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 strike through 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. +5. Text emphasis can only be used in comments and paragraphs. Headings and meta data tags don't + allow for formatting, and any formatting markup will be displayed as-is. + +.. tip:: + + novelWriter supports standard escape syntax for the emphasis markup characters in case the + editor misunderstands your intended usage of them. That is, ``\*``, ``\_`` and ``\~`` will + generate a plain ``*``, ``_`` and ``~``, respectively, without interpreting them as part of the + markup. diff --git a/docs/source/usage/chapters_and_scenes.rst b/docs/source/usage/chapters_and_scenes.rst new file mode 100644 index 00000000..106e2364 --- /dev/null +++ b/docs/source/usage/chapters_and_scenes.rst @@ -0,0 +1,96 @@ +.. _docs_usage_headings: + +******************* +Chapters and Scenes +******************* + +.. _Markdown: https://en.wikipedia.org/wiki/Markdown + +Since novelWriter uses a plain text format, the structure of your novel must follow a certain set +of simple rules. For documents in a **Novel** type root folder, it is the heading that determines +if the document is a chapter or a scene. + +The formatting of headings is based on Markdown_. A heading is indicated by a line starting with +one or more ``#`` characters. It accepts up to four of these. You can use multiple headings in the +same document, but it is the first heading that determines which icon and information is displayed +in the project tree. + +.. note:: + + You can use the same heading levels for your notes in the other root folders, but they aren't + treated as chapters or scenes, so there you are free to use them as you want. + + +.. _docs_usage_headings_levels: + +Heading Levels +============== + +.. figure:: images/fig_heading_levels.png + + An illustration of how heading levels correspond to the novel structure. + +Four levels of headings are understood for novel documents. You can pick and choose from these as +you want, but if your story has chapters, you should use these headings to indicate them. If you +also add scene headings, you have better control of how your scene separators are formatted in your +manuscript. The chapter and scenes headings are also displayed in the +:ref:`Novel View ` and :ref:`Outline View `. + +``# Title Text`` + This is a heading level one. This heading indicates the start of a new partition. Partitions are + for when you want to split your story into "Part 1", "Part 2", etc. You can also choose to use + them for splitting the text up into acts, and then hide these headings in your manuscript so + that they are not included in the output. + +``## Chapter Title`` + This is a heading level two. This heading indicates the start of a new chapter. Chapter numbers + can be inserted automatically when building the manuscript, so you don't have to do this in the + title. See :ref:`docs_ui_manuscript_head_numbers` for more details. + +``### Scene Title`` + This is a heading level three. This heading indicates the start of a new scene. Scene numbers or + scene separators can be inserted automatically when building the manuscript, so you can use the + title field as a working title for your scenes if you wish, but you must provide a minimal + title. + +``#### Section Title`` + This is a heading level four. This heading indicates the start of a new section. Section titles + can be replaced by separators or ignored completely when building the manuscript. The meaning of + a section is really whatever you want it to be. You can use it to split your scenes up into + chunks, or into separate documents. + +For headings level one through three, adding a ``!`` modifies the meaning of the heading. The +alternative meaning of the heading is only relevant when you generate your manuscript, but you may +want to keep the use cases in mind while writing. + +``#! Title Text`` + This tells the **Manuscript Build** tool that the level one heading is intended to be used for + the novel or notes folder's main title, like for instance the novel title on the cover page. + When building the manuscript, this will use a different styling of the title, which you can + modify independently from how partition titles are styled. + See :ref:`docs_usage_front_back_matter_title` for more details. + +``##! Chapter Title`` + This tells the **Manuscript Build** tool to not assign a chapter number to this chapter title if + automatic chapter numbers are enabled. Such titles are useful for prologues and epilogues for + instance. See :ref:`docs_usage_front_back_matter_unnumbered` for more details. + +``###! Scene Title`` + This is an alternative scene heading that can be formatted differently in the **Manuscript + Build** tool. It is intended for separating "soft" and "hard" scene breaks. Aside from this, it + behaves identically to a regular scene heading. See :ref:`docs_ui_manuscript_head_hard_soft` + for more details. + +The formatting of these headings can be customised quite extensively in the +:ref:`Manuscript Tool `, which is covered in a separate part of the +documentation. + +.. note:: + + The space after the ``#`` or ``!`` character is mandatory. The editor will change colour and + font size when the heading is correctly formatted. + +Page breaks can be automatically added before titles, partition, chapter and scene headings from +the **Manuscript Build** tool when you build your project to a format that supports page breaks. +If you want page breaks in other places, you have to specify them manually. +See :ref:`docs_usage_formatting_breaks` for more details. diff --git a/docs/source/usage/comments.rst b/docs/source/usage/comments.rst new file mode 100644 index 00000000..426f32b1 --- /dev/null +++ b/docs/source/usage/comments.rst @@ -0,0 +1,164 @@ +.. _docs_usage_comments: + +****************** +Comments and Notes +****************** + +You can add comments to your text that are not a part of the story. Regular comments are intended +for you to add notes to yourself inside the text, which may be useful when you revise your drafts. +However, there are several types of comments you can use. + +This section covers the basic comment types. There are a couple of advanced features that use +comment syntax too, but they are covered later. + + +.. _docs_usage_comments_plain: + +Plain Comments +============== + +A plain comment is a line or paragraph that starts with the character ``%`` as its first character. +You can put them wherever you like in your documents, and you can choose to include or exclude them +from your manuscript. + +For the most part, novelWriter completely ignores these comments. They are not included in your +word or character counts either, and are only displayed in the document viewer panel if you enable +them. + +:bdg-info:`Example` + +.. code-block:: md + + ### Scene + + A regular text paragraph in the scene. + + % A comment you've added for your own notes. + + Another regular text paragraph in the scene. + + +.. _docs_usage_comments_synopsis: + +Synopsis or Description Comments +================================ + +A special kind of comments are **Synopsis** and **Short Description** comments. They are different +from plain comments in that they can be displayed alongside other information about a scene or a +character or other story element described in a note. As with plain comments, they can be included +in your manuscript, but they are formatted differently than plain comments. + +.. note:: + + A summary or description comment can be used once, and only once, for each heading as they are + considered a description of the content of the text under that heading. If you add two such + comments under the same heading, the last one will be used. + + +Synopsis +-------- + +A **Synopsis** comment is intended for adding a summary of your chapters and scenes. + +:bdg-info:`Example` + +.. code-block:: md + + ### Scene + + %Synopsis: A summary of the content of the scene. + + The actual scene text. + + +Short Description +----------------- + +A **Short Description** comment behaves exactly the same as a synopsis comment, but is intended as +a description of a story element, like a character. + +:bdg-info:`Example` + +.. code-block:: md + + # Characters + + ## Darth Vader + + %Short: A Sith Lord that used to be a Jedi. + + Your text about the character. + + ## Luke Skywalker + + %Short: A Jedi. The son of Darth Vader. + + Your text about the character. + +.. note:: + + The ``%Synopsis:`` and ``%Short:`` comment prefixes are interchangeable, but when you include + them in the manuscript, they are labelled based on the prefix, so the latter may make more sense + for a Character note than the former. + + +.. _docs_usage_comments_footnotes: + +Footnote Comments +================= + +Footnotes are added with a shortcode, paired with a matching comment for the actual footnote text. +The matching is done with a key that links the two. If you insert a footnote from the **Insert** +menu, a unique key is generated for you. Shortcodes in general are covered in more detail in +:ref:`docs_usage_formatting_shortcodes`. + +The insert footnote feature will add the footnote shortcode marker at the position of your cursor +in the editor panel, and create the associated footnote comment right after the paragraph. It will +then move the cursor there so you can immediately start typing the footnote text. + +The footnote comment can be anywhere in the document, so if you wish to move them to, say, the +bottom of the text, you are free to do so. + +Footnote keys are only required to be unique within a document, so if you copy, move or merge text, +you must make sure the keys are not duplicated. If you use the automatically generated keys from +the **Insert** menu, they are unique among all indexed documents. They are not guaranteed to be +unique against footnotes in the **Archive** or **Trash** folder though, but the chance of +accidentally generating the same key twice in a project is relatively small. + +:bdg-info:`Example` + +.. code-block:: md + + ### Scene + + This is a text paragraph with a footnote[footnote:fn1] in the middle. + + %Footnote.fn1: This is the text of the footnote. + +.. versionadded:: 2.5 + + +.. _docs_usage_comments_ignored: + +Ignored Text +============ + +If you want to completely ignore some of the text in your documents, but are not ready to delete +it, you can add ``%~`` before the text paragraph or line. This will cause novelWriter to skip the +text entirely when generating previews or building manuscripts. + +This is a better way of removing text than converting them to regular comments, as you may want to +include regular comments in your previews or draft manuscript. + +You can toggle the ignored text feature on and off for a paragraph by pressing :kbd:`Ctrl+Shift+D` +on your keyboard with your cursor somewhere in the paragraph. + +:bdg-info:`Example` + +.. code-block:: md + + ### Scene + + %~ This text is ignored. + + This text is a regular paragraph. diff --git a/docs/source/usage/front_back_matter.rst b/docs/source/usage/front_back_matter.rst new file mode 100644 index 00000000..27a0fcbb --- /dev/null +++ b/docs/source/usage/front_back_matter.rst @@ -0,0 +1,79 @@ +.. _docs_usage_front_back_matter: + +********************* +Front and Back Matter +********************* + +Front and back matter documents are documents that go before and after your main story text. They +can include pages like your cover page, content tables, prologues, epilogues, etc. These special +pages and sections are supported to some extent by novelWriter. + + +.. _docs_usage_front_back_matter_title: + +The Title Page +============== + +It is recommended that you add a document at the very top of each **Novel** root folder with the +novel title in it. You should modify the level 1 heading format code with an ``!`` in order to +render it as a document title that is excluded from any automatic Table of Content in a manuscript +build document. + +You can also add the author name and address above this if this is required by the manuscript +format you use, and additional space added before the title. + +:bdg-info:`Example` + +This is the title page novelWriter generates automatically for a new project as of version 2.6: + +.. code-block:: md + + Jane Doe[br] + Address Line 1[br] + Address Line 2 << + + [vspace:5] + + #! My Novel + + >> **By Jane Doe** << + + >> Word Count: [field:textWords] << + +The title is by default centred on the page. You can add more text to the page as you wish, like +for instance the author's name and details. + +The default title page inserts the word count for text only, but you can add other counts too. +See :ref:`docs_usage_formatting_counts` for more details. + + +.. _docs_usage_front_back_matter_pages: + +Additional Pages +================ + +If you want an additional page of text 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 +before the text. See :ref:`docs_usage_formatting_breaks` for more details. + + +.. _docs_usage_front_back_matter_unnumbered: + +Unnumbered Chapters +=================== + +If you use the automatic numbering feature for your chapters, but you want to keep some special +chapters separate from this, you can add an ``!`` to the level 2 heading formatting code to tell +the build tool to skip these chapters when adding numbers. + +Unnumbered chapters are useful for prologue and epilogue chapters, and also for interlude chapters +if you use those in your text. There is a separate formatting feature for such chapter titles in +the **Manuscript Build** tool. See the :ref:`docs_ui_manuscript` page for more details. + +:bdg-info:`Example` + +.. code-block:: md + + ##! Unnumbered Chapter Title + + Chapter Text diff --git a/docs/source/int_howto.rst b/docs/source/usage/howto.rst similarity index 94% rename from docs/source/int_howto.rst rename to docs/source/usage/howto.rst index 0a393f40..3e884029 100644 --- a/docs/source/int_howto.rst +++ b/docs/source/usage/howto.rst @@ -1,4 +1,4 @@ -.. _a_howto: +.. _docs_usage_howto: ************* Tips & Tricks @@ -33,7 +33,7 @@ Managing the Project 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 - can 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:`docs_ui_split_merge` for more details. .. dropdown:: How do I share status or importance labels between projects? :animate: fade-in-slide-down @@ -76,7 +76,7 @@ Layout Tricks indented, you can disable the indentation by explicitly adding text alignment. For instance by adding ``<<`` to the end to left-align it. Aligned paragraphs are not indented. - See :ref:`a_fmt_align` for more details. + See :ref:`docs_usage_align_indent` for more details. Organising Your Text @@ -102,7 +102,7 @@ Organising Your Text **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 hide soft scene breaks, which will just insert - an empty paragraph in their place. See :ref:`a_manuscript_settings` for more details. + an empty paragraph in their place. See :ref:`docs_ui_manuscript_settings` for more details. .. versionadded:: 2.4 diff --git a/docs/source/usage/images/fig_heading_levels.png b/docs/source/usage/images/fig_heading_levels.png new file mode 100644 index 00000000..f9be1e37 Binary files /dev/null and b/docs/source/usage/images/fig_heading_levels.png differ diff --git a/docs/source/usage/images/fig_project_tree.png b/docs/source/usage/images/fig_project_tree.png new file mode 100644 index 00000000..eab2ac7e Binary files /dev/null and b/docs/source/usage/images/fig_project_tree.png differ diff --git a/docs/source/usage/introduction.rst b/docs/source/usage/introduction.rst new file mode 100644 index 00000000..47dceb98 --- /dev/null +++ b/docs/source/usage/introduction.rst @@ -0,0 +1,57 @@ +.. _docs_usage: + +************ +Introduction +************ + +.. _Markdown: https://en.wikipedia.org/wiki/Markdown + +In a nutshell, novelWriter is a plain text editor that lets you organise one or more novels and +associated notes as many smaller documents. You can at any time generate standard document formats +from these plain text documents. Whether it is an outline of your story, a draft, a complete +manuscript, or even a collection of your character notes or other notes. + + +Why Plain Text? +=============== + +The idea is to let you be creative without having to deal with formatting while you are writing, or +be distracted by it. + +Of course, you probably need *some* form of minimal 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, which is how you distinguish +between chapters and scenes. + +For those special cases where you need more complex formatting, a set of shortcodes are available. +To make these codes easier to use, a dropdown button bar is available in the editor panel with +standard format buttons. So don't worry. You don't have to learn any of these codes. + + +Adding Meta Data +================ + +In addition to the body text of your story, novelWriter allows you to enter some additional meta +data into your text documents to indicate things like which characters are present in a chapter or +scene, whose point of view we're seeing, what location the events take place in, and so on. + +Since the editor is plain text, this is done on special lines of text starting with an ``@`` +character. The editor will show an auto-complete menu to help you write these lines. We will talk +more about this later. + +You can also add your own author's comments in your text, without these comments becoming a part of +the story itself. A comment line starts with a ``%`` character. There are different types of +comments, and an auto-complete menu can help you here too. More about this later as well. + +.. admonition:: Limitations + + Please keep in mind that 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. It is also *not* a full-featured Markdown editor. + + In addition, novelWriter is 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 is + mainly intended for character profiles and plot outlines. It is recommended to use a proper + note-taking tool for research. This is anyway more practical as you may use the same research + for multiple projects. diff --git a/docs/source/usage/organising_project.rst b/docs/source/usage/organising_project.rst new file mode 100644 index 00000000..4c8f1cf4 --- /dev/null +++ b/docs/source/usage/organising_project.rst @@ -0,0 +1,202 @@ +.. _docs_usage_project: + +*********************** +Organising Your Project +*********************** + +Your project is organised into a set of top level folders called "Root Folders", which each have +specific meaning in the project. Your project documents and notes are stored under these root +folders. All the content of your project is available in the **Project Content** panel on the left +side of the main window. + +.. figure:: images/fig_project_tree.png + + The **Project Content** tree populated with example documents. + +Each line in the project tree shows the name of each item, its word count (or alternatively +character count), an icon for :ref:`docs_usage_project_active`, and a custom icon for +:ref:`docs_usage_project_status` of each item. These latter two are covered alter in this section. + +You can add, view and edit documents in the project tree by right-clicking on them. Some features +are also located in the buttons along the top, next to the **Project Content** label. + + +.. _docs_usage_project_roots: + +How Root Folders Work +===================== + +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. Each type of root folder has a distinct icon. + +The documents that make up your story go into a root folder of type **Novel**. Your notes go into +the other root folders. These other root folder types are separated into types depending on what +kind of notes go into them. This is not only for organisation. It also matters to how you can +reference these notes later. We will come back to this in the :ref:`docs_usage_tags_refs` section. + +A new project may not have all of the root folders present, but you can add the ones you want from +the project tree tool bar. + +The intended usage of each type of root folder is listed below. However, aside from the **Novel** +folder, no restrictions are applied by novelWriter on what you put in them. You can use them +however you want. + + +Root Folder Types +----------------- + +**Novel** (Story) + This is where you put the documents that are part of your story. You can create multiple Novel + folders if you wish, but various parts of the application assumes each Novel folder belong to + one novel. + + The Novel folder is somewhat special in that it can contain documents for chapters, scenes and + story partitions. How this is indicated is covered in the section :ref:`docs_usage_headings`. + +**Plot** (Notes) + This is where you can keep notes and outlines of your story plots. Such notes can be + particularly useful if you have outlines for sub plot. You can make references to these subplots + from the scene documents, which makes it easier to track story progress. + +**Characters** (Notes) + Character notes go in this root folder type. For your main characters, you may want to make one + document for each character. For smaller characters you can put multiple into the same document. + In your chapters and scenes you can reference these character notes as point-of-view or focus + characters. + +**Locations** (Notes) + The locations where your story takes place can be documented here. This, together with Plot and + Characters are the key story elements to track, and to reference from your chapter and scene + documents. + +**Timeline** (Notes) + If the story has multiple plot timelines or jumps in time within the same plot, this folder type + can be used to track this. + +**Objects** (Notes) + Important objects in the story, for instance physical objects that change hands often, can be + tracked here. + +**Entities** (Notes) + Does your plot have many powerful organisations or companies? Or other entities that are part of + the plot? They can be organised here. + +**Custom** (Notes) + The custom root folder type can be used for tracking anything else not covered by the above + options. + +**Templates** + Any document added under this root folder will be made available as template options when + creating new documents. See :ref:`docs_usage_project_documents_templates` for more details. + +**Archive** + If you don't want to delete a document, or put it in the **Trash** folder where it may be + deleted, but still want it out of your main project, you can put it in this folder. The contents + of the document will be ignored by the scanner that looks for tags, and it will be ignored in + any outline view and in your manuscript. + +**Trash** + This folder behaves like you expect. Anything dropped in here can be deleted permanently from + the project, and the content doesn't show up anywhere else in novelWriter. + +The root folder types are closely tied to the tags and reference system. Each folder type for novel +and notes corresponds to one or more categories of tags that can be used to reference the content +in them. See :ref:`docs_usage_tags_refs` for more details. + +.. tip:: + + The root folders have standard names, but you can rename them to whatever you want. + + +.. _docs_usage_project_folders: + +Regular Folders +=============== + +You can add regular folders anywhere you want in the project. The folders are there purely as a way +for you to organise the documents in meaningful sections and to be able to collapse and hide them +in the project tree when you're not working on those documents. + +When novelWriter is processing the documents in a project, like for instance when you create a +manuscript from it, these folders are ignored. Only the order of the documents themselves matter. + + +.. _docs_usage_project_documents: + +Documents +========= + +You can add documents anywhere you want in your project structure. You can even add documents as +child items of other documents, just as if they were folders. This makes it easy to associate a set +of scenes with their chapter. You can also do this in your notes, where you for instance may have a +hierarchy of your locations. + +The name on a document in the project tree is not linked to any headings in the document text. +Think of the document name as a file name. You can rename a document, or any other item in the +project, at any time. + +Documents come in two types: + +**Novel Documents** + These are the documents that make up your story or novel. They can only be added under a root + folder of type **Novel**. You can technically also add them under **Archive**. See + :ref:`docs_usage_headings` for more details on how these documents are handled by novelWriter. + +**Project Notes** + These are the documents where you keep your notes. You can add them anywhere in your project, + including under **Novel** type folders. If you do add them there, they are not treated as a part + of the story by default. + +You can convert between the two types of documents where both types are allowed. You can also +convert folders into documents, which may sometimes be convenient too. + +Another convenient feature is that documents can be split into sub-documents by its headings, or +multiple documents merged into one. This is particularly useful if you start out with larger +structural documents, like one containing all chapters and scenes in an act, and then split those +when you start writing. See :ref:`docs_ui_split_merge` for more details. + + +.. _docs_usage_project_documents_templates: + +Document Templates +------------------ + +If you wish to create template documents to be used when creating new documents, like for instance +a character note template, you can add a **Templates** root folder to your project. Any document +added to this root folder will show up in the **Add Item** menu in the project tree toolbar. When +selected, a new document is created with its content copied from the chosen template. + +.. versionadded:: 2.3 + + +.. _docs_usage_project_active: + +Active and Inactive Documents +============================= + +A document can be set as "Active" or "Inactive", which alters the icon in the third column of the +project tree. These are mostly intended for your convenience as they will indicate whether the +document is meant to be included in the manuscript or not. You can think of an inactive status as a +whole-document out-take. It allows you to take it out without moving it to **Archive**. + +Inactive documents are by default excluded from your manuscript, but you can override this if you +wish. See :ref:`docs_ui_manuscript_selection` for more details. + + +.. _docs_usage_project_status: + +Importance and Status +===================== + +Each document or folder in your project can have either a "Status" or "Importance" label set. These +are labels and icons that you control and define yourself, and novelWriter doesn't use them for +anything. You can modify these labels in **Project Settings**. +See :ref:`docs_ui_projects_settings_status` for more details. + +The "Status" labels are intended to tag a novel document as for instance a draft or as completed, +and the "Importance" labels are intended to tag character notes, or other project notes, as for +instance a main, major, or minor character or story element. + +Whether a document uses a "Status" or "Importance" label depends on which root folder it lives in. +If it's in a **Novel** type folder, it uses the "Status" label, otherwise it uses an "Importance" +label. diff --git a/docs/source/usage/tags_and_references.rst b/docs/source/usage/tags_and_references.rst new file mode 100644 index 00000000..e99ea6ce --- /dev/null +++ b/docs/source/usage/tags_and_references.rst @@ -0,0 +1,231 @@ +.. _docs_usage_tags_refs: + +******************* +Tags and References +******************* + +One of the core features of novelWriter is its **Tags and References** system. This is perhaps one +of the features that makes novelWriter different from other similar applications. It is therefore +not always obvious to new users how this is supposed to work. + +In novelWriter there are no forms or tables to fill in to define characters, locations or other +elements of your story. Instead, you create documents in one of the root folders for notes. Within +these documents you can set **tags**, like for instance for your main character. If you then want +to annotate a scene with this character as its point-of-view, you create a **reference** to the +tag. + +.. tip:: + + If you find the Tags and Reference system difficult to follow just from reading this chapter, + you can create a new project in the **Welcome** dialog's New Project form and select "Create an + example project" from the "Pre-fill project" option. The example project contains several + examples of tags and references. + + +.. _docs_usage_tags_refs_tags: + +How to Use Tags +=============== + +The structure of your novelWriter project is inferred from the headings within the documents, not +the documents themselves. See :ref:`docs_usage_headings` for more details. Therefore, metadata is +also associated with headings, and not the documents themselves. + +A "tag" in novelWriter is a word or phrase that you define as belonging to a heading. Tags are set +by using the ``@tag`` keyword. + +The basic format of a tag is ``@tag: TagName``. + +An alternative format of a tag is ``@tag: TagName | Display Name``. + +``tagName`` (Required) + This is a unique identifier of your choosing. It is the value you use later for making + references back to the heading in the document. The tag must be unique. + +``Display Name`` (Optional) + This is an optional display name used for the tag. When you build your manuscript, you can for + instance insert the point-of-view character name directly into chapter titles. By default, the + ``tagName`` value is used in such headings, but if you use a shortened format internally in your + project, you can use the display name to specify a more suitable format for your chapter title. + +.. note:: + + You can only set **one** tag per heading, and the tag has to be unique across **all** documents + in the project. + +After a tag has been defined, it can be referenced in novel documents, or cross-referenced in other +notes. Tags will also show up in the **Outline View** and in the **References** panel under the +document viewer when a document is open in the viewer. See :ref:`docs_ui_main_outline` and +:ref:`docs_ui_edit_view_view_references` for more details. + +The editor will indicate to you that the keyword is correctly used and that the tag is allowed, +that is, the tag is unique, by adding a colour highlighting to it. An invalid tag should have a +wiggly line under it, and will not receive the colour that valid tags do. + +The tag is the only part of notes that novelWriter uses. The rest of the document content is there +for you to use in whatever way you wish. + +.. versionadded:: 2.2 + + Tags are no longer case sensitive. The tags are by default displayed with the capitalisation you + use when defining the tag, but you don't have to use the same capitalisation when referencing + it later. + +.. versionadded:: 2.3 + + Tags can have an optional display name for manuscript builds. + +.. versionadded:: 2.6 + + You can now add tags also to Novel Documents. These can be used for cross-referencing between + chapters and scenes, and also from notes if desired. + +:bdg-info:`Example` + +Example of a note document for a character with a tag set: + +.. code-block:: md + + # Character: Jane Doe + + @tag: Jane | Jane Doe + + Some information about the character Jane Doe. + +When this is done in a document in a root folder of type **Characters**, the tag is automatically +treated as an available character in your project with the value "Jane". You will then be able to +reference "Jane" in any of your other documents using the reference keywords for characters. + +The character "Jane" will also show up in the **Character** tab in the **Reference** panel below +the document viewer. + +.. note:: + + It is the root folder type that defines what category of story elements the tag is indexed + under. See :ref:`docs_usage_project_roots` for more details. + + +.. _docs_usage_tags_refs_refs: + +How to Use References +===================== + +Each heading of any level in your project can contain references to tags set in your notes. The +references are gathered by the project index and used to generate the **Outline View**, among other +things. + +References are set with a special keyword, with a list of corresponding tags. The valid keywords +are listed below. The format of a reference line is ``@keyword: value1, [value2] ... [valueN]``. +All reference keywords allow multiple values. + +``@pov`` + The point-of-view character for the current section. The target must be a note tag in a + **Character** type root folder. + +``@focus`` + The character that has the focus for the current section. This can be used in cases where the + focus is not the point-of-view character. The target must be a note tag in a **Character** type + root folder. + +``@char`` + For other characters in the current section. The target must be a note tag in a **Character** + type root folder. This should not include the point-of-view or focus character if those + references are used. + +``@plot`` + The plot or subplot advanced in the current section. The target must be a note tag in a **Plot** + type root folder. + +``@time`` + The timelines touched by the current section. The target must be a note tag in a **Timeline** + type root folder. + +``@location`` + The location the current section takes place in. The target must be a note tag in a + **Locations** type root folder. + +``@object`` + Objects present in the current section. The target must be a note tag in a **Object** type root + folder. + +``@entity`` + Entities present in the current section. The target must be a note tag in an **Entities** type + root folder. + +``@custom`` + Custom references in the current section. The target must be a note tag in a **Custom** type + root folder. The custom folder are for any other category of notes you may want to use. + +``@mention`` + For anything, anyone or anyplace mentioned, but not present in the current section. It is + intended for those cases where you reveal details about a character or place in a scene without + otherwise being a part of it. This can be useful when checking for consistency later. Any tag in + any root note folder can be listed under ``@mention``. + +``@story`` + This is used when referencing a Novel Document, like a scene or chapter, from somewhere else in + your project. It is possible to also set tags in documents in a **Novel** type folder, and this + is the keyword you use to reference those. + +When tags and references are used correctly, it will be indicated by highlight colours in the +editor. + +.. note:: + + The highlighter may be mistaken if the index of defined tags is out of date. If so, press + :kbd:`F9` to regenerate it, or select **Rebuild Index** from the **Tools** menu. In general, the + index for a document is regenerated when it is saved, so this shouldn't normally be necessary. + +.. tip:: + + If you add a reference in the editor to a tag that doesn't yet exist, you can right-click it and + select **Create Note for Tag**. This will generate a new note automatically in the correct type + of root folder, with the new tag defined. + +One note can also reference another note in the same way novel documents do. When the note is +opened in the document viewer, the references become clickable links, making it easier to follow +connections in the plot. You can follow links in the document editor by clicking them with the +mouse while holding down the :kbd:`Ctrl` key. Clicked links are always opened in the view panel. + +Your notes don't show up in the **Outline View**, so referencing between notes is only meaningful +if you want to be able to click-navigate between them, or of course if you just want to highlight +that two notes are related. + +.. tip:: + + If you cross-reference between notes and export your project as an HTML document using the + **Manuscript Build** tool, the cross-references become clickable links in the exported HTML + document as well. + +:bdg-info:`Example` + +Example of a novel document with references to characters and plots: + +.. code-block:: md + + ## Chapter 1 + + @pov: Jane + + ### Scene 1 + + @char: John, Sam + @plot: Main + + Once upon a time ... + + +.. _docs_usage_tags_refs_completer: + +Auto-Completion in the Editor +----------------------------- + +An auto-completer context menu will show up automatically in the document editor when you type the +character ``@`` on a new line. It will first suggest tag or reference keywords for you to add, and +after the ``:`` has been added, suggest references from the list of tags you have already defined. + +You can use the auto-completer to add multiple references with a ``,`` between them, and even type +new ones. Notes for new references can be created by right-clicking on them and selecting **Create +Note for Tag** from the menu. + +.. versionadded:: 2.2 diff --git a/docs/source/usage_breakdown.rst b/docs/source/usage_breakdown.rst deleted file mode 100644 index d4bc5fad..00000000 --- a/docs/source/usage_breakdown.rst +++ /dev/null @@ -1,290 +0,0 @@ -.. _a_breakdown: - -************ -How it Works -************ - -.. _Fusion: https://doc.qt.io/qt-6/gallery.html -.. _Pandoc: https://pandoc.org/ -.. _Open Document: https://en.wikipedia.org/wiki/OpenDocument -.. _Office Open XML: https://en.wikipedia.org/wiki/Office_Open_XML -.. _version control: https://en.wikipedia.org/wiki/Version_control - -The main features of novelWriter are listed in the :ref:`a_intro` chapter. In this chapter, we go -into some more details on how they are implemented. This is intended as an overview. Later on in -this documentation these features will be covered in more detail. - - -.. _a_breakdown_design: - -GUI Layout and Design -===================== - -The user interface of novelWriter is intended to be as minimalistic as practically possible, while -at the same time provide useful features needed for writing a novel. - -The main window does not by default have an editor toolbar like many other applications do. This -reduces clutter, and since the documents are formatted with style tags, it is not needed most of -the time. Still, a small formatting toolbar can be popped out by clicking the left-most button in -the header of the document editor. It gives quick access to standard formatting codes. - -Most formatting features supported are available through convenient keyboard shortcuts. They are -also available in the main menu under **Format**, so you don't have to look up formatting codes -every time you need them. For reference, a list of all shortcuts can be found in the :ref:`a_kb` -chapter. - -.. note:: - novelWriter is not intended to be a full office type word processor. It doesn't support images, - links, tables, and other complex structures and objects often needed for such documents. - Formatting is limited to headings, in-line basic text formats, text alignment, and a few other - simple features. - -On the left side of the main window, you will find a sidebar. This bar has buttons for the standard -views you can switch between, a quick link to the **Build Manuscript** tool, and a set of -project-related tools and quick access to settings at the bottom. - -.. versionadded:: 2.2 - - A number of new formatting options were added in 2.2 to allow for some special formatting cases. - At the same time, a small formatting toolbar was added to the editor. It is hidden by default, - but can be opened by pressing the button in the top--left corner of the editor header. - - -Project Tree and Editor View ----------------------------- - -.. figure:: images/fig_project_tree_view.png - - A screenshot of the Project Tree and Editor View. - -When the application is in **Project Tree View** mode, the work area of 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 on the right side contains a document viewer which can view any document in -your project independently of what is open in the document editor. This panel is not intended as a -preview window, although you can use it for this purpose if you wish. For instance if you need to -check that the formatting tags behave as you expect. However, the main purpose of the viewer is for -viewing your notes next to your editor while you're writing. - -The editor also has a **Focus Mode** you can toggle either from the menu, from the icon in the -editor's header, or by pressing :kbd:`F8`. When **Focus Mode** is enabled, all the user interface -elements other than the document editor itself are hidden away. - -The project tree will highlight with a different background colour the document that is currently -open in the editor. - -.. versionadded:: 2.6 - - You can now drag and drop documents from the project tree onto the editor or viewer panels to - open them. - - -Novel View and Editor View --------------------------- - -.. figure:: images/fig_novel_tree_view.png - - A screenshot of the Novel Tree and Editor View. - -When the application is in **Novel Tree View** mode, the project tree is replaced by an overview of -your novel structure for a specific Novel :term:`root folder`. Instead of showing individual -documents, the tree now shows all headings of your novel text. This includes multiple headings -within the same document. - -Each heading is indented according to the heading level, not its parent/child relationship to other -elements of your project. You can open and edit your novel documents from this view as well. All -headings contained in the currently open document should be highlighted in the view to indicate -which ones belong together in the same document. - -If you have multiple **Novel** type root folders, the header of the novel view becomes a dropdown -box. You can then switch between them by clicking the :guilabel:`Outline of ...` text. You can also -click the novel icon button next to it. - -Generally, the novel view should update when you make changes to the novel structure, including -edits of the current document in the editor. The information is only updated when the automatic -save of the document is triggered, or you manually press :kbd:`Ctrl+S` to save changes. (You can -adjust the auto-save interval in **Preferences**.) You can also regenerate the whole novel view by -pressing the refresh button in the novel view header. - -It is possible to show an optional third column in the novel view. The settings are available from -the menu button in the toolbar. - -If you click the triangular icon to the right of each item, a tooltip will pop out showing all the -meta data collected for that heading. - - -Novel Outline View ------------------- - -.. figure:: images/fig_outline_view.png - - A screenshot of the Novel Outline View. - -When the application is in **Novel Outline View** mode, the tree, editor and viewer are replaced by -a large table that shows the entire novel structure with all the tags and references listed. Pretty -much all collected meta data is available here in different columns. - -You can select which novel root folder to display from the dropdown box, and you can select which -columns to show or hide from the menu button. You can also rearrange the columns by drag and drop. -The app remembers your column order and sizes between sessions, and for each individual project. - - -Colour Themes -------------- - -By default, novelWriter uses a light colour theme. You can also choose between a standard dark -theme that have neutral colours, or a series of other included themes, from **Preferences**. - -If you wish, you *can* create your own colour themes, and even have them added to the application. -See :ref:`a_custom_theme` for more details. - -Switching the GUI colour theme does not affect the colours of the editor and viewer. They have -separate colour selectable from the "Document colour theme" setting in **Preferences**. They are -separated because there are a lot more options to choose from for the editor and viewer. - -.. note:: - - If you switch between light and dark mode on the GUI, you should also switch editor theme to - match, otherwise icons may be hard to see in the editor and viewer. - - -Project Search --------------- - -A global search tool is available from the side bar. It allows you to search through your entire -project. The tool does not provide a replace feature. There is a search and replace tool available -in the document editor that acts on the open document. - -.. versionadded:: 2.4 - - -Switching Focus ---------------- - -If the project or novel view does not have focus, pressing :kbd:`Ctrl+T` switches focus to -whichever of the two is visible. If one of them already has focus, the key press will switch -between them instead. - -Likewise, pressing :kbd:`Ctrl+E` will switch focus to the document editor or viewer, or if any of -them already have focus, it will switch focus between them, - -These two shortcuts make it possible to jump between all these GUI elements without having to reach -for the mouse or touchpad. - - -.. _a_breakdown_project: - -Project Layout -============== - -This is a brief introduction to how you should structure your writing projects. All of this will be -covered in more detail later. - -The main point of novelWriter is that you are free to organise your project documents as you wish -into sub-folders or sub-documents, and split the text between these documents in whatever way suits -you. All that matters to novelWriter is the linear order the documents appear at in the project -tree (top to bottom). The chapters, scenes and sections of the novel are determined by the headings -within those documents. - -.. figure:: images/fig_header_levels.png - - An illustration of how heading levels correspond to the novel structure. - -The four heading levels, **Level 1** to **Level 4**, are treated as follows: - -* **Level 1** is used for the novel title, and for partitions. -* **Level 2** is used for chapter tiles. -* **Level 3** is used for scene titles -- optionally replaced by separators. -* **Level 4** is for section titles within scenes, if such granularity is needed. - -The project tree will select an icon for the document based on the first heading in it. - -This heading level structure is only taken into account for :term:`novel documents`. For -:term:`project notes`, the heading levels have no structural meaning, and you are free to use them -however you want. See :ref:`a_struct` and :ref:`a_references` for more details. - -.. tip:: - - You can add documents as child items of other documents. This is often more useful than adding - folders, since you anyway may want to have the chapter heading in a separate document from your - individual scene documents so that you can rearrange scene documents freely without affecting - chapter placement. - -.. versionadded:: 2.6 - - The heading levels for partitions, chapters and scenes only apply within novelWriter. When you - generate your manuscript, chapters are considered as the topmost heading level, with scenes - below it. Partitions are inserted as text elements in most formats. - - -.. _a_breakdown_export: - -Building a Manuscript -===================== - -The project can at any time be assembled into a range of different formats through the -**Build Manuscript** tool. Natively, novelWriter supports `Open Document`_, Microsoft Word Document -(known as `Office Open XML`_), HTML5, and various flavours of Markdown. You can also generate a PDF -document. - -The HTML5 format is suitable for conversion by a number of other tools like Pandoc_, or for -importing into word processors if the Open Document or Word Document format isn't suitable. The -Open Document format is supported by most office type applications, so is the Word Document format. -In addition, printing is also possible. - -For advanced processing, you can export the content of the project to a JSON file. This is useful -if you want to write your own custom 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 -with either HTML formatted text, or with the raw text as typed it into the novel documents. - -See :ref:`a_manuscript` for more details. - -.. versionadded:: 2.1 - - You can now define multiple build definitions in the **Build Manuscript** tool. This allows you - to define specific settings for various types of draft documents, outline documents, and - manuscript formats. See :ref:`a_manuscript` for more details. - - -.. _a_breakdown_storage: - -Project Storage -=============== - -The files of a novelWriter project are stored in a dedicated project folder. The project structure -is kept in a file at the root of this folder called ``nwProject.nwx``. All the document files and -associated meta data are stored in other folders below the project folder. For a more technical -description of what all the files mean and how they're organised, see the :ref:`a_storage` section. - -This way of storing data was chosen for several reasons. - -Firstly, all the text you add to your project is saved directly to your project folder in separate -files. Only the project structure and the text you are currently editing is stored in memory at any -given time, which means there is a smaller risk of losing data if the application or your computer -crashes. - -Secondly, having multiple small files means it is very easy to synchronise them between computers -with standard file synchronisation tools. - -Thirdly, if you use `version control`_ software to track the changes to your project, the file -formats used for the files are well suited. All the JSON documents have line breaks and indents as -well, which makes it easier to track them with version control software. - -.. note:: - - Since novelWriter has to keep track of a bunch of files and folders when a project is open, it - may not run well on some virtual file systems. A file or folder must be accessible with exactly - the path it was saved or created with. An example where this is not the case is the way Google - Drive is mapped on Linux Gnome desktops using gvfs/gio. - -.. caution:: - - You should not add additional files to the project folder yourself. Nor should you, as a rule, - manually edit files within it. If you really must manually edit the text files, e.g. with some - automated task you want to perform, you need to rebuild the :term:`Project Index` when you open - the project again. - - Editing text files in the ``content`` folder is less risky as these are just plain text. Editing - the main project XML file, however, may make the project file unreadable and you may crash - novelWriter and lose project structure information and project settings. diff --git a/docs/source/usage_format.rst b/docs/source/usage_format.rst deleted file mode 100644 index c57a10fb..00000000 --- a/docs/source/usage_format.rst +++ /dev/null @@ -1,470 +0,0 @@ -.. _a_fmt: - -******************** -Formatting Your Text -******************** - -The novelWriter text editor 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 strike through text, as well as four levels of headings. For some further complex -formatting needs, a set of shortcodes can be used. - -In addition to formatting codes, novelWriter allows for comments, a synopsis tag, and a number of -keyword and value sets used for :term:`tags` and :term:`references`. There are also -some codes that apply to whole paragraphs. See :ref:`a_fmt_text` for more details. - -URLs should also be highlighted and become clickable. However, only URLs starting with "http" or -"https" are recognised. In the editor, you must hold down the :kbd:`Ctrl` key when clicking a URL -to follow it. - - -.. _a_fmt_hlight: - -Syntax Highlighting -=================== - -The editor has a syntax highlighter feature that is meant to help you know when you've used the -formatting tags or other features correctly. It will change the colour and font size of your -headings, change the text colour of emphasised text, and it can also show you where you have -dialogue in your text. - -.. figure:: images/fig_references.png - - An example of the colour highlighting of references. "Bob" is not defined, and "@blabla" is not - a valid reference type. - -When you use the keywords to set tags and references, these also change colour. Correct keywords -have a distinct colour, and the references themselves will get a colour if they are valid. Invalid -references will get a squiggly error line underneath. The same applies to duplicate tags. - -There are a number of syntax highlighter colour themes available, both for light and dark GUIs. You -can select them from **Preferences**. - - -.. _a_fmt_head: - -Headings -======== - -.. figure:: images/fig_header_levels.png - - An illustration of how heading levels correspond to the novel structure. - -Four levels of headings are allowed. For :term:`project notes`, they are free to be used as you see -fit. That is, novelWriter doesn't assign the different headings any particular meaning. However, -for :term:`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 level indicates the start of a new partition. - Partitions are for when you want to split your story into "Part 1", "Part 2", etc. You can also - choose to use them for splitting the text up into acts, and then hide these headings in your - manuscript. - -``## Title Text`` - Heading level two. For novel documents, the level indicates the start of a new chapter. Chapter - numbers can be inserted automatically when building the manuscript. - -``### Title Text`` - Heading level three. For novel documents, the level indicates the start of a new scene. Scene - numbers or scene separators can be inserted automatically when building the manuscript, so you - can use the title field as a working title for your scenes if you wish, but you must provide a - minimal title. - -``#### Title Text`` - Heading level four. For novel documents, the level indicates the start of a new section. Section - titles can be replaced by separators or ignored completely when building the manuscript. - -For headings level one through three, adding a ``!`` modifies the meaning of the heading: - -``#! Title Text`` - This tells the build tool that the level one heading is intended to be used for the novel or - notes folder's main title, like for instance the novel title on the cover page. When building - the manuscript, this will use a different styling. - -``##! 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 prologues and epilogues for instance. - See :ref:`a_struct_heads_unnum` for more details. - -``###! Title Text`` - This is an alternative scene heading that can be formatted differently in the **Manuscript - Build** tool. It is intended for separating "soft" and "hard" scene breaks. Aside from this, it - behaves identically to a regular scene heading. See :ref:`a_struct_heads_scenes` 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 white spaces: - -* A non-breaking space can be inserted with :kbd:`Ctrl+K`, :kbd:`Space`. -* Thin spaces are also supported, and can be inserted with :kbd:`Ctrl+K`, :kbd:`Shift+Space`. -* Non-breaking thin space can be inserted with :kbd:`Ctrl+K`, :kbd:`Ctrl+Space`. - -These are all insert features, and the **Insert** menu has more. The keyboard shortcuts for them -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 for instance the correct type of space to separate a number from its - unit. Generally, non-breaking spaces are used to prevent line wrapping algorithms from adding - line breaks where they shouldn't. - -.. note:: - - You should not manually apply text indentation in your paragraphs in the editor. These can be - added automatically in the **Manuscript Build** tool if you want to have them in the manuscript. - Each new paragraph should be separated from the previous content by an empty line and with no - indentation. - - -.. _a_fmt_emph: - -Text Emphasis with Markdown -=========================== - -A minimal set of Markdown text emphasis styles are supported for text paragraphs. - -``_text_`` - The text is rendered as emphasised text (italicised). - -``**text**`` - The text is rendered as strongly emphasised text (bold). - -``~~text~~`` - Strike through text. - -In Markdown guides it is often recommended to differentiate between strong emphasis 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 strike through 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. -5. Text emphasis can only be used in comments and paragraphs. Headings and meta data tags don't - allow for formatting, and any formatting markup will be rendered as-is. - -.. tip:: - - novelWriter supports standard escape syntax for the emphasis markup characters in case the - editor misunderstands your intended usage of them. That is, ``\*``, ``\_`` and ``\~`` will - generate a plain ``*``, ``_`` and ``~``, respectively, without interpreting them as part of the - markup. - - -.. _a_fmt_shortcodes: - -Formatting with Shortcodes -========================== - -For additional formatting options, you can use shortcodes. Shortcodes is a form of in-line codes -that can be used to change the format of the text that follows and opening code, and last until -that formatting region is ended with a closing code. - -These shortcodes are intended for special formatting cases, or more complex cases that cannot be -solved with simple Markdown-like formatting codes. Available shortcodes are listed below. - -.. csv-table:: Shortcodes Formats - :header: "Syntax", "Description" - :widths: 40, 60 - :class: "tight-table" - - "``[b]text[/b]``", "Text is rendered as bold text." - "``[i]text[/i]``", "Text is rendered as italicised text." - "``[s]text[/s]``", "Text is rendered as strike through text." - "``[u]text[/u]``", "Text is rendered as underlined text." - "``[m]text[/m]``", "Text is rendered as highlighted text." - "``[sup]text[/sup]``", "Text is rendered as superscript text." - "``[sub]text[/sub]``", "Text is rendered as subscript text." - -Unlike Markdown style codes, these can be used anywhere within a paragraph. Even in the middle of a -word if you need to. You can also freely combine them to form more complex formatting. - -The shortcodes are available from the **Format** menu and in the editor toolbar, which can be -activated by clicking the left-most icon button in the editor header. - -.. note:: - - Shortcodes are not processed until you generate a preview or generate a manuscript document. So - there is no highlighting of the text between the formatting markers. There is also no check that - your markers make sense. You must ensure that you have both the opening and closing formatting - markers where you want them. - -.. versionadded:: 2.2 - - -.. _a_fmt_comm: - -Comments and Synopsis -===================== - -In addition to the above formatting features, novelWriter also allows for comments in documents. -The text of a comment is always ignored by the word counter. The text can also be filtered out -when building the manuscript or viewing the document. - -The first word of a comment, followed by a colon, can be one of a set of modifiers that indicates -the comment is intended for a specific purpose. For instance, if the comment starts with -``Synopsis:``, the comment is treated in a special manner 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. - -The different styles of comments are as follows: - -``% Your comment text ...`` - This is a comment. The text is not rendered by default (this can be overridden), seen in the - document viewer, or counted towards word counts. It is intended for you to make notes in your - text for your own sake, whatever that may be, that isn't part of the story text. This is the - general format of a comment. - -``%Synopsis: Your 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 building the project to for instance generate an outline - document of the whole project. - -``%Short: Your short description ...`` - This is a short description comment. It is identical to the synopsis comment (they are - interchangeable), but is intended to be used for project notes. The text shows up in the - Reference panel below the document viewer in the last column labelled **Short Description**. - -``%Footnote.: Your footnote text ...`` - This is a special comment assigned to a footnote marker. See :ref:`a_fmt_footnote` for how to - use them in your text. - -.. note:: - - Only one comment can be flagged as a synopsis or short comment for each heading. If multiple - comments are flagged as synopsis or short comments, the last one will be used and the rest - ignored. - - -.. _a_fmt_footnote: - -Footnotes -========= - -Footnotes are added with a shortcode, paired with a matching comment for the actual footnote text. -The matching is done with a key that links the two. If you insert a footnote from the **Insert** -menu, a unique key is generated for you. - -The insert feature will add the footnote shortcode marker at the position of your cursor in the -text, and create the associated footnote comment right after the paragraph, and move the cursor -there so you can immediately start typing the footnote text. - -The footnote comment can be anywhere in the document, so if you wish to move them to, say, the -bottom of the text, you are free to do so. - -Footnote keys are only required to be unique within a document, so if you copy, move or merge text, -you must make sure the keys are not duplicated. If you use the automatically generated keys from -the **Insert** menu, they are unique among all indexed documents. They are not guaranteed to be -unique against footnotes in the Archive or Trash folder though, but the chance of accidentally -generating the same key twice in a project is relatively small in the first place (1 in 810 000). - -This is what a footnote inserted into a paragraph may look like when completed: - -.. code-block:: md - - This is a text paragraph with a footnote[footnote:fn1] in the middle. - - %Footnote.fn1: This is the text of the footnote. - -.. versionadded:: 2.5 - - -.. _a_fmt_ignore: - -Ignored Text -============ - -If you want to completely ignore some of the text in your documents, but are not ready to delete -it, you can add ``%~`` before the text paragraph or line. This will cause novelWriter to skip the -text entirely when generating previews or building manuscripts. - -This is a better way of removing text than converting them to regular comments, as you may want to -include regular comments in your previews or draft manuscript. - -You can toggle the ignored text feature on and off for a paragraph by pressing :kbd:`Ctrl+Shift+D` -on your keyboard with your cursor somewhere in the paragraph. - -Example: - -.. code-block:: md - - %~ This text is ignored. - - This text is a regular paragraph. - - -.. _a_fmt_tags: - -Tags and References -=================== - -The document editor supports a set of keywords used for setting tags, and making references between -documents based on those tags. - -You must use the keyword ``@tag:`` to define a tag. The tag can be set once per section defined by -a heading. Setting it multiple times under the same heading will just override the previous -setting. - -``@tag: value`` - A tag keyword followed by the tag value, like for instance the name of a character. - -References can be set anywhere within a section, and are collected according to their category. -References are on the form: - -``@keyword: value1, value2, ..., valueN`` - A reference keyword followed by a value, or a comma separated list of values. - -Tags and references are covered in detail in the :ref:`a_references` chapter. The keywords can be -inserted at the cursor position in the editor via the **Insert** menu. If you start typing an ``@`` -on a new line, and auto-complete menu will also pop up suggesting keywords. - - -.. _a_fmt_align: - -Paragraph Alignment and Indentation -=================================== - -All documents have the text by default aligned to the left or justified, depending on your setting -in **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." - "``> Left indented text``", "The text has an increased left margin." - "``Right indented text <``", "The text has an increased right margin." - "``> Left/right indented text <``", "The text has 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 manuscript build tool as long as the format supports paragraph alignment. - - -Alignment with Line Breaks --------------------------- - -If you have line breaks in the paragraph, the markers for all the lines are combined and used for -the entire paragraph. For the following text, all lines will be centred: - -.. code-block:: md - - >> I am the very model of a modern Major-General - I've information vegetable, animal, and mineral - I know the kings of England, and I quote the fights historical - From Marathon to Waterloo, in order categorical << - - -Alignment with First Line Indent --------------------------------- - -If you have first line indent enabled in your Manuscript build settings, you probably want to -disable it for text in verses. Adding any alignment tags will cause the first line indent to be -switched off for that paragraph. - -The following text will always be aligned against the left margin: - -.. code-block:: md - - I am the very model of a modern Major-General << - I've information vegetable, animal, and mineral - I know the kings of England, and I quote the fights historical - From Marathon to Waterloo, in order categorical - - -.. _a_fmt_break: - -Vertical Space and Page Breaks -============================== - -You can apply page breaks to partition, chapter and scene headings for novel documents from the -**Manuscript Build** tool. If you need to add a page break or additional vertical spacing in other -places, there are special codes available for this purpose. - -Adding more than one line break between paragraphs will **not** increase the space between those -paragraphs when building 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. - -If you need to add a page break somewhere, put the text ``[new page]`` on a line by itself before -the text you wish to start on a new page. - -.. note:: - - The page break code is applied to the text that follows it. It adds a "page break before" mark - to the text when exporting to HTML or Open Document. This means that a ``[new page]`` which has - no text following it, it will not result in a page break. - -**Example:** - -.. code-block:: md - - This is a text paragraph. - - [vspace:2] - - This is another text paragraph, but there will be two empty paragraphs - between them. - - [new page] - - This text will start on a new page if the build format has pages. - - -.. _a_fmt_stats: - -Inserting Word Counts in the Text -================================= - -The cover page of a manuscript normally has the word count stated on it. Any statistics value -collected by novelWriter can be inserted into any document. You can generate the code for this from -the **Insert** menu under **Word/Character Count**. - -The value inserted is the actual count for your entire manuscript, so it is not populated until you -run the **Manuscript Build** tool. Until then they will show up as "0" in the viewer panel. diff --git a/docs/source/usage_project.rst b/docs/source/usage_project.rst deleted file mode 100644 index 0a19c7bd..00000000 --- a/docs/source/usage_project.rst +++ /dev/null @@ -1,235 +0,0 @@ -.. _a_ui_project: - -************* -Project Views -************* - -This chapter covers in more detail the different project views available in novelWriter. - -.. figure:: images/fig_project_tree_detailed.png - - The **Project Content** tree as it appears when loading a sample project. - - -.. _a_ui_tree: - -The Project Tree -================ - -The main window contains a project tree in the left-most panel. It shows the entire structure of -the project, and has four columns. - -**Column 1** - 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 heading 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. The icon is selected based on the type of item, and for novel - documents, the level of the first heading in the document text. - -**Column 2** - The second column shows the word count of the document, or the sum of words of the child items - for folders and documents with sub-documents. If the counts seem incorrect, they can be updated - by rebuilding the :term:`project index` from the **Tools** menu, or by pressing :kbd:`F9`. - -**Column 3** - The third column indicates whether the document is considered active or inactive in the project. - You can use this flag to indicate that a document is still in the project, but should not be - considered an active part of it. When you run the **Build Manuscript** tool, you can include or - exclude documents based on this flag. You can change this value from the right-click - :term:`context menu`. - -**Column 4** - The fourth column shows the user-defined status or importance labels you've assigned to each - project item. See :ref:`a_ui_tree_status` for more details on how to uses these labels. You can - select these labels from the :term:`context menu`, and define them in **Project Settings**. - -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. - -At the top of the project tree, you will find a set of buttons. - -* The first button is a quick links button that will show you a dropdown menu of all the - :term:`root folders` in your project. Selecting one will move to that position in - the tree. You can also activate this menu by pressing :kbd:`Ctrl+L`. -* The next two buttons can be used to move items up and down in the project tree. This is the only - way to move root folders. -* The next button opens a dropdown menu for adding new items to the tree. This includes root - folders and template documents. You can also activate this dropdown menu by pressing - :kbd:`Ctrl+N`. -* The last button is a menu of further actions you can apply to the project tree. - -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. - -.. tip:: - - If you want to set the label of a document to be the same as a header within it, you can - right-click a header in the document when it is open in the editor and select - :guilabel:`Set as Document Name` from the context menu. - - -.. _a_ui_tree_split_merge: - -Splitting and Merging Documents -------------------------------- - -Under the **Transform** submenu in the context menu of an item in the project tree, you will find -several options on how to change a document or folder. This includes changing between document and -note, but also splitting them into multiple documents, or merging child items into a single -document. - - -Splitting Documents -^^^^^^^^^^^^^^^^^^^ - -.. figure:: images/fig_project_split_tool.png - - The **Split Document** dialog. - -The **Split Document by Headings** option will open a dialog that allows you to split the selected -document into multiple new documents based on the headings it contains. You can select at which -heading level the split is to be performed from the dropdown box. The list box will preview which -headings will be split into new documents. - -You are given the option to create a folder for these new documents, and whether or not to create a -hierarchy of documents. That is, put sections under scenes, and scenes under chapters. - -The source document **is not** deleted in the process, but you have the option to let the tool move -the source document to the :guilabel:`Trash` folder. - - -Merging Documents -^^^^^^^^^^^^^^^^^ - -.. figure:: images/fig_project_merge_tool.png - - The **Merge Documents** dialog. - -You have two options for merging documents that are child elements of another document. You can -either **Merge Child Items into Self** and **Merge Child Items into New**. The first option will -pull all content of child items and merge them into the parent document, while the second option -will create a new document in the process. - -When merging documents in a folder, you only have the latter process is possible, so only the -choice **Merge Documents in Folder** is available. - -In either case, the **Merge Documents** dialog will let you exclude documents you don't want to -include, and it also lets you reorder them if you wish. - - -.. _a_ui_tree_status: - -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 yourself, and novelWriter doesn't use them for anything. To -modify the labels, go to their respective tabs in **Project Settings**. - -The "Status" flag is intended to tag a :term:`novel document` as for instance a -draft or as completed, and the "Importance" flag is intended to tag character notes, or other -:term:`project notes`, as for instance a main, major, or minor character or story element. - -Whether a document uses a "Status" or "Importance" flag depends on which :term:`root folder` it -lives in. If it's in a **Novel** type folder, it uses the "Status" flag, otherwise it uses an -"Importance" flag. - - -.. _a_ui_tree_dnd: - -Project Tree Drag & Drop ------------------------- - -The project tree allows drag & drop to allow you to reorder your documents and folders. Moving a -document in the project tree will affect the text's position when you assemble your manuscript in -the **Manuscript Build** tool. - -.. versionadded:: 2.2 - - You can now select multiple items in the project tree by holding down the :kbd:`Ctrl` or - :kbd:`Shift` key while selecting items. - -Documents and their folders can be rearranged freely within their root folders. If you move a -**Novel Document** out of a **Novel** folder, it will be converted to a **Project Note**. Notes can -be moved freely between all root folders, but keep in mind that if you move a note into a **Novel** -type root folder, its "Importance" setting will be replaced by a "Status" setting. See -:ref:`a_ui_tree_status`. The old value will not be overwritten though, and should be restored if -you move it back at some point. - -Root folders in the project tree cannot be dragged and dropped at all. If you want to reorder them, -you can move them up or down with respect to each other from the arrow buttons at the top of the -project tree, or by pressing :kbd:`Ctrl+Up` or :kbd:`Ctrl+Down` when they are selected. - -.. tip:: - - You can drag and drop documents onto the editor or viewer panel to open them. - - -.. _a_ui_tree_novel: - -The Novel Tree View -=================== - -.. figure:: images/fig_novel_tree_view.png - - A screenshot of the Novel Tree View. - -An alternative way to view the project structure is the novel view. You can switch to this view by -selecting the :guilabel:`Novel View` button in the sidebar. This view is a simplified version of -the view in the **Outline View**. It is convenient when you want to browse the structure of the -story itself rather than the document files. - -.. note:: - - You cannot reorganise the entries in the novel view, or add any new documents, as that would - imply restructuring the content of the document files themselves. Any such editing must be done - in the project tree. However, you can add new headings to existing documents, or change - references, which will be updated in this view when the document is saved. - - -.. _a_ui_outline: - -The Novel Outline View -====================== - -.. figure:: images/fig_outline_view.png - - A screenshot of the Novel Outline View. - -The project's **Novel Outline View** is available as another view option from the sidebar. The -outline provides an overview of the novel structure, displaying a tree hierarchy of the elements of -the novel, that is, the level 1 to 4 headings representing partitions, chapters, scenes and -sections. - -The document containing the heading can also be displayed as a separate column, as well as the line -number where the heading is defined. Double-clicking an entry will open the corresponding document -in the editor and switch to **Project Tree View** mode. - -You can select which novel folder to display from the dropdown menu. You can optionally also choose -to show a combination of all novel folders. - -.. note:: - - Since the internal structure of the novel does not depend directly on the folder and document - structure of the project tree, this view will not necessarily look the same, depending on how - you choose to organise your documents. See the :ref:`a_struct` page for more details. - -Various meta data and information extracted from :term:`tags` can be displayed in columns in -the outline. A default set of such columns is visible, but you can turn on or off more columns from -the menu button in the toolbar. The order of the columns can also be rearranged by dragging them to -a different position. You column settings are saved between sessions on a per-project basis. - -.. note:: - - The **Title** column cannot be disabled or moved. - -The information viewed in the outline is based on the :term:`project index`. While novelWriter does -its best to keep the index up to date when contents change, you can always rebuild it manually by -pressing :kbd:`F9` if something isn't right. - -The outline view itself can be regenerated by pressing the refresh button. By default, the content -is refreshed each time you switch to this view. - -The **Synopsis** column of the outline view takes its information from a specially formatted -comment. See :ref:`a_fmt_comm`. diff --git a/docs/source/usage_writing.rst b/docs/source/user_interface/editor_viewer.rst similarity index 59% rename from docs/source/usage_writing.rst rename to docs/source/user_interface/editor_viewer.rst index 245cd631..841be0b0 100644 --- a/docs/source/usage_writing.rst +++ b/docs/source/user_interface/editor_viewer.rst @@ -1,4 +1,4 @@ -.. _a_ui_writing: +.. _docs_ui_edit_view: ********************* The Editor and Viewer @@ -9,7 +9,7 @@ The Editor and Viewer This chapter covers in more detail how the document editor and viewer panels work. -.. _a_ui_edit: +.. _docs_ui_edit_view_edit: Editing a Document ================== @@ -20,8 +20,7 @@ Editing a Document To edit a document, double-click it in the project tree, press the :kbd:`Return` key while having it selected, or drag and drop it onto the editor panel. 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_fmt` chapter. +editor. The editor has a maximise button, which toggles the **Focus Mode**, and a close button in the top--right corner. On the top--left side you will find a tools button that opens a toolbar with a @@ -37,86 +36,56 @@ be shown. This can be set in **Preferences**. Clicking on the document title bar will select the document in the project tree and thus reveal its location there, making it easier to find in a large project. -Any :term:`references` in the editor can be opened in the viewer by moving the cursor to -the label and pressing :kbd:`Ctrl+Return`. You can also control-click them with your mouse. +Any references in the editor can be opened in the viewer by moving the cursor to the label and +pressing :kbd:`Ctrl+Return`. You can also control-click them with your mouse. Spell Checking -------------- A third party library called Enchant is used for spell checking in the editor. The controls for -spell checking can be found in the **Tools** menu. You can also set spell checking language in +spell checking are found in the **Tools** menu. You can also set spell checking language in **Project Settings**. This spell checking library comes with support for custom words that you can add by selecting "Add Word to Dictionary" from the context menu when a word is highlighted by the spell checker as -misspelled. The custom words are managed on a per-project basis, and can the list of words can be +misspelled. The custom words are managed on a per-project basis, and the list of words can be edited from the **Project Word List** tool available from the **Tools** menu. .. note:: Generally, spell checking dictionaries are collected from your operating system, but on Windows - they are not. See :ref:`a_custom_dict` for how to add spell checking dictionaries on Windows. + they are not. See :ref:`docs_more_custom_dict` for how to add spell checking dictionaries on + Windows. -Editor Auto-Completer ---------------------- +Word Counts +----------- -If you type the character ``@`` on a new line, a pop-up menu will appear showing the different -available keywords. The list will shorten as you type. Once a keyword command has been selected or -typed, the editor may suggest further options based on your project content. See -:ref:`a_references_completer` for more details. +A character, word, and paragraph count is maintained for each document, as well as for each section +of a document following a heading. The word count and change of words in the current session is +displayed in the footer of any document open in the editor, and all stats are shown in the details +panel below the project tree for any document selected in the project or novel trees. -.. versionadded:: 2.2 +The word counts are not updated in real time, but run in the background every few seconds for as +long as the document is being actively edited. + +A total project word count is displayed in the status bar. The total count depends on the sum of +the values in the project tree, which again depend on an up to date project index. If the counts +seem wrong, a full project word recount can be initiated by rebuilding the project's index. Either +from the **Tools** menu, or by pressing :kbd:`F9`. + +The rules for how the counts are made is covered in more detail in :ref:`docs_more_counting`. + +.. tip:: + + For some languages, character count is the more interesting statistics. You can select to + display character count instead of word count in the user interface in **Preferences**. + + .. versionadded:: 2.7 -.. _a_ui_view: - -Viewing a Document -================== - -.. figure:: images/fig_viewer.png - - A screenshot of the Document Viewer panel. - -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+R`, select **View Document** in the menu or context -menu, or drag and drop the document onto the viewer panel. 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 as the one currently being edited. -However, If you *are* viewing the same document, pressing :kbd:`Ctrl+R` from the editor will update -the document with your latest changes. You can also press the reload button in the top--right -corner of the viewer panel, next to the close button, to achieve the same thing. - -In the viewer :term:`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 backward and forward navigation -buttons, these can be used as well. They work just like the backward and forward features in a -browser. The left-most button is a dropdown menu for quickly navigation between headings in the -document. The edit button on the right will open the viewed document in the editor. - -At the bottom of the view panel there is a **References** panel. (If it is hidden, click the button -on the left side of the footer area to reveal it.) This panel contains a References tab with links -to all documents referring back to the one you're currently viewing, if any has been defined. If -you have created root folders and tags for various story elements like characters and plot points, -these will appear as additional tabs in this panel. - -.. note:: - - The **References** panel relies on an up-to-date :term:`index` of the project. - The index is maintained automatically. However, if anything is missing, or seems wrong, the - index can always be rebuilt by selecting **Rebuild Index** from the **Tools** menu, or by - pressing :kbd:`F9`. - -.. versionadded:: 2.2 - - The reference panel was redesigned and the additional tabs added. - - -.. _a_ui_edit_search: +.. _docs_ui_edit_view_search: Search & Replace ================ @@ -139,14 +108,8 @@ document when reaching the end. There is also a switch that will try to match th when the replacement is made. That is, it will try to keep the word upper, lower, or capitalised to match the word being replaced. -.. seealso:: - For more information on the capabilities of the Regular Expression option, see the Qt - documentation for the `QRegularExpression `_ - class. - - -.. _a_ui_edit_auto: +.. _docs_ui_edit_view_auto: Auto-Replace as You Type ======================== @@ -157,32 +120,69 @@ auto-replace feature from **Preferences**. You can also disable this feature ent .. tip:: If you don't like auto-replacement, all symbols inserted by this feature are also available in - the :guilabel:`Insert` menu, and via :ref:`a_kb_ins`. You may also be using a `Compose Key`_ - setup, which means you may not need the auto-replace feature at all. + the :guilabel:`Insert` menu, and via :ref:`docs_features_shortcuts_insert`. You may also be + using a `Compose Key`_ setup, which means you may not need the auto-replace feature at all. -The editor is able to replace two and three hyphens with short and long dashes, triple points with -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, like English does. +The editor is able to replace two and three hyphens with short and long dashes, four dashes with a +horizontal bar, three dots with 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, like +English does. .. tip:: If the auto-replace feature changes a symbol when you did not want it to change, pressing :kbd:`Ctrl+Z` once after the auto-replacement will undo it without undoing the character - you typed before it. + you typed. -.. _a_ui_edit_dialogue: +.. _docs_ui_edit_view_view: -Dialogue Highlighting -===================== +Viewing a Document +================== -The editor and viewer can optionally highlight character dialogue in your novel documents. By -default, this feature is set to display text in double quotes as dialogue. In **Preferences**, you -can change this to support various other dialogue markers that instead uses dashes to indicate -dialogue, like those used in Spanish, Portuguese, Polish, etc. +.. figure:: images/fig_viewer.png -Various styles are supported by changing the settings under "Text Highlighting" in **Preferences**. + A screenshot of the Document Viewer panel. -It is also possible to include the dialogue highlighting in your manuscripts. +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+R`, select **View Document** in the menu or context +menu, or drag and drop the document onto the viewer panel. 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 as the one currently being edited. +However, If you *are* viewing the same document, pressing :kbd:`Ctrl+R` from the editor will update +the document with your latest changes. You can also press the reload button in the top--right +corner of the viewer panel, next to the close button, to achieve the same thing. + +In the viewer, 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 backward and forward navigation +buttons, these can be used as well. They work just like the backward and forward features in a +browser. The left-most button is a dropdown menu for quickly navigation between headings in the +document. The edit button on the right will open the viewed document in the editor. + + +.. _docs_ui_edit_view_view_references: + +Document References +------------------- + +At the bottom of the viewer panel you will find a **References** panel. (If it is hidden, click the +button on the left side of the footer area to reveal it.) This panel contains a References tab with +links to all documents referring back to the one you're currently viewing, if any has been defined. +If you have created root folders and tags for various story elements like characters and plot +points, these will appear as additional tabs in this panel. + +.. note:: + + The **References** panel relies on an up-to-date project index. The index is maintained + automatically. However, if anything is missing, or seems wrong, the index can always be rebuilt + by selecting **Rebuild Index** from the **Tools** menu, or by pressing :kbd:`F9`. + +.. versionadded:: 2.2 + + The reference panel was redesigned and the additional tabs added. diff --git a/docs/source/user_interface/images/fig_build_build.png b/docs/source/user_interface/images/fig_build_build.png new file mode 100644 index 00000000..d66c1d55 Binary files /dev/null and b/docs/source/user_interface/images/fig_build_build.png differ diff --git a/docs/source/images/fig_build_settings_headings.png b/docs/source/user_interface/images/fig_build_settings_headings.png similarity index 100% rename from docs/source/images/fig_build_settings_headings.png rename to docs/source/user_interface/images/fig_build_settings_headings.png diff --git a/docs/source/user_interface/images/fig_build_settings_selections.png b/docs/source/user_interface/images/fig_build_settings_selections.png new file mode 100644 index 00000000..d7820ec9 Binary files /dev/null and b/docs/source/user_interface/images/fig_build_settings_selections.png differ diff --git a/docs/source/images/fig_editor.png b/docs/source/user_interface/images/fig_editor.png similarity index 100% rename from docs/source/images/fig_editor.png rename to docs/source/user_interface/images/fig_editor.png diff --git a/docs/source/images/fig_editor_search.png b/docs/source/user_interface/images/fig_editor_search.png similarity index 100% rename from docs/source/images/fig_editor_search.png rename to docs/source/user_interface/images/fig_editor_search.png diff --git a/docs/source/images/fig_manuscript_build.png b/docs/source/user_interface/images/fig_manuscript_build.png similarity index 100% rename from docs/source/images/fig_manuscript_build.png rename to docs/source/user_interface/images/fig_manuscript_build.png diff --git a/docs/source/images/fig_manuscript_build_outline.png b/docs/source/user_interface/images/fig_manuscript_build_outline.png similarity index 100% rename from docs/source/images/fig_manuscript_build_outline.png rename to docs/source/user_interface/images/fig_manuscript_build_outline.png diff --git a/docs/source/images/fig_novel_tree_view.png b/docs/source/user_interface/images/fig_novel_tree_view.png similarity index 100% rename from docs/source/images/fig_novel_tree_view.png rename to docs/source/user_interface/images/fig_novel_tree_view.png diff --git a/docs/source/images/fig_outline_view.png b/docs/source/user_interface/images/fig_outline_view.png similarity index 100% rename from docs/source/images/fig_outline_view.png rename to docs/source/user_interface/images/fig_outline_view.png diff --git a/docs/source/images/fig_project_merge_tool.png b/docs/source/user_interface/images/fig_project_merge_tool.png similarity index 100% rename from docs/source/images/fig_project_merge_tool.png rename to docs/source/user_interface/images/fig_project_merge_tool.png diff --git a/docs/source/images/fig_project_split_tool.png b/docs/source/user_interface/images/fig_project_split_tool.png similarity index 100% rename from docs/source/images/fig_project_split_tool.png rename to docs/source/user_interface/images/fig_project_split_tool.png diff --git a/docs/source/images/fig_project_tree_view.png b/docs/source/user_interface/images/fig_project_tree_view.png similarity index 100% rename from docs/source/images/fig_project_tree_view.png rename to docs/source/user_interface/images/fig_project_tree_view.png diff --git a/docs/source/images/fig_viewer.png b/docs/source/user_interface/images/fig_viewer.png similarity index 100% rename from docs/source/images/fig_viewer.png rename to docs/source/user_interface/images/fig_viewer.png diff --git a/docs/source/images/fig_welcome.jpg b/docs/source/user_interface/images/fig_welcome.jpg similarity index 100% rename from docs/source/images/fig_welcome.jpg rename to docs/source/user_interface/images/fig_welcome.jpg diff --git a/docs/source/user_interface/main_window.rst b/docs/source/user_interface/main_window.rst new file mode 100644 index 00000000..f15a98fd --- /dev/null +++ b/docs/source/user_interface/main_window.rst @@ -0,0 +1,202 @@ +.. _docs_ui_main: + +*************** +The Main Window +*************** + +The user interface of novelWriter is intended to be as minimalistic as practically possible, while +at the same time provide useful features needed for writing a novel. + +The main window does not by default have an editor toolbar like many other applications do. This +reduces clutter, and since the documents are formatted with style tags, it is not needed most of +the time. Still, a small formatting toolbar can be popped out by clicking the left-most button in +the header of the document editor. It gives quick access to standard formatting codes. + +Most formatting features supported are also available through keyboard shortcuts, as well as +available in the main menu under **Format**, so you don't have to look up formatting codes every +time you need them. For reference, a list of all shortcuts can be found in the +:ref:`docs_features_shortcuts` section. + +On the left side of the main window you will find a sidebar. This bar has buttons for the standard +views you can switch between, a quick link to the **Build Manuscript** tool, and a set of +project-related tools and quick access to settings at the bottom. + + +Project Tree and Editor View +============================ + +.. figure:: images/fig_project_tree_view.png + + A screenshot of the Project Tree and Editor View. + +When **Project Tree View** in the sidebar is selected, the work area 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 on the right side contains a document viewer which can view any document in +your project independently of what is open in the document editor. This panel is not intended as a +preview window, although you can use it for this purpose if you wish. For instance if you need to +check that the formatting tags behave as you expect. However, the main purpose of the viewer is for +viewing your notes next to your editor while you're writing. + +The editor also has a **Focus Mode** you can toggle either from the menu, from the icon in the +editor's header, or by pressing :kbd:`F8`. When **Focus Mode** is enabled, all the user interface +elements other than the document editor itself are hidden away. + +The project tree will highlight with a different background colour the document that is currently +open in the editor. + + +Drag & Drop +----------- + +The project tree allows drag & drop so you to reorder your documents and folders. Moving a document +in the project tree will affect the text's position when you assemble your manuscript in the +**Manuscript Build** tool. + +Documents and their folders can be rearranged freely within their root folders. If you move a +**Novel Document** out of a **Novel** folder, it will be converted to a **Project Note**. Notes can +be moved freely between all root folders, but keep in mind that if you move a note into a **Novel** +type root folder, its "Importance" setting will be replaced by a "Status" setting. See +:ref:`docs_usage_project_status` for more details. The old value will not be overwritten though, +and should be restored if you move it back at some point. + +Root folders in the project tree cannot be dragged and dropped at all. If you want to reorder them, +you can move them up or down with respect to each other using the arrow buttons at the top of the +project tree, or by pressing :kbd:`Ctrl+Up` or :kbd:`Ctrl+Down` when they are selected. + +.. tip:: + + You can drag and drop documents onto the editor or viewer panel to open them. + + .. versionadded:: 2.6 + +.. tip:: + + You can now select multiple items in the project tree by holding down the :kbd:`Ctrl` or + :kbd:`Shift` key while selecting items. + + .. versionadded:: 2.2 + + +.. _docs_ui_main_novel: + +Novel View and Editor View +========================== + +.. figure:: images/fig_novel_tree_view.png + + A screenshot of the Novel Tree and Editor View. + +When **Novel Tree View** in the sidebar is selected, the project tree is replaced by an overview of +your novel structure for a specific **Novel** type root folder. Instead of showing individual +documents, the tree now shows all headings of your text. This includes multiple headings within the +same document. + +Each heading is indented according to the heading level, not its parent/child relationship to other +elements of your project. You can open and edit your novel documents from this view as well. All +headings contained in the currently open document should be highlighted in the view to indicate +which ones belong together in the same document. + +If you have multiple **Novel** type root folders, the header of the novel view becomes a dropdown +box. You can then switch between them by clicking the :guilabel:`Outline of ...` text. You can also +click the novel icon button next to it. + +Generally, the novel view should update when you make changes to the novel structure, including +edits of the current document in the editor. The information is only updated when the automatic +save of the document is triggered, or you manually press :kbd:`Ctrl+S` to save changes. (You can +adjust the auto-save interval in **Preferences**.) You can also regenerate the whole novel view by +pressing the refresh button in the novel view header. + +It is possible to show an optional third column in the novel view. The settings are available from +the menu button in the toolbar. + +If you click the triangular icon to the right of each item, a tooltip will pop out showing all the +meta data collected for that heading. + +.. note:: + + You cannot reorganise the entries in the novel view, or add any new documents, as that would + imply restructuring the content of the documents themselves. Any such editing must be done in + the project tree. However, you can add new headings to existing documents, or change references, + which will be updated in this view when the document is saved. + + +.. _docs_ui_main_outline: + +Novel Outline View +================== + +.. figure:: images/fig_outline_view.png + + A screenshot of the Novel Outline View. + +When **Novel Outline View** in the sidebar is selected, the tree, editor and viewer are replaced by +a table that shows the entire novel structure with all the tags and references listed. You can +select which novel folder to display from the dropdown menu. You can optionally choose to show a +combination of all novel folders. + +Pretty much all collected meta data is available in this view. You can select which columns to +display from the menu button. This includes various meta data and information extracted from your +:ref:`docs_usage_tags_refs`. The order of the columns can also be changed by dragging them to a +different position. You column settings are saved between sessions on a per-project basis. + +.. note:: + + The **Title** column cannot be disabled or moved. + +The information viewed in the outline is based on the project index. While novelWriter does its +best to keep the index up to date when contents change, you can always rebuild it manually by +pressing :kbd:`F9` if something isn't right. + +The outline view itself can be regenerated by pressing the refresh button. By default, the content +is refreshed each time you switch to this view. + +The **Synopsis** column of the outline view takes its information from a specially formatted +comment. See :ref:`docs_usage_comments_synopsis`. + + +Project Search +============== + +A global search tool is available from the side bar. It allows you to search through your entire +project. The tool does not provide a replace feature. There is a search and replace tool available +in the document editor that acts on the open document. See :ref:`docs_ui_edit_view_search` for more +details. + +.. versionadded:: 2.4 + + +Switching Focus +=============== + +If the project or novel view does not have focus, pressing :kbd:`Ctrl+T` switches focus to +whichever of the two is visible. If one of them already has focus, the key press will switch +between them instead. + +Likewise, pressing :kbd:`Ctrl+E` will switch focus to the document editor or viewer, or if any of +them already have focus, it will switch focus between them. + +These two shortcuts make it possible to jump between all these GUI elements without having to reach +for the mouse or touchpad. + +See :ref:`docs_features_shortcuts` for more details. + + +Colour Themes +============= + +By default, novelWriter uses a light colour theme. You can also choose between a standard dark +theme that have neutral colours, or a series of other included themes, from **Preferences**. + +If you wish, you *can* create your own colour themes, and even have them added to the application. +See :ref:`docs_more_custom_theme` for more details. + +Switching the GUI colour theme does not affect the colours of the editor and viewer. They have +separate themes selectable from the "Document colour theme" setting in **Preferences**. They are +separated because there are a lot more options to choose from for the editor and viewer. + +.. note:: + + If you switch between light and dark mode on the GUI, you should also switch editor theme to + match, otherwise icons may be hard to see in the editor and viewer. diff --git a/docs/source/project_manuscript.rst b/docs/source/user_interface/manuscript.rst similarity index 61% rename from docs/source/project_manuscript.rst rename to docs/source/user_interface/manuscript.rst index 18e64441..2e37bb1a 100644 --- a/docs/source/project_manuscript.rst +++ b/docs/source/user_interface/manuscript.rst @@ -1,4 +1,4 @@ -.. _a_manuscript: +.. _docs_ui_manuscript: *********************** Building the Manuscript @@ -10,14 +10,17 @@ You can at any time build a manuscript, an outline of your notes, or any other t from the text in your project. All of this is handled by the **Manuscript Build** tool. You can activate it from the sidebar, the **Tools** menu, or by pressing :kbd:`F5`. +.. note:: + + The term "Build" in this context means to assemble or generate a single document from a + selection of your project documents. You can select between multiple standard document formats. + .. versionadded:: 2.1 - This tool is new for version 2.1. A simpler tool was used for earlier versions. The simpler tool - only allows you to define a single set of options for the build, but otherwise had much the same - functionality. + This tool is new for version 2.1. A simpler tool was used for earlier versions. -.. _a_manuscript_main: +.. _docs_ui_manuscript_main: The Manuscript Build Tool ========================= @@ -43,29 +46,31 @@ Outline and Word Counts The **Outline** tab on the left lets you navigate the headings in the preview document. It will show up to scene level headings for novel documents, and level 2 headings for notes. -A collapsible panel of word and character counts are also available below the preview document. -These are calculated from the text you have included in the document, and are more accurate counts -than what's available in the project tree since they are counted *after formatting*. +A collapsible panel of word and character counts is also available below the preview pane. These +are calculated from the text you have included in the document, and are more accurate counts than +what's available in the project tree since they are counted *after formatting*. -For a detailed description on how they are counted, see :ref:`a_counting`. +For a detailed description on how they are counted, see :ref:`docs_more_counting`. -.. _a_manuscript_settings: +.. _docs_ui_manuscript_settings: Build Settings ============== -Each build definition can be edited by opening it in the **Manuscript Build Settings** dialog, -either by double-clicking or by selecting it and pressing the edit button in the toolbar. +You can edit a build definition by opening it in the **Manuscript Build Settings** dialog, either +by double-clicking or by selecting it and pressing the edit button in the toolbar. .. tip:: You can keep the **Manuscript Build Settings** dialog open while testing the different options, - and just hit the :guilabel:`Apply` button. You can test the result of your settings by pressing - the :guilabel:`Preview` button in the main **Manuscript Build** window. When you're happy with - the result, you can close the settings. + and just hit the :guilabel:`Apply` button. You can test the result of your settings change by + pressing the :guilabel:`Preview` button in the main **Manuscript Build** window. When you're + happy with the result, you can close the settings. +.. _docs_ui_manuscript_selection: + Document Selection ------------------ @@ -75,19 +80,22 @@ Document Selection The **Selections** page of the **Manuscript Build Settings** dialog. The **Selections** page of the **Manuscript Build Settings** dialog allows you to fine tune which -documents are included in the build. They are indicated by a green arrow icon in the last column. -On the right you have some filter options for selecting content of a specific type, and a set of -switches for which root folders to include. +documents are included in the build. The included documents are indicated by an icon in the last +column. On the right you have some filter options for selecting content of a specific type, and a +set of switches for which root folders to include. You can override the result of these filters by marking one or more documents and selecting to explicitly include or exclude them by using the buttons below the tree view. The last button can be used to reset the override and return control to the filter settings. -In the figure, the green arrow icon and the blue pin icon indicates which documents are included, -and the red forbidden icon indicates that a document is explicitly excluded. +In the figure, the orange icon and the blue icon indicates which documents are included, and the +red icon indicates that a document is explicitly excluded. + +By default, inactive documents are excluded, but you can override this in the filter settings. +See :ref:`docs_usage_project_active` for more details. -.. _a_manuscript_settings_head: +.. _docs_ui_manuscript_head: Formatting Headings ------------------- @@ -98,7 +106,7 @@ Formatting Headings The **Headings** page of the **Manuscript Build Settings** dialog. The **Headings** page of the **Manuscript Build Settings** dialog allows you to set how the -headings in your :term:`Novel Documents` are formatted. By default, the title is just copied as-is, +headings in your Novel Documents are formatted. By default, the title is just copied as-is, indicated by the ``{Title}`` format. You can change this to for instance add chapter numbers and scene numbers, or insert character names, like shown in the figure above. @@ -110,24 +118,68 @@ selecting one will insert it at the position of the cursor. Any text you add that isn't highlighted in colours will remain in your formatted titles. ``{Title}`` will always be replaced by the text in the heading from your documents. +.. csv-table:: Heading Formats + :header: "Code", "Description" + :class: "tight-table" + + "``{BR}``", "Insert a line break." + "``{Title}``", "Insert the original title text." + "``{Chapter}``", "Insert a chapter number." + "``{Chapter:Word}``", "Insert a chapter number as a word." + "``{Chapter:URoman}``", "Insert a chapter number as an upper case Roman numeral." + "``{Chapter:LRoman}``", "Insert a chapter number as an lower case Roman numeral." + "``{Scene}``", "Insert a scene number within the current chapter." + "``{Scene:Abs}``", "Insert a scene number unique to the whole manuscript." + "``{Char:POV}``", "Insert the point-of-view character's :ref:`display name `." + "``{Char:Focus}``", "Insert the focus character's :ref:`display name `." + You can preview the result of these format strings by clicking :guilabel:`Apply`, and then clicking :guilabel:`Preview` in the **Manuscript Build** tool main window. +.. _docs_ui_manuscript_head_numbers: + +Automatic Numbering +^^^^^^^^^^^^^^^^^^^ + +The headings formatter allows you to automatically insert chapter and scene numbers into your +headings. The automatic chapter number counter will skip all chapter headings marked as unnumbered +using the heading format described in :ref:`docs_usage_headings_levels`. + +Scene numbers are mostly intended for use in a draft manuscript. You can either insert absolute +scene numbers that counts every scene in the novel, or you can insert per-chapter scene numbers +that reset to 1 for each new chapter. + +:bdg-info:`Example` + +This will create a chapter title on the format "Chapter 1: Title Text": + +.. code-block:: md + + Chapter {Chapter}: {Title} + +This will create a scene title on the format "Scene 1.1: Title Text": + +.. code-block:: md + + Scene {Chapter}.{Scene}: {Title} + + Scene Separators ^^^^^^^^^^^^^^^^ If you don't want any titles for your scenes (or for your sections if you have them), you can leave the formatting boxes empty. If so, an empty paragraph will be inserted between the scenes or -sections instead, resulting in a gap in the text. You can also switch on the :guilabel:`Hide` -setting, which will ignore them completely. That is, there won't even be an extra gap inserted. +sections instead, resulting in a gap in the text. You can also enable the :guilabel:`Hide` setting, +which will ignore them completely. That is, there won't even be an extra gap inserted. Alternatively, if you want a separator text between them, like the common ``* * *``, you can enter the desired separator text as the format. If the format is any piece of static text, it will always -be treated as a separator. +be treated as a separator. A static separator is only inserted between scenes, as opposed to a +formatted heading which is also inserted before the first scene of a chapter. -.. _a_manuscript_settings_head_hard: +.. _docs_ui_manuscript_head_hard_soft: Hard and Soft Scenes ^^^^^^^^^^^^^^^^^^^^ @@ -136,18 +188,20 @@ If you wish to distinguish between so-called soft and hard scene breaks, you can alternative scene heading format in your text. You can then give these headings a different formatting in the **Headings** settings. -See :ref:`a_fmt_head` for more info on how to format headings in your text. +See :ref:`docs_usage_headings_levels` for more info on how to format alternative scene headings in +your text. Output Settings --------------- -The **Content**, **Format** and **Output** pages of the **Manuscript Build Settings** dialog -control a number of other settings for the output. Some of these only apply to specific output -formats, which is indicated by the section headings on the settings pages. +The **Formatting** sections of the **Manuscript Build Settings** dialog control a number of other +settings for the output. This includes formatting, but also what content is included. You can for +instance select to include comments, synopsis. tags and reference, and even exclude the body text +itself. -.. _a_manuscript_build: +.. _docs_ui_manuscript_build: Building Manuscript Documents ============================= @@ -172,14 +226,14 @@ show the build progress, but for small projects it may pass very fast. File Formats ------------ -Currently, four document formats are supported. +The following document formats are supported: -Open Document Format +Open Document The Build tool can produce either an ``.odt`` file, or an ``.fodt`` file. The latter is just a flat version of the document format as a single XML file. Most rich text editors support the former, and only a few the latter. -Microsoft Word Document Format +Microsoft Word Document The Microsoft Word Document format writes a single ``.docx`` file. It uses a fairly basic format that should be compatible with most rich text editors. @@ -213,8 +267,7 @@ Additional Formats ------------------ In addition to the above document formats, the novelWriter HTML and Markup formats can also be -wrapped in a JSON file. These files will have a meta data entry and a body entry. For HTML, also -the accompanying CSS styles used by the preview are included. +wrapped in a JSON file. These files will have a meta data entry and a body entry. The text body is saved in a two-level list. The outer list contains one entry per document, in the order they appear in the project tree. Each document is then split up into a list as well, with one @@ -224,7 +277,7 @@ These files are mainly intended for scripted post-processing for those who want file can be imported directly into a Python dict object or a PHP array, to mentions a few options. -.. _a_manuscript_print: +.. _docs_ui_manuscript_print: Printing ======== @@ -235,5 +288,5 @@ on the print dialog. .. note:: - The paper format should in all cases default to whatever your system default is. If you want to - change it, you have to select it from the **Print Preview** dialog. + The paper format should default to whatever your system default is. If you want to change it, + you have to select it from the **Print Preview** dialog. diff --git a/docs/source/user_interface/projects.rst b/docs/source/user_interface/projects.rst new file mode 100644 index 00000000..6c3ab4e4 --- /dev/null +++ b/docs/source/user_interface/projects.rst @@ -0,0 +1,146 @@ +.. _docs_ui_projects: + +***************** +Managing Projects +***************** + +Your text in novelWriter is organised into projects. Each project is meant to contain one novel +and associated notes. If you have multiple novels in a series, with the same characters and shared +notes, it is also possible to keep all of them in the same project by creating multiple **Novel** +root folders. See :ref:`docs_usage_project_roots` for more details. + + +.. _docs_ui_projects_new: + +Creating A New Project +====================== + +You can create a new project from the **Project** menu by selecting **Create or Open Project**. +This will open the **Welcome** dialog, where you can select the :guilabel:`New` button that will +assist you in creating a project. This dialog is also displayed when you start novelWriter. + +A novelWriter project requires a dedicated folder for storing its files on the local file system. +If you're interested in the details of how projects are stored, you can have a look at the section +:ref:`docs_technical_storage`. + +A list of recently opened projects is maintained, and displayed in the **Welcome** dialog. A +project can be removed from this list by selecting it and pressing the :kbd:`Del` key or by +right-clicking it and selecting the **Remove Project** option. + +.. figure:: images/fig_welcome.jpg + + The project list (left) and new project form (right) of the **Welcome** dialog. + +Project-specific settings are available in **Project Settings** in the **Project** menu. See +further details below in the :ref:`docs_ui_projects_settings` section. + +Details about the project's novel text, including word counts, and a table of contents with word +and page counts, is available through the **Novel Details** dialog. Statistics about the project +is also available in the **Manuscript Build** tool. + + +Template Projects +----------------- + +From the Welcome dialog you can also create a new from another existing project. If you have a +specific structure you want to use for all your new projects, you can create a dedicated project to +be used as a template, and select to copy an existing project from the "Prefill Project" option +from the **New Project** form. + + +.. _docs_ui_projects_settings: + +Project Settings +================ + +The **Project Settings** can be accessed from the **Project** menu, or by pressing +:kbd:`Ctrl+Shift+,`. This will open a dialog box, with a set of tabs. + + +General Settings +---------------- + +The **Settings** tab holds the project name, author, and language settings. + +The **Project Name** can be edited here. It is used for the main window title and for generating +backup files. So keep in mind that if you do change this setting, the backup file names will change +too. + +You can also change the **Author** and **Project Language** setting. These are only used when +building the manuscript, for some formats. The language setting is also used when inserting text +into documents in the viewer, like for instance labels for keywords and special comments. + +If your project is in a different language than your main spell checking language is set to, you +can override the default setting here. The project language can also be changed from the **Tools** +menu. + +You can also override the automatic backup setting for the project if you wish. + + +.. _docs_ui_projects_settings_status: + +Status and Importance +--------------------- + +Each document or folder of type **Novel** can be given a "Status" label accompanied by a coloured +icon with an optional shape selected from a list of pre-defined shapes. Each document or folder of +the remaining types can be given an "Importance" label with the same customisation options. + +These labels are there purely for your convenience, and you are not required to use them for any +other features to work. No other part of novelWriter accesses this information. The intention is to +use these to indicate at what stage of completion each novel document is, or how important the +content of a note is to the story. You don't have to use them this way, that's just what they were +intended for, but you can make them whatever you want. + +Both status and importance labels can be exported and imported so you can share them between +projects, or define a standard set for all your writing projects. When you import labels to a +project, they are always added as *new* labels. + +See also :ref:`docs_usage_project_status`. + +.. note:: + + Status or importance level currently in use cannot be deleted, but they can be edited. + + +Text Auto-Replace +----------------- + +A set of automatically replaced keywords can be added in this tab. The keywords in the left column +will be replaced by the text in the right column when documents are opened in the viewer. They will +also be applied to manuscript builds. + +The auto-replace feature will replace text in angle brackets that is in this list. The syntax +highlighter will add an alternate colour to text matching the syntax, but it doesn't check if the +text is in this list. + +.. note:: + + A keyword cannot contain spaces. The angle brackets are added by default, and when used in the + text are a part of the keyword to be replaced. This is to ensure that parts of the text aren't + unintentionally replaced by the content of the list. + + +.. _docs_ui_projects_backup: + +Backup +====== + +An automatic backup system is built into novelWriter. In order to use it, a backup path to where +the backup files are to be stored must be provided in **Preferences**. The path defaults to a +folder named "Backups" in your home directory. + +Backups can run automatically when a project is closed, which also implies it is run when the +application itself is closed. Backups are date stamped zip files of the project files in the +project folder (files not strictly a part of the project are ignored). The zip archives are stored +in a subfolder of the backup path. The subfolder will have the same name as the **Project Name** +defined in :ref:`docs_ui_projects_settings`. + +The backup feature, when configured, can also be run manually from the **Tools** menu. It is also +possible to disable automated backups for a given project in **Project Settings**. + +.. note:: + + For the backup to be able to run, the **Project Name** must be set in **Project Settings**. This + value is used to generate the name and path of the backups. Without it, the backup will not run + at all, but it will produce a warning message. diff --git a/docs/source/user_interface/split_and_merge.rst b/docs/source/user_interface/split_and_merge.rst new file mode 100644 index 00000000..e1ab0f54 --- /dev/null +++ b/docs/source/user_interface/split_and_merge.rst @@ -0,0 +1,48 @@ +.. _docs_ui_split_merge: + +************************* +Split and Merge Documents +************************* + +Under the **Transform** submenu in the context menu of an item in the project tree, you will find +several options on how to change a document or folder. This includes changing between document and +note, but also splitting them into multiple documents, or merging child items into a single +document. + + +Splitting Documents +=================== + +.. figure:: images/fig_project_split_tool.png + + The **Split Document** dialog. + +The **Split Document by Headings** option will open a dialog that allows you to split the selected +document into multiple new documents based on the headings it contains. You can select at which +heading level the split is to be performed from the dropdown box. The list box will preview which +headings will be split into new documents. + +You are given the option to create a folder for these new documents, and whether or not to create a +hierarchy of documents. That is, put sections under scenes, and scenes under chapters. + +The source document *is not* deleted in the process, but you have the option to let the tool move +the source document to the **Trash** folder. + + +Merging Documents +================= + +.. figure:: images/fig_project_merge_tool.png + + The **Merge Documents** dialog. + +You have two options for merging documents that are child elements of another document. You can +either **Merge Child Items into Self** and **Merge Child Items into New**. The first option will +pull all content of child items and merge them into the parent document, while the second option +will create a new document in the process. + +When merging documents in a folder, only the latter option is possible, so only the choice +**Merge Documents in Folder** is available. + +In either case, the **Merge Documents** dialog will let you exclude documents you don't want to +include, and it also lets you reorder them if you wish. diff --git a/docs/source/user_interface/statistics.rst b/docs/source/user_interface/statistics.rst new file mode 100644 index 00000000..b1c11e1b --- /dev/null +++ b/docs/source/user_interface/statistics.rst @@ -0,0 +1,39 @@ +.. _docs_ui_statistics: + +****************** +Writing Statistics +****************** + +When you work on a project, a log file records when you opened it, when you closed it, and the +total word counts of your novel documents and notes at the end of the session, provided that the +session lasted either more than 5 minutes, or that the total word count changed. For more details +about the log file itself, see :ref:`docs_technical_storage`. + +A tool to view the content of the log file is available in the **Tools** menu under **Writing +Statistics**. You can also launch it by pressing :kbd:`F6`, or find it on the sidebar. + +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 or Excel. + + +Idle Time +========= + +The log file stores how much of the session time was spent idle. The 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. You can change the number of minutes in **Preferences**. + + +Session Timer +============= + +A session timer is by default visible in the status bar. The icon will show you a clock icon when +you are active, and a pause icon when you are considered "idle" per the criteria mentioned above. + +If you do not wish to see the timer, you can click on it once to hide it. The icon will still be +visible. Click the icon once more to display the timer again. + +.. versionadded:: 2.6 + + As of version 2.6, clicking the timer text or icon in the status bar will toggle its visibility.