New help section 'Global Options'?

[Gabriela Gibson <ga...@gmail.com>]

Currently, the global options are displayed on many svn help topics, and
that's an extra 16 lines at the end, which makes the actual help info that
is sought scroll off the screen, and it's not information that always
needed.

What do you think about moving the global options to their own help section
and leaving just one line with a pointer to them?

Proposed:

Global options: Type svn help global for details

Current:

Global options:
  --username ARG           : specify a username ARG
  --password ARG           : specify a password ARG
  --no-auth-cache          : do not cache authentication tokens
  --non-interactive        : do no interactive prompting (default is to
prompt
                             only if standard input is a terminal device)
  --force-interactive      : do interactive prompting even if standard input
                             is not a terminal device
  --trust-server-cert      : accept SSL server certificates from unknown
                             certificate authorities without prompting (but
only
                             with '--non-interactive')
  --config-dir ARG         : read user configuration files from directory
ARG
  --config-option ARG      : set user configuration option in the format:
                                 FILE:SECTION:OPTION=[VALUE]
                             For example:
                                 servers:global:http-library=serf

Gabriela
-- 
Visit my Coding Diary: http://gabriela-gibson.blogspot.com/

Re: New help section 'Global Options'?

[Julian Foad <ju...@btopenworld.com>]

Ben Reser wrote:
> On 7/3/14 12:21 PM, Gabriela Gibson wrote:
>> Currently, the global options are displayed on many svn help topics, and that's
>> an extra 16 lines at the end, which makes the actual help info that is sought
>> scroll off the screen, and it's not information that always needed.
>> 
>> What do you think about moving the global options to their own help section and
>> leaving just one line with a pointer to them?
> 
> I'd rather we left things as they are.  Especially if we actually finish and
> merge in the work to execute the pager automatically as we've started working
> on over in the automatic-pager branch.

As it is, without the pager, I find it poor. The help section describing global options is long and irrelevant to a large proportion of use cases. I don't feel terribly strongly about it for my own sake -- I always use a terminal with a fairly large number of visible lines and a large scroll-back capacity -- but I think it's poor form to display all this minority-interest text right in front of every user's face every time.

Notice that half of this text is about authentication, and is displayed even for the commands that can't do authentication such as 'svn add'!

I think Subversion would be better if changed the way we show it.

> Once we have the automatic pager it'll be inconvenient to flip from one help
> topic to another since you'll have to leave the pager.

The point is we think people don't often need or want to flip from the help on 'svn add' to the help on supplying a password or any of the other global options. Or even from 'svn commit'. Anyway, we don't have the automatic pager, and when we do, it isn't going to be mandatory, is it? The help output in pager mode can list the global options in full if we want.

> There's also been some discussion about making the man pages be generated from
> our help output rather than be a fairly static file telling people to run our
> help sub-command.

Yup, but we don't have that either, and that doesn't detract from this suggestion either, as the man page for a subcommand doesn't have to be generated as a straight dump of the corresponding help output: it could have all the global options explained in full if we want.

- Julian

Re: New help section 'Global Options'?

[Ben Reser <be...@reser.org>]

On 7/3/14 12:21 PM, Gabriela Gibson wrote:
> Currently, the global options are displayed on many svn help topics, and that's
> an extra 16 lines at the end, which makes the actual help info that is sought
> scroll off the screen, and it's not information that always needed.
> 
> What do you think about moving the global options to their own help section and
> leaving just one line with a pointer to them?

I'd rather we left things as they are.  Especially if we actually finish and
merge in the work to execute the pager automatically as we've started working
on over in the automatic-pager branch.

Once we have the automatic pager it'll be inconvenient to flip from one help
topic to another since you'll have to leave the pager.

There's also been some discussion about making the man pages be generated from
our help output rather than be a fairly static file telling people to run our
help sub-command.