diff --git a/docs/source/_outtakes.rst b/docs/source/_outtakes.rst new file mode 100644 index 00000000..ac67e044 --- /dev/null +++ b/docs/source/_outtakes.rst @@ -0,0 +1,10 @@ +From Index +---------- + +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. diff --git a/docs/source/features/breaks_and_spaces.rst b/docs/source/features/breaks_and_spaces.rst new file mode 100644 index 00000000..a9ef06ca --- /dev/null +++ b/docs/source/features/breaks_and_spaces.rst @@ -0,0 +1,24 @@ +.. _docs_features_breaks_spaces: + +********************** +Page Breaks and Spaces +********************** + + +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:`docs_features_shortcuts`. + +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. diff --git a/docs/source/features/introduction.rst b/docs/source/features/introduction.rst new file mode 100644 index 00000000..bd05dde2 --- /dev/null +++ b/docs/source/features/introduction.rst @@ -0,0 +1,20 @@ +.. _docs_features: + +************ +Introduction +************ + +.. _docs_features_scene_breaks: + +Soft and Hard Scene Breaks +========================== + +.. _docs_features_active: + +Active and Inactive Documents +============================= + +.. _docs_features_status: + +Document Status Labels +====================== diff --git a/docs/source/features/shortcuts.rst b/docs/source/features/shortcuts.rst new file mode 100644 index 00000000..1ed000d0 --- /dev/null +++ b/docs/source/features/shortcuts.rst @@ -0,0 +1,189 @@ +.. _docs_features_shortcuts: + +****************** +Keyboard Shortcuts +****************** + +Most features in novelWriter are available as keyboard shortcuts. This is a reference list of those +shortcuts. Most of them are also listed in the application's user interface. + +.. note:: + On MacOS, replace :kbd:`Ctrl` with :kbd:`Cmd`. + + +Main Window Shortcuts +===================== + +.. csv-table:: + :header: "Shortcut", "Description" + + ":kbd:`F1`", "Open the online user manual" + ":kbd:`F5`", "Open the **Build Manuscript** tool" + ":kbd:`F6`", "Open the **Writing Statistics** tool" + ":kbd:`F8`", "Toggle **Focus Mode**" + ":kbd:`F9`", "Re-build the project's index" + ":kbd:`F11`", "Toggle full screen mode" + ":kbd:`Ctrl+,`", "Open the **Preferences** dialog" + ":kbd:`Ctrl+E`", "Switch or toggle focus for the editor or viewer" + ":kbd:`Ctrl+T`", "Switch or toggle focus for the project tree or novel view" + ":kbd:`Ctrl+Q`", "Exit novelWriter" + ":kbd:`Ctrl+Shift+,`", "Open the **Project Settings** dialog" + ":kbd:`Ctrl+Shift+O`", "Open the Welcome dialog to open or create a project" + ":kbd:`Ctrl+Shift+S`", "Save the current project" + ":kbd:`Ctrl+Shift+T`", "Switch focus to the outline view" + ":kbd:`Ctrl+Shift+W`", "Close the current project" + ":kbd:`Shift+F1`", "Open the local user manual (PDF) if it is available" + ":kbd:`Shift+F6`", "Open the **Project Details** dialog" + + +Project Tree Shortcuts +====================== + +.. csv-table:: + :header: "Shortcut", "Description" + + ":kbd:`F2`", "Edit the label of the selected item" + ":kbd:`Return`", "Open the selected document in the editor" + ":kbd:`Alt+Up`", "Jump or go to the previous item at same level in the tree" + ":kbd:`Alt+Down`", "Jump or go to the next item at same level in the tree" + ":kbd:`Alt+Left`", "Jump to the parent item in the tree" + ":kbd:`Alt+Right`", "Jump to the first child item in the project tree" + ":kbd:`Ctrl+.`", "Open the context menu on the selected item" + ":kbd:`Ctrl+L`", "Open the **Quick Links** menu" + ":kbd:`Ctrl+N`", "Open the **Create New Item** menu" + ":kbd:`Ctrl+O`", "Open the selected document in the editor" + ":kbd:`Ctrl+R`", "Open the selected document in the viewer" + ":kbd:`Ctrl+Up`", "Move selected item one step up in the tree" + ":kbd:`Ctrl+Down`", "Move selected item one step down in the tree" + ":kbd:`Ctrl+Shift+Del`", "Move the selected item to Trash" + + +Document Editor Shortcuts +========================= + + +Text Search Shortcuts +--------------------- + +.. csv-table:: + :header: "Shortcut", "Description" + + ":kbd:`F3`", "Find the next occurrence of the search word" + ":kbd:`Ctrl+F`", "Open search and look for the selected word" + ":kbd:`Ctrl+G`", "Find the next occurrence of the search word" + ":kbd:`Ctrl+H`", "Open replace and look for the selected word (Mac :kbd:`Cmd+=`)" + ":kbd:`Ctrl+Shift+1`", "Replace selected occurrence, and move to the next" + ":kbd:`Ctrl+Shift+G`", "Find the previous occurrence of the search word" + ":kbd:`Ctrl+Shift+F`", "Open project search and look for the selected word" + ":kbd:`Shift+F3`", "Find the previous occurrence of the search word" + + +Text Formatting Shortcuts +------------------------- + +.. csv-table:: + :header: "Shortcut", "Description" + + ":kbd:`Ctrl+'`", "Wrap selected text, or word under cursor, in single quotes" + ":kbd:`Ctrl+""`", "Wrap selected text, or word under cursor, in double quotes" + ":kbd:`Ctrl+/`", "Toggle comment format for block or selected text" + ":kbd:`Ctrl+0`", "Remove format for block or selected text" + ":kbd:`Ctrl+1`", "Change block format to heading level 1" + ":kbd:`Ctrl+2`", "Change block format to heading level 2" + ":kbd:`Ctrl+3`", "Change block format to heading level 3" + ":kbd:`Ctrl+4`", "Change block format to heading level 4" + ":kbd:`Ctrl+5`", "Change block alignment to left-aligned" + ":kbd:`Ctrl+6`", "Change block alignment to centred" + ":kbd:`Ctrl+7`", "Change block alignment to right-aligned" + ":kbd:`Ctrl+8`", "Add a left margin to the block" + ":kbd:`Ctrl+9`", "Add a right margin to the block" + ":kbd:`Ctrl+B`", "Format selected text, or word under cursor, with bold" + ":kbd:`Ctrl+D`", "Format selected text, or word under cursor, with strike through" + ":kbd:`Ctrl+I`", "Format selected text, or word under cursor, with italic" + ":kbd:`Ctrl+Shift+/`", "Remove format for block or selected text" + ":kbd:`Ctrl+Shift+D`", "Toggle ignored text format for block or selected text" + + +Other Editor Shortcuts +---------------------- + +.. csv-table:: + :header: "Shortcut", "Description" + + ":kbd:`F7`", "Re-run the spell checker on the document" + ":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+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" + ":kbd:`Ctrl+W`", "Close the current document" + ":kbd:`Ctrl+X`", "Cut selected text to clipboard" + ":kbd:`Ctrl+Y`", "Redo latest undo" + ":kbd:`Ctrl+Z`", "Undo latest changes" + ":kbd:`Ctrl+Backspace`", "Delete the word before the cursor" + ":kbd:`Ctrl+Del`", "Delete the word after the cursor" + ":kbd:`Ctrl+F7`", "Toggle spell checking" + ":kbd:`Ctrl+Return`", "Open the tag or reference under the cursor in the viewer" + ":kbd:`Ctrl+Shift+A`", "Select all text in the current paragraph" + + +Insert Shortcuts +---------------- + +A set of insert features are also available through shortcuts, but they require a double +combination of key sequences. The insert feature is activated with :kbd:`Ctrl+K`, followed by +a key or key combination for the inserted content. + +.. csv-table:: + :header: "Shortcut", "Description" + + ":kbd:`Ctrl+K`, :kbd:`Space`", "Insert a non-breaking space" + ":kbd:`Ctrl+K`, :kbd:`_`", "Insert a long dash (em dash)" + ":kbd:`Ctrl+K`, :kbd:`.`", "Insert an ellipsis" + ":kbd:`Ctrl+K`, :kbd:`'`", "Insert a modifier apostrophe" + ":kbd:`Ctrl+K`, :kbd:`*`", "Insert a list bullet" + ":kbd:`Ctrl+K`, :kbd:`%`", "Insert a per mille symbol" + ":kbd:`Ctrl+K`, :kbd:`~`", "Insert a figure dash (same width as a number)" + ":kbd:`Ctrl+K`, :kbd:`−`", "Insert a short dash (en dash)" + ":kbd:`Ctrl+K`, :kbd:`1`", "Insert a left single quote" + ":kbd:`Ctrl+K`, :kbd:`2`", "Insert a right single quote" + ":kbd:`Ctrl+K`, :kbd:`3`", "Insert a left double quote" + ":kbd:`Ctrl+K`, :kbd:`4`", "Insert a right double quote" + ":kbd:`Ctrl+K`, :kbd:`C`", "Insert a ``@char`` keyword" + ":kbd:`Ctrl+K`, :kbd:`E`", "Insert an ``@entity`` keyword" + ":kbd:`Ctrl+K`, :kbd:`F`", "Insert a ``@focus`` keyword" + ":kbd:`Ctrl+K`, :kbd:`G`", "Insert a ``@tag`` keyword" + ":kbd:`Ctrl+K`, :kbd:`H`", "Insert a short description comment" + ":kbd:`Ctrl+K`, :kbd:`L`", "Insert a ``@location`` keyword" + ":kbd:`Ctrl+K`, :kbd:`M`", "Insert a ``@mention`` keyword" + ":kbd:`Ctrl+K`, :kbd:`O`", "Insert an ``@object`` keyword" + ":kbd:`Ctrl+K`, :kbd:`P`", "Insert a ``@plot`` keyword" + ":kbd:`Ctrl+K`, :kbd:`S`", "Insert a synopsis comment" + ":kbd:`Ctrl+K`, :kbd:`T`", "Insert a ``@time`` keyword" + ":kbd:`Ctrl+K`, :kbd:`V`", "Insert a ``@pov`` keyword" + ":kbd:`Ctrl+K`, :kbd:`X`", "Insert a ``@custom`` keyword" + ":kbd:`Ctrl+K`, :kbd:`Ctrl+Space`", "Insert a thin non-breaking space" + ":kbd:`Ctrl+K`, :kbd:`Ctrl+_`", "Insert a horizontal bar (quotation dash)" + ":kbd:`Ctrl+K`, :kbd:`Ctrl+'`", "Insert a prime" + ":kbd:`Ctrl+K`, :kbd:`Ctrl+""`", "Insert a double prime" + ":kbd:`Ctrl+K`, :kbd:`Ctrl+*`", "Insert a flower mark (alternative bullet)" + ":kbd:`Ctrl+K`, :kbd:`Ctrl+−`", "Insert a hyphen bullet (alternative bullet)" + ":kbd:`Ctrl+K`, :kbd:`Ctrl+D`", "Insert a division sign" + ":kbd:`Ctrl+K`, :kbd:`Ctrl+O`", "Insert a degree symbol" + ":kbd:`Ctrl+K`, :kbd:`Ctrl+X`", "Insert a times sign" + ":kbd:`Ctrl+K`, :kbd:`Shift+Space`", "Insert a thin space" + + +Document Viewer Shortcuts +========================= + +.. csv-table:: + :header: "Shortcut", "Description" + + ":kbd:`Alt+Left`", "Move backward in the view history" + ":kbd:`Alt+Right`", "Move forward in the view history" + ":kbd:`Ctrl+C`", "Copy selected text to clipboard" + ":kbd:`Ctrl+Shift+A`", "Select all text in the current paragraph" + ":kbd:`Ctrl+Shift+R`", "Close the document viewer" diff --git a/docs/source/index.rst b/docs/source/index.rst index d3d81ecb..0041d168 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -40,12 +40,27 @@ storage for robustness. :hidden: usage/introduction - usage/folders_and_documents + usage/organising_project usage/chapters_and_scenes usage/basic_formatting usage/comments usage/tags_and_references usage/alignment_and_indent + usage/advanced_formatting + +.. toctree:: + :caption: The Manuscript Tool + :hidden: + + manuscript/introduction + +.. toctree:: + :caption: Additional Features + :hidden: + + features/introduction + features/shortcuts + features/breaks_and_spaces .. toctree:: :maxdepth: 1 diff --git a/docs/source/manuscript/introduction.rst b/docs/source/manuscript/introduction.rst new file mode 100644 index 00000000..90c1ce73 --- /dev/null +++ b/docs/source/manuscript/introduction.rst @@ -0,0 +1,10 @@ +.. _docs_manuscript: + +************ +Introduction +************ + +.. _docs_manuscript_numbers: + +Automatic Numbering +=================== diff --git a/docs/source/project_overview.rst b/docs/source/project_overview.rst index 0fe08327..58a327de 100644 --- a/docs/source/project_overview.rst +++ b/docs/source/project_overview.rst @@ -50,82 +50,6 @@ option from the **New Project** form. 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: @@ -145,34 +69,12 @@ A document or a folder can be moved to trash from the **Project** menu, or by pr 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: diff --git a/docs/source/usage/advanced_formatting.rst b/docs/source/usage/advanced_formatting.rst new file mode 100644 index 00000000..a2b7f4ab --- /dev/null +++ b/docs/source/usage/advanced_formatting.rst @@ -0,0 +1,5 @@ +.. _docs_usage_shortcodes: + +******************* +Advanced Formatting +******************* diff --git a/docs/source/usage/basic_formatting.rst b/docs/source/usage/basic_formatting.rst index a25336ad..81fd601c 100644 --- a/docs/source/usage/basic_formatting.rst +++ b/docs/source/usage/basic_formatting.rst @@ -3,3 +3,93 @@ **************** 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. + +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 ` depends 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 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. diff --git a/docs/source/usage/chapters_and_scenes.rst b/docs/source/usage/chapters_and_scenes.rst index 97b7d115..eefa847b 100644 --- a/docs/source/usage/chapters_and_scenes.rst +++ b/docs/source/usage/chapters_and_scenes.rst @@ -3,3 +3,82 @@ ******************* 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 it is a Chapter or a Scene document. + +The formatting of headings is based on Markdown_, and a heading is indicated by a line starting +with the ``#`` character. It accepts from one two 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 headings for your notes in the other root folders, but they aren't + treated as chapters or scenes, so you are free to use them as you want. + + +.. _docs_usage_headers_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: + +``# 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. + +``## 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_manuscript_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 to 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. + +``##! 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. + +``###! 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_features_scene_breaks` 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 syntax highlighter will change + colour and font size when the heading is correctly formatted. diff --git a/docs/source/usage/folders_and_documents.rst b/docs/source/usage/folders_and_documents.rst deleted file mode 100644 index 1f86274e..00000000 --- a/docs/source/usage/folders_and_documents.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. _docs_usage_dirs_docs: - -********************* -Folders and Documents -********************* 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..e427e3a2 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/organising_project.rst b/docs/source/usage/organising_project.rst new file mode 100644 index 00000000..1c93d90d --- /dev/null +++ b/docs/source/usage/organising_project.rst @@ -0,0 +1,118 @@ +.. _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 label of each item, its word count (or alternatively +character count), an active/inactive icon (see :ref:`docs_features_active`), and a custom status +icon (see :ref:`docs_features_status`). + +You can add, view and edit the 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. + +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 the application on what you put in them. You can use them +however you want. + + +Root Folder Types +----------------- + +**Novel** + 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_headers`. + +**Plot** + 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** + 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** + The locations where your story takes place can be documented here. This, together with Plot and + Characters are the particularly useful story elements to track, and to reference from your + chapter and scene documents. + +**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. + +**Objects** + Important objects in the story, for instance physical objects that change hands often, can be + tracked here. + +**Entities** + Does your plot have many powerful organisations or companies? Or other entities that are part of + the plot? They can be organised here. + +**Custom** + The custom root folder type can be used for tracking anything else not covered by the above + options. + +**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 folders are closely tied to the tags and reference system. Each folder type except +**Archive** and **Trash** 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 +=============== + +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. diff --git a/docs/source/usage_format.rst b/docs/source/usage_format.rst index c57a10fb..6a030b46 100644 --- a/docs/source/usage_format.rst +++ b/docs/source/usage_format.rst @@ -47,137 +47,16 @@ can select them from **Preferences**. 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: