When I do "darcs record -h", the most basic and fundamental details about how it
works immediately scroll off the screen, and I instead see the "Advanced
options" which is far less likely to be what I need, and is generally the same
for all the commands. 

I would suggest that with --help, the last line is just: 

"Help for advanced options is available through --help-advanced"

Running "--help-advanced" would behave as --help does now, showing the regular
and advanced help. 

Besides the scrolling issue, I think provider shorter, more relevant help by
default will increase the impression that darcs is simple and easy to use.

Excerpts from bugs's message of Thu Jan 24 02:20:30 UTC 2008:
> 
> New submission from Mark Stosberg <mark@summersault.com>:
> 
> When I do "darcs record -h", the most basic and fundamental details about how it
> works immediately scroll off the screen, and I instead see the "Advanced
> options" which is far less likely to be what I need, and is generally the same
> for all the commands. 
> 
> I would suggest that with --help, the last line is just: 
> 
> "Help for advanced options is available through --help-advanced"
> 
> Running "--help-advanced" would behave as --help does now, showing the regular
> and advanced help. 
> 
> Besides the scrolling issue, I think provider shorter, more relevant help by
> default will increase the impression that darcs is simple and easy to use.

What about automatically launching a pager ($PAGER) when the output is a tty?

Note: That's git default

> What about automatically launching a pager ($PAGER) when the output is a tty?

That would help because it would leave the basic help visible at the top 
of the screen. And I suppose I could quit the pager before scrolling 
down to view the advanced text.

There definitely other uses of darcs where I wish that was the default. 
For example, on a project with any history, you almost always want

darcs changes | $PAGER

not just "darcs changes" anyway.

   Mark

On Thu, Jan 24, 2008 at 09:56:18AM +0100, Nicolas Pouillard wrote:
> What about automatically launching a pager ($PAGER) when the output is a tty?
> 
> Note: That's git default

I think this is probably the better option.
-- 
David Roundy
Department of Physics
Oregon State University

David Roundy <droundy@darcs.net> writes:

> On Thu, Jan 24, 2008 at 09:56:18AM +0100, Nicolas Pouillard wrote:
>> What about automatically launching a pager ($PAGER) when the output is a tty?
>> 
>> Note: That's git default
>
> I think this is probably the better option.

It would be especially nice if the pager preserved coloring of the
output.  Is there a way to get darcs1 output escape sequences when
writing to a pipe?  Er, I could as well have a look...
-- 
Thanks,
Feri.

Wagner Ferenc wrote:
> 
> David Roundy <droundy@darcs.net> writes:
> 
>> On Thu, Jan 24, 2008 at 09:56:18AM +0100, Nicolas Pouillard wrote:
>>> What about automatically launching a pager ($PAGER) when the output is a tty?
>>>
>>> Note: That's git default
>> I think this is probably the better option.
> 
> It would be especially nice if the pager preserved coloring of the
> output.  Is there a way to get darcs1 output escape sequences when
> writing to a pipe?  Er, I could as well have a look...

I think what you are getting at might be how the defaults are set up for 
the Perl-based 'ack' program:

If the output is a tty, color is on by default. However, if output is a 
pipe, color is off by default, since other programs tend to expect plain 
text.

Related: I believe "less" doesn't handle color escape codes by default. 
You have to invoke it with "-R" for that.

   Mark

This well-commented perl function "is_interactive" may be of interest 
when writing code that decides when to show color and use a $PAGER by 
default and when to not.  It is what the 'ack' utility uses:

http://search.cpan.org/src/DCONWAY/IO-Interactive-v0.0.3/lib/IO/Interactive.pm

( ack is a programmer-friendly alternative to "grep" ).

   Mark

While the exact use-cases of the pager are still discussed, I noticed that
"darcs help <command>" launches a pager, but "darcs <command> --help" doesn't.

We now use pager for darcs commmand --help.  I'm closing this bug, and folks who
like could open a fresh bug with a specific request.