"fossil help" by itself only shows the most common commands, to avoid overwhelming the user. Run "fossil help --all" to see the "ticket" command.

What do you think? Should we change this policy so that "fossil help" shows all commands and some new option "fossil help --common" shows only the most common commands? Maybe the output of "fossil help" suggests --common to the user to get an abbreviated output? Which approach is the most newbie friendly?

A crazy idea. If output is going to a terminal, show the brief list with a note that fossil help --all will show more. If output is going to a non-terminal perhaps default to --all with the theory being that they will be running it through less or to a file they can browse in their text editor of choice.

Today's fossil, invoked via "fossil help", does your note already. It says, 'Try "fossil help help" or "fossil help -a" for more options'.

It is not clear that --all as a default is good for newbies. Nor do I see a need for the extra blather that "help --all" will also show more of actual use to the newbie. I say this because, among the commands shown by unadorned "fossil help", is the help command itself. And "fossil help help" emits a complete (I assume) list of options for help, including -a or --all .

There will always be users who have not gotten the hang of exploration. Maybe, with enough unsolicited information, they can get their tasks done despite that handicap. Sadly, too much can easily be worse for all users. It takes time to sift through, and shoves stuff off the screen that may also be of current interest. The blurt-a-lot approach seems inferior to carefully structuring the help to be discoverable and provide helpful detail when asked, while providing good tips for further discovery.

I pretty much agree with Mr. Bram that the current volume and structure choices are right already.

I guess I should have written "with the note" instead of "with a note" (the latter implying that it didn't already exist).

My thought was simply that it is in theory a usability improvement. If going to a tty it will overflow a single screen, so keep it to the most common list of commands that doesn't involve scrolling. If not a tty, piping or redirection of some sort is in progress so assume the user is not limited to "a single screen of information". This way when a user decides to "fossil help | grep ticket" they are more likely to find what they want.

This is not a huge deal to me, it just occurred to me and I thought I'd offer the suggestion. I am in complete agreement that the default interactive method should work as currently designed.

I am even happy to work on the functionality myself. I'm not asking anyone else to make the change. I just wanted to open the idea up for discussion.

So I did it. There is a branch "help-no-tty" that writes all the help info except for test commands and "help help". And I'm wondering about adding one or both of those.

Note that fossil help is unchanged if working from a tty. It is only in the case of no tty that it becomes extra verbose.

Anonymous Coward's arguments make a lot of sense to me, actually. I retract my earlier suggestion about changing the output based on isatty().

Tangentially to this, one the annoyances I am currently enduring with Ubuntu is that the "grep" output changes according to isatty(). In particular, the output is color-coded for TTY output, but not for pipe or file output. I have my terminals set to a dark background with light text. One of the foreground colors chosen by grep is a deep purple, which is unreadable on a black background. So I end up having to run

     grep ... | cat

Just so I can read the output text.

Lately, for the same reason with other utilities, I have aliased a number of their names to make them as "dumb" and useful as they were years ago.

You might find this useful somewhere: alias grep=grep --color=never

I was slightly dismayed to see the specialized trickery for TTY output. To me, it violates the notion I once had that output sent to stdout goes where I want and is otherwise unchanged. I wonder how one is supposed to capture auto-magically colorized or otherwise altered for the TTY output. Screen-scrapes don't quite do it.

Fair enough. The rationale is reasonable. It's on a branch and not committed directly to trunk.

That --full option is nice. Sometimes blurt-a-lot is useful with a decent pager where keyword search can be used to find something without the distraction (or mental effort when tired) of navigating through piecemeal help. I still use that for 'man bash' output sometimes. I imagine 'fossil help --full' will be similarly voluminous, and if not, an --everything option would be useful at times.

Thanks.

Sometimes crazy ideas turn out to be crazy ideas, as it turns out.

An everything option ...

It truly helps when perusing the 5 k-line bash man entry that it has section headers at the left margin, easily searched for with 'less' or other competent pagers.

I hope the --full output is so easily navigated by virtue of some regular, repeating structure, particularly for topic headers. I would be willing to help make that happen.

The full option I implemented merely outputs all the help sections that help could output. It only lists the commands, aux commands, test commands, common options, web pages, and settings, trusting that once you find the key you want in there, you can go find specific help.

Then there is the test-all-help command I addressed in a separate post below in a different fiber of this thread.

You may notice that "fossil test-all-help -e" emits its 2^13 lines with a lot of headers (210 by count) which match the regex "^# /". That is helpful for getting to a section on X rather than visiting places where X is merely mentioned.

Yes, I believe that should be a supported command+option for these reasons.

And, No, I did not know it. Now I do, for awhile, and for longer if the help doc mentions it.

One more modification pushed that includes a "help --everything" that behaves as test-all-help -e (by refactoring the code out into a static function shared between the two help commands). Not certain that's the right approach, but it is there for people to try.

(Biting my tongue to try to keep my comments polite...)

I strongly believe the current behavior is exactly how it should be.

Typing more in order to get more, I think, makes sense. The opposite seems to me quite bizarre.

I strongly believe the current behavior is exactly how it should be.

FWIW, i do as well (probably less strongly), but also like Scott's idea of printing only the common ones if the output is a tty and all of them if it's not.

Hello guys. Thank for all the answers.

I still would like to insist in one not answered point: why can't I found tickets section in the main site? I'm not going to open any ticket, but I'm curious why you disabled it (or I just didn't find it?). Spamming?

why can't I found tickets section in the main site?

It's been our experience that many users tend to post tickets for non-bugs, asking for help with topics covered by the docs or easily resolvable via the mailing list/forum. The ticket system is still there but is rarely used and not publicized. The developers only use it when they want to keep track of a fix long-term, but most problems reported in the forum are resolved within a few days, at most, and never get tickets.