Update help message comments. Closes #517

[externl]

This PR updates the generated help messages. Both -h and --help are still the same, clap_derive seems to generate this automatically. I think it's fine to keep for now.

Closes #517

[pepone]

@externl can you Include the output of -h and --help?

[externl]

❯ cargo run -- -h
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
     Running `target/debug/slicec-cs -h`
The slicec-cs compiler, for compiling Slice files into C# code.


Usage: slicec-cs [OPTIONS] <SOURCES>...

Arguments:
  <SOURCES>...  List of Slice files to compile

Options:
  -R, --references <REFERENCES>
          Reference Slice files or directories containing Slice files. Reference files are used to resolve definitions in the Slice sources being compiled. Directories are searched recursively
  -D, --definitions <DEFINITIONS>
          Define a preprocessor definition. Preprocessor definitions do not have an associated value. Multiple values can be specified by using multiple `-D|--definition` options or by using a comma
  -w, --warn-as-error
          Instructs the compiler to treat warnings as errors
  -A, --allow <ALLOW>
          Instructs the compiler to allow the specified warning(s). An allowed warning will not be emitted as a diagnostic. Multiple values can be specified by using multiple `-A|--allow` options or by using a comma
      --dry-run
          Validates input files without generating code for them
      --output-dir <OUTPUT_DIR>
          Output directory for generated code, defaults to the current working directory
      --diagnostic-format <DIAGNOSTIC_FORMAT>
          Output format for emitted errors [default: human] [possible values: human, json]
      --disable-color
          Disables ANSI escape code for diagnostic output
  -h, --help
          Print help (see more with '--help')
  -V, --version
          Print version

❯ cargo run -- --help
    Finished dev [unoptimized + debuginfo] target(s) in 0.04s
     Running `target/debug/slicec-cs --help`
The slice compiler for C#.
Generates C# code from Slice files for use with IceRpc.

Usage: slicec-cs [OPTIONS] <SOURCES>...

Arguments:
  <SOURCES>...
          List of Slice files to compile

Options:
  -R, --references <REFERENCES>
          Reference Slice files or directories containing Slice files. Reference files are used to resolve definitions in the Slice sources being compiled. Directories are searched recursively

  -D, --definitions <DEFINITIONS>
          Define a preprocessor definition. Preprocessor definitions do not have an associated value. Multiple values can be specified by using multiple `-D|--definition` options or by using a comma

  -w, --warn-as-error
          Instructs the compiler to treat warnings as errors

  -A, --allow <ALLOW>
          Instructs the compiler to allow the specified warning(s). An allowed warning will not be emitted as a diagnostic. Multiple values can be specified by using multiple `-A|--allow` options or by using a comma

      --dry-run
          Validates input files without generating code for them

      --output-dir <OUTPUT_DIR>
          Output directory for generated code, defaults to the current working directory

      --diagnostic-format <DIAGNOSTIC_FORMAT>
          Output format for emitted errors

          [default: human]
          [possible values: human, json]

      --disable-color
          Disables ANSI escape code for diagnostic output

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

[pepone]

It looks weird that the last dot is stripped in the output.

[externl]

It looks weird that the last dot is stripped in the output.

Yeah, not sure what we can do about that. I haven't look to see if maybe that's standard?

[InsertCreativityHere]

TL;DR all tools do their own things with periods apparently.

git doesn't end anything with periods.

PS C:\Users\Me\Desktop\slicec> git --help
usage: git [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           [--super-prefix=<path>] [--config-env=<name>=<envvar>]
           <command> [<args>]

These are common Git commands used in various situations:

start a working area (see also: git help tutorial)
   clone     Clone a repository into a new directory
   init      Create an empty Git repository or reinitialize an existing one

work on the current change (see also: git help everyday)
   add       Add file contents to the index
   mv        Move or rename a file, a directory, or a symlink
   restore   Restore working tree files
   rm        Remove files from the working tree and from the index

examine the history and state (see also: git help revisions)
   bisect    Use binary search to find the commit that introduced a bug
   diff      Show changes between commits, commit and working tree, etc
   grep      Print lines matching a pattern
   log       Show commit logs
...

rustc ends some things with periods, but most things without

PS C:\Users\Me\Desktop\slicec> rustc --help
Usage: rustc [OPTIONS] INPUT

Options:
    -h, --help          Display this message
        --cfg SPEC      Configure the compilation environment
    -L [KIND=]PATH      Add a directory to the library search path. The
                        optional KIND can be one of dependency, crate, native,
                        framework, or all (the default).
    -l [KIND[:MODIFIERS]=]NAME[:RENAME]
                        Link the generated crate(s) to the specified native
                        library NAME. The optional KIND can be one of
                        static, framework, or dylib (the default).
                        Optional comma separated MODIFIERS
                        (bundle|verbatim|whole-archive|as-needed)
                        may be specified each with a prefix of either '+' to
                        enable or '-' to disable.
        --crate-type [bin|lib|rlib|dylib|cdylib|staticlib|proc-macro]
                        Comma separated list of types of crates
                        for the compiler to emit
        --crate-name NAME
                        Specify the name of the crate being built
        --edition 2015|2018|2021|2024
                        Specify which edition of the compiler to use when
                        compiling code.
        --emit [asm|llvm-bc|llvm-ir|obj|metadata|link|dep-info|mir]
                        Comma separated list of types of output for the
                        compiler to emit
        --print [crate-name|file-names|sysroot|target-libdir|cfg|target-list|target-cpus|target-features|relocation-models|code-models|tls-models|target-spec-json|native-static-libs|stack-protector-strategies|link-args]
                        Compiler information to print on stdout
    -g                  Equivalent to -C debuginfo=2
    -O                  Equivalent to -C opt-level=2
    -o FILENAME         Write output to <filename>
        --out-dir DIR   Write output to compiler-chosen filename in <dir>
        --explain OPT   Provide a detailed explanation of an error message
        --test          Build a test harness
        --target TARGET Target triple for which the code is compiled
    -A, --allow LINT    Set lint allowed
    -W, --warn LINT     Set lint warnings
        --force-warn LINT
                        Set lint force-warn
    -D, --deny LINT     Set lint denied
    -F, --forbid LINT   Set lint forbidden
        --cap-lints LEVEL
                        Set the most restrictive lint level. More restrictive
                        lints are capped at this level
    -C, --codegen OPT[=VALUE]
                        Set a codegen option
    -V, --version       Print version info and exit
    -v, --verbose       Use verbose output

dotnet ends everything with a period.

PS C:\Users\Me\Desktop\slicec> dotnet --help
Usage: dotnet [runtime-options] [path-to-application] [arguments]

Execute a .NET application.

runtime-options:
  --additionalprobingpath <path>   Path containing probing policy and assemblies to probe for.
  --additional-deps <path>         Path to additional deps.json file.
  --depsfile                       Path to <application>.deps.json file.
  --fx-version <version>           Version of the installed Shared Framework to use to run the application.
  --roll-forward <setting>         Roll forward to framework version  (LatestPatch, Minor, LatestMinor, Major, LatestMajor, Disable).
  --runtimeconfig                  Path to <application>.runtimeconfig.json file.

path-to-application:
  The path to an application .dll file to execute.

Usage: dotnet [sdk-options] [command] [command-options] [arguments]

Execute a .NET SDK command.

sdk-options:
  -d|--diagnostics  Enable diagnostic output.
  -h|--help         Show command line help.
  --info            Display .NET information.
  --list-runtimes   Display the installed runtimes.
  --list-sdks       Display the installed SDKs.
  --version         Display .NET SDK version in use.

SDK commands:
  add               Add a package or reference to a .NET project.
  build             Build a .NET project.
  build-server      Interact with servers started by a build.
  clean             Clean build outputs of a .NET project.

[InsertCreativityHere]

Should we still remove the -V option?
#517 (comment)

[externl]

ld we still remove the -V option?

The version flag actually comes from slicec-cs!

[pepone]

What about: "Comma separated list of preprocessor symbols that will be defined for the compilation"

[InsertCreativityHere]

We don't support comma separated lists, if you want to define multiple symbols, each one needs a -D in front of it:
okay: slicec-cs.exe test.slice -D foo -DBar
bad: slicec-cs.exe test.slice -D foo,bar

[pepone]

mm ok, the --help output posted earlier mentioned the comma thing

          Define a preprocessor definition. Preprocessor definitions do not have an associated value. Multiple values can be specified by using multiple `-D|--definition` options or by using a comma

[pepone]

Seems good, a sorter version can be "Specify additional directories containing Slice files or Slice files to resolve Slice definitions during compilation"

[bernardnormier]

-D, --definitions

My preference would be no long version. And if we need a long version, it should be --define.

Print help (see a summary with '-h')

The message should be consistent: Print or Prints, Define or Defines?
It would also change Output to Sets the output directory for the generated code...; otherwise, it looks odd when all other descriptions start with a verb.

-R, --references

I would call it --reference. Like -I and --include, not --includes.

Can you have multiple --reference options?

[InsertCreativityHere]

My preference would be no long version. And if we need a long version, it should be --define.

I'd lean towards keeping both a short and long version, and let users decide what they want.
But I agree, the option should be --define, not --definitions.

The message should be consistent: Print or Prints, Define or Defines?

I think our messages should be written in present-single tense: Print, Define, Disable, Instruct, etc.
That's the simplest tense to use, and seems to be what other tools use.

Can you have multiple --reference options?

Yes: slicec-cs.exe test.slice -R first -Rsecond is totally fine.

[externl]

I've changed this PR to be a draft. I need to read the clap docs and figure out the correct way to fix the output.
For example, I changed the references field to show as long option --reference but it still shows the field name in the output which looks weird: -R, --reference <REFERENCES>. Currently you can't , separate either. There appears to be a value_delimiter settings that we can use.

    Finished dev [unoptimized + debuginfo] target(s) in 0.18s
     Running `target/debug/slicec-cs -h`
The slicec-cs compiler, for compiling Slice files into C# code.


Usage: slicec-cs [OPTIONS] <SOURCES>...

Arguments:
  <SOURCES>...  List of Slice files to compile

Options:
  -R, --reference <REFERENCES>
          Reference Slice file or directory containing Slice files. Reference files are used to resolve definitions in the Slice sources being compiled. Directories are searched recursively. This option can be repeated
  -D, --define <DEFINITIONS>
          Define a preprocessor definition. Preprocessor definitions do not have an associated value. This option can be repeated
  -w, --warn-as-error
          Instruct the compiler to treat warnings as errors
  -A, --allow <ALLOWED_WARNINGS>
          Instruct the compiler to allow the specified warning. An allowed warning will not be emitted as a diagnostic. This option can be repeated
      --dry-run
          Validate input files without generating code for them
      --output-dir <OUTPUT_DIR>
          Set the output directory for the generated code, defaults to the current working directory
      --diagnostic-format <DIAGNOSTIC_FORMAT>
          Output format for emitted errors [default: human] [possible values: human, json]
      --disable-color
          Disable ANSI escape code for diagnostic output
  -h, --help
          Print help (see more with '--help')
  -V, --version
          Print version

[InsertCreativityHere]

If Clap becomes more of a liability than an aid, I think it would be pretty trivial to write a simple command line parser ourselves. We already have all the structure and logic for parsing slice files, comments, and preprocessor directives; command line options can't be any harder than any of those things.

Like, Clap is neat, but we're perfectly capable of replacing it with a simple hand-written parser of our own.

[externl]

If Clap becomes more of a liability than an aid, I think it would be pretty trivial to write a simple command line parser ourselves. We already have all the structure and logic for parsing slice files, comments, and preprocessor directives; command line options can't be any harder than any of those things.

Like, Clap is neat, but we're perfectly capable of replacing it with a simple hand-written parser of our own.

I don't think Clap is the problem, it's just setup wrong.

[externl]

Here's the latest output:

The slicec-cs compiler, for compiling Slice files into C# code.


Usage: slicec-cs [OPTIONS] <SOURCES>...

Arguments:
  <SOURCES>...  List of Slice files to compile

Options:
  -R <REFERENCE>
          Reference Slice file or directory containing Slice files. Reference files are used to resolve definitions in the Slice sources being compiled. Directories are searched recursively. This option can be repeated
  -D <DEFINITION>
          Define a preprocessor definition. Preprocessor definitions do not have associated values. This option can be repeated
  -W
          Instruct the compiler to treat warnings as errors
  -A, --allow <WARNING>
          Instruct the compiler to allow the specified warning. An allowed warning will not be emitted as a diagnostic. This option can be repeated
      --dry-run
          Validate input files without generating code for them
  -O, --output-dir <OUTPUT_DIR>
          Set the output directory for the generated code. Defaults to the current working directory
      --diagnostic-format <DIAGNOSTIC_FORMAT>
          Output format for emitted errors [default: human] [possible values: human, json]
      --disable-color
          Disable ANSI color codes in diagnostic output
  -h, --help
          Print help (see more with '--help')
  -V, --version
          Print version

[InsertCreativityHere]

Looks fine, just some nitpicks about the wording of some messages!