Indentation-sensitive usage? #102

Open
keleshev opened this Issue Mar 21, 2013 · 9 comments

Comments

Projects
None yet
3 participants
Owner

keleshev commented Mar 21, 2013

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

ghost commented Mar 23, 2013

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

Owner

keleshev commented Mar 23, 2013

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").

Owner

keleshev commented Mar 24, 2013

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-

"""
Member

shabbyrobe commented Apr 3, 2013

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

    DocoptExit.usage = printable_usage(doc)
Owner

keleshev commented Apr 3, 2013

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

@keleshev keleshev pushed a commit that referenced this issue Apr 3, 2013

Vladimir Keleshev Fix printing usage on exit (see #102) 10c1b39

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

Owner

keleshev commented Apr 8, 2013

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)?

Owner

keleshev commented Apr 17, 2013

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 :-(

Member

shabbyrobe commented Apr 18, 2013

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 😃

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment