Support interpolation in diary page titles

game/scripts/interface/book.rpy

@@ -63,21 +63,23 @@ init python:
     class diary_class(book_readable_class):
         def __init__(self, *args, dictionary, **kwargs):
             """
-            `dictionary` is a dict containing two types of entries:
+            `dictionary` is a dict containing two kinds of entries:
-            - for normal text pages, id: (title, text).
+            - the first kind is to store the possible pages which can be added to the dict.
-                `text` may contain interpolation fields, such as {code}.
+                These entries are the form {str page_id : (str|None page_title, str page_text)}.
-                When that's the case, there must be an 2nd-type entry for "code" in this dict.
+                `page_title` and `page_text` may contain interpolation fields, such as {code}.
-                `title` may be None.
+            - the second kind is to store the for interpolation codes to fill in those blanks.
-            - for interpolation codes, code: text.
+                These entries are of the form {str interpo_id : str interpo_text}.
-                `text` is the text to be used for the interpolation.
+                `interpo_text` is the text to be used for the interpolation.
+
+            See the diary_append method to match interpolation fields with interpolation ids when adding the pages.
 
             Alternatively, `dictionary` may be the name of a store variable containing the actual dictionary
             (that's better when not in a testing phase, for pickling/saving/updating reasons)
             """
             super().__init__(*args, **kwargs)
 
-            self.dictionary_ = dictionary # str id : either (title, text) or text
+            self.dictionary_ = dictionary # type: dict[str, tuple[str|None, str]|str]|str
-            self.entry_ids = set() # str id
+            self.entry_ids = set() # set[str]
 
         @property
         def dictionary(self):
@@ -90,18 +92,27 @@ init python:
         def diary_append(self, id, day=None, **branches):
             """
             Adds a page to the diary.
-            `id` is the key of the event that just happened, in the dictionary.
+            `id` is the key of the event that just happened, in the dictionary - a first-kind key.
             `day` sets the day number for the entry, defaulting to the current day.
 
-            `branches` is a dict of {sub-event id : code} for every happened sub-event specializing event `id`.
+            `branches` is a dict of {code : interpo_id} for every happened sub-event specializing the `id` event.
-            the specified codes will be looked for in the dictionary, and the original entry of id `id`
+            The specified interpolation ids will be looked for in the dictionary, and the original entry of id `id`
-            will be formatted by associating {sub-event id} with dictionary[code].
+            will be formatted by replacing {code} with the page title and page text found in dictionary[interpo_id].
-            If `code` is not a valid entry in the dict, the `code` value itself will be interpolated instead,
+            If `interpo_id` is not a valid entry in the dict, the passed value itself will be interpolated instead,
-            or nothing if v is a false value (like None).
+            or nothing if it is a false value (like None).
 
-            If the page for the key `id` contains interpolation fields,
+            For example, if the entry associated with "id1549" is ("Tittle", "Today I met {a} and did {b}. I liked it{c}.").
-            it is a mistake to not specify all interpolation fields in `branches`.
+            Calling `diary_append("id1549", a="Alice", b="nothing", c=" a lot")` will add the page
-            It is benign to specify keys which are not interpolation fields.
+            "Today I met Alice and did nothing. I liked it a lot." to the diary, with the title "Tittle".
+            Passing c="" or c=None or c=False will all result in "Today I met Alice and did nothing. I liked it.".
+
+            If the page and title for the key `id` contain interpolation fields, it is a mistake
+            not to pass all interpolation fields as kwargs.
+            It is benign to specify keys which are not interpolation fields in the entry : in the previous example,
+            passing d=whatever will not change anything to the result.
+
+            Passing the same page `id` several times will only work the first time, subsequent tries will be ignored.
+            The entry_id attribute (a set) can be accessed, read only, to check if an entry has already been added.
             """
 
             if id in self.entry_ids:
@@ -113,6 +124,8 @@ init python:
             if branches:
                 branches = {k : dictionary.get(v, v or "") for k, v in branches.items()}
                 page_text = page_text.format(**branches)
+                if page_title:
+                    page_title = page_title.format(**branches)
 
             if day is None:
                 day = game.day