Re: 9.4 pg_restore --help changes

9.3 pg_restore --help output:

-I, --index=NAME restore named index
-n, --schema=NAME restore only objects in this schema
-P, --function=NAME(args) restore named function
-t, --table=NAME restore named table(s)
-T, --trigger=NAME restore named trigger
--section=SECTION restore named section (pre-data, data, or post-data)

9.4 pg_restore --help output:

-I, --index=NAME restore named indexes
-n, --schema=NAME restore only objects in these schemas
-P, --function=NAME(args) restore named functions
-t, --table=NAME restore named tables
-T, --trigger=NAME restore named triggers
--section=SECTION restore named sections (pre-data, data, or post-data)

This is a valuable feature change, but I think the help output is
unhelpful. The left side has a singular placeholder, but the right side
talks about objects in plural. How do I actually specify multiple
indexes? Is is --index=foo,bar? It's --index=foo --index=bar, but
that's unclear from the help.

I think it would be clearer to write something like

-I, --index=NAME restore named indexes (repeat for multiple)

or perhaps make a note at the bottom

The options -I, -n, -P, -t, -T, --section can be combined and
specified multiple times to select multiple objects.

Other ideas?

On Sat, Aug 9, 2014 at 10:44 AM, Peter Eisentraut <peter_e(at)gmx(dot)net> wrote:
> -I, --index=NAME restore named indexes (repeat for multiple)
A single --index entry restores only one index, so what about
something like that:
-I, --index=NAME restore named index (repeat for multiple entries)

> or perhaps make a note at the bottom
>
> The options -I, -n, -P, -t, -T, --section can be combined and
> specified multiple times to select multiple objects.
>
> Other ideas?
Specifying both to make it clearer to the user. The note at the bottom
is a good thing as well.
Regards,
--
Michael

Peter Eisentraut-2 wrote
> 9.3 pg_restore --help output:
>
> -I, --index=NAME restore named index
> -n, --schema=NAME restore only objects in this schema
> -P, --function=NAME(args) restore named function
> -t, --table=NAME restore named table(s)
> -T, --trigger=NAME restore named trigger
> --section=SECTION restore named section (pre-data, data, or
> post-data)
>
> 9.4 pg_restore --help output:
>
> -I, --index=NAME restore named indexes
> -n, --schema=NAME restore only objects in these schemas
> -P, --function=NAME(args) restore named functions
> -t, --table=NAME restore named tables
> -T, --trigger=NAME restore named triggers
> --section=SECTION restore named sections (pre-data, data, or
> post-data)
>
> This is a valuable feature change, but I think the help output is
> unhelpful. The left side has a singular placeholder, but the right side
> talks about objects in plural. How do I actually specify multiple
> indexes? Is is --index=foo,bar? It's --index=foo --index=bar, but
> that's unclear from the help.
>
> I think it would be clearer to write something like
>
> -I, --index=NAME restore named indexes (repeat for multiple)
>
> or perhaps make a note at the bottom
>
> The options -I, -n, -P, -t, -T, --section can be combined and
> specified multiple times to select multiple objects.

"each* restores named <type>"

For the schema version how about:

"each* restores named schema - including objects"

Then at the end:

* You may specify a flag multiple times to restore multiple entries of the
given type.

Though to be fair is there some platform standard that we can attempt to
emulate here? It seems pointless to create our own design if we borrow
something more universal.

David J.

--
View this message in context: http://postgresql.1045698.n5.nabble.com/9-4-pg-restore-help-changes-tp5814288p5814304.html
Sent from the PostgreSQL - hackers mailing list archive at Nabble.com.

On Fri, Aug 8, 2014 at 9:44 PM, Peter Eisentraut <peter_e(at)gmx(dot)net> wrote:
> This is a valuable feature change, but I think the help output is
> unhelpful. The left side has a singular placeholder, but the right side
> talks about objects in plural. How do I actually specify multiple
> indexes? Is is --index=foo,bar? It's --index=foo --index=bar, but
> that's unclear from the help.
>
> I think it would be clearer to write something like
>
> -I, --index=NAME restore named indexes (repeat for multiple)
>
> or perhaps make a note at the bottom
>
> The options -I, -n, -P, -t, -T, --section can be combined and
> specified multiple times to select multiple objects.
>
> Other ideas?

I like the "note at the bottom" idea.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Robert Haas wrote:
> On Fri, Aug 8, 2014 at 9:44 PM, Peter Eisentraut <peter_e(at)gmx(dot)net> wrote:

> > or perhaps make a note at the bottom
> >
> > The options -I, -n, -P, -t, -T, --section can be combined and
> > specified multiple times to select multiple objects.
> >
> > Other ideas?
>
> I like the "note at the bottom" idea.

+1

--
Álvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services