소스 검색

Make all the option descriptions the same

The old option descriptions were all written at different times, and needed some consistency. This makes everything consistent between the help text, README, man page, and shell completions, and fixes some mistakes made when writing them.

This also adds the missing options to the man page, fixing #175.
Benjamin Sago 8 년 전
부모
커밋
e2f73927c7
6개의 변경된 파일148개의 추가작업 그리고 134개의 파일을 삭제
  1. 27 27
      README.md
  2. 12 12
      contrib/completions.fish
  3. 11 10
      contrib/completions.zsh
  4. 39 28
      contrib/man/exa.1
  5. 30 28
      src/options/help.rs
  6. 29 29
      src/options/mod.rs

+ 27 - 27
README.md

@@ -14,21 +14,21 @@ exa’s options are similar, but not exactly the same, as `ls`.
 ### Display Options
 
 - **-1**, **--oneline**: display one entry per line
-- **-G**, **--grid**: display entries in a grid view (default)
+- **-G**, **--grid**: display entries as a grid (default)
 - **-l**, **--long**: display extended details and attributes
 - **-R**, **--recurse**: recurse into directories
-- **-T**, **--tree**: recurse into subdirectories in a tree view
-- **-x**, **--across**: sort multi-column view entries across
-- **--color**, **--colour**: when to colourise the output
-- **--color-scale**, **--colour-scale**: colour file sizes according to their magnitude
+- **-T**, **--tree**: recurse into directories as a tree
+- **-x**, **--across**: sort the grid across, rather than downwards
+- **--colo[u]r**: when to use terminal colours
+- **--colo[u]r-scale**: highlight levels of file sizes distinctly
 
 ### Filtering Options
 
-- **-a**, **--all**: show dot files
-- **-d**, **--list-dirs**: list directories as regular files
-- **-L**, **--level=(depth)**: maximum depth of recursion
-- **-r**, **--reverse**: reverse sort order
-- **-s**, **--sort=(field)**: field to sort by
+- **-a**, **--all**: don't hide hidden and 'dot' files
+- **-d**, **--list-dirs**: list directories like regular files
+- **-L**, **--level=(depth)**: limit the depth of recursion
+- **-r**, **--reverse**: reverse the sort order
+- **-s**, **--sort=(field)**: which field to sort by
 - **--group-directories-first**: list directories before other files
 - **-I**, **--ignore-glob=(globs)**: glob patterns (pipe-separated) of files to ignore
 
@@ -36,23 +36,23 @@ exa’s options are similar, but not exactly the same, as `ls`.
 
 These options are available when running with --long (`-l`):
 
-- **-b**, **--binary**: use binary (power of two) file sizes
-- **-B**, **--bytes**: list file sizes in bytes, without prefixes
-- **-g**, **--group**: show group as well as user
-- **-h**, **--header**: show a header row
-- **-H**, **--links**: show number of hard links column
-- **-i**, **--inode**: show inode number column
-- **-m**, **--modified**: display timestamp of most recent modification
-- **-S**, **--blocks**: show number of file system blocks
-- **-t**, **--time=(field)**: which timestamp to show for a file
-- **-u**, **--accessed**: display timestamp of last access for a file
-- **-U**, **--created**: display timestamp of creation of a file
-- **-@**, **--extended**: display extended attribute keys and sizes
-- **--git**: show Git status for a file
-
-Accepted **--color** options are **always**, **automatic**, and **never**.
-Valid sort fields are **name**, **size**, **extension**, **modified**, **accessed**, **created**, **inode**, and **none**.
-Valid time fields are **modified**, **accessed**, and **created**.
+- **-b**, **--binary**: list file sizes with binary prefixes
+- **-B**, **--bytes**: list file sizes in bytes, without any prefixes
+- **-g**, **--group**: list each file's group
+- **-h**, **--header**: add a header row to each column
+- **-H**, **--links**: list each file's number of hard links
+- **-i**, **--inode**: list each file's inode number
+- **-m**, **--modified**: use the modified timestamp field
+- **-S**, **--blocks**: list each file's number of file system blocks
+- **-t**, **--time=(field)**: which timestamp field to use
+- **-u**, **--accessed**: use the accessed timestamp field
+- **-U**, **--created**: use the created timestamp field
+- **-@**, **--extended**: list each file's extended attributes and sizes
+- **--git**: list each file's Git status, if tracked
+
+- Valid **--color** options are **always**, **automatic**, and **never**.
+- Valid sort fields are **accessed**, **created**, **extension**, **Extension**, **inode**, **modified**, **name**, **Name**, **size**, and **none**. Fields starting with a capital letter are case-sensitive.
+- Valid time fields are **modified**, **accessed**, and **created**.
 
 
 ## Installation

+ 12 - 12
contrib/completions.fish

@@ -4,11 +4,11 @@ complete -c exa -s '?' -l 'help'    -d "Show list of command-line options"
 
 # Display options
 complete -c exa -s '1' -l 'oneline'      -d "Display one entry per line"
+complete -c exa -s 'l' -l 'long'         -d "Display extended file metadata as a table"
 complete -c exa -s 'G' -l 'grid'         -d "Display entries in a grid"
-complete -c exa -s 'l' -l 'long'         -d "Display extended details and attributes"
+complete -c exa -s 'x' -l 'across'       -d "Sort the grid across, rather than downwards"
 complete -c exa -s 'R' -l 'recurse'      -d "Recurse into directories"
 complete -c exa -s 'T' -l 'tree'         -d "Recurse into directories as a tree"
-complete -c exa -s 'x' -l 'across'       -d "Sort multi-column view entries accross"
 complete -c exa -s 'F' -l 'classify'     -d "Display type indicator by file names"
 complete -c exa        -l 'color'        -d "When to use terminal colours"
 complete -c exa        -l 'colour'       -d "When to use terminal colours"
@@ -19,6 +19,7 @@ complete -c exa        -l 'colour-scale' -d "Highlight levels of file sizes dist
 complete -c exa -l 'group-directories-first' -d "Sort directories before other files"
 complete -c exa -s 'a' -l 'all'       -d "Don't hide hidden and 'dot' files"
 complete -c exa -s 'd' -l 'list-dirs' -d "List directories like regular files"
+complete -c exa -s 'L' -l 'level'     -d "Limit the depth of recursion" -a "1 2 3 4 5 6 7 8 9"
 complete -c exa -s 'r' -l 'reverse'   -d "Reverse the sort order"
 complete -c exa -s 's' -l 'sort'   -x -d "Which field to sort by" -a "
     accessed\t'Sort by file accessed time'
@@ -40,16 +41,15 @@ complete -c exa -s 's' -l 'sort'   -x -d "Which field to sort by" -a "
 complete -c exa -s 'I' -l 'ignore-glob' -d "Ignore files that match these glob patterns" -r
 
 # Long view options
-complete -c exa -s 'b' -l 'binary'   -d "Display file sizes with binary prefixes"
-complete -c exa -s 'B' -l 'bytes'    -d "Display file sizes in bytes, without any prefixes"
-complete -c exa -s 'g' -l 'group'    -d "Show each file's group"
+complete -c exa -s 'b' -l 'binary'   -d "List file sizes with binary prefixes"
+complete -c exa -s 'B' -l 'bytes'    -d "List file sizes in bytes, without any prefixes"
+complete -c exa -s 'g' -l 'group'    -d "List each file's group"
 complete -c exa -s 'h' -l 'header'   -d "Add a header row to each column"
-complete -c exa -s 'h' -l 'links'    -d "Show each file's number of hard links"
-complete -c exa -s 'g' -l 'group'    -d "Show each file's inode number"
-complete -c exa -s 'L' -l 'level'    -d "Limit the depth of recursion" -a "1 2 3 4 5 6 7 8 9"
+complete -c exa -s 'h' -l 'links'    -d "List each file's number of hard links"
+complete -c exa -s 'g' -l 'group'    -d "List each file's inode number"
 complete -c exa -s 'm' -l 'modified' -d "Use the modified timestamp field"
-complete -c exa -s 'S' -l 'blocks'   -d "Show each file's number of filesystem blocks"
-complete -c exa -s 't' -l 'time'  -x -d "Which time field to show" -a "
+complete -c exa -s 'S' -l 'blocks'   -d "List each file's number of filesystem blocks"
+complete -c exa -s 't' -l 'time'  -x -d "Which timestamp field to list" -a "
     accessed\t'Display accessed time'
     created\t'Display created time'
     modified\t'Display modified time'
@@ -58,5 +58,5 @@ complete -c exa -s 'u' -l 'accessed' -d "Use the accessed timestamp field"
 complete -c exa -s 'U' -l 'created'  -d "Use the created timestamp field"
 
 # Optional extras
-complete -c exa -s 'g' -l 'git'      -d "Show the group column"
-complete -c exa -s '@' -l 'extended' -d "Show each file's extended attributes and sizes"
+complete -c exa -s 'g' -l 'git'      -d "List each file's Git status, if tracked"
+complete -c exa -s '@' -l 'extended' -d "List each file's extended attributes and sizes"

+ 11 - 10
contrib/completions.zsh

@@ -5,8 +5,9 @@ __exa() {
         "(- 1 *)"{-v,--version}"[Show version of exa]" \
         "(- 1 *)"{-\?,--help}"[Show list of command-line options]" \
         {-1,--oneline}"[Display one entry per line]" \
+        {-l,--long}"[Display extended file metadata as a table]" \
         {-G,--grid}"[Display entries as a grid]" \
-        {-l,--long}"[Display extended metadata as a table]" \
+        {-x,--across}"[Sort the grid across, rather than downwards]" \
         {-R,--recurse}"[Recurse into directories]" \
         {-T,--tree}"[Recurse into directories as a tree]" \
         {-F,--classify}"[Display type indicator by file names]" \
@@ -15,23 +16,23 @@ __exa() {
         --group-directories-first"[Sort directories before other files]" \
         {-a,--all}"[Don't hide hidden and 'dot' files]" \
         {-d,--list-dirs}"[List directories like regular files]" \
+        {-L,--level}"+[Limit the depth of recursion]" \
         {-r,--reverse}"[Reverse the sort order]" \
         {-s,--sort}"[Which field to sort by]:(sort field):(accessed created extension Extension filename Filename inode modified name Name none size)" \
         {-I,--ignore-glob}"[Ignore files that match these glob patterns]" \
-        {-b,--binary}"[Display file sizes with binary prefixes]" \
-        {-B,--bytes}"[Display file sizes in bytes, without any prefixes]" \
-        {-g,--group}"[Show each file's group]" \
+        {-b,--binary}"[List file sizes with binary prefixes]" \
+        {-B,--bytes}"[List file sizes in bytes, without any prefixes]" \
+        {-g,--group}"[List each file's group]" \
         {-h,--header}"[Add a header row to each column]" \
-        {-H,--links}"[Show each file's number of hard links]" \
-        {-i,--inode}"[Show each file's inode number]" \
-        {-L,--level}"+[Limit the depth of recursion]" \
+        {-H,--links}"[List each file's number of hard links]" \
+        {-i,--inode}"[List each file's inode number]" \
         {-m,--modified}"[Use the modified timestamp field]" \
-        {-S,--blocks}"[Show each file's number of filesystem blocks]" \
+        {-S,--blocks}"[List each file's number of filesystem blocks]" \
         {-t,--time}"[Which time field to show]:(time field):(accessed created modified)" \
         {-u,--accessed}"[Use the accessed timestamp field]" \
         {-U,--created}"[Use the created timestamp field]" \
-        {-U,--created}"[Show each file's Git status, if tracked]" \
-        {-@,--extended}"[Show each file's extended attributes and sizes]" \
+        --git"[List each file's Git status, if tracked]" \
+        {-@,--extended}"[List each file's extended attributes and sizes]" \
         '*:filename:_files'
 }
 

+ 39 - 28
contrib/man/exa.1

@@ -1,5 +1,5 @@
 .hy
-.TH "exa" "1" "2015\-10\-18" "exa 0.4.0" ""
+.TH "exa" "1" "2017\-05\-06" "exa 0.5.0" ""
 .SH NAME
 .PP
 exa \- a modern replacement for ls
@@ -23,12 +23,17 @@ display one entry per line
 .RE
 .TP
 .B \-G, \-\-grid
-display entries in a grid view (default)
+display entries as a grid (default)
 .RS
 .RE
 .TP
 .B \-l, \-\-long
-display extended details and attributes
+display extended file metadata as a table
+.RS
+.RE
+.TP
+.B \-x, \-\-across
+sort the grid across, rather than downwards
 .RS
 .RE
 .TP
@@ -38,39 +43,45 @@ recurse into directories
 .RE
 .TP
 .B \-T, \-\-tree
-recurse into subdirectories in a tree view
+recurse into directories as a tree
 .RS
 .RE
 .TP
-.B \-x, \-\-across
-sort multi\-column view entries across
+.B \-\-color, \-\-colour=\f[I]WHEN\f[]
+when to use terminal colours (always, automatic, never)
 .RS
 .RE
 .TP
-.B \-\-color, \-\-colour=\f[I]WHEN\f[]
-when to colourise the output (always, automatic, never)
+.B \-\-color-scale, \-\-colour-scale
+highlight levels of file sizes distinctly
 .RS
 .RE
 .SH FILTERING AND SORTING OPTIONS
 .TP
 .B \-a, \-\-all
-show dot\-files
+don\[aq]t hide hidden and \[aq]dot\[aq] files
 .RS
 .RE
 .TP
 .B \-d, \-\-list\-dirs
-list directories as regular files
+list directories like regular files
 .RS
 .RE
 .TP
 .B \-r, \-\-reverse
-reverse order of files
+reverse the sort order
+.RS
+.RE
+.TP
+.B \-s, \-\-sort=\f[I]SORT_FIELD\f[]
+which field to sort by.
+Valid fields are name, Name, extension, Extension, size, modified, accessed, created, inode, and none.
+Fields starting with a capital letter are case-sensitive.
 .RS
 .RE
 .TP
-.B \-s, \-\-sort=\f[I]WORD\f[]
-field to sort by (name, size, extension, modified, accessed, created,
-inode, none)
+.B \-I, \-\-ignore\-glob=\f[I]GLOBS\f[]
+Glob patterns, pipe-separated, of files to ignore
 .RS
 .RE
 .TP
@@ -84,72 +95,72 @@ These options are available when running with \f[C]\-\-long\f[]
 (\f[C]\-l\f[]):
 .TP
 .B \-b, \-\-binary
-use binary prefixes in file sizes
+list file sizes with binary prefixes
 .RS
 .RE
 .TP
 .B \-B, \-\-bytes
-list file sizes in bytes, without prefixes
+list file sizes in bytes, without any prefixes
 .RS
 .RE
 .TP
 .B \-g, \-\-group
-show group as well as user
+list each file\[aq]s group
 .RS
 .RE
 .TP
 .B \-h, \-\-header
-show a header row at the top
+add a header row to each column
 .RS
 .RE
 .TP
 .B \-H, \-\-links
-show number of hard links
+list each file\[aq]s number of hard links
 .RS
 .RE
 .TP
 .B \-i, \-\-inode
-show each file\[aq]s inode number
+list each file\[aq]s inode number
 .RS
 .RE
 .TP
 .B \-L, \-\-level=\f[I]DEPTH\f[]
-maximum depth of recursion
+limit the depth of recursion
 .RS
 .RE
 .TP
 .B \-m, \-\-modified
-display timestamp of most recent modification
+use the modified timestamp field
 .RS
 .RE
 .TP
 .B \-S, \-\-blocks
-show number of file system blocks
+list each file\[aq]s number of file system blocks
 .RS
 .RE
 .TP
 .B \-t, \-\-time=\f[I]WORD\f[]
-which timestamp to show for a file (modified, accessed, created)
+which timestamp field to list (modified, accessed, created)
 .RS
 .RE
 .TP
 .B \-u, \-\-accessed
-display timestamp of last access for a file
+use the accessed timestamp field
 .RS
 .RE
 .TP
 .B \-U, \-\-created
-display timestamp of creation for a file
+use the created timestamp field
 .RS
 .RE
 .TP
 .B \-\@, \-\-extended
-display extended attribute keys and sizes
+list each file\[aq]s extended attributes and sizes
 .RS
 .RE
 .TP
 .B \-\-git
-display Git status for a file, if available
+list each file\[aq]s Git status, if tracked
 .RS
 .RE
 .SH EXAMPLES

+ 30 - 28
src/options/help.rs

@@ -1,44 +1,46 @@
 
 pub static OPTIONS: &'static str = r##"
+  -?, --help         show list of command-line options
+  -v, --version      show version of exa
+
 DISPLAY OPTIONS
   -1, --oneline      display one entry per line
-  -G, --grid         display entries in a grid view (default)
-  -l, --long         display extended details and attributes
+  -l, --long         display extended file metadata as a table
+  -G, --grid         display entries as a grid (default)
+  -x, --across       sort the grid across, rather than downwards
   -R, --recurse      recurse into directories
-  -T, --tree         recurse into subdirectories in a tree view
-  -x, --across       sort multi-column view entries across
-  -F, --classify     show file type indicator (one of */=@|)
-
-  --color=WHEN,  --colour=WHEN   when to colourise the output (always, auto, never)
-  --color-scale, --colour-scale  colour file sizes according to their magnitude
+  -T, --tree         recurse into directories as a tree
+  -F, --classify     display type indicator by file names
+  --colo[u]r=WHEN    when to use terminal colours (always, auto, never)
+  --colo[u]r-scale   highlight levels of file sizes distinctly
 
 FILTERING AND SORTING OPTIONS
-  -a, --all                  show dot-files
-  -d, --list-dirs            list directories as regular files
-  -r, --reverse              reverse order of files
-  -s, --sort SORT_FIELD      field to sort by. Choices: name,
-                                 size, extension, modified,
-                                 accessed, created, inode, none
+  -a, --all                  don't hide hidden and 'dot' files
+  -d, --list-dirs            list directories like regular files
+  -r, --reverse              reverse the sort order
+  -s, --sort SORT_FIELD      which field to sort by:
   --group-directories-first  list directories before other files
   -I, --ignore-glob GLOBS    glob patterns (pipe-separated) of files to ignore
+  Valid sort fields:         name, Name, extension, Extension, size,
+                             modified, accessed, created, inode, none
+
 "##;
 
 pub static LONG_OPTIONS: &'static str = r##"
 LONG VIEW OPTIONS
-  -b, --binary       use binary prefixes in file sizes
-  -B, --bytes        list file sizes in bytes, without prefixes
-  -g, --group        show group as well as user
-  -h, --header       show a header row at the top
-  -H, --links        show number of hard links
-  -i, --inode        show each file's inode number
-  -L, --level DEPTH  maximum depth of recursion
-  -m, --modified     display timestamp of most recent modification
+  -b, --binary       list file sizes with binary prefixes
+  -B, --bytes        list file sizes in bytes, without any prefixes
+  -g, --group        list each file's group
+  -h, --header       add a header row to each column
+  -H, --links        list each file's number of hard links
+  -i, --inode        list each file's inode number
+  -L, --level DEPTH  limit the depth of recursion
+  -m, --modified     use the modified timestamp field
   -S, --blocks       show number of file system blocks
-  -t, --time FIELD   which timestamp to show for a file. Choices:
-                         modified, accessed, created
-  -u, --accessed     display timestamp of last access for a file
-  -U, --created      display timestamp of creation for a file
+  -t, --time FIELD   which timestamp field to list (modified, accessed, created)
+  -u, --accessed     use the accessed timestamp field
+  -U, --created      use the created timestamp field
 "##;
 
-pub static GIT_HELP:      &'static str = r##"  --git              show git status for files"##;
-pub static EXTENDED_HELP: &'static str = r##"  -@, --extended     display extended attribute keys and sizes"##;
+pub static GIT_HELP:      &'static str = r##"  --git              list each file's Git status, if tracked"##;
+pub static EXTENDED_HELP: &'static str = r##"  -@, --extended     list each file's extended attributes and sizes"##;

+ 29 - 29
src/options/mod.rs

@@ -45,50 +45,50 @@ impl Options {
     where S: AsRef<OsStr> {
         let mut opts = getopts::Options::new();
 
-        opts.optflag("v", "version",   "display version of exa");
+        opts.optflag("v", "version",   "show version of exa");
         opts.optflag("?", "help",      "show list of command-line options");
 
         // Display options
         opts.optflag("1", "oneline",      "display one entry per line");
-        opts.optflag("G", "grid",         "display entries in a grid view (default)");
-        opts.optflag("l", "long",         "display extended details and attributes");
+        opts.optflag("l", "long",         "display extended file metadata in a table");
+        opts.optflag("G", "grid",         "display entries as a grid (default)");
+        opts.optflag("x", "across",       "sort the grid across, rather than downwards");
         opts.optflag("R", "recurse",      "recurse into directories");
-        opts.optflag("T", "tree",         "recurse into subdirectories in a tree view");
-        opts.optflag("x", "across",       "sort multi-column view entries across");
-        opts.optflag("F", "classify",     "show file type indicator (one of */=@|)");
-        opts.optopt ("",  "color",        "when to show anything in colours", "WHEN");
-        opts.optopt ("",  "colour",       "when to show anything in colours (alternate spelling)", "WHEN");
-        opts.optflag("",  "color-scale",  "use a colour scale when displaying file sizes (alternate spelling)");
-        opts.optflag("",  "colour-scale", "use a colour scale when displaying file sizes");
+        opts.optflag("T", "tree",         "recurse into directories as a tree");
+        opts.optflag("F", "classify",     "display type indicator by file names (one of */=@|)");
+        opts.optopt ("",  "color",        "when to use terminal colours", "WHEN");
+        opts.optopt ("",  "colour",       "when to use terminal colours", "WHEN");
+        opts.optflag("",  "color-scale",  "highlight levels of file sizes distinctly");
+        opts.optflag("",  "colour-scale", "highlight levels of file sizes distinctly");
 
         // Filtering and sorting options
-        opts.optflag("",  "group-directories-first", "list directories before other files");
-        opts.optflag("a", "all",         "show dot-files");
-        opts.optflag("d", "list-dirs",   "list directories as regular files");
-        opts.optflag("r", "reverse",     "reverse order of files");
-        opts.optopt ("s", "sort",        "field to sort by", "WORD");
-        opts.optopt ("I", "ignore-glob", "patterns (|-separated) of names to ignore", "GLOBS");
+        opts.optflag("",  "group-directories-first", "sort directories before other files");
+        opts.optflag("a", "all",         "don't hide hidden and 'dot' files");
+        opts.optflag("d", "list-dirs",   "list directories like regular files");
+        opts.optopt ("L", "level",       "limit the depth of recursion", "DEPTH");
+        opts.optflag("r", "reverse",     "reverse the sert order");
+        opts.optopt ("s", "sort",        "which field to sort by", "WORD");
+        opts.optopt ("I", "ignore-glob", "ignore files that match these glob patterns", "GLOB1|GLOB2...");
 
         // Long view options
-        opts.optflag("b", "binary",    "use binary prefixes in file sizes");
+        opts.optflag("b", "binary",    "list file sizes with binary prefixes");
         opts.optflag("B", "bytes",     "list file sizes in bytes, without prefixes");
-        opts.optflag("g", "group",     "show group as well as user");
-        opts.optflag("h", "header",    "show a header row at the top");
-        opts.optflag("H", "links",     "show number of hard links");
-        opts.optflag("i", "inode",     "show each file's inode number");
-        opts.optopt ("L", "level",     "maximum depth of recursion", "DEPTH");
-        opts.optflag("m", "modified",  "display timestamp of most recent modification");
-        opts.optflag("S", "blocks",    "show number of file system blocks");
-        opts.optopt ("t", "time",      "which timestamp to show for a file", "WORD");
-        opts.optflag("u", "accessed",  "display timestamp of last access for a file");
-        opts.optflag("U", "created",   "display timestamp of creation for a file");
+        opts.optflag("g", "group",     "list each file's group");
+        opts.optflag("h", "header",    "add a header row to each column");
+        opts.optflag("H", "links",     "list each file's number of hard links");
+        opts.optflag("i", "inode",     "list each file's inode number");
+        opts.optflag("m", "modified",  "use the modified timestamp field");
+        opts.optflag("S", "blocks",    "list each file's number of file system blocks");
+        opts.optopt ("t", "time",      "which timestamp field to show", "WORD");
+        opts.optflag("u", "accessed",  "use the accessed timestamp field");
+        opts.optflag("U", "created",   "use the created timestamp field");
 
         if cfg!(feature="git") {
-            opts.optflag("", "git", "show git status");
+            opts.optflag("", "git", "list each file's git status");
         }
 
         if xattr::ENABLED {
-            opts.optflag("@", "extended", "display extended attribute keys and sizes");
+            opts.optflag("@", "extended", "list each file's extended attribute keys and sizes");
         }
 
         let matches = match opts.parse(args) {