docs: document leading period-abbreviation title inference (#109)

Author: derek73

docs/release_log.rst

@@ -30,6 +30,7 @@ Release Log
       ``CONSTANTS.first_name_prefixes.clear()``. **Default-on: changes parsing
       output for names with these prefixes.** (#150)
     - Add ``middle_name_as_last`` flag to ``Constants`` and ``HumanName`` for opt-in folding of middle names into the last name, for naming systems with no middle-name concept (e.g. Arabic patronymic chaining) (#133)
+    - Treat an unrecognized, multi-letter token ending in a period at the start of a name (e.g. ``"Major."``) as a ``title`` instead of a ``first`` name; internal-period abbreviations (``"E.T."``) and single-letter initials (``"J."``) are unaffected. **Default-on: changes parsing of names with a leading unknown period-abbreviation** (closes #109)
 * 1.2.1 - June 19, 2026
     - Fix ``initials()`` interpolating the literal ``None`` for empty name parts when ``empty_attribute_default = None`` (e.g. ``"J. None D."``); empty parts now render as an empty string and a fully-empty result returns ``empty_attribute_default``
     - Add ``python -m nameparser "Name String"`` command-line helper that prints a parsed name

docs/usage.rst

@@ -188,6 +188,35 @@ reading in that ambiguous context:
       nickname: 'JD'
     ]>
 
+Leading Period-Abbreviation Titles
+-----------------------------------
+
+An unrecognized, multi-letter word ending in a period, appearing before the
+first name, is treated as a title -- this covers military ranks and other
+abbreviations that aren't in the built-in titles list. Single-letter
+initials (``"J."``) and internal-period abbreviations (``"E.T."``) are not
+affected, and the same word appearing after the first name is left as a
+middle name.
+
+.. doctest:: leading_period_titles
+    :options: +NORMALIZE_WHITESPACE
+
+    >>> name = HumanName("Major. Dona Smith")
+    >>> name
+    <HumanName : [
+      title: 'Major.'
+      first: 'Dona'
+      middle: ''
+      last: 'Smith'
+      suffix: ''
+      nickname: ''
+    ]>
+    >>> name = HumanName("J. Smith")
+    >>> name.first
+    'J.'
+    >>> name.title
+    ''
+
 Change the output string with string formatting
 -----------------------------------------------