Revise TypeScript CLI help documentation

[orta]

⭐ Suggestion

We'd like to give the TypeScript CLI's help a fresh lick of paint! The tsc --help is often the second command someone would run after tsc to understand what is going on, and we're like the output to focus on improving your knowledge of how to use the CLI.

There are two modes for --help, the default and --help --all.

I'd like to use a mix of color, weighting, spacing and some more examples to make the CLI fit in with modern CLI projects and try to be a bit closer to the CLI HIG. You can clone a prototype of the CLI at https://github.com/orta/tsc-cli-example

📃 What it looks like:

💻 Details

The default --help usage section

The common compiler section. The defaults can be found here

Using --help --all where it uses the categories for compiler flags

Interested in building this?

I'd expect the majority of the work to be in compilerParser.ts and executeCommandLine.ts - with some of the new copy being added into the diagnosticMessages.json.

I'm available in the TypeScript Community discord to chat design and edge cases!

Misc

Current 4.2.4 CLI output for tsc --help.

$ /home/orta/dev/ts/node_modules/.bin/tsc --help
Version 4.2.4
Syntax:   tsc [options] [file...]

Examples: tsc hello.ts
          tsc --outFile file.js file.ts
          tsc @args.txt
          tsc --build tsconfig.json

Options:
 -h, --help                                         Print this message.
 -w, --watch                                        Watch input files.
 --pretty                                           Stylize errors and messages using color and context (experimental).
 --all                                              Show all compiler options.
 -v, --version                                      Print the compiler's version.
 --init                                             Initializes a TypeScript project and creates a tsconfig.json file.
 -p FILE OR DIRECTORY, --project FILE OR DIRECTORY  Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.
 -b, --build                                        Build one or more projects and their dependencies, if out of date
 -t VERSION, --target VERSION                       Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', or 'ESNEXT'.
 -m KIND, --module KIND                             Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'.
 --lib                                              Specify library files to be included in the compilation.
                                                      'es5' 'es6' 'es2015' 'es7' 'es2016' 'es2017' 'es2018' 'es2019' 'es2020' 'esnext' 'dom' 'dom.iterable' 'webworker' 'webworker.importscripts' 'webworker.iterable' 'scripthost' 'es2015.core' 'es2015.collection' 'es2015.generator' 'es2015.iterable' 'es2015.promise' 'es2015.proxy' 'es2015.reflect' 'es2015.symbol' 'es2015.symbol.wellknown' 'es2016.array.include' 'es2017.object' 'es2017.sharedmemory' 'es2017.string' 'es2017.intl' 'es2017.typedarrays' 'es2018.asyncgenerator' 'es2018.asynciterable' 'es2018.intl' 'es2018.promise' 'es2018.regexp' 'es2019.array' 'es2019.object' 'es2019.string' 'es2019.symbol' 'es2020.bigint' 'es2020.promise' 'es2020.sharedmemory' 'es2020.string' 'es2020.symbol.wellknown' 'es2020.intl' 'esnext.array' 'esnext.symbol' 'esnext.asynciterable' 'esnext.intl' 'esnext.bigint' 'esnext.string' 'esnext.promise' 'esnext.weakref' 
 --allowJs                                          Allow javascript files to be compiled.
 --jsx KIND                                         Specify JSX code generation: 'preserve', 'react-native', 'react', 'react-jsx' or 'react-jsxdev'.
 -d, --declaration                                  Generates corresponding '.d.ts' file.
 --declarationMap                                   Generates a sourcemap for each corresponding '.d.ts' file.
 --sourceMap                                        Generates corresponding '.map' file.
 --outFile FILE                                     Concatenate and emit output to single file.
 --outDir DIRECTORY                                 Redirect output structure to the directory.
 --removeComments                                   Do not emit comments to output.
 --noEmit                                           Do not emit outputs.
 --strict                                           Enable all strict type-checking options.
 --noImplicitAny                                    Raise error on expressions and declarations with an implied 'any' type.
 --strictNullChecks                                 Enable strict null checks.
 --strictFunctionTypes                              Enable strict checking of function types.
 --strictBindCallApply                              Enable strict 'bind', 'call', and 'apply' methods on functions.
 --strictPropertyInitialization                     Enable strict checking of property initialization in classes.
 --noImplicitThis                                   Raise error on 'this' expressions with an implied 'any' type.
 --alwaysStrict                                     Parse in strict mode and emit "use strict" for each source file.
 --noUnusedLocals                                   Report errors on unused locals.
 --noUnusedParameters                               Report errors on unused parameters.
 --noImplicitReturns                                Report error when not all code paths in function return a value.
 --noFallthroughCasesInSwitch                       Report errors for fallthrough cases in switch statement.
 --types                                            Type declaration files to be included in compilation.
 --esModuleInterop                                  Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'.
 @<file>                                            Insert command line options and files from a file.
Done in 0.13s.

Current 4.2.4 CLI output for tsc --help --all.

$ /home/orta/dev/ts/node_modules/.bin/tsc --help
Version 4.2.4
Syntax:   tsc [options] [file...]

Examples: tsc hello.ts
          tsc --outFile file.js file.ts
          tsc @args.txt
          tsc --build tsconfig.json

Options:
 -h, --help                                         Print this message.
 -w, --watch                                        Watch input files.
 --pretty                                           Stylize errors and messages using color and context (experimental).
 --all                                              Show all compiler options.
 -v, --version                                      Print the compiler's version.
 --init                                             Initializes a TypeScript project and creates a tsconfig.json file.
 -p FILE OR DIRECTORY, --project FILE OR DIRECTORY  Compile the project given the path to its configuration file, or to a folder with a 'tsconfig.json'.
 -b, --build                                        Build one or more projects and their dependencies, if out of date
 -t VERSION, --target VERSION                       Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', or 'ESNEXT'.
 -m KIND, --module KIND                             Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'.
 --lib                                              Specify library files to be included in the compilation.
                                                      'es5' 'es6' 'es2015' 'es7' 'es2016' 'es2017' 'es2018' 'es2019' 'es2020' 'esnext' 'dom' 'dom.iterable' 'webworker' 'webworker.importscripts' 'webworker.iterable' 'scripthost' 'es2015.core' 'es2015.collection' 'es2015.generator' 'es2015.iterable' 'es2015.promise' 'es2015.proxy' 'es2015.reflect' 'es2015.symbol' 'es2015.symbol.wellknown' 'es2016.array.include' 'es2017.object' 'es2017.sharedmemory' 'es2017.string' 'es2017.intl' 'es2017.typedarrays' 'es2018.asyncgenerator' 'es2018.asynciterable' 'es2018.intl' 'es2018.promise' 'es2018.regexp' 'es2019.array' 'es2019.object' 'es2019.string' 'es2019.symbol' 'es2020.bigint' 'es2020.promise' 'es2020.sharedmemory' 'es2020.string' 'es2020.symbol.wellknown' 'es2020.intl' 'esnext.array' 'esnext.symbol' 'esnext.asynciterable' 'esnext.intl' 'esnext.bigint' 'esnext.string' 'esnext.promise' 'esnext.weakref' 
 --allowJs                                          Allow javascript files to be compiled.
 --jsx KIND                                         Specify JSX code generation: 'preserve', 'react-native', 'react', 'react-jsx' or 'react-jsxdev'.
 -d, --declaration                                  Generates corresponding '.d.ts' file.
 --declarationMap                                   Generates a sourcemap for each corresponding '.d.ts' file.
 --sourceMap                                        Generates corresponding '.map' file.
 --outFile FILE                                     Concatenate and emit output to single file.
 --outDir DIRECTORY                                 Redirect output structure to the directory.
 --removeComments                                   Do not emit comments to output.
 --noEmit                                           Do not emit outputs.
 --strict                                           Enable all strict type-checking options.
 --noImplicitAny                                    Raise error on expressions and declarations with an implied 'any' type.
 --strictNullChecks                                 Enable strict null checks.
 --strictFunctionTypes                              Enable strict checking of function types.
 --strictBindCallApply                              Enable strict 'bind', 'call', and 'apply' methods on functions.
 --strictPropertyInitialization                     Enable strict checking of property initialization in classes.
 --noImplicitThis                                   Raise error on 'this' expressions with an implied 'any' type.
 --alwaysStrict                                     Parse in strict mode and emit "use strict" for each source file.
 --noUnusedLocals                                   Report errors on unused locals.
 --noUnusedParameters                               Report errors on unused parameters.
 --noImplicitReturns                                Report error when not all code paths in function return a value.
 --noFallthroughCasesInSwitch                       Report errors for fallthrough cases in switch statement.
 --types                                            Type declaration files to be included in compilation.
 --esModuleInterop                                  Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'.
 // ... 

[ShuiRuTian]

Looks great! I am trying to implement the beta version.
And, sadly, in China, I could not visit discord directly, so I have to list my questions on the issues.

1. about change the line.
   Sometimes, the description might be too long and we need to use multi lines, like

|                       |
  --target, -t:    XXXXX(line break)
                   XXX

But, the column of the console might be not wide enough
what should we do in this case? Or even a worse case, like

|                   |
  --target, -t:    X
                   X
                   ...(a lot of lines! Is this acceptable?)

|       |
  --targ(oh, no! we reach the right margin of console! but we not reach the start width of description)

Maybe we could judge the width of console, if its width is enough(maybe enough for 20 chars of description?), we output pretty like this , otherwise just one line like old style.

2. Uh, how to get the width of current console? Should we add a new method to System?

[orta]

Dang, sorry about the Discord china block :-/

1 - Wrapping

I agree.

For example --disableSourceOfProjectReferenceRedirect is the longest! (41 characters) - which would only leave 80 - 41 - 2 - 2 = 35 characters on an 80 column terminal. We could pick a lower bound and instead move the description to the next line:

  --composite   
    Enable constraints that allow a TypeScript project to be used with project references.

  --disableSourceOfProjectReferenceRedirect   
    Disable preferring source files instead of declaration files when referencing composite projects.

  --disableSolutionSearching   
    Opt a project out of multi-project reference checking when editing.

  --tsBuildInfoFile   
    Specify the folder for .tsbuildinfo incremental compilation files.

  --disableReferencedProjectLoad   
    Reduce the number of projects loaded automatically by TypeScript.

Think of it as switching from 2 column to 1 column like websites do. Maybe that could work when the terminal is smaller than 60 chars?

2 - System

Yeah, I think so, and it can be grabbed in node from the stdout object:

❯ node
Welcome to Node.js v14.5.0.
Type ".help" for more information.

> process.stdout.columns
139
// I re-sized the window
> process.stdout.columns
88
>

3 - An updated image

I updated the design to be more consistent with what I said I the sidebar comments, as I got a few alignment issues in the original post

[Zzzen]

Why not use vpn? @ShuiRuTian

[ShuiRuTian]

@Zzzen Another sad story :( The experience of finding a manual to use VPN sucks, and I do not want to suck the taste again.

@orta
If type of Option is boolean or string, what should we display?
About boolean, should it be "any of: boolean" or "any of: true or false", or something else?
About string, it is "any of: string"?

In current draft PR, it is "any of: boolean" and "any of: string"

[Zzzen]

👌 Having been using cordcloud for almost two years. I can't imagine what a day would be without access to google/twitter/reddit.