Args Package: Inconsistent spacing in getUsage() string.

[DartBot]

This issue was originally filed by @butlermatt

---

import('package:args/args.dart');

void main() {
  var parser = new ArgParser();
  
  parser.addOption('test', help: 'A short help line. Only one line');
  parser.addOption('test2', help: 'Another short help line. Still one.\n\n');
  parser.addOption('works', help: 'This is multiline help\nNext should work');
  parser.addOption('fails', help: 'Theres a proper space before this');
  
  print(parser.getUsage());
}

If you notice when running the above code, any single line comments only have one new line after them in the usage. Even when I manually specify two. However once I have a multi-line help content it provides two new lines after the option in the string.

Personally I would like to see all help followed by two new lines to prevent clumping of commands when there is a one-line help vs multi-line.

[sethladd]

Thanks for all the reports, Matt. If you're interested, we can help you get any CL's through that might address these issues.

---

Set owner to @munificent.
Added Area-Library, Library-Args, Triaged labels.

[DartBot]

This comment was originally written by @butlermatt

---

Looking at the source for Args about this issue, it appears this particular behaviour is by design.
http://code.google.com/p/dart/source/browse/branches/bleeding_edge/dart/pkg/args/lib/args.dart#­646

      // If any given option displays more than one line of text on the right
      // column (i.e. help, default value, allowed options, etc.) then put a
      // blank line after it. This gives space where it's useful while still
      // keeping simple one-line options clumped together.

So this sounds like a style recommendation for options. If enforcing this convention (clumping one line options together) then should we add documentation to the package to reflect this so this can be accounted for by the users? Or would it be best to provide consistent spacing regardless of length of help information?

[munificent]

The comment is describing what the code itself does and not what a user has to do, so there isn't much to recommend. My goal was to have it create usage that worked well (nice and compact) when the help text is short but wasn't a wall of text when you had longer help text. The above behavior is a bit magical and arbitrary, but I think it looks pretty nice and doesn't require any configuration. I wanted something that just worked.

We could maybe provide an option to control the formatting in case you really care, but I don't know if that starts to go too far down the minutiae rabbithole.

[DartBot]

This comment was originally written by @butlermatt

---

I realize it was describing what the code itself does, but for me the issue appears when you start having a significant number of options with short and long help text interspersed between each other. As in my small example above, it starts adding the extra line after the long help text, but if we say doubled the options listed, then we have clumps of short help with the long one.

Ie)

#library('args_parser');
#import('package:args/args.dart');

void main() {
  var parser = new ArgParser();
  
  parser.addOption('test', help: 'A short help line. Only one line');
  parser.addOption('test2', help: 'Another short help line. Still one.\n\n');
  parser.addOption('works', help: 'This is multiline help\nNext should work');
  parser.addOption('fails', help: 'Theres a proper space before this');
  parser.addOption('test3', help: 'A short help line. Only one line');
  parser.addOption('test4', help: 'Another short help line. Still one.\n\n');
  parser.addOption('works1', help: 'This is multiline help\nNext should work');
  parser.addOption('fails3', help: 'Theres a proper space before this');
  
  
  print(parser.getUsage());
}
==== Output ====

--test A short help line. Only one line
--test2 Another short help line. Still one.
--works This is multiline help
            Next should work

--fails Theres a proper space before this
--test3 A short help line. Only one line
--test4 Another short help line. Still one.
--works1 This is multiline help
            Next should work

--fails3 Theres a proper space before this
=======

So my option now as a user is, in the code, to keep all my short help options together, then put all my long help options together to avoid spacing between options. Which if that's how you'd like to suggest users do it is totally fine to me, just give a heads up in the docs :)

[munificent]

So my option now as a user is, in the code, to keep all my short help options together, then put all my long help options together to avoid spacing between options. Which if that's how you'd like to suggest users do it is totally fine to me, just give a heads up in the docs :)

Yeah, I think that's what I would recommend too. I'm fine with adding it to the docs.

[DartBot]

This comment was originally written by @butlermatt

---

https://codereview.chromium.org/10967042/

[munificent]

Added Fixed label.

[dgrove]

Removed Library-Args label.
Added Package-Args label.

[dgrove]

Removed Area-Library label.
Added area-package label.

[dgrove]

Removed area-package label.
Added Area-Pkg label.

[DartBot]

This comment was originally written by amouravski@google.com

---

Removed Package-Args label.
Added Library-Args label.

[anders-sandholm]

Removed Library-Args label.
Added Pkg-Args label.

[DartBot]

This issue has been moved to dart-lang/args#16.