[
https://issues.apache.org/jira/browse/MESOS-3818?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15026016#comment-15026016
]
Shuai Lin commented on MESOS-3818:
----------------------------------
Yeah, I would also like the "adjust the newlines in the existing help strings."
solution, but the main reasons that I recommend against it is because: the line
wrapping in the source code may not be consistent with the final line wrapping
in the help output, because we use constant variables in the help strings. For
example:
{code}
add(&Flags::acls,
"acls",
"The value could be a JSON-formatted string of ACLs or a file path\n"
"containing the JSON-formatted ACLs used for authorization. Path\n"
"could be of the form 'file:///path/to/file' or '/path/to/file'.\n"
"\n"
"Note that if the flag --authorizers is provided with a value\n"
"different than '" + DEFAULT_AUTHORIZER + "', the ACLs contents will be
ignored.\n"
"\n"
"See the ACLs protobuf in mesos.proto for the expected format.\n");
{code}
It's very difficult to tell where to the wrap line that has the constant
{{DEFAULT_AUTHORIZER}} by looking with eyes, except try-compile-check, and
try-compile-check again, without any hint. And this case appears in a lots of
help strings.
The same happens when deciding where to wrap the constant used as a default
value of a flag:
{code}
add(&Flags::allocator,
"allocator",
"Allocator to use for resource allocation to frameworks.\n"
"Use the default '" + DEFAULT_ALLOCATOR + "' allocator, or\n"
"load an alternate allocator module using --modules.",
DEFAULT_ALLOCATOR);
{code}
If we take the "adjust the newlines in the existing help strings." solution
this time, next time when someone else need to modify these help strings, e.g.
when the usage of a flag is changed, it would be a pain for them to manually
wrap the help string, and more likely they would ignore that completely, so
after a while we may need to open another jira issue like this one again to fix
the line wrapping.
On the contrary, If we let the the flags implementation code handle the the
task of line wrapping, it would be way more easier to modify the help strings
in the future, or when we want to make the help output wrap at a differnt line
width.
About handling special-cases like JSON example text: maybe we can define a
marker, e.g two consequtive newline character, and everything that follows the
marker would not be formatted.
> Line wrapping for "--help" output
> ---------------------------------
>
> Key: MESOS-3818
> URL: https://issues.apache.org/jira/browse/MESOS-3818
> Project: Mesos
> Issue Type: Improvement
> Reporter: Neil Conway
> Assignee: Shuai Lin
> Priority: Trivial
> Labels: mesosphere, newbie
>
> The output of `mesos-slave --help`, `mesos-master --help`, and perhaps other
> programs has very inconsistent line wrapping: different help text fragments
> are wrapped at very different column numbers, which harms readability.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
