From b2507dbb4a3b6b34c9951cdef1c1c58c8f9ce5a0 Mon Sep 17 00:00:00 2001 From: Ryan Zimmerman Date: Wed, 26 Aug 2020 16:14:34 -0400 Subject: [PATCH] Organize and clarify --help text --- README.md | 46 +++++++++++++++++++++++++--------------------- lib/args.js | 29 +++++++++++++++-------------- 2 files changed, 40 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 4eeb62a..50bade6 100644 --- a/README.md +++ b/README.md @@ -30,33 +30,36 @@ Usage: postcss ... [OPTIONS] --replace Basic options: - -o, --output Output file [string] - -d, --dir Output directory [string] - -r, --replace Replace (overwrite) the input file [boolean] - --map, -m Create an external sourcemap - --no-map Disable the default inline sourcemaps - --verbose Be verbose [boolean] - --watch, -w Watch files for changes and recompile as needed [boolean] - --env A shortcut for setting NODE_ENV [string] - --include-dotfiles Enables glob to match files/dirs that begin with "." [boolean] - -Options for when not using a config file: + -o, --output Output file [string] + -d, --dir Output directory [string] + -r, --replace Replace (overwrite) the input file [boolean] + -m, --map Create an external sourcemap + --no-map Disable the default inline sourcemaps + -w, --watch Watch files for changes and recompile as needed [boolean] + --verbose Be verbose [boolean] + --env A shortcut for setting NODE_ENV [string] + +Options for use without a config file: -u, --use List of postcss plugins to use [array] --parser Custom postcss parser [string] --stringifier Custom postcss stringifier [string] --syntax Custom postcss syntax [string] +Options for use with --dir: + --ext Override the output file extension; for use with --dir [string] + --base Mirror the directory structure relative to this path in the output + directory, for use with --dir [string] + Advanced options: - --ext Override the output file extension; for use with --dir [string] - --base Mirror the directory structure relative to this path in the output - directory, for use with --dir [string] - --poll Use polling for file watching. Can optionally pass polling interval; - default 100 ms - --config Set a custom directory to look for a config file [string] + --include-dotfiles Enable glob to match files/dirs that begin with "." + [boolean] + --poll Use polling for file watching. Can optionally pass polling + interval; default 100 ms + --config Set a custom directory to look for a config file [string] Options: - --version Show version number [boolean] - -h, --help Show help [boolean] + --version Show version number [boolean] + -h, --help Show help [boolean] Examples: postcss input.css -o output.css Basic usage @@ -68,8 +71,9 @@ If no input files are passed, it reads from stdin. If neither -o, --dir, or If there are multiple input files, the --dir or --replace option must be passed. -Input files may contain globs (e.g. src/**/*.css). If you pass an input directory, it will process -all files in the directory and any subdirectories, respecting the glob pattern. +Input files may contain globs (e.g. src/**/*.css). If you pass an input +directory, it will process all files in the directory and any subdirectories, +respecting the glob pattern. ``` > ℹ️ More details on custom parsers, stringifiers and syntaxes, can be found [here](https://github.com/postcss/postcss#syntaxes). diff --git a/lib/args.js b/lib/args.js index 9172a93..77127d3 100644 --- a/lib/args.js +++ b/lib/args.js @@ -37,7 +37,7 @@ Usage: $0 ... [OPTIONS] --replace` ) .group( - ['o', 'd', 'r', 'map', 'no-map', 'verbose', 'watch', 'env'], + ['o', 'd', 'r', 'map', 'no-map', 'watch', 'verbose', 'env'], 'Basic options:' ) .option('o', { @@ -58,30 +58,26 @@ Usage: type: 'boolean', conflicts: ['output', 'dir'], }) - .option('include-dotfiles', { - desc: 'Enables glob to match files/dirs that begin with "."', - type: 'boolean', - }) - .alias('map', 'm') + .alias('m', 'map') .describe('map', 'Create an external sourcemap') .describe('no-map', 'Disable the default inline sourcemaps') - .option('verbose', { - desc: 'Be verbose', - type: 'boolean', - }) - .option('watch', { - alias: 'w', + .option('w', { + alias: 'watch', desc: 'Watch files for changes and recompile as needed', type: 'boolean', conflicts: 'replace', }) + .option('verbose', { + desc: 'Be verbose', + type: 'boolean', + }) .option('env', { desc: 'A shortcut for setting NODE_ENV', type: 'string', }) .group( ['u', 'parser', 'stringifier', 'syntax'], - 'Options for when not using a config file:' + 'Options for use without a config file:' ) .option('u', { alias: 'use', @@ -100,7 +96,7 @@ Usage: desc: 'Custom postcss syntax', type: 'string', }) - .group(['ext', 'base', 'poll', 'config'], 'Advanced options:') + .group(['ext', 'base'], 'Options for use with --dir:') .option('ext', { desc: 'Override the output file extension; for use with --dir', type: 'string', @@ -116,6 +112,11 @@ Usage: type: 'string', implies: 'dir', }) + .group(['include-dotfiles', 'poll', 'config'], 'Advanced options:') + .option('include-dotfiles', { + desc: 'Enable glob to match files/dirs that begin with "."', + type: 'boolean', + }) .option('poll', { desc: 'Use polling for file watching. Can optionally pass polling interval; default 100 ms',