diff --git a/docs/source/structure.rst b/docs/source/structure.rst index 6da2f893..d6ecceae 100644 --- a/docs/source/structure.rst +++ b/docs/source/structure.rst @@ -7,122 +7,177 @@ Novel Structure This section covers the structure of a novel project. .. note:: - This section concerns files under the Novel type root folder only. - There are some restrictions and features that only applies to these type of files. + This section concerns files under the Novel type root folder only. There are some restrictions + and features that only applies to these type of files. + .. _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. -Four levels of headings are supported, signified by the number of hashes preceding the title. -See the Markdown section. +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 headers within the text files. Four levels of headings +are supported, signified by the number of hashes preceding the title. See also the :ref:`a_ui_md` +section. -The header levels are not only important when generating the exported novel file, but they are also used by the indexer and Outline View. -Each heading starts a new region where new references to tags can be set. +.. note:: + The header levels are not only important when generating the exported novel file, but they are + also used by the indexer when building the outline tree in the :guilabel:`Outline` tab. Each + heading also starts a new region where new references to tags can be set. -The different header levels are interpreted as specific section types of the novel. +The different header levels are interpreted as specific section types of the novel in the following +way: + +``# Header1`` + Header level 1 signifies that the text refers to either the novel title or the name of a top + level partition when you want to split the manuscript up into books, parts, or acts. + +``## Header2`` + Header level 2 signifies a chapter level partition. Each time you want to start a new chapter, + you must add such a heading. If you chose to split your manuscript up into one file per scene, + you need a single chapeter file with just the heading. You can of course also add a synopsis and + tags and references to the chapter file. If you want to open the chaper with a quote, this is + also where you'd put the text for that. + +``### Header3`` + Header level 3 signifies a scene level partition. The title itself can be replaced with a scene + separator or just skipped entirely when you export your manuscript. + +``#### Header4`` + Header level 4 signifies a sub-scene level partition (section). These can be useful if you want + to change tag references mid-scene, like if you change the point of view character. You are free + to use sections as you wish, and can filter the titles out of the final manuscript just like with + scene titles. + +There are multiple options of how to process novel titles when exporting the manuscript. For +instance, chapter numbers can be applied automatically, and so can scene numbers if you want them in +a draft manuscript. See the :ref:`a_export` page for more details. -* ``# Header1``: Header level 1 signifies that the text refers to either the novel title or the name of a top level partition. -* ``## Header2``: Header level 2 signifies a chapter level partition. -* ``### Header3``: Header level 3 signifies a scene level partition. -* ``#### Header4``: Header level 4 signifies a sub-scene level partition (section). .. _a_struct_tags: Tag References ============== -Each partition, indicated by a heading, can contain references to tags set in the supporting files of the project. +Each partition, indicated by a heading, can contain references to tags set in the supporting files +of the project. The references are gathered by the indexer and used to generate the outline view on +the :guilabel:`Outline` tab of how the different parts of the novel are connected. -The references are gathered by the indexer and used to generate the Outline View of how the different parts of the novel are connected. -References and tags are also clickable in the view panel, and makes it easy to navigate reference notes while writing. -The targets of references can also be set per header. -This is covered in the "Supporting Files" section. +References and tags are also clickable in the document editor and viewer, making it easy to navigate +reference notes while writing. -References are set as keyword and a list of corresponding tags. -The valid keywords are listed below. -The format of a meta line is ``@keyword: value1, [value2] ... [valueN]``. -All keywords allow multiple values. +References are set as keyword and a list of corresponding tags. The valid keywords are listed below. +The format of a meta line is ``@keyword: value1, [value2] ... [valueN]``. All keywords allow +multiple values. -* ``@pov``: The point-of-view character for the current section. - The target must be a note tag in the character root folder. -* ``@char``: Other characters in the current section. - The target must be a note tag in the character root folder. - This should not include the point-of-view character. -* ``@plot``: The plot timelines touched by the current section. - The target must be a note tag in the plot root folder. -* ``@time``: The timelines touched by the current section. - The target must be a note tag in the timeline root folder. -* ``@location``: The location the current section takes place in. - The target must be a note tag in the locations root folder. -* ``@object``: Objects present in the current section. - The target must be a note tag in the object root folder. -* ``@entity``: Entities present in the current section. - The target must be a note tag in the entities root folder. -* ``@custom``: Custom references in the current section. - The target must be a note tag in the custom root folder. +``@pov`` + The point-of-view character for the current section. The target must be a note tag in the + 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 character. + +``@plot`` + The plot or subplot touched by 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 syntax highlighter will alert the user that the tags and references are used correctly, and that +the tags referenced exist. + +The highlighter may be mistake if the index of defined tags is out of date. If so, press :kbd:`F9` +to regenerate it, or select :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu. In general, +the index for a file is regenerated when a file is saved, so this shouldn't normally be necessary. -The syntax highlighter will alert the user that only the correct keywords are used, and that the tags referenced exist. -If the index of defined tags is out of date, press :kbd:`F9` to regenerate it, or select :menuselection:`Tools --> Rebuild Index` from the menu. -In general, the index for a file is regenerated when a file is saved, so this shouldn't normally be necessary. .. _a_struct_layout: Novel File Layout ================= -Files in a novelWriter project can have a layout format set. -These layouts are important when the project is exported, as they indicate how to treat the content in terms of formatting, headings and page breaks. -The layout for each file is indicated as the last set of characters in the Flags column of the project tree. -They also help to indicate what each file is for in your project. +All files in a novelWriter project can have a layout format set. These layouts are important when +the project is exported as they indicate how to treat the content in terms of formatting, headings, +and page breaks. The layout for each file is indicated as the last set of characters in the +:guilabel:`Flags` column of the project tree. -Some of these layout types are different, some are just cosmetic. -The "Book" layout is a generic novel file layout that in formatting is identical to "Chapter" and "Scene", but may help to indicate what files do in your project. -You can lay out your project using Book files for each act, and then later split those into chapter or scene files by using the "Split Document" tool. -Scenes can also be contained within chapter files, but you lose the drag and drop feature that comes with having them in separate files. +Not all layout types are actually treated differently, but they also help to indicate what each file +is for in your project. The "Book" layout is a generic novel file layout that in formatting is +identical to "Chapter" and "Scene", but may help to indicate what files do in your project. -Some layouts have implications on how the project is exported. -Files with layout "Title" and "Partition" have all headings and text centred, while the "Unnumbered" layout disables the automatic chapter numbering feature for everything contained within it. +You can for instance lay out your project using Book files for each act, and then later split those +into chapter or scene files by using the :guilabel:`Split Document` tool. Scenes can also be +contained within chapter files, but you lose the drag and drop feature that comes with having them +in separate files if you organise them this way. -All of the above layout formats are only usable in the Novel root folder. -Files that are not a part of the novel itself should have the Note layout. -These files are not getting any special formatting, and it is possible to collectively filter them out during export. -Note files can be used anywhere in the project. +Some layouts *do* have implications on how the project is exported. Files with layout "Title" and +"Partition" have all headings and text centred, while the "Unnumbered" layout disables the automatic +chapter numbering feature for everything contained within it. The latter is convenient for Prologue +and Epilogue type chapters. + +All of the above layout formats are only usable in the Novel root folder. Files that are not a part +of the novel itself should have the Note layout. These files are not getting any special formatting, +and it is possible to collectively filter them out during export. Note files can be used anywhere +in the project, also in the Novel root folder. Below is an overview of all available layout formats. -* **Title Page**: The title page layout. - The title should be formatted as a heading level one. - All text is automatically centred on exports. -* **Plain Page**: A plain page layout useful for instance for front matter pages. - Heading levels are ignored for this layout format, and so are formatting options like Justify Text. - The page is exported with a page break before it. -* **Book**: This is the generic novel file format that in principle can be used for all novel files. - Since the internal structure of the novel is controlled by the heading levels, this file will produce the same result as a collection of Partition, Chapter and Scene type files. - However, it does not provide the functionality of the Unnumbered layout format. -* **Partition**: A partition can be used to split the novel into parts. - Partition titles are indicated with a level one heading. - You can also add text and meta data to the page. - The Partition file layout will in addition force a page break before the heading, and centre all content on the page. -* **Chapter**: Signifies the start of a new chapter. - If the text itself is contained in scene files, these files should only contain the title, comments, synopsis, and tag references for characters, plot, etc. - The heading for chapters should be level two. - If you need an opening text, like a quote or other leading text before the first scene, this is also where you'd want to add this text. -* **Unnumbered**: Same as Chapter, but when exporting the files and automatic chapter numbering is enabled, this file will not receive a number. - This makes the layout suitable for Prologue and Epilogue type chapters. -* **Scene**: A scene file. - This file should have a header of level three. - Further sections can have headers of level four, but there are no file layout specifically for sections. -* **Note**: A generic file that is optionally ignored when the novel is exported. - Use these files for descriptions of content in the supporting root folders. - Note files can also be added to the Novel root folder if you need to insert notes there. - Note file headers receive no formatting when building the project. - They are always exported as-is. +Title Page + The title page layout. The title should be formatted as a heading level one. All text is automatically centred on exports. + +Plain Page + A plain page layout useful for instance for front matter pages. Heading levels are ignored for this layout format, and so are + formatting options like Justify Text. The page is exported with a page break before it. + +Book + This is the generic novel file format that in principle can be used for all novel files. Since the internal structure of the + novel is controlled by the heading levels, this file will produce the same result as a collection of Partition, Chapter and Scene + type files. However, it does not provide the functionality of the Unnumbered layout format. + +Partition + A partition can be used to split the novel into parts. Partition titles are indicated with a level one heading. You can also add + text and meta data to the page. The Partition file layout will in addition force a page break before the heading, and centre all + content on the page. + +Chapter + Signifies the start of a new chapter. If the text itself is contained in scene files, these files should only contain the title, + comments, synopsis, and tag references for characters, plot, etc. The heading for chapters should be level two. If you need an + opening text, like a quote or other leading text before the first scene, this is also where you'd want to add this text. + +Unnumbered + Same as Chapter, but when exporting the files and automatic chapter numbering is enabled, this file will not receive a number. + This makes the layout suitable for Prologue and Epilogue type chapters. + +Scene + A scene file. This file should have a header of level three. Further sections can have headers of level four, but there are no + file layout specifically for sections. + +Note + A generic file that is optionally ignored when the novel is exported. Use these files for descriptions of content in the + supporting root folders. Note files can also be added to the Novel root folder if you need to insert notes there. Note file + headers receive no formatting when building the project. They are always exported as-is. .. note:: - The layout granularity is entirely optional. - In principle, you can write the entire novel in a single file with layout "Book". - You can also have a single file per chapter. + The layout granularity is entirely optional. In principle, you can write the entire novel in a single file with layout "Book". + You can also have a single file per chapter if that suits you better. The :guilabel:`Outline` will show your structure of + chapters and scenes regardless of how your files are organised.