diff --git a/commands/core/core.drush.inc b/commands/core/core.drush.inc index 05276c3..f78ab3c 100644 --- a/commands/core/core.drush.inc +++ b/commands/core/core.drush.inc @@ -26,7 +26,11 @@ function core_drush_command() { 'bootstrap' => DRUSH_BOOTSTRAP_DRUSH, // No bootstrap. 'options' => array( 'sort' => 'Sort commands in alphabetical order. drush waits for full bootstrap before printing any commands when this option is used.', - 'filter' => 'Restrict command list to those commands defined in the specified file.', + 'filter' => array( + 'description' => 'Restrict command list to those commands defined in the specified file. Omit value to choose from a list of names.', + 'example-value' => 'category', + 'value' => 'optional', + ), 'html' => 'Print help for all commands in HTML format.', 'pipe' => 'A list of available commands, one per line.', ), @@ -105,7 +109,11 @@ function core_drush_command() { 'drush core-requirements --pipe' => 'Print out a short report in the format "identifier: severity", where severity 2=error, 1=warning, and 0/-1=OK', ), 'options' => array( - 'severity' => 'Only show status report messages with a severity greater than or equal to the specified value.', + 'severity' => array( + 'description' => 'Only show status report messages with a severity greater than or equal to the specified value.', + 'value' => 'required', + 'example-value' => '3', + ), 'ignore' => 'Comma-separated list of requirements to remove from output. Run with --pipe to see key values to use.', ), ); @@ -204,7 +212,11 @@ function core_drush_command() { 'clean-url'=> 'Defaults to 1', 'site-name' => 'Defaults to Site-Install', 'site-mail' => 'From: for system mailings. Defaults to admin@example.com', - 'sites-subdir' => "Name of directory under 'sites' which should be created. Only needed when the subdirectory does not already exist. Defaults to 'default'", + 'sites-subdir' => array( + 'description' => "Name of directory under 'sites' which should be created. Only needed when the subdirectory does not already exist. Defaults to 'default'", + 'value' => 'required', + 'example-value' => 'directory_name', + ), ), 'examples' => array( 'drush site-install expert --locale=uk' => '(Re)install using the expert install profile. Set default language to Ukranian.', @@ -531,7 +543,7 @@ function _core_site_status_table($project = '', $full = FALSE) { $status_table['Drush alias files'] = dt("There are !count alias files. Run with --full to see the full list.", array('!count' => count($alias_files))); } } - + // None of the Status keys are in dt(); this helps with machine-parsing of status? $path_names['root'] = 'Drupal root'; $path_names['site'] = 'Site path'; diff --git a/commands/core/help.drush.inc b/commands/core/help.drush.inc index 9083882..f5a5813 100644 --- a/commands/core/help.drush.inc +++ b/commands/core/help.drush.inc @@ -193,10 +193,18 @@ function drush_help_section_formatter_options($command, &$help_attributes) { if (array_key_exists('required', $help_attributes)) { $help_attributes['description'] .= " " . dt("Required."); } + + $prefix = '<'; + $suffix = '>'; if (array_key_exists('example-value', $help_attributes)) { - $help_attributes['label'] .= '=' . $help_attributes['example-value']; + if (isset($help_attributes['value']) && $help_attributes['value'] == 'optional') { + $prefix = '['; + $suffix = ']'; + } + $help_attributes['label'] .= '=' . $prefix . $help_attributes['example-value'] . $suffix; + if (array_key_exists('short-form', $help_attributes)) { - $help_attributes['short-form'] .= ' ' . $help_attributes['example-value']; + $help_attributes['short-form'] .= " $prefix" . $help_attributes['example-value'] . $suffix; } } if (array_key_exists('short-form', $help_attributes)) { diff --git a/docs/commands.html b/docs/commands.html index 1811b8b..c7796aa 100644 --- a/docs/commands.html +++ b/docs/commands.html @@ -147,7 +147,9 @@ are shown below. diff --git a/includes/drush.inc b/includes/drush.inc index f3cd4bf..43b220f 100644 --- a/includes/drush.inc +++ b/includes/drush.inc @@ -371,7 +371,7 @@ function _convert_csv_to_array($args) { * - description: The help text for this item. displayed by `drush help`. */ function drush_get_global_options($brief = FALSE) { - $options['root'] = array('short-form' => 'r', 'short-has-arg' => TRUE, 'never-post' => TRUE, 'description' => "Drupal root directory to use (default: current directory).", 'example-value' => ''); + $options['root'] = array('short-form' => 'r', 'short-has-arg' => TRUE, 'never-post' => TRUE, 'description' => "Drupal root directory to use (default: current directory).", 'example-value' => 'path'); $options['uri'] = array('short-form' => 'l', 'short-has-arg' => TRUE, 'never-post' => TRUE, 'description' => 'URI of the drupal site to use (only needed in multisite environments or when running on an alternate port).', 'example-value' => 'http://example.com:8888'); $options['verbose'] = array('short-form' => 'v', 'context' => 'DRUSH_VERBOSE', 'description' => 'Display extra information about the command.'); $options['debug'] = array('short-form' => 'd', 'context' => 'DRUSH_DEBUG', 'description' => 'Display even more information, including internal messages.'); @@ -381,19 +381,19 @@ function drush_get_global_options($brief = FALSE) { $options['pipe'] = array('short-form' => 'p', 'description' => "Emit a compact representation of the command for scripting."); $options['help'] = array('short-form' => 'h', 'description' => "This help system."); $options['version'] = array('description' => "Show drush version."); - $options['php'] = array('description' => "The absolute path to your PHP intepreter, if not 'php' in the path."); + $options['php'] = array('description' => "The absolute path to your PHP intepreter, if not 'php' in the path.", 'example-value' => '/path/to/file'); $options['interactive'] = array('short-form' => 'ia', 'description' => "Force interactive mode for commands run on multiple targets (e.g. `drush @site1,@site2 cc --ia`)."); if (!$brief) { $options['quiet'] = array('short-form' => 'q', 'description' => 'Suppress non-error messages.'); - $options['include'] = array('short-form' => 'i', 'short-has-arg' => TRUE, 'context' => 'DRUSH_INCLUDE', 'local-context-only' => TRUE, 'never-post' => TRUE, 'propagate-cli-value' => TRUE, 'merge-pathlist' => TRUE, 'description' => "A list of additional directory paths to search for drush commands."); + $options['include'] = array('short-form' => 'i', 'short-has-arg' => TRUE, 'context' => 'DRUSH_INCLUDE', 'local-context-only' => TRUE, 'never-post' => TRUE, 'propagate-cli-value' => TRUE, 'merge-pathlist' => TRUE, 'description' => "A list of additional directory paths to search for drush commands.", 'example-value' => '/path/to/directory'); $options['config'] = array('short-form' => 'c', 'short-has-arg' => TRUE, 'context' => 'DRUSH_CONFIG', 'local-context-only' => TRUE, 'merge-pathlist' => TRUE, 'description' => "Specify an additional config file to load. See example.drushrc.php."); - $options['user'] = array('short-form' => 'u', 'short-has-arg' => TRUE, 'propagate-cli-value' => TRUE, 'description' => "Specify a Drupal user to login with. May be a name or a number."); + $options['user'] = array('short-form' => 'u', 'short-has-arg' => TRUE, 'propagate-cli-value' => TRUE, 'description' => "Specify a Drupal user to login with. May be a name or a number.", 'example-value' => 'name_or_number'); $options['backend'] = array('short-form' => 'b', 'never-propagate' => TRUE, 'description' => "Hide all output and return structured data (internal use only)."); $options['invoke'] = array('hidden' => TRUE, 'description' => 'Invoked from a script; skip option verification.'); - $options['choice'] = array('description' => "Provide an answer to a multiple-choice prompt."); - $options['variables'] = array('description' => "Comma delimited list of name=value pairs. These values take precedence even over settings.php variable overrides."); - $options['search-depth'] = array('description' => "Control the depth that drush will search for alias files."); + $options['choice'] = array('description' => "Provide an answer to a multiple-choice prompt.", 'example-value' => 'number'); + $options['variables'] = array('description' => "Comma delimited list of name=value pairs. These values take precedence even over settings.php variable overrides.", 'example-value' => 'foo=bar,baz=yaz'); + $options['search-depth'] = array('description' => "Control the depth that drush will search for alias files.", 'example-value' => 'number'); $options['ignored-modules'] = array('description' => "Exclude some modules from consideration when searching for drush command files."); $options['no-label'] = array('description' => "Remove the site label that drush includes in multi-site command output(e.g. `drush @site1,@site2 status`)."); $options['nocolor'] = array('context' => 'DRUSH_NOCOLOR', 'propagate-cli-value' => TRUE, 'description' => "Suppress color highlighting on log messages.");