tahoe-lafs/trac

Mention 'tahoe run' in running.html, and improve tahoe --help text #856

New issue

Closed

opened 2009-12-13 05:32:08 +00:00 by daira · 15 comments

daira commented

2009-12-13 05:32:08 +00:00

From #355:

I guess you missed the existence of tahoe run because it isn't mentioned in source:docs/running.html. Perhaps we should change that document to describe tahoe run instead of tahoe start? (That document is intended for the beginner, who might prefer the simplicity of tahoe run.)

Something else that might help is if the output of tahoe --help separated node control (start, stop, restart, run, create-client, create-introducer) from filesystem usage (put, get, rm, etc.)

These seem like good doc improvements to me. They're independent of the other problems with tahoe run in #355.

From #355: > I guess you missed the existence of `tahoe run` because it isn't mentioned in source:docs/running.html. Perhaps we should change that document to describe `tahoe run` instead of `tahoe start`? (That document is intended for the beginner, who might prefer the simplicity of `tahoe run`.) > Something else that might help is if the output of `tahoe --help` separated node control (`start`, `stop`, `restart`, `run`, `create-client`, `create-introducer`) from filesystem usage (`put`, `get`, `rm`, etc.) These seem like good doc improvements to me. They're independent of the other problems with `tahoe run` in #355.

daira added the

labels 2009-12-13 05:32:08 +00:00

daira added this to the 1.6.0 milestone 2009-12-13 05:32:08 +00:00

daira self-assigned this 2009-12-20 01:10:57 +00:00

warner commented

2010-01-09 03:08:41 +00:00

FYI, I don't think there's a way to override the alphabetical sorting of subcommands in twisted.python.usage.Option's base-class code which generates the output that "bin/tahoe" (without a subcommand) provokes. But if you override the "getUsage" method on allmydata.scripts.runner.Options (using allmydata.scripts.cli.GetOptions.getUsage as a template), you can probably replace the command listing with different text. This might be a good place to emit something else, like:

Commands for node admin:
   create-client       Create a client node.
   create-introducer   ...
   create-key-generator
   create-stats-gatherer
   start
   stop
   restart
   run
Commands for filesystem manipulation:
   mkdir
   ls
   cp
   ...

FYI, I don't think there's a way to override the alphabetical sorting of subcommands in `twisted.python.usage.Option`'s base-class code which generates the output that "bin/tahoe" (without a subcommand) provokes. But if you override the "getUsage" method on `allmydata.scripts.runner.Options` (using `allmydata.scripts.cli.GetOptions.getUsage` as a template), you can probably replace the command listing with different text. This might be a good place to emit something else, like: ``` Commands for node admin: create-client Create a client node. create-introducer ... create-key-generator create-stats-gatherer start stop restart run Commands for filesystem manipulation: mkdir ls cp ... ```

warner commented

2010-01-09 03:29:12 +00:00

Oh, one correction, usage.Option doesn't just sort its subcommands alphabetically: it retains the order in which they were provided (notice that bin/tahoe's output puts all the create-node commands at the start, and all the start/stop commands at the end.. this matches the way that _general_commands and subCommands are built in src/allmydata/scripts/runner.py).

That probably doesn't help insert extra text into the usage output, though.. you'll probably still have to override getUsage. But consider upcalling and then inserting text into the result (instead of writing something entirely new), because doing it that way will be more robust against the addition of new subcommands in the future.

Oh, one correction, usage.Option doesn't just sort its subcommands alphabetically: it retains the order in which they were provided (notice that `bin/tahoe`'s output puts all the create-node commands at the start, and all the start/stop commands at the end.. this matches the way that `_general_commands` and `subCommands` are built in src/allmydata/scripts/runner.py). That probably doesn't help insert extra text into the usage output, though.. you'll probably still have to override getUsage. But consider upcalling and then inserting text into the result (instead of writing something entirely new), because doing it that way will be more robust against the addition of new subcommands in the future.

daira commented

2010-01-09 23:50:48 +00:00

Author

Attachment running.html_diff.txt (2280 bytes) added

Diff for source:docs/running.html to describe tahoe run

**Attachment** running.html_diff.txt (2280 bytes) added Diff for source:docs/running.html to describe tahoe run

running.html_diff.txt

2.2 KiB

daira commented

2010-01-10 02:10:38 +00:00

Author

New help text:

$ tahoe
Usage:  tahoe <command> [command options]
Options:
  -q, --quiet             Operate silently.
  -V, --version           Display version numbers and exit.
      --version-and-path  Display version numbers and paths to their locations
                          and exit.
      --help              Display this help and exit.
Commands:

Node adminstration
    create-client              Create a client node.
    create-introducer          Create a introducer node.
    create-key-generator       Create a key generator service.
    create-stats-gatherer      Create a stats-gatherer service.

Using the filesystem
    mkdir                      Create a new directory
    add-alias                  Add a new alias cap
    create-alias               Create a new alias cap
    list-aliases               List all alias caps
    ls                         List a directory
    get                        Retrieve a file from the virtual drive.
    put                        Upload a file into the virtual drive.
    cp                         Copy one or more files.
    rm                         Unlink a file or directory in the virtual drive.
    mv                         Move a file within the virtual drive.
    ln                         Make an additional link to an existing file.
    backup                     Make target dir look like local dir.
    webopen                    Open a webbrowser to the root_dir
    manifest                   List all files/dirs in a subtree
    stats                      Print statistics about all files/dirs in a
                               subtree
    check                      Check a single file or directory
    deep-check                 Check all files/directories reachable from a
                               starting point

Debugging
    debug                      debug subcommands: use 'tahoe debug' for a list

Controlling a node
    start                      Start a node (of any type).
    stop                       Stop a node.
    restart                    Restart a node.
    run                        Run a node synchronously.

c:\Python26\Scripts\tahoe-script.py:  must specify a command

New help text: ``` $ tahoe Usage: tahoe <command> [command options] Options: -q, --quiet Operate silently. -V, --version Display version numbers and exit. --version-and-path Display version numbers and paths to their locations and exit. --help Display this help and exit. Commands: Node adminstration create-client Create a client node. create-introducer Create a introducer node. create-key-generator Create a key generator service. create-stats-gatherer Create a stats-gatherer service. Using the filesystem mkdir Create a new directory add-alias Add a new alias cap create-alias Create a new alias cap list-aliases List all alias caps ls List a directory get Retrieve a file from the virtual drive. put Upload a file into the virtual drive. cp Copy one or more files. rm Unlink a file or directory in the virtual drive. mv Move a file within the virtual drive. ln Make an additional link to an existing file. backup Make target dir look like local dir. webopen Open a webbrowser to the root_dir manifest List all files/dirs in a subtree stats Print statistics about all files/dirs in a subtree check Check a single file or directory deep-check Check all files/directories reachable from a starting point Debugging debug debug subcommands: use 'tahoe debug' for a list Controlling a node start Start a node (of any type). stop Stop a node. restart Restart a node. run Run a node synchronously. c:\Python26\Scripts\tahoe-script.py: must specify a command ```

daira commented

2010-01-10 03:03:45 +00:00

Author

Rearranging the command groups and adding some text about tahoe <command> --help at the bottom:

$ tahoe --help
Usage:  tahoe <command> [command options]
Options:
  -q, --quiet             Operate silently.
  -V, --version           Display version numbers and exit.
      --version-and-path  Display version numbers and paths to their locations
                          and exit.
      --help              Display this help and exit.
Commands:

Administration
    create-client              Create a client node.
    create-introducer          Create a introducer node.
    create-key-generator       Create a key generator service.
    create-stats-gatherer      Create a stats-gatherer service.

Controlling a node
    start                      Start a node (of any type).
    stop                       Stop a node.
    restart                    Restart a node.
    run                        Run a node synchronously.

Debugging
    debug                      debug subcommands: use 'tahoe debug' for a list

Using the filesystem
    mkdir                      Create a new directory
    add-alias                  Add a new alias cap
    create-alias               Create a new alias cap
    list-aliases               List all alias caps
    ls                         List a directory
    get                        Retrieve a file from the virtual drive.
    put                        Upload a file into the virtual drive.
    cp                         Copy one or more files.
    rm                         Unlink a file or directory in the virtual drive.
    mv                         Move a file within the virtual drive.
    ln                         Make an additional link to an existing file.
    backup                     Make target dir look like local dir.
    webopen                    Open a webbrowser to the root_dir
    manifest                   List all files/dirs in a subtree
    stats                      Print statistics about all files/dirs in a
                               subtree
    check                      Check a single file or directory
    deep-check                 Check all files/directories reachable from a
                               starting point

Please run 'tahoe <command> --help' for more details on each command.

Rearranging the command groups and adding some text about `tahoe <command> --help` at the bottom: ``` $ tahoe --help Usage: tahoe <command> [command options] Options: -q, --quiet Operate silently. -V, --version Display version numbers and exit. --version-and-path Display version numbers and paths to their locations and exit. --help Display this help and exit. Commands: Administration create-client Create a client node. create-introducer Create a introducer node. create-key-generator Create a key generator service. create-stats-gatherer Create a stats-gatherer service. Controlling a node start Start a node (of any type). stop Stop a node. restart Restart a node. run Run a node synchronously. Debugging debug debug subcommands: use 'tahoe debug' for a list Using the filesystem mkdir Create a new directory add-alias Add a new alias cap create-alias Create a new alias cap list-aliases List all alias caps ls List a directory get Retrieve a file from the virtual drive. put Upload a file into the virtual drive. cp Copy one or more files. rm Unlink a file or directory in the virtual drive. mv Move a file within the virtual drive. ln Make an additional link to an existing file. backup Make target dir look like local dir. webopen Open a webbrowser to the root_dir manifest List all files/dirs in a subtree stats Print statistics about all files/dirs in a subtree check Check a single file or directory deep-check Check all files/directories reachable from a starting point Please run 'tahoe <command> --help' for more details on each command. ```

warner commented

2010-01-10 08:41:05 +00:00

wow, that's awesome, in a kinda scary way :). I'd sort of suggest using a try:finally: clause to make sure that self.subCommands gets set back to its original value even if an exception is raised in the middle, but that code is only going to get invoked after subCommands is used and just before the whole process exits, so it probably isn't too important.

Please double-check that the trick you're using will work against our oldest supported version of Twisted (which is.. aagh! zooko! well, it used to be in README, and then in INSTALL, and now I can't find it in the docs/ directory. So first harass Zooko to ressurect our human-readable dependency list, then check it for the oldest version of Twisted that we claim compatibility with, and then check that version of Twisted :). I believe usage.Options has remained unchanged for years, so I expect your trick to work everywhere, but it'd be good to make sure.

wow, that's awesome, in a kinda scary way :). I'd sort of suggest using a try:finally: clause to make sure that `self.subCommands` gets set back to its original value even if an exception is raised in the middle, but that code is only going to get invoked after subCommands is used and just before the whole process exits, so it probably isn't too important. Please double-check that the trick you're using will work against our oldest supported version of Twisted (which is.. aagh! zooko! well, it used to be in README, and then in INSTALL, and now I can't find it in the docs/ directory. So first harass Zooko to ressurect our human-readable dependency list, then check it for the oldest version of Twisted that we claim compatibility with, and then check that version of Twisted :). I believe usage.Options has remained unchanged for years, so I expect your trick to work everywhere, but it'd be good to make sure.

zooko commented

2010-01-10 18:30:31 +00:00

Our "human-readable" dependency list is in source:_auto_deps.py, and it says "Twisted >= 2.4.0". If David-Sarah's hack doesn't work with Twisted 2.4.0 we should consider raising the minimum version requirement. Currently on our Supported builders the oldest version of Twisted in use is Twisted 8.1.0 (in Debian 5.0 Lenny and in NetBSD 4). If David-Sarah's hack works for all versions of Twisted > X for some X <= 8.1.0 then I would support it.

Our "human-readable" dependency list is in source:_auto_deps.py, and it says `"Twisted >= 2.4.0"`. If David-Sarah's hack doesn't work with Twisted 2.4.0 we should consider raising the minimum version requirement. Currently on our Supported builders the oldest version of Twisted in use is Twisted 8.1.0 (in Debian 5.0 Lenny and in NetBSD 4). If David-Sarah's hack works for all versions of Twisted > X for some X <= 8.1.0 then I would support it.

warner commented

2010-01-10 20:57:26 +00:00

ok, I think we need a pointer to it from some other human-readable document, like the way that most projects have a README or an INSTALL which tells you what the dependencies are (grep auto_deps README docs/* shows nothing). I know that you've tried hard to not frighten people with such details, but I think they need to be findable by the people who want them.

But anyways, I don't see any changes to twisted.python.usage between 2.4.0 and current trunk (which is 9.0.0+), so I think David-Sarah's hack should work equally well across that range.

ok, I think we need a pointer to it from some other human-readable document, like the way that most projects have a README or an INSTALL which tells you what the dependencies are (`grep auto_deps README docs/*` shows nothing). I know that you've tried hard to not frighten people with such details, but I think they need to be findable by the people who want them. But anyways, I don't see any changes to twisted.python.usage between 2.4.0 and current trunk (which is 9.0.0+), so I think David-Sarah's hack should work equally well across that range.

daira commented

2010-01-10 21:04:06 +00:00

Author

Looking at the source for Twisted's usage.py, this hack should work going back to revision 7653 in July 2003, which introduced the getUsage method. We depend on getUsage elsewhere, e.g. in cli.py. That would have been way before Twisted 2.4.0, which was released in 2006.

I agree about the try: finally:.

Looking at the source for Twisted's `usage.py`, this hack *should* work going back to [revision 7653](http://twistedmatrix.com/trac/browser/trunk/twisted/python/usage.py?rev=7653) in July 2003, which introduced the `getUsage` method. We depend on `getUsage` elsewhere, e.g. in `cli.py`. That would have been way before Twisted 2.4.0, which was released in 2006. I agree about the `try: finally:`.

daira commented

2010-01-11 05:23:20 +00:00

Author

Attachment runner.py_diff.txt (2010 bytes) added

Diff for source:src/allmydata/scripts/runner.py to split usage into groups (better approach)

**Attachment** runner.py_diff.txt (2010 bytes) added Diff for source:src/allmydata/scripts/runner.py to split usage into groups (better approach)

runner.py_diff.txt

2 KiB

daira commented

2010-01-12 04:38:04 +00:00

Author

Replying to warner:

wow, that's awesome, in a kinda scary way :). I'd sort of suggest using a try:finally: clause to make sure that self.subCommands gets set back to its original value even if an exception is raised in the middle, [...]

I changed it to use another class so that self.subCommands doesn't need to be modified in the Options instance.

Replying to [warner](/tahoe-lafs/trac/issues/856#issuecomment-374779): > wow, that's awesome, in a kinda scary way :). I'd sort of suggest using a try:finally: clause to make sure that `self.subCommands` gets set back to its original value even if an exception is raised in the middle, [...] I changed it to use another class so that `self.subCommands` doesn't need to be modified in the `Options` instance.

daira commented

2010-01-12 04:46:53 +00:00

Author

Attachment tahoe-help-group-commands.darcspatch.txt (36634 bytes) added

Split tahoe --help options into groups

**Attachment** tahoe-help-group-commands.darcspatch.txt (36634 bytes) added Split tahoe --help options into groups

tahoe-help-group-commands.darcspatch.txt

36 KiB

daira commented

2010-01-12 04:50:55 +00:00

Author

Attachment change-running-html-to-describe-tahoe-run.darcspatch.txt (36458 bytes) added

Change running.html to describe 'tahoe run'

**Attachment** change-running-html-to-describe-tahoe-run.darcspatch.txt (36458 bytes) added Change running.html to describe 'tahoe run'

change-running-html-to-describe-tahoe-run.darcspatch.txt

36 KiB

daira commented

2010-01-24 21:55:07 +00:00

Author

The command grouping is a very simple patch, and I think it does help make the tahoe --help text more readable. Anyone want to review it for 1.6?

The command grouping is a very simple patch, and I think it does help make the `tahoe --help text` more readable. Anyone want to review it for 1.6?

zooko commented

2010-01-26 04:56:29 +00:00

Thank you! I really like the command grouping! Applied as changeset:b94b9af1896ec527, changeset:b079f32da2aa0746, changeset:a1444d9367554df7, and changeset:5c04fd689ab4b3bf.