diff --git a/docs/source/images/fig_editor.png b/docs/source/images/fig_editor.png index ba7181be..f8aee5bb 100644 Binary files a/docs/source/images/fig_editor.png and b/docs/source/images/fig_editor.png differ diff --git a/docs/source/images/fig_novel_tree_view.png b/docs/source/images/fig_novel_tree_view.png index f2938842..b0f92b8f 100644 Binary files a/docs/source/images/fig_novel_tree_view.png and b/docs/source/images/fig_novel_tree_view.png differ diff --git a/docs/source/images/fig_outline_view.png b/docs/source/images/fig_outline_view.png index 467fa89a..90b4f3d1 100644 Binary files a/docs/source/images/fig_outline_view.png and b/docs/source/images/fig_outline_view.png differ diff --git a/docs/source/images/fig_project_tree_view.png b/docs/source/images/fig_project_tree_view.png index 667229ca..f5058038 100644 Binary files a/docs/source/images/fig_project_tree_view.png and b/docs/source/images/fig_project_tree_view.png differ diff --git a/docs/source/images/fig_viewer.png b/docs/source/images/fig_viewer.png index 05d4c459..7fbdc71d 100644 Binary files a/docs/source/images/fig_viewer.png and b/docs/source/images/fig_viewer.png differ diff --git a/docs/source/usage_breakdown.rst b/docs/source/usage_breakdown.rst index b0b0c8f7..ddfd5b99 100644 --- a/docs/source/usage_breakdown.rst +++ b/docs/source/usage_breakdown.rst @@ -23,6 +23,7 @@ at the same time provide useful features needed for writing a novel. The main window does not have an editor toolbar like many other applications do. This reduces clutter, and since the documents are formatted with style tags, it is more or less redundant. + Most formatting features supported are available through convenient keyboard shortcuts. They are also available in the main menu, so you don't have to look up formatting codes every time you need them. For reference, a list of all shortcuts can be found in the :ref:`a_kb` chapter. @@ -36,13 +37,18 @@ On the left side of the main window, you will find a sidebar. This bar has butto views you can switch between, a quick link to the :guilabel:`Build Manuscript` tool, and a set of project-related tools and quick access to settings at the bottom. +.. versionadded:: 2.2 + A number of new formatting options were added in 2.2 to allow for some special formatting cases. + At the same time, a small formatting toolbar was added in the editor. It is hidden by default, + but can be opened by pressing the three dots icon in the top right corner. -Project Tree View ------------------ + +Project Tree and Editor View +---------------------------- .. figure:: images/fig_project_tree_view.png - A screenshot of the Project Tree View. + A screenshot of the Project Tree and Editor View. When in :guilabel:`Project Tree View` mode, the main work area of the main window is split in two, or optionally three, panels. The left-most panel contains the project tree and all the documents in @@ -59,8 +65,8 @@ the editor's header, or by pressing :kbd:`F8`. When :guilabel:`Focus Mode` is en interface elements other than the document editor itself are hidden away. -Novel Tree View ---------------- +Novel Tree and Editor View +-------------------------- .. figure:: images/fig_novel_tree_view.png @@ -134,7 +140,7 @@ This is a brief introduction to how you structure your writing projects. All of covered in more detail later. The main point of novelWriter is that you are free to organise your project documents as you wish -into subfolders or subdocuments, and split the text between these documents in whatever way suits +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. @@ -153,8 +159,8 @@ The four heading levels (**H1** to **H4**) are treated as follows: The project tree will select an icon for the document based on the first heading in it. This header level structure is only taken into account for :term:`novel documents`. For -:term:`project notes`, the header levels have no structural meaning, and the user is free to do -whatever they want. See :ref:`a_struct` and :ref:`a_references` for more details. +:term:`project notes`, the header 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. .. versionadded:: 2.0 You can add documents as child items of other documents. This is often more useful than adding @@ -173,8 +179,9 @@ The project can at any time be assembled into a range of different formats throu various flavours of Markdown. The HTML5 format is suitable for conversion by a number of other tools like Pandoc_, or for -importing into word processors if the Open Document format isn't suitable. In addition, printing -is also possible. Print to PDF is available from the print dialog. +importing into word processors if the Open Document format isn't suitable. The Open Document format +is supported by most Office type applications. In addition, printing is also possible. Print to PDF +is available from the print dialog. In addition, you can export the content of the project to a JSON file. This is useful if you want to write your own custom processing script in for instance Python, as the entire novel can be read diff --git a/docs/source/usage_format.rst b/docs/source/usage_format.rst index 567695ff..a33e1262 100644 --- a/docs/source/usage_format.rst +++ b/docs/source/usage_format.rst @@ -7,7 +7,8 @@ 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 strikethrough text, as well as four levels of headings. +(bold) and strike through text, as well as four levels of headings. Form 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 set of keyword and value sets used for :term:`tags` and :term:`references`. There are also @@ -20,7 +21,7 @@ Syntax Highlighting =================== The editor has a syntax highlighter feature that is meant to help you know when you've used the -formtatting tags or other features correctly. It will change the colour and font size of your +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. @@ -94,7 +95,7 @@ A text paragraph is indicated by a blank line. That is, you need two line breaks 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 whitespaces: +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`. @@ -126,7 +127,7 @@ A minimal set of text emphasis styles are supported for text paragraphs. The text is rendered as strongly important text (bold). ``~~text~~`` - Strikethrough text. + Strike through text. In Markdown guides it is often recommended to differentiate between strong importance and emphasis by using ``**`` for strong and ``_`` for emphasis, although Markdown generally also supports ``__`` @@ -136,8 +137,8 @@ recommendation. In addition, the following rules apply: -1. The emphasis and strikethrough formatting tags do not allow spaces between the words and the tag - itself. That is, ``**text**`` is valid, ``**text **`` is not. +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* @@ -146,7 +147,7 @@ In addition, the following rules apply: 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 plain paragraphs. Comments, titles, and meta data tags don't - allow for formatting, and any formatting markup will be renderred as-is. + 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 @@ -155,6 +156,39 @@ In addition, the following rules apply: markup. +.. _a_fmt_shortcodes: + +Extended 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." + "``[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 :guilabel:`Format` menu and in the editor toolbar, which can +be activated by clicking the three dots in the editor header. + +.. versionadded:: 2.2 + + .. _a_fmt_comm: Comments and Synopsis @@ -169,19 +203,25 @@ in a special manner and will show up in the :ref:`a_ui_outline` in a dedicated c ``synopsis`` is not case sensitive. If it is correctly formatted, the syntax highlighter will indicate this by altering the colour of the word. -``% text...`` +``% 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. -``% Synopsis: text...`` +``%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: text ...`` + This is a short description comment. It is identical to the synopsis comment, 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 :guilabel:`Short Description`. + .. note:: - Only one comment can be flagged as a synopsis comment for each heading. If multiple comments are - flagged as synopsis comments, the last one will be used and the rest ignored. + 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_tags: @@ -204,8 +244,9 @@ References are in the form: ``@keyword: value`` A reference keyword followed by a value, or a comma separated list of values. -Tags andreferences are covered in detail in the :ref:`a_references` chapter. The keywords can be -inserted at the cursor position in the editor via the :guilabel:`Insert` menu. +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 :guilabel:`Insert` menu. If you start typing +an ``@`` on a new line, and auto-complete menu will also pop up suggesting keywords. .. _a_fmt_align: diff --git a/docs/source/usage_project.rst b/docs/source/usage_project.rst index 4229b6eb..746cf49c 100644 --- a/docs/source/usage_project.rst +++ b/docs/source/usage_project.rst @@ -28,7 +28,7 @@ the project, and has four columns. **Column 2** The second column shows the word count of the document, or the sum of words of the child items - for folders and documents with subdocuments. If the counts seem incorrect, they can be updated + for folders and documents with sub-documents. If the counts seem incorrect, they can be updated by rebuilding the :term:`project index` from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`. @@ -73,6 +73,7 @@ will find several options on how to change a document or folder. This includes c document and note, but also splitting them into multiple documents, or merging child items into a single document. + Splitting Documents ^^^^^^^^^^^^^^^^^^^ @@ -91,6 +92,7 @@ hierarchy of documents. That is, put sections under scenes, and scenes under cha The source document *is not* deleted in the process, but you have the option to let the tool move the source document to the :guilabel:`Trash` folder. + Merging Documents ^^^^^^^^^^^^^^^^^ @@ -137,10 +139,14 @@ The project tree allows drag & drop to a certain extent to allow you to reorder folders. Moving a document in the project tree will affect the text's position when you assemble your manuscript in the :guilabel:`Manuscript Build` tool. -Drag & drop has only limited support for moving documents. In general, bulk actions are not -allowed. This is deliberate to avoid accidentally messing up your project. If you make a mistake, -the last move action can be undone by pressing :kbd:`Ctrl+Shift+Z` or from the menu icon in the -project tree's toolbar. +.. versionadded:: 2.2 + You can now select multiple items in the project tree by holding down the :kbd:`Ctrl` or + :kbd:`Shift` key while selecting items. + +You can drag and drop documents and regular folders, but not root folders. If you select multiple +items, they can only be dragged and dropped if they are siblings. That is, they have the same +parent item in the project. This is due to the way drag and drop is implemented in the user +interface framework novelWriter is built upon. Documents and their folders can be rearranged freely within their root folders. If you move a Novel document out of a Novel folder, it will be converted to a project note. Notes can be moved freely @@ -149,8 +155,8 @@ folder, its "Importance" setting will be switched with a "Status" setting. See :ref:`a_ui_tree_status`. The old value will not be overwritten though, and should be restored if you move it back at some point. -Root folders in the project tree cannot be dragged & dropped at all. If you want to reorder them, -you can move them up or down with respect to eachother from the arrow buttons at the top of the +Root folders in the project tree cannot be dragged and dropped at all. If you want to reorder them, +you can move them up or down with respect to each other from the arrow buttons at the top of the project tree, or by pressing :kbd:`Ctrl+Shift+Up` or :kbd:`Ctrl+Shift+Down` when they are selected. diff --git a/docs/source/usage_shortcuts.rst b/docs/source/usage_shortcuts.rst index 4ddbde83..8c9fb8cb 100644 --- a/docs/source/usage_shortcuts.rst +++ b/docs/source/usage_shortcuts.rst @@ -104,7 +104,7 @@ Text Formatting Shortcuts ":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 strong emphasis (bold)" - ":kbd:`Ctrl+D`", "Strikethrough selected text, or word under cursor" + ":kbd:`Ctrl+D`", "Strike through selected text, or word under cursor" ":kbd:`Ctrl+I`", "Format selected text, or word under cursor, with emphasis (italic)" ":kbd:`Ctrl+Shift+/`", "Remove block formatting for block under cursor" diff --git a/docs/source/usage_typography.rst b/docs/source/usage_typography.rst index 95585195..e96d6185 100644 --- a/docs/source/usage_typography.rst +++ b/docs/source/usage_typography.rst @@ -61,7 +61,7 @@ Single and Double Prime Both single and double prime symbols are available in the :guilabel:`Insert` menu. These symbols are the correct symbols to use for unit symbols for feet, inches, minutes, and seconds. The usage of these is described in more detail on the Wikipedia Prime_ page. They look very similar to single -and double straight quotes, and may be renderred similarly by the font, but they have different +and double straight quotes, and may be rendered similarly by the font, but they have different codes. Using these correctly will also prevent the auto-replace and dialogue highlighting features misunderstanding their meaning in the text. @@ -74,7 +74,7 @@ even if it is intended as an apostrophe. This also includes the syntax highlight assume the first following apostrophe is the closing symbol of a single quoted region of text. To get around this, an alternative apostrophe is available. It is a special Unicode character that -is not categorised as punctuation, but as a modifier. It is usually renderred the same way as the +is not categorised as punctuation, but as a modifier. It is usually rendered the same way as the right single quotation marks, depending on the font. There is a Wikipedia article for the `Modifier letter apostrophe`_ with more details. diff --git a/docs/source/usage_writing.rst b/docs/source/usage_writing.rst index 56c2ff78..2579232b 100644 --- a/docs/source/usage_writing.rst +++ b/docs/source/usage_writing.rst @@ -24,9 +24,8 @@ Markdown-like syntax for some features, and a novelWriter-specific syntax for ot format is described in the :ref:`a_fmt` chapter. The editor has a maximise button (toggles the :guilabel:`Focus Mode`) and a close button in the -top--right corner. On the top--left side you will find an edit button that opens the -:guilabel:`Item Label` dialog for the currently open document, and a search button to open the -search dialog. +top--right corner. On the top--left side you will find a tools button that opens a toolbar with a +few buttons for applying text formatting, and a search button to open the search dialog. Both the document editor and viewer will show the label of the currently open document in the header at the top of the edit or view panel. Optionally, the full project path to the document can @@ -40,6 +39,18 @@ Any :term:`references` in the editor can be opened in the viewer by m the label and pressing :kbd:`Ctrl+Return`. You can also control-click them with your mouse. +Editor Auto-Completer +--------------------- + +If you type the character ``@`` on a new line, a context menu will appear showing the different +available keywords. The list will shorten as you type. Once a keyword command has been selected or +typed, the editor may suggest further content based on your project content. See +:ref:`a_references_completer` for more details. + +.. versionadded:: 2.2 + The auto-completer feature was added. + + .. _a_ui_view: Viewing a Document @@ -68,11 +79,10 @@ buttons, these can be used as well. They work just like the backward and forward browser. At the bottom of the view panel there is a :guilabel:`References` panel. (If it is hidden, click -the icon next to it to reveal it.) This panel will show links to all documents referring back to -the one you're currently viewing, if any has been defined. The :guilabel:`Sticky` button will -freeze the content of the panel to the current document, even if you navigate to another document. -This is convenient if you want to quickly look through all documents in the list in the -:guilabel:`References` panel without losing the list in the process. +the button on the left side of the footer area to reveal it.) This panel contains a References tab +with links to all documents referring back to the one you're currently viewing, if any has been +defined. If you have created root folders and tags for various story elements like characters and +plot points, these will appear as additional tabs in this panel. .. note:: The :guilabel:`References` panel relies on an up-to-date :term:`index` of the @@ -80,6 +90,9 @@ This is convenient if you want to quickly look through all documents in the list the index can always be rebuilt by selecting :guilabel:`Rebuild Index` from the :guilabel:`Tools` menu, or by pressing :kbd:`F9`. +.. versionadded:: 2.2 + The reference panel was redesigned and the additional tabs added. + .. _a_ui_edit_search: