Add footnotes

.github/workflows/test_mac.yml

@@ -12,7 +12,7 @@ on:
 
 jobs:
   testMac:
-    runs-on: macos-latest
+    runs-on: macos-13
     steps:
       - name: Python Setup
         uses: actions/setup-python@v5

novelwriter/assets/i18n/project_en_GB.json

@@ -1,6 +1,7 @@
 {
   "Synopsis": "Synopsis",
   "Short Description": "Short Description",
+  "Footnotes": "Footnotes",
   "Comment": "Comment",
   "Notes": "Notes",
   "Tag": "Tag",

novelwriter/common.py

@@ -24,30 +24,32 @@
 from __future__ import annotations
 
 import json
-import uuid
 import logging
 import unicodedata
+import uuid
 import xml.etree.ElementTree as ET
 
-from typing import TYPE_CHECKING, Any, Literal
-from pathlib import Path
-from datetime import datetime
 from configparser import ConfigParser
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, TypeVar
 from urllib.parse import urljoin
 from urllib.request import pathname2url
 
-from PyQt5.QtGui import QColor, QDesktopServices
 from PyQt5.QtCore import QCoreApplication, QUrl
+from PyQt5.QtGui import QColor, QDesktopServices
 
-from novelwriter.enum import nwItemClass, nwItemType, nwItemLayout
-from novelwriter.error import logException
 from novelwriter.constants import nwConst, nwLabels, nwUnicode, trConst
+from novelwriter.enum import nwItemClass, nwItemLayout, nwItemType
+from novelwriter.error import logException
 
 if TYPE_CHECKING:  # pragma: no cover
     from typing import TypeGuard  # Requires Python 3.10
 
 logger = logging.getLogger(__name__)
 
+_Type = TypeVar("_Type")
+
 
 ##
 #  Checker Functions
@@ -172,6 +174,11 @@ def isItemLayout(value: Any) -> TypeGuard[str]:
     return isinstance(value, str) and value in nwItemLayout.__members__
 
 
+def isListInstance(data: Any, check: type[_Type]) -> TypeGuard[list[_Type]]:
+    """Check that all items of a list is of a given type."""
+    return isinstance(data, list) and all(isinstance(item, check) for item in data)
+
+
 def hexToInt(value: Any, default: int = 0) -> int:
     """Convert a hex string to an integer."""
     if isinstance(value, str):
@@ -272,6 +279,13 @@ def simplified(text: str) -> str:
     return " ".join(str(text).strip().split())
 
 
+def elide(text: str, length: int) -> str:
+    """Elide a piece of text to a maximum length."""
+    if len(text) > (cut := max(4, length)):
+        return f"{text[:cut-4].rstrip()} ..."
+    return text
+
+
 def yesNo(value: int | bool | None) -> Literal["yes", "no"]:
     """Convert a boolean evaluated variable to a yes or no."""
     return "yes" if value else "no"

novelwriter/constants.py

@@ -23,9 +23,11 @@
 """
 from __future__ import annotations
 
-from PyQt5.QtCore import QCoreApplication, QT_TRANSLATE_NOOP
+from PyQt5.QtCore import QT_TRANSLATE_NOOP, QCoreApplication
 
-from novelwriter.enum import nwBuildFmt, nwItemClass, nwItemLayout, nwOutline, nwStatusShape
+from novelwriter.enum import (
+    nwBuildFmt, nwComment, nwItemClass, nwItemLayout, nwOutline, nwStatusShape
+)
 
 
 def trConst(text: str) -> str:
@@ -67,7 +69,7 @@ class nwRegEx:
     FMT_EB = r"(?<![\w\\])([\*]{2})(?![\s\*])(.+?)(?<![\s\\])(\1)(?!\w)"
     FMT_ST = r"(?<![\w\\])([~]{2})(?![\s~])(.+?)(?<![\s\\])(\1)(?!\w)"
     FMT_SC = r"(?i)(?<!\\)(\[[\/\!]?(?:i|b|s|u|m|sup|sub)\])"
-    FMT_SV = r"(?<!\\)(\[(?i)(?:fn|footnote):)(.+?)(?<!\\)(\])"
+    FMT_SV = r"(?<!\\)(\[(?i)(?:footnote):)(.+?)(?<!\\)(\])"
 
 # END Class nwRegEx
 
@@ -89,6 +91,13 @@ class nwShortcode:
     SUB_O    = "[sub]"
     SUB_C    = "[/sub]"
 
+    FOOTNOTE_B = "[footnote:"
+
+    COMMENT_STYLES = {
+        nwComment.FOOTNOTE: "[footnote:{0}]",
+        nwComment.COMMENT:  "[comment:{0}]",
+    }
+
 # END Class nwShortcode
 
 

novelwriter/core/docbuild.py

@@ -191,6 +191,8 @@ def iterBuildHTML(self, path: Path | None, asJson: bool = False) -> Iterable[tup
             else:
                 yield i, False
 
+        makeObj.appendFootnotes()
+
         if not (self._build.getBool("html.preserveTabs") or self._preview):
             makeObj.replaceTabs()
 
@@ -231,6 +233,8 @@ def iterBuildMarkdown(self, path: Path, extendedMd: bool) -> Iterable[tuple[int,
             else:
                 yield i, False
 
+        makeObj.appendFootnotes()
+
         self._error = None
         self._cache = makeObj
 

novelwriter/core/index.py

@@ -29,17 +29,20 @@
 
 import json
 import logging
+import random
 
-from time import time
-from typing import TYPE_CHECKING
-from pathlib import Path
 from collections.abc import ItemsView, Iterable
+from pathlib import Path
+from time import time
+from typing import TYPE_CHECKING, Literal
 
 from novelwriter import SHARED
-from novelwriter.enum import nwComment, nwItemClass, nwItemType, nwItemLayout
+from novelwriter.common import (
+    checkInt, isHandle, isItemClass, isListInstance, isTitleTag, jsonEncode
+)
+from novelwriter.constants import nwFiles, nwHeaders, nwKeyWords
+from novelwriter.enum import nwComment, nwItemClass, nwItemLayout, nwItemType
 from novelwriter.error import logException
-from novelwriter.common import checkInt, isHandle, isItemClass, isTitleTag, jsonEncode
-from novelwriter.constants import nwFiles, nwKeyWords, nwHeaders
 from novelwriter.text.counting import standardCounter
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -48,7 +51,12 @@
 
 logger = logging.getLogger(__name__)
 
-TT_NONE = "T0000"
+T_NoteTypes = Literal["footnotes", "comments"]
+
+TT_NONE = "T0000"  # Default title key
+MAX_RETRY = 1000  # Key generator recursion limit
+KEY_SOURCE = "0123456789bcdfghjklmnpqrstvwxz"
+NOTE_TYPES: list[T_NoteTypes] = ["footnotes", "comments"]
 
 
 class NWIndex:
@@ -301,9 +309,9 @@ def scanText(self, tHandle: str, text: str, blockSignal: bool = False) -> bool:
 
     def _scanActive(self, tHandle: str, nwItem: NWItem, text: str, tags: dict[str, bool]) -> None:
         """Scan an active document for meta data."""
-        nTitle = 0           # Line Number of the previous title
-        cTitle = TT_NONE     # Tag of the current title
-        pTitle = TT_NONE     # Tag of the previous title
+        nTitle = 0         # Line Number of the previous title
+        cTitle = TT_NONE   # Tag of the current title
+        pTitle = TT_NONE   # Tag of the previous title
         canSetHead = True  # First heading has not yet been set
 
         lines = text.splitlines()
@@ -335,10 +343,11 @@ def _scanActive(self, tHandle: str, nwItem: NWItem, text: str, tags: dict[str, b
                     self._indexKeyword(tHandle, line, cTitle, nwItem.itemClass, tags)
 
             elif line.startswith("%"):
-                if cTitle != TT_NONE:
-                    cStyle, cText, _ = processComment(line)
-                    if cStyle in (nwComment.SYNOPSIS, nwComment.SHORT):
-                        self._itemIndex.setHeadingSynopsis(tHandle, cTitle, cText)
+                cStyle, cKey, cText, _, _ = processComment(line)
+                if cStyle in (nwComment.SYNOPSIS, nwComment.SHORT):
+                    self._itemIndex.setHeadingSynopsis(tHandle, cTitle, cText)
+                elif cStyle == nwComment.FOOTNOTE:
+                    self._itemIndex.addNoteKey(tHandle, "footnotes", cKey)
 
         # Count words for remaining text after last heading
         if pTitle != TT_NONE:
@@ -506,6 +515,14 @@ def parseValue(self, text: str) -> tuple[str, str]:
         name, _, display = text.partition("|")
         return name.rstrip(), display.lstrip()
 
+    def newCommentKey(self, tHandle: str, style: nwComment) -> str:
+        """Generate a new key for a comment style."""
+        if style == nwComment.FOOTNOTE:
+            return self._itemIndex.genNewNoteKey(tHandle, "footnotes")
+        elif style == nwComment.COMMENT:
+            return self._itemIndex.genNewNoteKey(tHandle, "comments")
+        return "err"
+
     ##
     #  Extract Data
     ##
@@ -790,7 +807,7 @@ def unpackData(self, data: dict) -> None:
 
         for key, entry in data.items():
             if not isinstance(key, str):
-                raise ValueError("tagsIndex keys must be a string")
+                raise ValueError("tagsIndex key must be a string")
             if not isinstance(entry, dict):
                 raise ValueError("tagsIndex entry is not a dict")
 
@@ -950,6 +967,25 @@ def addHeadingRef(self, tHandle: str, sTitle: str, tagKeys: list[str], refType:
             self._items[tHandle].addHeadingRef(sTitle, tagKeys, refType)
         return
 
+    def addNoteKey(self, tHandle: str, style: T_NoteTypes, key: str) -> None:
+        """Set notes key for a given item."""
+        if tHandle in self._items:
+            self._items[tHandle].addNoteKey(style, key)
+        return
+
+    def genNewNoteKey(self, tHandle: str, style: T_NoteTypes) -> str:
+        """Set notes key for a given item."""
+        if style in NOTE_TYPES and (item := self._items.get(tHandle)):
+            keys = set()
+            for entry in self._items.values():
+                keys.update(entry.noteKeys(style))
+            for _ in range(MAX_RETRY):
+                key = style[:1] + "".join(random.choices(KEY_SOURCE, k=4))
+                if key not in keys:
+                    item.addNoteKey(style, key)
+                    return key
+        return "err"
+
     ##
     #  Pack/Unpack
     ##
@@ -991,12 +1027,13 @@ class IndexItem:
     must be reset each time the item is re-indexed.
     """
 
-    __slots__ = ("_handle", "_item", "_headings", "_count")
+    __slots__ = ("_handle", "_item", "_headings", "_count", "_notes")
 
     def __init__(self, tHandle: str, nwItem: NWItem) -> None:
         self._handle = tHandle
         self._item = nwItem
         self._headings: dict[str, IndexHeading] = {TT_NONE: IndexHeading(TT_NONE)}
+        self._notes: dict[str, set[str]] = {}
         self._count = 0
         return
 
@@ -1064,6 +1101,13 @@ def addHeadingRef(self, sTitle: str, tagKeys: list[str], refType: str) -> None:
                 self._headings[sTitle].addReference(tagKey, refType)
         return
 
+    def addNoteKey(self, style: T_NoteTypes, key: str) -> None:
+        """Add a note key to the index."""
+        if style not in self._notes:
+            self._notes[style] = set()
+        self._notes[style].add(key)
+        return
+
     ##
     #  Data Methods
     ##
@@ -1085,6 +1129,10 @@ def nextHeading(self) -> str:
         self._count += 1
         return f"T{self._count:04d}"
 
+    def noteKeys(self, style: T_NoteTypes) -> set[str]:
+        """Return a set of all note keys."""
+        return self._notes.get(style, set())
+
     ##
     #  Pack/Unpack
     ##
@@ -1103,6 +1151,8 @@ def packData(self) -> dict:
         data["headings"] = heads
         if refs:
             data["references"] = refs
+        if self._notes:
+            data["notes"] = {style: list(keys) for style, keys in self._notes.items()}
 
         return data
 
@@ -1116,6 +1166,14 @@ def unpackData(self, data: dict) -> None:
             tHeading.unpackData(hData)
             tHeading.unpackReferences(references.get(sTitle, {}))
             self.addHeading(tHeading)
+
+        for style, keys in data.get("notes", {}).items():
+            if style not in NOTE_TYPES:
+                raise ValueError("The notes style is invalid")
+            if not isListInstance(keys, str):
+                raise ValueError("The notes keys must be a list of strings")
+            self._notes[style] = set(keys)
+
         return
 
 # END Class IndexItem
@@ -1302,18 +1360,43 @@ def unpackReferences(self, data: dict) -> None:
 #  Text Processing Functions
 # =============================================================================================== #
 
-CLASSIFIERS = {
-    "short": nwComment.SHORT,
+MODIFIERS = {
     "synopsis": nwComment.SYNOPSIS,
+    "short":    nwComment.SHORT,
+    "note":     nwComment.NOTE,
+    "footnote": nwComment.FOOTNOTE,
+}
+KEY_REQ = {
+    "synopsis": 0,  # Key not allowed
+    "short":    0,  # Key not allowed
+    "note":     1,  # Key optional
+    "footnote": 2,  # Key required
 }
 
 
-def processComment(text: str) -> tuple[nwComment, str, int]:
-    """Extract comment style and text. Should only be called on text
-    starting with a %.
+def _checkModKey(modifier: str, key: str) -> bool:
+    """Check if a modifier and key set are ok."""
+    if modifier in MODIFIERS:
+        if key == "":
+            return KEY_REQ[modifier] < 2
+        elif key.replace("_", "").isalnum():
+            return KEY_REQ[modifier] > 0
+    return False
+
+
+def processComment(text: str) -> tuple[nwComment, str, str, int, int]:
+    """Extract comment style, key and text. Should only be called on
+    text starting with a %.
     """
-    check = text[1:].lstrip()
-    classifier, _, content = check.partition(":")
-    if content and (clean := classifier.strip().lower()) in CLASSIFIERS:
-        return CLASSIFIERS[clean], content.strip(), text.find(":") + 1
-    return nwComment.PLAIN, check, 0
+    if text[:2] == "%~":
+        return nwComment.IGNORE, "", text[2:].lstrip(), 0, 0
+
+    check = text[1:].strip()
+    start, _, content = check.partition(":")
+    modifier, _, key = start.rstrip().partition(".")
+    if content and (clean := modifier.lower()) and _checkModKey(clean, key):
+        col = text.find(":") + 1
+        dot = text.find(".", 0, col) + 1
+        return MODIFIERS[clean], key, content.lstrip(), dot, col
+
+    return nwComment.PLAIN, "", check, 0, 0

novelwriter/core/status.py

@@ -29,7 +29,7 @@
 import random
 
 from collections.abc import Iterable
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
 
 from PyQt5.QtCore import QPointF, Qt
 from PyQt5.QtGui import QIcon, QPainter, QPainterPath, QPixmap, QColor, QPolygonF
@@ -75,7 +75,7 @@ class NWStatus:
 
     __slots__ = ("_store", "_default", "_prefix", "_height")
 
-    def __init__(self, prefix: str) -> None:
+    def __init__(self, prefix: Literal["s", "i"]) -> None:
         self._store: dict[str, StatusEntry] = {}
         self._default = None
         self._prefix = prefix[:1]