From 9f7fc90f2dcdd84471f73aafb7212812836b0a6c Mon Sep 17 00:00:00 2001
From: Veronica Berglyd Olsen <1619840+vkbo@users.noreply.github.com>
Date: Wed, 28 Feb 2024 18:20:20 +0100
Subject: [PATCH] Add documentation of counting rules

---
 docs/source/index.rst                         | 11 ++-
 docs/source/more_counting.rst                 | 98 +++++++++++++++++++
 ...ojectformat.rst => more_projectformat.rst} |  0
 requirements-dev.txt                          |  2 +
 4 files changed, 109 insertions(+), 2 deletions(-)
 create mode 100644 docs/source/more_counting.rst
 rename docs/source/{usage_projectformat.rst => more_projectformat.rst} (100%)
 create mode 100644 requirements-dev.txt

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 1495d713..34daef4d 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -66,7 +66,6 @@ with pip. See :ref:`a_started` for more details.
    usage_format
    usage_shortcuts
    usage_typography
-   usage_projectformat
 
 .. toctree::
    :maxdepth: 1
@@ -80,7 +79,15 @@ with pip. See :ref:`a_started` for more details.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Additional Topics
+   :caption: Additional Details
+   :hidden:
+
+   more_projectformat
+   more_counting
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Technical Topics
    :hidden:
 
    tech_locations
diff --git a/docs/source/more_counting.rst b/docs/source/more_counting.rst
new file mode 100644
index 00000000..d312fd76
--- /dev/null
+++ b/docs/source/more_counting.rst
@@ -0,0 +1,98 @@
+.. _a_counting:
+
+********************
+Word and Text Counts
+********************
+
+This is an overview of how words and other counts of your text are performed. The counting rules
+should be relatively standard, and are compared to LibreOffice Writer rules.
+
+The counts provided in the app on the raw text is meant to be approximate. For more accurate
+counts, you need to build your manuscript in the :guilabel:`Manuscript Tool` and check the counts
+on the generated preview.
+
+
+Text Word Counts and Stats
+==========================
+
+These are the rules for the main counts available for for each document in a project.
+
+For all counts, the following rules apply.
+
+#. Short (–) and long (—) dashes are considered word separators.
+#. Any line starting with ``%`` or ``@`` is ignored.
+#. Trailing white spaces are ignored, including line breaks.
+#. Leading ``>`` and trailing ``<`` are ignored with any spaces next to them.
+#. Valid shortcodes and other commands wrapped in brackets ``[]`` are ignored.
+#. In-line Markdown syntax in text paragraphs is treated as part of the text.
+
+After the above preparation of the text, the following counts are available.
+
+**Character Count**
+   The character count is the sum of characters per line, including leading and in-text white space
+   characters, but excluding trailing white space characters. Shortcodes in the text are not
+   included, but Markdown codes are. Only headers and text are counted.
+
+**Word Count**
+   The words count is the sum of blocks of continuous character per line separated by any number of
+   white space characters or dashes. Only headers and text are counted.
+
+**Paragraph Count**
+   The paragraph count is the number of text blocks separated by one or more empty line. A line
+   consisting only of white spaces is considered empty.
+
+
+Manuscript Counts
+=================
+
+These are the rules for the counts available for a manuscript in the :guilabel:`Manuscript Tool`.
+The rules have been tuned to agree with LibreOffice Writer, but will vary slightly depending on the
+content of your text. LibreOffice Writer also counts the text in the page header, which the
+Manuscript Tool does not.
+
+The content of each line is counted after all formatting has been processed, so the result will be
+more accurate than the counts for text documents elsewhere in the app. The following rules apply:
+
+#. Short (–) and long (—) dashes are considered word separators.
+#. Leading and trailing white spaces are generally included, but paragraph breaks are not.
+#. Hard line breaks within paragraph are considered white space characters.
+#. All formatting codes are ignored, including shortcodes, commands and Markdown.
+#. Scene and section separators are counted.
+#. Comments and meta data lines are counted after they are formatted.
+#. Headers are counted after they are formatted with custom formats.
+
+The following counts are available:
+
+**Header Count**
+   The number of headers in the manuscript.
+
+**Paragraph Count**
+   The number of body text paragraphs in the manuscript.
+
+**Total Word Count**
+   The number of words in the manuscript, including any comments and meta data text.
+
+**Text Word Count**
+   The number of words in body text paragraphs, excluding all other text.
+
+**Header Word Count**
+   The number of words in headers, including inserted formatting like chapter numbers, etc.
+
+**Total Character Count**
+   The number of characters on all lines, including any comments and meta data text. Paragraph
+   breaks are not counted, but in-paragraph hard line breaks are.
+
+**Text Character Count**
+   The number of characters in body text paragraphs. Paragraph breaks are not counted, but
+   in-paragraph hard line breaks are.
+
+**Header Character Count**
+   The number of characters in headings.
+
+**Text Words Character Count**
+   The number of characters in body text paragraphs considered part of a word or punctuation. That
+   is, white space characters are not counted.
+
+**Header Words Character Count**
+   The number of characters in headers considered part of a word or punctuation. That is, white
+   space characters are not counted.
diff --git a/docs/source/usage_projectformat.rst b/docs/source/more_projectformat.rst
similarity index 100%
rename from docs/source/usage_projectformat.rst
rename to docs/source/more_projectformat.rst
diff --git a/requirements-dev.txt b/requirements-dev.txt
new file mode 100644
index 00000000..65bec68e
--- /dev/null
+++ b/requirements-dev.txt
@@ -0,0 +1,2 @@
+flake8
+flake8-pep585