help on globals

[sina-masoud-ansari]

It may be useful to have a command to explain global variables and their possible values:

help [keywords]

gricli> help globals Globals: Variables that specify job properties (or some such)

queue [ * | auto]: submission location for a job. For a list of valid, package specific locations use 'print queues [package]'

It may be better to list each global as a keyword on help so they can be accessed individually. So we can explain in depth and use examples.

[makkus]

Ties in with https://github.com/grisu/gricli/issues/37

Should we add new syntax for help command like:

help topic globals help keyword jobs

help globals by itself we could do as well, but in terms of implementation it would be better to use "help topic globals" because we could add additional topics easier subsequently...

?

[sina-masoud-ansari]

Tying into #51 : I'm suggesting info in place of 'help topic'

I agree, just want to clearly define the functionality we have and are proposing:

Currently:

help : shows available commands help [keywords] : describes a particular command. Here I think it should be help [command]. You can specify the first term in the command for a list of matching commands. apropos [keyword]: searches help text for keywords.

Proposed: help : shows available commands help [command] : describes command and lists commands if there is more than one match on the first word help [keyword]: performs apropos [keyword] on help text. info : lists topics eg globals, jobs, queues (things with properties presented the user or that can be set ?) info [topic] : lists the properties of a topic info [topic] [property] : describes a property eg globals::jobtype with examples perhaps

?.

[makkus]

Makes sense to me. Should I start implementing it that way?

[yuriyh]

i would be in favor of single "help" that covers both commands and keywords. If there is ambiguity, just print all possible help topics.

[sina-masoud-ansari]

Yeah good point:

Proposed: help : shows available commands help [keyword] : describes command and lists commands if there is more than one match on the first word, else does apropos [keyword] on help text. info : lists topics eg globals, jobs, queues (things with properties presented the user or that can be set ?) info [topic] : lists the properties of a topic info [topic] [property] : describes a property eg globals::jobtype with examples perhaps

[makkus]

help [keyword] : describes command and lists commands if there is more than one match on the first word, else does apropos [keyword] on help text.

Shouldn't that be the other way round: if there is an exact match for the keyword (in the commands list) then that command should be printed with details, otherwise it should do apropos? On the other hand, that way you can't easily do something like help submit where you want to find all the commands that do have to do with submit (apropos-style).

Actually, I would find it easier not to try to make commands do 2 different things depending on the context, if at all possible. Don't really see the advantage of having a small list of commands...

Also, not too sure about the info [topic] [property] thing. What exactly is a property of a topic? How do we define that and how do we explain it to users. That's probably easy enough for globals, because that is a list of properties, but what about other topics? Not sure what those would be, but I could imagine "scripting", "workflow", "batchjobs",... I think it would be enough to only have info [topic] which gives you an article about the topic, like the "man" command under Linux. One can scroll within that text (or maybe even search, like one can within man). Shouldn't that be enough? At least for now?

[sina-masoud-ansari]

Ok probably best to have two functions that are easier to implement. We could stick with help [command] and apropos [keyword].

In that case could apropos scan the topics as well? What do you guys think of calling it search [keyword]?

Sure we can leave the topic properties for now, perhaps once we get a few topics we can see whether it is still appropriate. Scrolling should be fine you mean like 'less'?

[makkus]

Hm, "search". Not sure whether it's clear that it is connected with help topics. One could search for jobs, files, all kinds of things... I agree, apropos command (whatever we decide to name it) should scan topics as well.

Scrolling would ideally be like "less", yes. Not sure how easy that'll be to implement though... For now, I guess we'd start with just printing the whole topic page (I suggest we use markdown for them -- that way we can reuse the topics on webpages and even in the swing client) and one scrolls with the scrollbar of the terminal window.

[yuriyh]

it is just that when people want to get help, they don't want to think about where the concept belongs to. all those "man", "info", "apropos", "help" are legacy stuff replaced by single google text box :)

Usually i am against contextual commands as well. But "help" is an exception, strict and clear semantics should give up to simplicity.

[makkus]

So, what are you suggesting?

[yuriyh]

help without arguments - print all help topics (but not commands, just single entry for 'commands') help commands - print all commands help x - print everything related to x, x can be command, global, concept etc. help x y z -print command x y z

[makkus]

Ok, fair enough. Lets do it like that then...

[sina-masoud-ansari]

Yeah that works ; )

[makkus]

Ok, about to implement that, but realized:

we don't have the apropos command covered with that: help x would print details about the exact command, topic or global that is specified.

So, one solution would be to use help x as apropos command and list all matching topics, commands and globals along with those categories so a user could use: help topic x help command x help global x to get more details

or we have an extra apropos command, either apropos x or help search x or something...

Which one? I think the latter is probably better...

[sina-masoud-ansari]

I prefer the second option 'help search x', but I thought apropos was used in case there was no match?

if x matches a topic or command then ::if one match show entry ::else list matches else do apropos

help search my be good to have anyway as help globals would never give the equivalent of apropos globals

[yuriyh]

"help search x" sounds good.

[makkus]

All right, this is almost finished now.

I decided to get rid of the properties file and have one file for every command, topic and global. Makes it easier to edit the files and allows for more formatting. All of those files should (if possible) use markdown, that way we can easily create documentation in different formats.

Here are the files: https://github.com/grisu/gricli/tree/develop/src/main/resources/help

If you want to create a new Topic, just create a md file with the title of the topic. For now, the name of the topic also needs to be added in the java source code, bit complicated to do otherwise. So tell me once you added a topic.

For all of those files: the first line (except for the title or lines with === or --- or empty lines) should be a short description ot the thing. That will be used if more topics are found as a description to each topic, command, global. Easier to display.

Man page creation is broken because of that at the moment, but I'll fix that later on.

Also, please help and fill in the dummies I created for the globals documentation, those only contain dummy text for now.

griclish-dev on login node should use this updated help system now.

[sina-masoud-ansari]

Great thanks, I'll start filling them out.

[makkus]

Cool.

[makkus]

Ok, now there is no way to list all commands, topics and globals.

What about those extra commands: help commands help topics help globals

to list them? Guess that makes sense...

[sina-masoud-ansari]

New help is looking good, I especially like the categorisation eg the results of help print.

Yeah those should be fine. Easy access to command help is still there ie help print globals , so to see the whole list with help commands etc seems fine to me.

[sina-masoud-ansari]

May want a help help to describe how to interpret help < x > [y] and how to use help now that there is a bit more to it. Pretty standard stuff but it may make things easier for newcomers to cli.

[makkus]

Doesn't the text that help produces (actually, help help produces the same text) explain that?

What exactly do you have in mind?

[sina-masoud-ansari]

Actually you're right it should be fine, I'll just add a few lines about the syntax. I think previously there was a properties file for examples. How would you like to work with examples in the new system?

[makkus]

Just put everything relevant to the command in the .md file, including examples.

[yuriyh]

Sina, we need this one for July release.

[makkus]

This one is getting there. Merged Sinas documentation into develop and release branch. Seems to be a bit of a bug when one wants help for topics, will look into that. Other than that, I think we can close this.