man-page is incorrectly formatted by GNU help2man

[vt-alt]

You use GNU help2man to generate man page but it does not understand Python argparse output properly. (This is known issue of GNU help2man.)

Broken formatting examples with explanations:

SYNOPSIS
       codespell [OPTIONS] [file1 file2 ... fileN]

DESCRIPTION
       codespell  is  designed  to  find  and  fix common misspellings in text
       files.  It is designed  primarily  for  checking  misspelled  words  in
       source code, but it can be used with other files as well.

       usage: codespell [-h] [--version] [-d] [-c] [-w] [-D DICTIONARY]

              [--builtin BUILTIN-LIST] [--ignore-regex IGNORE_REGEX] [-I FILE]
              [-L   WORDS]   [--uri-ignore-words-list   WORDS]   [-r    REGEX]
              [--uri-regex  URI_REGEX]  [-s] [--count] [-S SKIP] [-x FILE] [-i
              INTERACTIVE] [-q QUIET_LEVEL] [-e]  [-f]  [-H]  [-A  LINES]  [-B
              LINES] [-C LINES] [--config CONFIG] [--toml TOML] [files ...]

   positional arguments:
       files  files or directories to check

• usage output should go into SYNOPSIS
• Empty line is inserted after first and following lines of usage.

• No OPTIONS section, all options went into DESCRIPTION.

     -i INTERACTIVE, --interactive `INTERACTIVE`
            set interactive mode when writing changes: - 0:  no  interactiv‐
            ity.   -  1:  ask for confirmation.  - 2: ask user to choose one
            fix when more than one is
  
     available.
            - 3: both 1 and 2

• available is incorrectly split into next paragraph.

Other converters you may consider using:

• https://pypi.org/project/argparse-manpage/
• https://pypi.org/project/help2man/

[DimitriPapadopoulos]

Indeed, a PR that fixes this issue would be welcome.