Label the CLI output sections; document the tussenvoegsel sort

The default output printed three things, two of them unlabeled
ParsedName reprs — the parse and the capitalized view. For input that
is already correctly cased those two are byte-identical, so the CLI
looked like it was printing the same thing twice, and there was no way
to tell which block was which. The third line was already labeled
"Initials:", so the inconsistency was internal to the command. Label
all three.

usage.rst gains an intro to that section framing the CLI as the quick
way to check how a string parses — trying a variation of a name that
came out wrong, or a locale pack before wiring it into code — plus the
real output, which the section previously showed only for --json.

The family_base example gains its reason for existing. #130 asked for
the surname split specifically for tussenvoegsels, the Dutch particle
that directories file a name *under* rather than *by*. Naming the
convention gives the searchable term, and the contrast doctest shows
what the split avoids: sorting on family files van Gogh under "v" and
de la Vega under "d".

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: derek73

docs/usage.rst

@@ -131,8 +131,10 @@ while ``given_names`` and ``surnames`` roll several fields together —
 the same sense in which a passport form asks for your "given names" as
 one blank that can hold more than one word.
 
-``family_base`` is what you want for alphabetizing, since it drops the
-particles a phone book ignores:
+``family_base`` is the one to sort on. Dutch and Belgian directories
+file a name under the base surname and ignore the *tussenvoegsel* — the
+``van``, ``de`` or ``van der`` in front of it — and the same convention
+applies wherever particles are common:
 
 .. doctest::
 
@@ -141,6 +143,14 @@ particles a phone book ignores:
     >>> [n.family_base for n in sorted(names, key=lambda n: n.family_base.lower())]
     ['Gogh', 'Smith', 'Vega']
 
+Sorting on ``family`` instead files those under "d", "S" and "v", which
+is the problem the split exists to solve:
+
+.. doctest::
+
+    >>> [n.family for n in sorted(names, key=lambda n: n.family.lower())]
+    ['de la Vega', 'Smith', 'van Gogh']
+
 Dicts and strings
 ------------------
 
@@ -358,6 +368,34 @@ everything else carried over.
 Command line
 ------------
 
+``python -m nameparser`` parses one name and prints what it found. It
+is the quickest way to see how a particular string comes out — worth
+reaching for when a name parsed unexpectedly and you want to check a
+variation of it, or when trying a locale pack before wiring one into
+code:
+
+::
+
+    $ python -m nameparser "dr. juan de la vega iii"
+    Parsed:
+    <ParsedName: [
+        title: 'dr.'
+        given: 'juan'
+        family: 'de la vega'
+        suffix: 'iii'
+    ]>
+    Capitalized:
+    <ParsedName: [
+        title: 'Dr.'
+        given: 'Juan'
+        family: 'de la Vega'
+        suffix: 'III'
+    ]>
+    Initials: j. v.
+
+``--json`` prints the fields as a single line instead, which is the
+form to pipe somewhere:
+
 ::
 
     $ python -m nameparser --json "Doe, John"

nameparser/__main__.py

@@ -33,7 +33,12 @@ def main(argv: list[str] | None = None) -> int:
     if args.json:
         print(json.dumps(n.as_dict(), ensure_ascii=False))
         return 0
+    # Label each section: the two reprs are byte-identical for input
+    # that is already correctly cased, so without labels there is no
+    # telling which is the parse and which is the capitalized view.
+    print("Parsed:")
     print(repr(n))
+    print("Capitalized:")
     print(repr(n.capitalized()))
     print("Initials:", n.initials())
     return 0

tests/v2/test_cli.py

@@ -15,6 +15,17 @@ def test_cli_prints_repr_capitalized_and_initials() -> None:
     assert "Initials:" in out
 
 
+def test_cli_labels_each_section() -> None:
+    # two of the three outputs were unlabeled ParsedName reprs, and for
+    # already-cased input they are byte-identical -- the reader cannot
+    # tell which is the parse and which is the capitalized view
+    out = _run("Dr. Juan de la Vega III").stdout
+    assert out.count("<ParsedName:") == 2     # still both shown
+    assert "Parsed:" in out
+    assert "Capitalized:" in out
+    assert out.index("Parsed:") < out.index("Capitalized:")
+
+
 def test_cli_json() -> None:
     proc = _run("John Smith", "--json")
     data = json.loads(proc.stdout)