Args Package: Inconsistent spacing in getUsage() string. about args HOT 12 CLOSED

<img src="https://avatars.githubusercontent.com/u/5479?v=3" align="left" width="48" height="48"hspace="10"> Comment by 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.

from args.

<img src="https://avatars.githubusercontent.com/u/1148886?v=3" align="left" width="48" height="48"hspace="10"> Comment 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#&#173;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?

from args.

<img src="https://avatars.githubusercontent.com/u/46275?v=3" align="left" width="48" height="48"hspace="10"> Comment by 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.

from args.

<img src="https://avatars.githubusercontent.com/u/1148886?v=3" align="left" width="48" height="48"hspace="10"> Comment 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 :)

from args.

<img src="https://avatars.githubusercontent.com/u/46275?v=3" align="left" width="48" height="48"hspace="10"> Comment by 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.

from args.

<img src="https://avatars.githubusercontent.com/u/1148886?v=3" align="left" width="48" height="48"hspace="10"> Comment by butlermatt

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

from args.

<img src="https://avatars.githubusercontent.com/u/46275?v=3" align="left" width="48" height="48"hspace="10"> Comment by munificent

Added Fixed label.

from args.

<img src="https://avatars.githubusercontent.com/u/2108507?v=3" align="left" width="48" height="48"hspace="10"> Comment by dgrove

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

from args.

<img src="https://avatars.githubusercontent.com/u/2108507?v=3" align="left" width="48" height="48"hspace="10"> Comment by dgrove

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

from args.

<img src="https://avatars.githubusercontent.com/u/2108507?v=3" align="left" width="48" height="48"hspace="10"> Comment by dgrove

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

from args.

<img src="https://avatars.githubusercontent.com/u/264967?v=3" align="left" width="48" height="48"hspace="10"> Comment by amouravski

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

from args.

<img src="https://avatars.githubusercontent.com/u/3276024?v=3" align="left" width="48" height="48"hspace="10"> Comment by anders-sandholm

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

from args.