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 252dadec..6c5a7f15 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -34,10 +34,9 @@ storage for robustness. Main Page More Documents - howto .. toctree:: - :caption: Using novelWriter + :caption: Getting Started :hidden: usage/introduction @@ -48,12 +47,13 @@ storage for robustness. usage/tags_and_references usage/alignment_and_indent usage/advanced_formatting + usage/front_back_matter + usage/howto .. toctree:: :caption: The User Interface :hidden: - user_interface/introduction user_interface/projects user_interface/editor_viewer user_interface/split_and_merge diff --git a/docs/source/project_structure.rst b/docs/source/project_structure.rst deleted file mode 100644 index 273525fc..00000000 --- a/docs/source/project_structure.rst +++ /dev/null @@ -1,156 +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. - -.. 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 - a_references for more details. - -The syntax for the four basic heading types, and the three special types, is listed in section -:ref:`docs_usage_headers_levels`. 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:`docs_usage_headers_levels`. - -**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:`docs_usage_headers_levels`. 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:`docs_usage_formatting_breaks`. - -.. 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:`docs_ui_manuscript` page for more details. - - - -.. _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:`docs_usage_formatting_breaks`. - - -.. _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:`docs_ui_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/usage/basic_formatting.rst b/docs/source/usage/basic_formatting.rst index 81fd601c..15b8435f 100644 --- a/docs/source/usage/basic_formatting.rst +++ b/docs/source/usage/basic_formatting.rst @@ -25,7 +25,7 @@ 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 +applied to text paragraphs in the :ref:`Manuscript Tool ` depends on paragraphs being separated by blank lines. :bdg-success:`Correct` diff --git a/docs/source/usage/chapters_and_scenes.rst b/docs/source/usage/chapters_and_scenes.rst index eefa847b..e9f9471c 100644 --- a/docs/source/usage/chapters_and_scenes.rst +++ b/docs/source/usage/chapters_and_scenes.rst @@ -30,7 +30,10 @@ Heading Levels An illustration of how heading levels correspond to the novel structure. -Four levels of headings are understood for novel documents: +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. ``# Title Text`` This is a heading level one. This heading indicates the start of a new partition. Partitions are @@ -40,7 +43,7 @@ Four levels of headings are understood for novel documents: ``## 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. + 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 @@ -72,13 +75,19 @@ may want to keep the use cases in mind while writing. ``###! 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. + 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. +: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. + +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 index c15ff3bc..11bb1e69 100644 --- a/docs/source/usage/comments.rst +++ b/docs/source/usage/comments.rst @@ -158,6 +158,6 @@ on your keyboard with your cursor somewhere in the paragraph. ### Scene - %~ This text is completely ignored. + %~ 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..a52cd35a --- /dev/null +++ b/docs/source/usage/front_back_matter.rst @@ -0,0 +1,77 @@ +.. _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. + + +.. _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/howto.rst b/docs/source/usage/howto.rst similarity index 99% rename from docs/source/howto.rst rename to docs/source/usage/howto.rst index da64e2fe..3e884029 100644 --- a/docs/source/howto.rst +++ b/docs/source/usage/howto.rst @@ -1,4 +1,4 @@ -.. _docs_more_howto: +.. _docs_usage_howto: ************* Tips & Tricks diff --git a/docs/source/usage/images/fig_heading_levels.png b/docs/source/usage/images/fig_heading_levels.png index e427e3a2..f9be1e37 100644 Binary files a/docs/source/usage/images/fig_heading_levels.png and b/docs/source/usage/images/fig_heading_levels.png differ diff --git a/docs/source/usage/organising_project.rst b/docs/source/usage/organising_project.rst index 8c7bf0ba..58e2b515 100644 --- a/docs/source/usage/organising_project.rst +++ b/docs/source/usage/organising_project.rst @@ -85,6 +85,10 @@ Root Folder Types 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 @@ -120,21 +124,41 @@ documents. .. _docs_usage_project_documents: -Project Documents -================= +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 add documents anywhere you want in your project structure. You can even add documents as +child items of other documents, just like 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. -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. +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. -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:`docs_ui_split_merge` for more details on -the latter two. +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_headers` for more details about 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 the types are allowed. You can also +convert folders into documents, which may sometimes be convenient. + +Another convenient feature is that documents can be split into sub-documents by its containing +headings, or multiple documents merged into one. This is particularly convenient if you start out +with larger structural documents, like one containing all chapters and scenes in an act, and then +split those. See :ref:`docs_ui_split_merge` for more details. + + +.. _docs_usage_project_documents_templates: Document Templates ------------------ diff --git a/docs/source/user_interface/introduction.rst b/docs/source/user_interface/introduction.rst deleted file mode 100644 index 90c1ce73..00000000 --- a/docs/source/user_interface/introduction.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _docs_manuscript: - -************ -Introduction -************ - -.. _docs_manuscript_numbers: - -Automatic Numbering -=================== diff --git a/docs/source/user_interface/manuscript.rst b/docs/source/user_interface/manuscript.rst index d4cb5399..17feaf5a 100644 --- a/docs/source/user_interface/manuscript.rst +++ b/docs/source/user_interface/manuscript.rst @@ -110,10 +110,53 @@ 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 also allows you to automatically insert chapter and scene numbers into your +heading formats. The automatic chapter number counter will skip all chapter headings marked as +unnumbered using the heading format described in :ref:`docs_usage_headers_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 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 ^^^^^^^^^^^^^^^^ @@ -127,7 +170,7 @@ the desired separator text as the format. If the format is any piece of static t be treated as a separator. -.. _docs_ui_manuscript_head_hard: +.. _docs_ui_manuscript_head_hard_soft: Hard and Soft Scenes ^^^^^^^^^^^^^^^^^^^^