Indentation-sensitive usage?

[keleshev]

I have seen at least 3 times people (including me :-) made the mistake of not putting newline after usage:

    @command
    def do_bar(self, arg, arguments):
        """Usage:
              bar -f FILE
              bar FILE
              bar list
         Arguments:
               FILE   a file name
         Options:
               -f      specify the file
         """

(from http://futuregrid.github.com/cmd3/manual.html#argument-parsing)

Maybe we should do something about it? Either:

• emphasise it more in documentation, or
• make usage indentation-sensitive (which is actually how POSIX does that).

Opinions? @docopt

[ghost]

If POSIX defines usage as indentation-sensitive then we should do that too, provided it doesn't complicate the implementation overmuch.

[keleshev]

Then, maybe, require to have usage:, options: and in future arguments: sections, which will be indentation-sensitive? That might make it easier to document docopt format (we can call these things "usage-section", "options-section", instead of "usage-pattern", "options' description").

[keleshev]

This is now in master, however I'm still not 100% sure: it seems like a good idea, but it will brake a lot of code.

As per new implementation there are 2 kinds of sections: usage-sections, and options-sections. They both are parsed in the same way:

• "options:" or "usage:" (case-insensitive) are the start of the section,
• empty line terminates a section (as previously),
• a string with no indentation ends a section.

This makes the following things valid (from new testcases):

r"""Usage: prog [options]

global options: --foo
local options: --baz
               --bar
other OPTIONS:
 --egg
 --spam
-not-an-option-

"""

[shabbyrobe]

This has broken printing usage on exit since the following line was removed:

    DocoptExit.usage = printable_usage(doc)

[keleshev]

Oh, thanks for noticing. Too bad we don't have any tests that capture stdin/stdout right now.

[fsaintjacques]

I prefer having indentation sensitive, as it will forces a certain standard across docopt strings.

[keleshev]

In current master the regex for "section" is:

re.compile('^([^\n]*' + section_name + '[^\n]*\n?(?:[ \t].*?(?:\n|$))*)', re.IGNORECASE | re.MULTILINE)

Which is not final, and maybe someone can comment on it or propose a different one. This one will match as long as there is some indentation (at least one space or one tab): ([ \t].*?(\n|$))*. Maybe it should require exact indentation instead? Say, 4 spaces? Or maybe it should require consistent indentation (same in a single section)?

[keleshev]

I'm actually very unhappy with this regexp. It makes even harder to describe docopt formally (using some grammar). Also harder to explain. I'm still sure that "sections" is a good feature, I'm just not sure how to implement them. I need to think more about it.

This will delay 0.7.0 release. Sorry @shabbyrobe for breaking your plans with releasing PHP 0.7.0 again :-(

[shabbyrobe]

Hehehe, it's all good, there's a develop branch in there, and the "everything in one file" is making it super easy for me to drop it in to projects as needed. I reckon it's better to take your time and get it right. I'm in no hurry 😃