Refactor localized and user-defined strings

- collect all localized string in Language
- remove StringCollection and subclasses
  - the sections in a template file corresponding to the string
    collections are replaced by the [STRINGS] section
- differentiate between builtin/user-defined strings by means of the
  @/$ symbols preceding the string identifiers (e.g. in [STRINGS])
- localize more strings: paragraph, section, listing

Author: brechtm

CHANGES.rst

@@ -41,6 +41,11 @@ New Features:
 
 Changed:
 
+* handling of localized strings and user-defined strings has been reworked
+  * built-in (localized) strings are now indicated by a ``@`` prefix, while
+    user-defined strings have the ``$`` prefix
+  * built-in strings can be overridden, and user-defined strings can be set in
+    a template configuration file in the ``[STRINGS]`` section (with prefix!)
 * "words" containing spaces (such as paths and URLs) can now be split before
   each forward slash for line wrapping (#188, #416)
 * Support for Python 3.7 was dropped (end-of-life in June 2023)
@@ -61,7 +66,7 @@ Changed:
 
 Fixed:
 
-* Caption labels ("Figure" ad "Table") were not localized
+* Caption labels ("Figure", "Table", "Listing") were not localized
 * Rendering of tables with no body (#420, PR #422 by th0mr)
 * Hyphenation of the first word on a line (#188, #416)
 * AttributeError: 'ZeroWidthSpace' object has no attribute 'hyphenate' (#415,

doc/api/strings.rst

@@ -5,18 +5,6 @@
 Strings (:mod:`rinoh.strings`)
 ==============================
 
-.. autoclass:: String
-    :members:
-
-
-.. autoclass:: StringCollection
-    :members:
-
-
-.. autoclass:: UserStrings
-    :members:
-
-
 .. autoclass:: Strings
     :members:
 

doc/api/structure.rst

@@ -17,10 +17,6 @@ Sections
     :members:
 
 
-.. autoclass:: SectionTitles
-    :members:
-
-
 Lists
 ~~~~~
 

doc/basicstyling.rst

@@ -167,11 +167,10 @@ distinction is only visible when using multiple columns for the page contents
 
 The standard document strings configured by the
 :attr:`~.DocumentTemplate.language` option described above can be overridden by
-user-defined strings in the :class:`~.SectionTitles` and
-:class:`~.AdmonitionTitles` sections of the configuration file. For example,
-the default title for the table of contents section (*Table of Contents*) is
-replaced with *Contents*. The configuration also sets custom titles for the
-caution and warning admonitions.
+user-defined strings in the ``STRINGS`` section of the configuration file. For
+example, the default title for the table of contents section (*Table of
+Contents*) is replaced with *Contents*. The configuration also sets custom
+titles for the caution and warning admonitions.
 
 The others sections in the configuration file are the ``VARIABLES`` section,
 followed by document part and page template sections. Similar to style sheets,

doc/my_book.rtt

@@ -10,12 +10,10 @@ parts =
 stylesheet = sphinx_base14
 language = fr
 
-[SectionTitles]
-contents = 'Contents'
-
-[AdmonitionTitles]
-caution = 'Careful!'
-warning = 'Please be warned'
+[STRINGS]
+@contents = 'Contents'
+@caution = 'Careful!'
+@warning = 'Please be warned'
 
 [VARIABLES]
 paper_size = A5

doc/rinohtype.rtt

@@ -11,8 +11,8 @@ parts =
 stylesheet = rinohtype.rts
 
 
-[SectionTitles]
-contents='Contents'
+[STRINGS]
+@contents='Contents'
 
 
 [VARIABLES]

src/rinoh/__init__.py

@@ -50,9 +50,3 @@
 
 register_template = resource._DISTRIBUTION.register_template
 register_typeface = resource._DISTRIBUTION.register_typeface
-
-# list all StringCollection subclasses in its docstring
-_ = ['* :class:`.{}`'.format(subclass_name)
-     for subclass_name in sorted(strings.StringCollection.subclasses)]
-strings.StringCollection.__doc__ += ('\n\n    :Subclasses: '
-                                     + '\n                 '.join(_))

src/rinoh/document.py

@@ -231,7 +231,8 @@ class Document(object):
         document_tree (DocumentTree): a tree of the document's contents
         stylesheet (StyleSheet): style sheet used to style document elements
         language (Language): the language to use for standard strings
-        strings (Strings): overrides localized strings provided by `language`
+        strings (Strings): user-defined string variables and can override
+          localized strings provided by `language`
         backend: the backend used for rendering the document
 
     """
@@ -380,21 +381,27 @@ def _save_cache(self, filename):
             cache = (self.part_page_counts, self.page_references)
             pickle.dump(cache, file)
 
-    def set_string(self, strings_class, key, value):
-        self._strings[strings_class][key] = value
-
-    def get_string(self, strings_class, key):
-        if (strings_class in self._strings
-                and key in self._strings[strings_class]):
-            return self._strings[strings_class][key]
+    def set_string(self, key, value, user=False):
+        if user:
+            self._strings.set_user_string(key, value)
+        else:
+            self._strings.set_builtin_string(key, value)
+
+    def get_string(self, key, user=False):
+        if user:
+            result = self._strings.user.get(key, None)
+            if result is None:
+                warn('The "{}" user string is not defined.')
+            return result or ''
+        if key in self._strings.builtin:
+            return self._strings.builtin[key]
         try:
-            return self.language.strings[strings_class][key]
+            return self.language.strings[key]
         except KeyError:
-            warn('The {} "{}" string is not defined for {} ({}). Using the '
-                 'English string instead.'.format(strings_class.__name__, key,
-                                                  self.language.name,
-                                                  self.language.code))
-            return EN.strings[strings_class][key]
+            warn('The "{}" string is not defined for {} ({}). Using the English'
+                 ' string instead.'
+                 .format(key, self.language.name, self.language.code))
+            return EN.strings[key]
 
     def add_sideways_float(self, float):
         self.sideways_floats.append(float)

src/rinoh/flowable.py

@@ -28,7 +28,6 @@
 from .layout import (InlineDownExpandingContainer, VirtualContainer,
                      MaybeContainer, ContainerOverflow, EndOfContainer,
                      PageBreakException, ReflowRequired)
-from .strings import UserStrings
 from .style import Styled, Style
 from .text import StyledText
 from .util import clamp, ReadAliasAttribute
@@ -431,7 +430,7 @@ def __init__(self, label, content, parent=None):
 
     def build_document(self, flowable_target):
         doc = flowable_target.document
-        doc.set_string(UserStrings, self.label, self.content)
+        doc.set_string(self.label, self.content, user=True)
 
 
 class SetOutOfLineFlowables(DummyFlowable):

src/rinoh/highlight.py

@@ -59,7 +59,7 @@ class CodeBlockWithCaptionStyle(FloatStyle, GroupedFlowablesStyle):
 
 class CodeBlockWithCaption(Float, StaticGroupedFlowables):
     style_class = CodeBlockWithCaptionStyle
-    category = 'Listing'
+    category = 'listing'
 
 
 def highlight_block(language, text, lexer_getter):

src/rinoh/image.py

@@ -23,7 +23,7 @@
 from .layout import ContainerOverflow, EndOfContainer
 from .number import NumberFormat
 from .paragraph import StaticParagraph, Paragraph, ParagraphStyle
-from .strings import StringCollection, String, StringField
+from .strings import StringField
 from .structure import ListOf, ListOfSection
 from .text import MixedStyledText, SingleStyledText, TextStyle, ErrorText
 from .util import posix_path, ReadAliasAttribute, PeekIterator
@@ -398,7 +398,7 @@ def referenceable(self):
     def text(self, container):
         try:
             number = self.number(container)
-            category_label = StringField(FloatLabels, self.referenceable.category)
+            category_label = StringField(self.referenceable.category)
             label = [category_label, ' ', number]
         except KeyError:
             label = []
@@ -420,10 +420,3 @@ class ListOfFigures(ListOf):
 
 class ListOfFiguresSection(ListOfSection):
     list_class = ListOfFigures
-
-
-class FloatLabels(StringCollection):
-    """Collection of localized titles for common sections"""
-
-    figure = String('Caption label for figures')
-    table = String('Caption label for tables')

src/rinoh/index.py

@@ -11,7 +11,7 @@
 from .paragraph import Paragraph
 from .reference import Reference
 from .strings import StringField
-from .structure import Section, Heading, SectionTitles
+from .structure import Section, Heading
 from .style import Styled
 from .text import MixedStyledText, StyledText
 from .util import intersperse
@@ -23,7 +23,7 @@
 
 class IndexSection(Section):
     def __init__(self, title=None, flowables=None, style=None):
-        section_title = title or StringField(SectionTitles, 'index')
+        section_title = title or StringField('index')
         contents = [Heading(section_title, style='unnumbered')]
         if flowables:
             contents += list(flowables)
@@ -127,7 +127,7 @@ def spans(self, container):
 
 
 class IndexTarget(IndexTargetBase, DummyFlowable):
-    category = 'Index'
+    category = 'index'
 
     def __init__(self, index_terms, parent=None):
         super().__init__(index_terms, parent=parent)

src/rinoh/language/__init__.py

@@ -26,10 +26,6 @@
 for code, language_ref in Language.languages.items():
     language = language_ref()
     lines = ['Localized strings for {}'.format(language.name)]
-    for string_collection in language.strings.values():
-        lines.append("\n.. rubric:: {}\n"
-                     .format(type(string_collection).__name__))
-        for string in string_collection._strings:
-            lines.append(":{}: {}".format(string.name,
-                                          string_collection[string.name]))
+    for name, localized_string in language.strings.items():
+        lines.append(":{}: {}".format(name, localized_string))
     language.__doc__ = '\n'.join(lines)

src/rinoh/language/cls.py

@@ -9,7 +9,6 @@
 import weakref
 
 from ..attribute import AttributeType
-from ..strings import StringCollection
 
 
 __all__ = ['Language']
@@ -22,27 +21,43 @@ class Language(AttributeType):
         code (str): short code identifying the language
         name (str): native name of the language
 
+        paragraph: label for referencing paragraphs
+        section: label for referencing sections
+        chapter: label for top-level sections
+        figure: caption label for figures
+        table: caption label for tables
+        listing: caption label for (source code) listings
+        contents: title for the table of contents section
+        list_of_figures: title for the list of figures section
+        list_of_tables: title for the list of tables section
+        index: title for the index section
+
+        attention: title for attention admonitions
+        caution: title for caution admonitions
+        danger: title for danger admonitions
+        error: title for error admonitions
+        hint: title for hint admonitions
+        important: title for important admonitions
+        note: title for note admonitions
+        tip: title for tip admonitions
+        warning: title for warning admonitions
+        seealso: title for see-also admonitions
+
     """
 
     languages = {}  #: Dictionary mapping codes to :class:`Language`\ s
 
-    def __init__(self, code, name):
+    def __init__(self, code, name, **localized_strings):
         self.languages[code] = weakref.ref(self)
         self.code = code
         self.name = name
-        self.strings = {}
+        self.strings = localized_strings
         self.no_break_after = []
 
     def __repr__(self):
         return "{}('{}', '{}')".format(type(self).__name__,
                                        self.code, self.name)
 
-    def __contains__(self, item):
-        assert isinstance(item, StringCollection)
-        strings_class = type(item)
-        assert strings_class not in self.strings
-        self.strings[strings_class] = item
-
     @classmethod
     def parse_string(cls, string, source):
         return cls.languages[string.lower()]()

src/rinoh/language/cs.py

@@ -7,26 +7,18 @@
 
 
 from .cls import Language
-from ..image import FloatLabels
-from ..structure import SectionTitles, AdmonitionTitles
 
 
-CS = Language('cs', 'Česky')
-
-FloatLabels(
+CS = Language('cs', 'Česky',
     figure='Obrázek',
     table='Tabulka',
-) in CS
-
-SectionTitles(
     contents='Obsah',
     list_of_figures='Seznam obrázků',
     list_of_tables='Seznam tabulek',
     chapter='Kapitola',
     index='Rejstřík',
-) in CS
 
-AdmonitionTitles(
+    # admonitions
     attention='Pozor!',
     caution='Pozor!',
     danger='!NEBEZPEČÍ!',
@@ -37,7 +29,7 @@
     tip='Tip',
     warning='Varování',
     seealso='Viz také',
-) in CS
+)
 
 
 CS.no_break_after = ("do od u z ze za k ke o na v ve nad pod za po s se "

src/rinoh/language/de.py

@@ -7,26 +7,18 @@
 
 
 from .cls import Language
-from ..image import FloatLabels
-from ..structure import SectionTitles, AdmonitionTitles
 
 
-DE = Language('de', 'Deutsch')
-
-FloatLabels(
+DE = Language('de', 'Deutsch',
     figure='Abbildung',
     table='Tabelle',
-) in DE
-
-SectionTitles(
     contents='Inhalt',
     list_of_figures='Abbildungsverzeichnis',
     list_of_tables='Tabellenverzeichnis',
     chapter='Kapitel',
     index='Index',
-) in DE
 
-AdmonitionTitles(
+    # admonitions
     attention='Aufgepasst!',
     caution='Vorsicht!',
     danger='!GEFAHR!',
@@ -37,4 +29,4 @@
     tip='Tipp',
     warning='Warnung',
     seealso='Siehe auch',
-) in DE
+)