tree c4a238b6f2150d68b981aa21bb451dc634c459ef
parent a9a634f3de0a7529baded7ad6b0c7467d5c6eca7
author Ian Campbell <ijc25@users.noreply.github.com> 1485812565 +0000
committer Eric Paris <eparis@redhat.com> 1485812565 -0500

Add FlagSet.FlagUsagesWrapped(cols) which wraps to the given column (#105)

This will allow applications to provide better help text without feeling
constrained by how it will wrap even on 80 column displays etc. This has been a
factor in tickets such as https://github.com/docker/docker/issues/18797.

The basic wrapping algorithm is rather simplistic, it will look for the last
whitespace (space or tab) before the given column and wrap there, indenting the
continuation lines to match the usage text (i.e. aligned after the flag names
themselves), e.g. when applied to `docker ps` wrapping at 70 columns (fairly
narrow):

Options:
[...]
  -f, --filter filter   Filter output based on conditions provided
[...]
  -n, --last int        Show n last created containers
                        (includes all states) (default -1)
  -l, --latest          Show the latest created container
                        (includes all states)

There are two main tweaks to this basic algorithm, first is to actually try and
wrap to a soft limit 5 columns less than requested but allow the line to take
up the full hard width if that prevents pushing a short word at the end of the
string to the next line which looks odd, particuarly for usage which ends with
"(default [])" and wraps the "[])" to the last line.

Second if the display is too narrow, meaning after indentation for the flag
names there is less than 24 columns allowed for the help text (24 chosen just
by my eye and what I thought looked odd) then it will start the help text on
the next line indented to the 16th column (16 chosen so as not to align with
the first character of either the short of long flag name as 8 would, since
that looked strange to me), e.g. wrapping the above example to a rather narrow
45 columns:

Options:
[...]
  -f, --filter filter
                Filter output based on
                conditions provided
[...]
  -n, --last int
                Show n last created
                containers (includes
                all states) (default -1)
  -l, --latest
                Show the latest
                created container
                (includes all states)

If even with starting the help on the next line there is still less than 24
characters of space available for the help text (implying columns < 24 + 16 ==
40) just give up and return the unwrapped version (same as before this change).

Signed-off-by: Ian Campbell <ian.campbell@docker.com>,