12 Apr 2013, 21:44
Generic-user-small

Keith Schomburg (3 posts)

How do you prevent long_desc from merging lines together? I had a long description like the following:

long_desc """
This argument may have values of the form:

  * foo
  * foo.bar
  * http://foo.bar
"""

When displaying help the long description looks like the following:

  This argument may have values of the form:

  * foo * foo.bar * http://foo.bar

It appears as though long_desc uses a blank line to identify the start of a new paragraph. I don’t want to add a blank line after each list item as it unnecessarily lengthens the help output. Is there a way to add free formatted text such the the bullet list does not get merged into a single line?

15 Apr 2013, 13:45
Dmfcb_pragsmall

David Copeland (98 posts)

Recent versions of GLI can give you more flexibility here. There is a top-level command called @wrap_help_text@. The default is @:to_terminal@, which does what you are observing, but also word-wraps to the size of your terminal.

What you want is @:verbatim@, which will not touch the text at all:

wrap_help_text :verbatim

desc 'does stuff'
long_desc "This argument may have values of the form:

  * foo
  * foo.bar
  * http://foo.bar"
command :stuff do |c|
  # ...
end

(note that you don’t need the triple quotes - regular quotes will preserve newlines)

To get this, you’ll need the latest version of GLI. If you are using the 1.x version from the book, just read this: http://forums.pragprog.com/forums/200/topics/10975 and make the small change noted there.

Also, I try to keep the rdoc up to date, so check it out: http://davetron5000.github.io/gli/rdoc/index.html the @DSL@ and @App@ modules document most of the interesting bits.

15 Apr 2013, 14:22
Generic-user-small

Keith Schomburg (3 posts)

Thanks David. I will give that a try.

A suggestion that may give a nice combination of :to_terminal and :verbatim would be to leave lines that begin with white space alone and merge other text as is presently done.

15 Apr 2013, 14:45
Generic-user-small

Keith Schomburg (3 posts)

So it seems like this is an all or nothing option in that you have to call wrap_help_text before the first call to desc and it will be in effect for all command descriptions.

I initially tried calling it just before the desc of the command I wanted to use the :verbatim on thinking it would just apply to the formatting of the following description but that didn’t work.

It would be nice to be able to specify the formatting option on a per command basis.

15 Apr 2013, 18:22
Dmfcb_pragsmall

David Copeland (98 posts)

Yeah, these features were added at another user’s request and I actually hadn’t considered such elaborate in-line documentation formatting.

If you’re feeling adventurous, it might not be too hard to implement what you are thinking about.

https://github.com/davetron5000/gli/blob/gli-2/lib/gli/commands/help.rb#L23 is how GLI determines what code to use to wrap lines.

https://github.com/davetron5000/gli/blob/gli-2/lib/gli/commands/help_modules/text_wrapper.rb is how the @:to_terminal@ wrapper is implemented.

I created https://github.com/davetron5000/gli/issues/141 to look into this.

  You must be logged in to comment