From aba339f8e3ac96c2f0eb1588818887610fe39531 Mon Sep 17 00:00:00 2001 From: "Veronica K. B. Olsen" <1619840+vkbo@users.noreply.github.com> Date: Sun, 27 Oct 2019 14:55:11 +0100 Subject: [PATCH] Added documentation for export, and renamed all files to .txt as per recommendation --- docs/source/conf.py | 4 +- docs/source/export.txt | 70 +++++++++++++++++++ docs/source/{index.rst => index.txt} | 10 ++- docs/source/{interface.rst => interface.txt} | 10 +-- .../{introduction.rst => introduction.txt} | 0 docs/source/{notes.rst => notes.txt} | 0 docs/source/{projects.rst => projects.txt} | 0 docs/source/{structure.rst => structure.txt} | 0 docs/source/{technical.rst => technical.txt} | 0 9 files changed, 85 insertions(+), 9 deletions(-) create mode 100644 docs/source/export.txt rename docs/source/{index.rst => index.txt} (66%) rename docs/source/{interface.rst => interface.txt} (97%) rename docs/source/{introduction.rst => introduction.txt} (100%) rename docs/source/{notes.rst => notes.txt} (100%) rename docs/source/{projects.rst => projects.txt} (100%) rename docs/source/{structure.rst => structure.txt} (100%) rename docs/source/{technical.rst => technical.txt} (100%) diff --git a/docs/source/conf.py b/docs/source/conf.py index d9602e38..4046d2fc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -48,7 +48,7 @@ templates_path = ["_templates"] # You can specify multiple suffix as a list of string: # # source_suffix = [".rst", ".md"] -source_suffix = ".rst" +source_suffix = ".txt" # The master toctree document. master_doc = "index" @@ -150,7 +150,7 @@ man_pages = [ # dir menu entry, description, category) texinfo_documents = [ (master_doc, "novelWriter", "novelWriter Documentation", - author, "novelWriter", "One line description of project.", + author, "novelWriter", "Markdown-like editor for novels.", "Miscellaneous"), ] diff --git a/docs/source/export.txt b/docs/source/export.txt new file mode 100644 index 00000000..52f374d2 --- /dev/null +++ b/docs/source/export.txt @@ -0,0 +1,70 @@ +################## +Exporting Projects +################## + +The novelWriter project can be exported in various formats using the export tool available from :menuselection:`Project --> Export Project` or by pressing :kbd:`F5`. + +************** +File Selection +************** + +Which files are selected for export can be controlled from the "Selection" section. +The check box for "Novel files" will select any file that isn't classified as a note. +This is useful when exporting a document containing the novel itself. + +It is also possible to select the "Note files" for export, with or without the "Novel files". +Comments can also optionally be included in the export for those formats that supports this. + +************** +Export Formats +************** + +Currently, five formats are supported for exporting. + +novelWriter Markdown +==================== + +This is simply a concatenation of the files selected by the filters. +The files in the project are stacked together in the order they appear in the tree view, with comments, tags, etc. included. +This is a useful format for exporting the project for later import back into novelWriter. + +Plain Text +========== + +The plain text export format writes a simple ``.txt`` file without any formatting at all. +It does, however, respect the centering of text if the + +***************** +Header Formatting +***************** + +The chapter, scene and section headers for novel files can receive some special treatment using the formats under "Chapter Headings" and "Other Headings". +The chapters can either be of numbered or unnumbered type, the latter being suitable for prologues, epilogues, interludes, etc. +The headers can be generated using free text in combination with replace tags. +The tooltip will explain which tags are available for each heading type. + +.. note:: + Header formatting only applies to novel files. + Headings in note files will will be left as-is, but heading levels 1 through 4 are converted to the correct heading level in the respective output formats. + +Numbered Chapters +================= + +Numbered chapters can be automatically assigned a number from 1 and upwards. +The number is inserted in place of the ``%num%`` tag. +Alternatively, the number can be translated to a word by using the ``%numword%`` tag. +The word numbers are currently only supported in English, and work for the range from "One" to "Nine Hundred and Ninety-Nine". + +Unnumbered Chapters +=================== + +Unnumbered chapters only support the ``%title%`` tag for auto-replacement. + +Scenes and Sections +=================== + +Both scenes and sections support the ``%title%`` tag. +In addition, scenes behave differently than the other headings when the format does not contain any auto-replace tags. +If the text in the box is any static text, the heading formatter will treat it as a scene separator, and insert that text as centred text between scenes, and ignoring the first scene of a chapter if the chapter heading is not followed by any text. + +Leaving these fields blank will disable any output of scene and section headers or separators to the exported file. diff --git a/docs/source/index.rst b/docs/source/index.txt similarity index 66% rename from docs/source/index.rst rename to docs/source/index.txt index c52b0877..a7435733 100644 --- a/docs/source/index.rst +++ b/docs/source/index.txt @@ -1,10 +1,12 @@ +#################################### Welcome to novelWriter Documentation -==================================== +#################################### This is the documentation for novelWriter |version|. +******** Contents -^^^^^^^^ +******** .. toctree:: :maxdepth: 2 @@ -14,10 +16,12 @@ Contents projects structure notes + export technical +****************** Indices and Tables -^^^^^^^^^^^^^^^^^^ +****************** * :ref:`genindex` * :ref:`modindex` diff --git a/docs/source/interface.rst b/docs/source/interface.txt similarity index 97% rename from docs/source/interface.rst rename to docs/source/interface.txt index 0d29c1c8..c38bfdc4 100644 --- a/docs/source/interface.rst +++ b/docs/source/interface.txt @@ -1,6 +1,6 @@ - +############## User Interface -============== +############## The user interface is kept as simple as possible to avoid distractions. The main window contains a tree vew pane with the entire structure of the project, and a small details panel below it to display additional information. @@ -11,8 +11,9 @@ This will open the source editor which uses a simplified markdown format describ The document can also be viewed as html with all the comments and commands stripped out. To view a document, simply press Ctrl+R or select a file and go to :menuselection:`Document --> View Document` in the menu. The document viewed does not need to be the same document currently being edited. +*************** Markdown Format -^^^^^^^^^^^^^^^ +*************** the document editor uses a simplified markdown format. That is, it supports basic formatting like bold, italics and underline, as well as four levels of headings. @@ -31,8 +32,9 @@ The editor also has a minimal set of commands used for setting tags and referenc * ``% text...``: A comment. The text is not exported, seen in viewer, or counted towards word counts. * ``@keyword: value``: A keyword argument followed by a value, or a comma separated list of values. +****************** Keyboard Shortcuts -^^^^^^^^^^^^^^^^^^ +****************** All features are available as keyboard shortcuts. These are as following: diff --git a/docs/source/introduction.rst b/docs/source/introduction.txt similarity index 100% rename from docs/source/introduction.rst rename to docs/source/introduction.txt diff --git a/docs/source/notes.rst b/docs/source/notes.txt similarity index 100% rename from docs/source/notes.rst rename to docs/source/notes.txt diff --git a/docs/source/projects.rst b/docs/source/projects.txt similarity index 100% rename from docs/source/projects.rst rename to docs/source/projects.txt diff --git a/docs/source/structure.rst b/docs/source/structure.txt similarity index 100% rename from docs/source/structure.rst rename to docs/source/structure.txt diff --git a/docs/source/technical.rst b/docs/source/technical.txt similarity index 100% rename from docs/source/technical.rst rename to docs/source/technical.txt