Man pages ignore \b characters in docstrings

[gtristan]

As is documented in click here, the docstrings for click commands are expected to contain \b characters before a paragraph which should not be made to wrap.

This allows better formatting of docstrings in the help output, without this it is impossible to make any kind of formatting of the help such as point form lists which describe the meaning of each click.Choice() option.

This works well for click's help output, but is also broken for the sphinx-click generated html docs, and for sphinx-man generated man pages.

Here are two examples to show the brokenness:

Broken man page output

NAME
       bst-show - Show elements in the pipeline

SYNOPSIS
       bst show [OPTIONS] TARGET

DESCRIPTION
       Show elements in the pipeline

       By default this will only show the specified element, use the --deps option to show an entire pipeline.

       FORMAT ~~~~~~ The --format option controls what should be printed for each element, the following symbols can be used in the format string:

           %{name}     The element name
           %{key}      The abbreviated cache key (if all sources are consistent)
           %{full-key} The full cache key (if all sources are consistent)
           %{state}    cached, buildable, waiting or inconsistent
           %{config}   The element configuration
           %{vars}     Variable configuration
           %{env}      Environment settings
           %{public}   Public domain data

       The value of the %{symbol} without the leading '%' character is understood as a pythonic formatting string, so python formatting features apply, examle:

           build-stream show target.bst --format         'Name: %{name: ^20} Key: %{key: ^8} State: %{state}'

       If you want to use a newline in a format string in bash, use the '$' modifier:

           build-stream show target.bst --format         $'---------- %{name} ----------1{vars}'

OPTIONS
       -d, --deps [all|build|run]
              Optionally specify a dependency scope to show

       --order [stage|alpha]
              Staging or alphabetic ordering of dependencies

       -f, --format FORMAT
              Format string for each element

       -a, --arch TEXT
              The target architecture (default: x86_64)

       --variant TEXT
              A variant of the specified target

                                                                                              09-May-2017                                                                                  BST SHOW(1)

Well formatted output of bst show --help

Usage: bst show [OPTIONS] TARGET

  Show elements in the pipeline

  By default this will only show the specified element, use the --deps
  option to show an entire pipeline.

  FORMAT
  ~~~~~~
  The --format option controls what should be printed for each element,
  the following symbols can be used in the format string:

      %{name}     The element name
      %{key}      The abbreviated cache key (if all sources are consistent)
      %{full-key} The full cache key (if all sources are consistent)
      %{state}    cached, buildable, waiting or inconsistent
      %{config}   The element configuration
      %{vars}     Variable configuration
      %{env}      Environment settings
      %{public}   Public domain data

  The value of the %{symbol} without the leading '%' character is understood
  as a pythonic formatting string, so python formatting features apply,
  examle:

      build-stream show target.bst --format \
          'Name: %{name: ^20} Key: %{key: ^8} State: %{state}'

  If you want to use a newline in a format string in bash, use the '$'
  modifier:

      build-stream show target.bst --format \
          $'---------- %{name} ----------\n%{vars}'

Options:
  -d, --deps [all|build|run]  Optionally specify a dependency scope to show
  --order [stage|alpha]       Staging or alphabetic ordering of dependencies
  -f, --format FORMAT         Format string for each element
  -a, --arch TEXT             The target architecture (default: x86_64)
  --variant TEXT              A variant of the specified target
  --help                      Show this message and exit.