diff --git a/docs/source/usage/advanced_formatting.rst b/docs/source/usage/advanced_formatting.rst index a2b7f4ab..807a175c 100644 --- a/docs/source/usage/advanced_formatting.rst +++ b/docs/source/usage/advanced_formatting.rst @@ -1,5 +1,150 @@ -.. _docs_usage_shortcodes: +.. _docs_usage_formatting: ******************* Advanced Formatting ******************* + +Markdown formatting is somewhat limited by default, so novelWriter has some additional formatting +codes for common use cases. These codes are all based on brackets, and some allow an additional +value 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`. + +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 overlap and intersect. + +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." + "``[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 building the project. To add additional space between paragraphs, add the text +``[vspace]`` on a line of its own, and the **Manuscript** 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. + +: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 has 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" + :widths: 40, 60 + :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. The Word Count uses a "field" shortcode to insert a count of all words in text paragraphs +on the cover page. + +.. 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 index 645b8f20..8d94ae5a 100644 --- a/docs/source/usage/alignment_and_indent.rst +++ b/docs/source/usage/alignment_and_indent.rst @@ -3,3 +3,76 @@ ************************* 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/comments.rst b/docs/source/usage/comments.rst index d9135307..c15ff3bc 100644 --- a/docs/source/usage/comments.rst +++ b/docs/source/usage/comments.rst @@ -3,3 +3,161 @@ ****************** 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 sue +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 chose 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 count, 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 only be used 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 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 completely ignored. + + This text is a regular paragraph. diff --git a/docs/source/usage/organising_project.rst b/docs/source/usage/organising_project.rst index 1c93d90d..f7030e0c 100644 --- a/docs/source/usage/organising_project.rst +++ b/docs/source/usage/organising_project.rst @@ -45,7 +45,7 @@ however you want. Root Folder Types ----------------- -**Novel** +**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. @@ -53,35 +53,35 @@ Root Folder Types 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** +**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** +**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** +**Locations** (Notes) 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** +**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** +**Objects** (Notes) Important objects in the story, for instance physical objects that change hands often, can be tracked here. -**Entities** +**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** +**Custom** (Notes) The custom root folder type can be used for tracking anything else not covered by the above options. diff --git a/docs/source/usage/tags_and_references.rst b/docs/source/usage/tags_and_references.rst index 03d4217b..9a88b46b 100644 --- a/docs/source/usage/tags_and_references.rst +++ b/docs/source/usage/tags_and_references.rst @@ -3,3 +3,226 @@ ******************* 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_headers` for more details. Therefore, metadata is +also associated with headings, and not the documents directly. + +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 | 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. + +``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 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 chapter 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 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 these 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 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 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 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. 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 index 7645eda4..b4f0e4ff 100644 --- a/docs/source/usage_breakdown.rst +++ b/docs/source/usage_breakdown.rst @@ -178,45 +178,6 @@ for the mouse or touchpad. 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 titles. -* **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: diff --git a/docs/source/usage_format.rst b/docs/source/usage_format.rst index 6a030b46..76f32cf2 100644 --- a/docs/source/usage_format.rst +++ b/docs/source/usage_format.rst @@ -4,44 +4,11 @@ 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 @@ -63,287 +30,42 @@ Text Emphasis with Markdown 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.