Issue 4908 - Updated several dsconf --help entries (typos, wrong desc…

…riptions, etc.)

Description:
The --help of dsconf and its subcommands contain several incorrect descriptions, typos, inconsistent language, some entries end with a ".", some doesn't, some descriptions start with lowercase, ...

For a better user experience, the descriptions of subcommands, and parameters should be reviewed and improved.

Fixes: #4908

Reviewed by: Mark Reynolds, William Brown, and Simon Pichugin

src/lib389/cli/dsconf

@@ -37,7 +37,7 @@ from lib389.cli_base import format_error_to_dict
 
 parser = argparse.ArgumentParser(allow_abbrev=True)
 parser.add_argument('instance',
-        help="The instance name OR the LDAP url to connect to, IE localhost, ldap://mai.example.com:389",
+        help="The name of the instance or its LDAP URL, such as ldap://server.example.com:389",
     )
 parser.add_argument('-v', '--verbose',
         help="Display verbose operation tracing during command execution",
@@ -48,19 +48,19 @@ parser.add_argument('-D', '--binddn',
         default=None
     )
 parser.add_argument('-w', '--bindpw',
-        help="Password for binddn",
+        help="Password for the bind DN",
         default=None
     )
 parser.add_argument('-W', '--prompt',
         action='store_true', default=False,
-        help="Prompt for password for the bind DN"
+        help="Prompt for password of the bind DN"
     )
 parser.add_argument('-y', '--pwdfile',
-        help="Specifies a file containing the password for the binddn",
+        help="Specifies a file containing the password of the bind DN",
         default=None
     )
 parser.add_argument('-b', '--basedn',
-        help="Basedn (root naming context) of the instance to manage",
+        help="Base DN (root naming context) of the instance to manage",
         default=None
     )
 parser.add_argument('-Z', '--starttls',

src/lib389/cli/dsidm

@@ -32,10 +32,10 @@ from lib389.cli_base import format_error_to_dict
 parser = argparse.ArgumentParser(allow_abbrev=True)
 # First, add the LDAP options
 parser.add_argument('instance',
-        help="The instance name OR the LDAP url to connect to, IE localhost, ldap://mai.example.com:389",
+        help="The name of the instance or its LDAP URL, such as ldap://server.example.com:389",
     )
 parser.add_argument('-b', '--basedn',
-        help="Basedn (root naming context) of the instance to manage",
+        help="Base DN (root naming context) of the instance to manage",
         default=None
     )
 parser.add_argument('-v', '--verbose',
@@ -47,15 +47,15 @@ parser.add_argument('-D', '--binddn',
         default=None
     )
 parser.add_argument('-w', '--bindpw',
-        help="Password for binddn",
+        help="Password for the bind DN",
         default=None
     )
 parser.add_argument('-W', '--prompt',
         action='store_true', default=False,
-        help="Prompt for password for binddn"
+        help="Prompt for password of the bind DN"
     )
 parser.add_argument('-y', '--pwdfile',
-        help="Specifies a file containing the password for the bind DN",
+        help="Specifies a file containing the password of the bind DN",
         default=None
     )
 parser.add_argument('-Z', '--starttls',

src/lib389/lib389/cli_conf/__init__.py

@@ -136,16 +136,16 @@ def generic_status(inst, basedn, log, args):
 
 
 def add_generic_plugin_parsers(subparser, plugin_cls):
-    show_parser = subparser.add_parser('show', help='display plugin configuration')
+    show_parser = subparser.add_parser('show', help='Displays the plugin configuration')
     show_parser.set_defaults(func=generic_show, plugin_cls=plugin_cls)
 
-    enable_parser = subparser.add_parser('enable', help='enable plugin')
+    enable_parser = subparser.add_parser('enable', help='Enables the plugin')
     enable_parser.set_defaults(func=generic_enable, plugin_cls=plugin_cls)
 
-    disable_parser = subparser.add_parser('disable', help='disable plugin')
+    disable_parser = subparser.add_parser('disable', help='Disables the plugin')
     disable_parser.set_defaults(func=generic_disable, plugin_cls=plugin_cls)
 
-    status_parser = subparser.add_parser('status', help='display plugin status')
+    status_parser = subparser.add_parser('status', help='Displays the plugin status')
     status_parser.set_defaults(func=generic_status, plugin_cls=plugin_cls)
 
 

src/lib389/lib389/cli_conf/backup.py

@@ -42,14 +42,14 @@ def create_parser(subparsers):
     create_parser = subcommands.add_parser('create', help="Creates a backup of the database")
     create_parser.set_defaults(func=backup_create)
     create_parser.add_argument('archive', nargs='?', default=None,
-                               help="The directory where the backup files will be stored."
-                                    "The /var/lib/dirsrv/slapd-instance/bak directory is used by default."
-                                    "The backup file is named according to the year-month-day-hour format.")
+                               help="Sets the directory where to store the backup files. "
+                                    "Format: instance_name-year_month_date_hour_minutes_seconds. "
+                                    "Default: /var/lib/dirsrv/slapd-instance/bak/ ")
     create_parser.add_argument('-t', '--db-type', default="ldbm database",
-                               help="Database type (default: ldbm database).")
+                               help="Sets the database type. Default: ldbm database")
 
     restore_parser = subcommands.add_parser('restore', help="Restores a database from a backup")
     restore_parser.set_defaults(func=backup_restore)
-    restore_parser.add_argument('archive', help="The directory of the backup files.")
+    restore_parser.add_argument('archive', help="Set the directory that contains the backup files")
     restore_parser.add_argument('-t', '--db-type', default="ldbm database",
-                                help="Database type (default: ldbm database).")
+                                help="Sets the database type. Default: ldbm database")

src/lib389/lib389/cli_conf/chaining.py

@@ -211,78 +211,78 @@ def list_links(inst, basedn, log, args):
 
 
 def create_parser(subparsers):
-    chaining_parser = subparsers.add_parser('chaining', help="Manage database chaining/database links")
+    chaining_parser = subparsers.add_parser('chaining', help="Manage database chaining and database links")
     subcommands = chaining_parser.add_subparsers(help="action")
 
-    config_get_parser = subcommands.add_parser('config-get', help='Get the chaining controls and server component lists')
+    config_get_parser = subcommands.add_parser('config-get', help='Display the chaining controls and server component lists')
     config_get_parser.set_defaults(func=config_get)
-    config_get_parser.add_argument('--avail-controls', action='store_true', help="List available controls for chaining")
-    config_get_parser.add_argument('--avail-comps', action='store_true', help="List available plugin components for chaining")
+    config_get_parser.add_argument('--avail-controls', action='store_true', help="Lists available chaining controls")
+    config_get_parser.add_argument('--avail-comps', action='store_true', help="Lists available chaining plugin components")
 
     config_set_parser = subcommands.add_parser('config-set', help='Set the chaining controls and server component lists')
     config_set_parser.set_defaults(func=config_set)
-    config_set_parser.add_argument('--add-control', action='append', help="Add a transmitted control OID")
-    config_set_parser.add_argument('--del-control', action='append', help="Delete a transmitted control OID")
-    config_set_parser.add_argument('--add-comp', action='append', help="Add a chaining component")
-    config_set_parser.add_argument('--del-comp', action='append', help="Delete a chaining component")
+    config_set_parser.add_argument('--add-control', action='append', help="Adds a transmitted control OID")
+    config_set_parser.add_argument('--del-control', action='append', help="Deletes a transmitted control OID")
+    config_set_parser.add_argument('--add-comp', action='append', help="Adds a chaining component")
+    config_set_parser.add_argument('--del-comp', action='append', help="Deletes a chaining component")
 
-    def_config_get_parser = subcommands.add_parser('config-get-def', help='Get the default creation parameters for new database links')
+    def_config_get_parser = subcommands.add_parser('config-get-def', help='Display the default creation parameters for new database links')
     def_config_get_parser.set_defaults(func=def_config_get)
 
     def_config_set_parser = subcommands.add_parser('config-set-def', help='Set the default creation parameters for new database links')
     def_config_set_parser.set_defaults(func=def_config_set)
-    def_config_set_parser.add_argument('--conn-bind-limit', help="The maximum number of BIND connections the database link establishes with the remote server.")
-    def_config_set_parser.add_argument('--conn-op-limit', help="The maximum number of LDAP connections the database link establishes with the remote server. ")
-    def_config_set_parser.add_argument('--abandon-check-interval', help="The number of seconds that pass before the server checks for abandoned operations.")
-    def_config_set_parser.add_argument('--bind-limit', help="The maximum number of concurrent bind operations per TCP connection.")
-    def_config_set_parser.add_argument('--op-limit', help="The maximum number of concurrent operations allowed.")
+    def_config_set_parser.add_argument('--conn-bind-limit', help="Sets the maximum number of BIND connections the database link establishes with the remote server")
+    def_config_set_parser.add_argument('--conn-op-limit', help="Sets the maximum number of LDAP connections the database link establishes with the remote server ")
+    def_config_set_parser.add_argument('--abandon-check-interval', help="Sets the number of seconds that pass before the server checks for abandoned operations")
+    def_config_set_parser.add_argument('--bind-limit', help="Sets the maximum number of concurrent bind operations per TCP connection")
+    def_config_set_parser.add_argument('--op-limit', help="Sets the maximum number of concurrent operations allowed")
     def_config_set_parser.add_argument('--proxied-auth',
-        help="Set to \"off\" to disable proxied authorization, then binds for chained operations are executed as the user set in the nsMultiplexorBindDn attribute (on/off).")
-    def_config_set_parser.add_argument('--conn-lifetime', help="Specifies connection lifetime in seconds.  0 keeps connection open forever.")
-    def_config_set_parser.add_argument('--bind-timeout', help="The amount of time in seconds before a bind attempt times out.")
-    def_config_set_parser.add_argument('--return-ref', help="Sets whether referrals are returned by scoped searches (on/off).")
-    def_config_set_parser.add_argument('--check-aci', help="Set whether ACIs are evaluated on the database link as well as the remote data server (on/off).")
-    def_config_set_parser.add_argument('--bind-attempts', help="Sets the number of times the server tries to bind with the remote server.")
-    def_config_set_parser.add_argument('--size-limit', help="Sets the maximum number of entries to return from a search operation.")
-    def_config_set_parser.add_argument('--time-limit', help="Sets the maximum number of seconds allowed for an operation.")
+        help="Enables or disables proxied authorization. If set to \"off\", the server executes bind for chained operations as the user set in the nsMultiplexorBindDn attribute.")
+    def_config_set_parser.add_argument('--conn-lifetime', help="Specifies connection lifetime in seconds. \"0\" keeps the connection open forever.")
+    def_config_set_parser.add_argument('--bind-timeout', help="Sets the amount of time in seconds before a bind attempt times out")
+    def_config_set_parser.add_argument('--return-ref', help="Enables or disables whether referrals are returned by scoped searches")
+    def_config_set_parser.add_argument('--check-aci', help="Enables or disables whether the server evaluates ACIs on the database link as well as the remote data server")
+    def_config_set_parser.add_argument('--bind-attempts', help="Sets the number of times the server tries to bind to the remote server")
+    def_config_set_parser.add_argument('--size-limit', help="Sets the maximum number of entries to return from a search operation")
+    def_config_set_parser.add_argument('--time-limit', help="Sets the maximum number of seconds allowed for an operation")
     def_config_set_parser.add_argument('--hop-limit',
-        help="Sets the maximum number of times a database is allowed to chain; that is, the number of times a request can be forwarded from one database link to another.")
+        help="Sets the maximum number of times a database is allowed to chain. That is the number of times a request can be forwarded from one database link to another.")
     def_config_set_parser.add_argument('--response-delay',
-        help="The maximum amount of time it can take a remote server to respond to an LDAP operation request made by a database link before an error is suspected.")
-    def_config_set_parser.add_argument('--test-response-delay', help="Sets the duration of the test issued by the database link to check whether the remote server is responding.")
-    def_config_set_parser.add_argument('--use-starttls', help="Set to \"on\" specifies that the database links should use StartTLS for its secure connections.")
+        help="Sets the maximum amount of time it can take a remote server to respond to an LDAP operation request made by a database link before an error is suspected")
+    def_config_set_parser.add_argument('--test-response-delay', help="Sets the duration of the test issued by the database link to check whether the remote server is responding")
+    def_config_set_parser.add_argument('--use-starttls', help="Configured that database links use StartTLS if set to \"on\"")
 
     create_link_parser = subcommands.add_parser('link-create', add_help=False, conflict_handler='resolve', parents=[def_config_set_parser],
         help='Create a database link to a remote server')
     create_link_parser.set_defaults(func=create_link)
     create_link_parser.add_argument('CHAIN_NAME', nargs=1, help='The name of the database link')
-    create_link_parser.add_argument('--suffix', required=True, help="The suffix managed by the database link.")
-    create_link_parser.add_argument('--server-url', required=True, help="Gives the LDAP/LDAPS URL of the remote server.")
+    create_link_parser.add_argument('--suffix', required=True, help="Sets the suffix managed by the database link")
+    create_link_parser.add_argument('--server-url', required=True, help="Sets the LDAP/LDAPS URL to the remote server")
     create_link_parser.add_argument('--bind-mech', required=True,
-        help="Sets the authentication method to use to authenticate to the remote server: SIMPLE, EXTERNAL, DIGEST-MD5, or GSSAPI. Default if unset is SIMPLE.")
-    create_link_parser.add_argument('--bind-dn', required=True, help="DN of the administrative entry used to communicate with the remote server")
-    create_link_parser.add_argument('--bind-pw', required=True, help="Password for the administrative user.")
+        help="Sets the authentication method to use to authenticate to the remote server. Valid values: \"SIMPLE\" (default), \"EXTERNAL\", \"DIGEST-MD5\", or \"GSSAPI\"")
+    create_link_parser.add_argument('--bind-dn', required=True, help="Sets the DN of the administrative entry used to communicate with the remote server")
+    create_link_parser.add_argument('--bind-pw', required=True, help="Sets the password of the administrative user")
 
-    get_link_parser = subcommands.add_parser('link-get', help='get chaining database link')
+    get_link_parser = subcommands.add_parser('link-get', help='Displays chaining database links')
     get_link_parser.set_defaults(func=get_link)
-    get_link_parser.add_argument('CHAIN_NAME', nargs=1, help='The chaining link name, or suffix, to retrieve')
+    get_link_parser.add_argument('CHAIN_NAME', nargs=1, help='The chaining link name or suffix to retrieve')
 
     edit_link_parser = subcommands.add_parser('link-set', add_help=False, conflict_handler='resolve',
         parents=[def_config_set_parser], help='Edit a database link to a remote server')
     edit_link_parser.set_defaults(func=edit_link)
     edit_link_parser.add_argument('CHAIN_NAME', nargs=1, help='The name of the database link')
-    edit_link_parser.add_argument('--suffix', help="The suffix managed by the database link.")
-    edit_link_parser.add_argument('--server-url', help="Gives the LDAP/LDAPS URL of the remote server.")
+    edit_link_parser.add_argument('--suffix', help="Sets the suffix managed by the database link")
+    edit_link_parser.add_argument('--server-url', help="Sets the LDAP/LDAPS URL to the remote server")
     edit_link_parser.add_argument('--bind-mech',
-        help="Sets the authentication method to use to authenticate to the remote server: SIMPLE, EXTERNAL, DIGEST-MD5, or GSSAPI. Default if unset is SIMPLE.")
-    edit_link_parser.add_argument('--bind-dn', help="DN of the administrative entry used to communicate with the remote server")
-    edit_link_parser.add_argument('--bind-pw', help="Password for the administrative user.")
+        help="Sets the authentication method to use to authenticate to the remote server: Valid values: \"SIMPLE\" (default), \"EXTERNAL\", \"DIGEST-MD5\", or \"GSSAPI\"")
+    edit_link_parser.add_argument('--bind-dn', help="Sets the DN of the administrative entry used to communicate with the remote server")
+    edit_link_parser.add_argument('--bind-pw', help="Sets the password of the administrative user")
 
     delete_link_parser = subcommands.add_parser('link-delete', help='Delete a database link')
     delete_link_parser.set_defaults(func=delete_link)
     delete_link_parser.add_argument('CHAIN_NAME', nargs=1, help='The name of the database link')
 
-    monitor_link_parser = subcommands.add_parser('monitor', help='Get the monitor information for a database chaining link')
+    monitor_link_parser = subcommands.add_parser('monitor', help='Display monitor information for a database chaining link')
     monitor_link_parser.set_defaults(func=monitor_link)
     monitor_link_parser.add_argument('CHAIN_NAME', nargs=1, help='The name of the database link')
 

src/lib389/lib389/cli_conf/config.py

@@ -37,7 +37,7 @@ def config_del_attr(inst, basedn, log, args):
 
 
 def create_parser(subparsers):
-    config_parser = subparsers.add_parser('config', help="Manage server configuration")
+    config_parser = subparsers.add_parser('config', help="Manage the server configuration")
 
     subcommands = config_parser.add_subparsers(help="action")
 

src/lib389/lib389/cli_conf/conflicts.py

@@ -89,7 +89,7 @@ def create_parser(subparsers):
 
     # coinflict entry arguments
     list_parser = subcommands.add_parser('list', help="List conflict entries")
-    list_parser.add_argument('suffix', help='The backend name, or suffix, to look for conflict entries')
+    list_parser.add_argument('suffix', help='Sets the backend name, or suffix, to look for conflict entries')
     list_parser.set_defaults(func=list_conflicts)
 
     cmp_parser = subcommands.add_parser('compare', help="Compare the conflict entry with its valid counterpart")
@@ -109,7 +109,7 @@ def create_parser(subparsers):
                                                             "This requires that the converted conflict entry have "
                                                             "a new RDN value.  For example: \"cn=my_new_rdn_value\".")
     replace_parser.add_argument('DN', help='The DN of the conflict entry')
-    replace_parser.add_argument('--new-rdn', required=True, help="The new RDN for the converted conflict entry.  "
+    replace_parser.add_argument('--new-rdn', required=True, help="Sets the new RDN for the converted conflict entry.  "
                                                                  "For example: \"cn=my_new_rdn_value\"")
     replace_parser.set_defaults(func=convert_conflict)