Hide Java variable name

[zappee]

Hello,

I would like to generate Unix-style documentation but it seems that Picoli not able to generate help without Java variable names.

As you can see in your example here the Java variable name is shown:
-a, --algorithm=<algorithm>

I would like to have this:
-a, --algorithm

For me, this is a little bit weird. The end-user is not interested in seeing the internal representation of the options. She only wants to see the pure options.

Is there any option that hides the Java variable names?

[remkop]

One thing: the option parameter label can be controlled with the paramLabel annotation attribute.
So you can pick a better name independent from the variable name.

The presence of a parameter label signals to the end user that they cannot just specify an option name: it must be followed by a value. Boolean options don’t accept a variable, so the usage help for boolean options doesn’t show a parameter label.

That’s why the default usage help message looks the way it does.

That said, it is possible to customize this to hide the parameter label. I think there’s an example in a previous issue or one of the picocli-examples. I’ll take a look and try to find it.

[remkop]

I found the example:

picocli-examples/src/main/java/picocli/examples/customhelp/HideOptionParams.java

Hope this helps.
Enjoy!

[zappee]

I thought that this "feature" was added to the new release and I can get rid of the custom code ;)

Unfortunately, the custom code hides the default value which is set by showDefaultValue param.

[remkop]

Not sure what you mean by hides the default value. Can you provide a sample program that demonstrates the issue, and explain what you expected to see and what’s actually happening?

[remkop]

Also note that you can embed a variable in the description to show the default value.

Please see section 14.19.1 of the manual for details: https://picocli.info/#_default_value_variable

[zappee]

And I can see still the variable names in the summary despite I use the additional OptionRender:

Usage: SqlRunner [-?qsv] [-c=<dialect>] [-e=<sqlCommandSeparator>] -U=<user> (-P=<password> | -I)
                 (-j=<jdbcUrl> | (-h=<host> -p=<port> -d=<database>)) <sqlStatements>

End users do not care about the Java variable names.

This is what I would like to have:

Usage: SqlRunner [-?qsv] [-c] [-e] -U (-P | -I)
                 (-j | (-h -p -d)) <sqlStatements>

[zappee]

Example for hiding the default value issue:

This is the original code I used:

@Option(names = {"-c", "--dialect"},
        defaultValue = Dialect.ORACLE_VALUE,
        showDefaultValue = CommandLine.Help.Visibility.ALWAYS,
        description = "SQL dialect used during the execution of the SQL statement. "
                + "Supported SQL dialects: ${COMPLETION-CANDIDATES}.")
private Dialect dialect;

But the custom OptionRender hides the default value somehow.

So I had to add the default value manually:

@Option(names = {"-c", "--dialect"},
        defaultValue = Dialect.ORACLE_VALUE,
        description = "SQL dialect used during the execution of the SQL statement. "
                + "Supported SQL dialects: ${COMPLETION-CANDIDATES}.%n"
                + " Default: " + Dialect.ORACLE_VALUE)
private Dialect dialect;

The source code available from here.

[remkop]

So I had to add the default value manually:

@Option(names = {"-c", "--dialect"},
        defaultValue = Dialect.ORACLE_VALUE,
        description = "SQL dialect used during the execution of the SQL statement. "
                + "Supported SQL dialects: ${COMPLETION-CANDIDATES}.%n"
                + " Default: " + Dialect.ORACLE_VALUE)
private Dialect dialect;

The source code available from here.

That is almost what I had in mind, yes, I would just suggest using the ${DEFAULT-VALUE} variable in the description. For example:

@Option(names = {"-c", "--dialect"},
        defaultValue = Dialect.ORACLE_VALUE,
        description = "SQL dialect used during the execution of the SQL statement. "
                + "Supported SQL dialects: ${COMPLETION-CANDIDATES}.%n"
                + " Default: ${DEFAULT-VALUE}") // <--- 

---

End users do not care about the Java variable names.

They are not Java variable names.
Parameter labels are one-word descriptions of the value that the end user needs to provide.
You can show any label, it does not need to be the Java variable name.

And I can see still the variable names in the summary despite I use the additional OptionRender:

Usage: SqlRunner [-?qsv] [-c=<dialect>] [-e=<sqlCommandSeparator>] -U=<user> (-P=<password> | -I)
                 (-j=<jdbcUrl> | (-h=<host> -p=<port> -d=<database>)) <sqlStatements>

This is what I would like to have:

Usage: SqlRunner [-?qsv] [-c] [-e] -U (-P | -I)
                 (-j | (-h -p -d)) <sqlStatements>

Quick question: have you asked your end users? You may be surprised. 😉

Anyway, if that is what you want to do, then this is certainly possible.

I added a new example HideOptionParamsFromSynopsis.java that shows how to hide the parameter label from the options in the synopsis. That should give you what you have in mind. 😉

Enjoy!

[remkop]

Hi @zappee, did this solve the issue?

[zappee]

Yes, thanks for the help!