proj/pkgcore/snakeoil:master commit in: src/snakeoil/dist/, /

commit:     e7793397bede7716c6dc7eb33248da014319dcd1
Author:     Arthur Zamarin <arthurzam <AT> gentoo <DOT> org>
AuthorDate: Sat Aug  8 06:25:12 2026 +0000
Commit:     Arthur Zamarin <arthurzam <AT> gentoo <DOT> org>
CommitDate: Sat Aug  8 06:25:12 2026 +0000
URL:        https://gitweb.gentoo.org/proj/pkgcore/snakeoil.git/commit/?id=e7793397

dist.generate_man_rsts: fix synopsis formatting

Usage was formatted at width 1000, so it came out as a single long line
and man reflowed it into justified mush - ragged inter-word spacing, and
mutually exclusive groups split at arbitrary points:

    pkgcheck cache [-r REPO] [-h]  [--debug]  [-q]  [-v]  [--color  BOOLEAN]
    [--cache-dir  CACHE_DIR]  [-l  | -u | -R] [-f] [-n] [-t CACHE] [-a ARCH]
    [-p PROFILE] [--commits [tree-ish] | --staged [tree-ish]]  [--git-remote
    REMOTE]

Format at a width that fits an 80 column man page and emit the result as a
literal block so troff leaves the line breaks alone:

    pkgcheck cache [-r REPO] [-h] [--debug] [-q] [-v] [--color BOOLEAN]
                   [--cache-dir CACHE_DIR] [-l | -u | -R] [-f] [-n]
                   [-t CACHE] [-a ARCH] [-p PROFILE]
                   [--commits [tree-ish] | --staged [tree-ish]]
                   [--git-remote REMOTE]

Pass an empty prefix to add_usage() rather than stripping "usage: " off
the formatted text afterwards. argparse indents continuation lines to
len(prefix) + len(prog) + 1, but the strip only ever touched the first
line, so every continuation sat seven columns too far right. That was
latent while nothing wrapped at width 1000; it is not once things wrap.

The width and max_help_position of 1000 only existed to defeat argparse's
column layout for option help, which is rendered as directives now, so
neither is worth keeping.

Signed-off-by: Arthur Zamarin <arthurzam <AT> gentoo.org>

 NEWS.rst                               |  5 +++++
 src/snakeoil/dist/generate_man_rsts.py | 12 ++++++------
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/NEWS.rst b/NEWS.rst
index 1704be3..18c1a06 100644
--- a/NEWS.rst
+++ b/NEWS.rst
@@ -21,6 +21,11 @@ snakeoil 0.11.4 (unreleased)
   every single argument.  Options are now properly rendered, indexed and
   cross-referenceable (Arthur Zamarin)
 
+- ``snakeoil.dist.generate_man_rsts``: the synopsis is no longer emitted as one
+  long line, and its continuation lines are no longer misaligned by the width
+  of the stripped ``usage:`` prefix. It is now wrapped to fit an 80 column man
+  page and kept as a literal block (Arthur Zamarin)
+
 - ``snakeoil.klass.immutable.Simple``/``Strict``: slotted subclasses are now
   picklable and copyable directly; a ``__setstate__`` restoring state past the
   mutation protections is injected for them.  Classes without slotting are left

diff --git a/src/snakeoil/dist/generate_man_rsts.py b/src/snakeoil/dist/generate_man_rsts.py
index 2d69c2b..a13546d 100644
--- a/src/snakeoil/dist/generate_man_rsts.py
+++ b/src/snakeoil/dist/generate_man_rsts.py
@@ -40,6 +40,7 @@ class ManConverter:
         out_path = os.path.join(base_path, out_name)
         script_time = int(os.stat(__file__).st_mtime)
         module = import_module(src)
+        assert module.__file__ is not None
         cur_time = int(os.stat(module.__file__).st_mtime)
         cur_time = max([cur_time, script_time])
         try:
@@ -88,7 +89,8 @@ class ManConverter:
 
     @staticmethod
     def _get_formatter(parser, name):
-        return RstFormatter(name, width=1000, max_help_position=1000)
+        # width only affects the usage; option docs are rendered as directives
+        return RstFormatter(name, width=70)
 
     def process_subcommands(self, parser, name, action_group):
         l = []
@@ -137,11 +139,9 @@ class ManConverter:
 
     def generate_usage(self, parser, name):
         h = self._get_formatter(parser, name)
-        h.add_usage(parser.usage, parser._actions, parser._mutually_exclusive_groups)
-        text = h.format_help()
-        if text.startswith("usage:"):
-            text = text[len("usage:"):].lstrip()
-        return (x for x in text.split('\n') if x)
+        h.add_usage(parser.usage, parser._actions, parser._mutually_exclusive_groups, prefix='')
+        # literal block, else troff reflows and justifies the usage into mush
+        return ['::', ''] + [f'   {x}' for x in h.format_help().split('\n') if x]
 
     def process_parser(self, parser, name):
         # forcibly run pre-parse functionality as extra arguments may be added