[GRASS-dev] Adding an expert mode to the parser

[Moritz Lennert]

On 26/09/16 23:50, Vaclav Petras wrote:
>
> On Mon, Sep 26, 2016 at 5:24 PM, Veronica Andreo <veroandreo at gmail.com
> <mailto:veroandreo at gmail.com>> wrote:
>
>     I'm with MaDi in that if I see a very long list of flags and
>     parameters in the terminal when using --h, i just go to the
>     manual... I just use --h in CLI for a quick recalling of
>     flags/options... A reduced list of most commonly used flags would be
>     nice, but still keep the possibility to get the advanced
>     flags/parameters as well, if the user needs more info...
>
>
> If the --help is just for scanning and the issue is that it simply too
> long, hiding some parameters is not the only option we have. For many
> (and more in the future hopefully) parameters we have (short) label and
> (longer) description. --help prints both (if both are present, that's at
> least 2 lines per parameter). Additionally, if the option has predefined
> values which have descriptions, there is one line for each of those. So,
> the question is would it be helpful (at least as a first step) if --help
> would print less information for each parameter but still provided all
> parameters?

In line with your other mail where you caution about "hiding" useful 
information, how about not changing the --help output, but rather adding 
a "--simple-help" or somthing like this which would output a simplified 
help. Although:

>     and manual pages then (a tab or section for advanced
>     flags/parameters)...
>
>
> Considering that we have currently as system of (gui) sections which
> place the options to individual tabs in GUI, isn't showing the different
> sections in the manual the right thing to do?

I would prefer this: show everything, but structure it differently, i.e. 
possibly introduce a new parser keyword (advanced: yes) which would put 
the option into a specific section of the manual. IMHO, this should be 
independent of the GUI sections logic as one might to group less 
advanced and advanced options in the same thematic tab...

> 	IMHO, a major issue however is the lack of examples for the usage of
> 	more advanced flags or options (or even the required and more common
> 	ones). Take the case of several i.* modules, for example... but maybe
> 	this should go in a separate thread :-)
 >
 >
 > Good point. If you have an explanation and example for a flag, perhaps
 > you can understand it and it is not so advanced at the end.

I think this is actually a major issue: man pages without description, 
notes and example sections are almost useless IMHO. At the foss4g.be 
last week someone presented a simple use of GRASS GIS (to create this 
map [1] for television) and explained how he actually found the GRASS 
GIS manual system extremely well done and useful, because of the 
explanations and examples...

Moritz

[1] http://www.rtbf.be/services/meteo/apere