ceylon help should page output

[hnridder]

When running ceylon help the output is sparsely formatted (indented, but no attributes) and not paged. I suggest to use man(1) to display the output formatted & paged, or alternatively, pipe the formatted output through $PAGER.

[tombentley]

I agree it would be nice if we could page the output. The thing is that the current help output is platform independent, and the moment you start talking about man and $PAGER you're into unix specific stuff, so we'd have to do some crufty OS detection and scripting stuff, just for the help command to look slightly more pretty.

Is it really worth the extra code maintainance and testing, when people can always write

ceylon help foo | less

or whatever?

[FroMage]

We could look at how git does it, perhaps just a little script-fu is enough to make this work?

[FroMage]

It has always pained me too that we don't support it OOTB.

[tombentley]

Sure it's worth looking in to. I'd prefer paged output too.

AFAICS we'd need the ceylon wrapper script to parse enough of the command line to know it was going to invoke help and then leap in and page the output for us (assuming help returned with a 0 status code). Which is fine, except that it's another bit of code which runs every time you run ceylon, and therefore makes running a module just a bit slower.

[quintesse]

And our help detection is already wrong because it's hard to detect correctly

[tombentley]

@quintesse what help detection is this?

[quintesse]

@tombentley right now the detection when the user wants help to be displayed is too simple, it can't handle "--help" being passed to sub tools for example (think ceylon run foo.bar --help)

[hnridder]

I checked how git does this, and it's actually (as one might expect) very flexible. The help pages are available in man, info and html format and they can be displayed using different programs. The format and the program to use can be set in the configuration file. On my machine (linux) the default is to run man and on windows the default seems to be display html in the default browser.

I don't think this is the right moment to spend a lot of time on creating the perfect help solution, but at the same time, as a user, I like to get nice help with a minimum of fuzz on my side. How about something like the following:

• In the startup script, add the bin directory to PATH so extension scripts can be distributed in ceylon.zip. And export CEYLON_HOME for step 2.
• Add ceylon-man and ceylon-browser scripts in bin that start man and the browser, resp., on the passed command.
• Add a global config option help-tool that, if set, is used to display the help pages. If it is not set (possibly: or returns with an error code) the builtin help is displayed, the way it is now.

The only change that affects the system then is the option; the first two points is just a bit of script work. And as a user I only need to set my help-tool config once. I can live with that.

[FroMage]

Moving to 1.2

[FroMage]

HAHA! It's not done in a shell script. It's done in C by spawning a pager program and piping stdout to it. We can do the same in Java by setting System.out (or just printing the help to a special pager stream) and we won't have issues with parsing the help flag :)

[FroMage]

https://github.com/git/git/blob/fbecd99861ea5795aeba46faf2ac7a8c1b70d485/pager.c for info

[quintesse]

We can do the same in Java by setting System.out

I'm not sure I understand, so who would do the paging?

[FroMage]

less, but it's started from Java where we already know how to parse the --help flag.

[quintesse]

Ah ok, so you start the pager from within the program and then pipe the output to it. Sounds easy enough. And like they do in the git helper, look at CEYLON_PAGER first, then at the default Linux (Unix?) PAGER and finally using less. And maybe some option to disable paging? (So you won't have to do PAGER=cat ceylon foo --help)

[quintesse]

Works great on Linux, but on Windows it doesn't show anything at all (unless I add the --no-pager flag).

[quintesse]

Works fine on Linux but doesn't work on Windows, neither in Git Bash (which simulates a unix-like environment) nor in the standard Windows command line. First because less doesn't exist in Windows but even when changing it to more it doesn't work and I guess this is because more is part of the Windows command "shell", so it's not a program that can be started.

[FroMage]

Damn, sorry about the missing push of ceylon-js.

[FroMage]

So, I tried to figure out what git does on Windows but it's not clear. Apparelty on Windows they have two strategies: one for using sh -c and the other using native windows calls like mingw_spawnvpe. Can we really start a Windows command shell with sh -c on Windows?

[FroMage]

Wow, reading back C files I can say I'm glad I didn't write C code in the last seven years, that stuff is nuts.

[quintesse]

Can we really start a Windows command shell with sh -c on Windows?

No, to me that sounds that they only take into account unix-like environments like MinGW.

Better yet, I just tested Git on Windows and it doesn't do paging at all... it... spawns an HTML page in a browser!

[FroMage]

Of course, my Windows drive is dead so I can't test any of this shit anymore :(

[FroMage]

Well, no idea then. I haven't found the code that does this in git.

[quintesse]

Well we do generate HTML docs for the distribution so we could go Git's way and spawn a browser and just forget about paging on Windows.

[quintesse]

And using --no-pager could still give us the current behaviour, in case someone wants to, I don't know, pipe the help text somewhere.

[quintesse]

Btw, Git only seems to do this for some commands though. git help checkout shows the HTML page for checkout, but git help shows the list of all Git commands in the console (unpaged). (And git help git again shows an HTML page)

[quintesse]

Also, on Windows the --paginate and --no-pager options are completely ignored. You can't set a different pager and you can't disable paging.

[FroMage]

I just don't see it. Apparently they have different code paths for Windows and for Cygwin, but both would call sh -c more. I don't see where this browser behaviour is coming from.

[FroMage]

I don't find anything about piping to the browser in the code for git, so I don't know how they do it. I'm tempted to just disable paging by default on Windows. Also I can't test because my Windows drive is dead.

[quintesse]

They don't pipe (I don't even think that's possible with browsers), they just start the browser pointing to the local HTML doc page : file:///C:/Program%20Files%20(x86)/Git/doc/git/html/git-checkout.html

[FroMage]

OK but I don't even know how to start a browser.

[quintesse]

You can just "execute" the link and Windows will open the default browser for you. But the thing is how to get the URL?

[FroMage]

Seriously? Just execute a link?

[quintesse]

Yes, although maybe better to use start, eg start file:///C:/Program%20Files%20(x86)/Git/doc/git/html/git-checkout.html , that would probably work both in a regular CMD box and in a Cygwin shell.

[FroMage]

I pushed a fix for Windows, can you try it please?

[quintesse]

Fixed NPE and added a fall-back to the console if the docs weren't found. Works perfectly now!

[FroMage]

OK, so we can close this?

[quintesse]

Yup

[FroMage]

Thanks