update cli help, add manpage

man/Makefile

@@ -0,0 +1,7 @@
+.PHONY: clean
+
+ffs.1: ffs.1.md
+	pandoc --standalone --from markdown-smart --to man $< -o $@
+
+clean:
+	rm ffs.1

man/ffs.1

@@ -0,0 +1,150 @@
+.\" Automatically generated by Pandoc 2.9.1.1
+.\"
+.TH "FFS" "1" "" "Version 0.1.0" "File Filesystem Documentation"
+.hy
+.SH NAME
+.PP
+ffs - the file filesystem
+.SH SYNOPSIS
+.PP
+ffs [\f[I]FLAGS\f[R]/\f[I]OPTIONS\f[R]] [\f[I]INPUT\f[R]]
+.SH DESCRIPTION
+.PP
+ffs---short for the file filesystem---lets you mount semi-structured
+data as a filesystem, allowing you to work with modern formats using
+familiar shell tools.
+.SS Flags
+.TP
+-d, --debug
+Give debug output on stderr
+.TP
+--exact
+Don\[aq]t add newlines to the end of values that don\[aq]t already have
+them (or strip them when loading)
+.TP
+-i, --in-place
+Writes the output back over the input file
+.TP
+--no-output
+Disables output of filesystem (normally on stdout)
+.TP
+-q, --quiet
+Quiet mode (turns off all errors and warnings, enables
+\f[I]--no-output\f[R])
+.TP
+--readonly
+Mounted filesystem will be readonly
+.TP
+--unpadded
+Don\[aq]t pad the numeric names of list elements with zeroes; will not
+sort properly
+.TP
+-h, --help
+Prints help information (and exits)
+.TP
+-V, --version
+Prints version information (and exits)
+.SS Options
+.TP
+--dirmode \f[I]DIRMODE\f[R]
+Sets the default mode of directories (parsed as octal; if unspecified,
+directories will have \f[I]FILEMODE\f[R], with execute bits set when
+read bits are set) [default: 755]
+.TP
+--mode \f[I]FILEMODE\f[R]
+Sets the default mode of files (parsed as octal) [default: 644]
+.TP
+-g, --gid \f[I]GID\f[R]
+Sets the group id of the generated filesystem (defaults to current
+effective group id)
+.TP
+-m, --mount \f[I]MOUNT\f[R]
+Sets the mountpoint; will be inferred when using a file, but must be
+specified when running on stdin
+.TP
+-o, --output \f[I]OUTPUT\f[R]
+Sets the output file for saving changes (defaults to stdout)
+.TP
+--completions \f[I]SHELL\f[R]
+Generate shell completions and exit [possible values: bash, fish, zsh]
+.TP
+-s, --source \f[I]SOURCE_FORMAT\f[R]
+Specify the source format explicitly (by default, automatically inferred
+from filename extension) [possible values: json, toml, yaml]
+.TP
+-t, --target \f[I]TARGET_FORMAT\f[R]
+Specify the target format explicitly (by default, automatically inferred
+from filename extension) [possible values: json, toml, yaml]
+.TP
+-u, --uid \f[I]UID\f[R]
+Sets the user id of the generated filesystem (defaults to current
+effective user id)
+.SS Arguments
+.TP
+\f[I]INPUT\f[R]
+Sets the input file (use \[aq]-\[aq] for stdin) [default: -]
+.SH ENVIRONMENT
+.TP
+RUST_LOG
+Configures tracing output.
+Use the format \f[I]key\f[R]=\f[I]level\f[R], where \f[I]key\f[R] should
+probably be \f[I]ffs\f[R] and \f[I]level\f[R] should be one of
+\f[I]error\f[R], \f[I]warn\f[R], \f[I]info\f[R], \f[I]debug\f[R], or
+\f[I]trace\f[R].
+The default is \f[I]ffs=warn\f[R].
+Setting \f[I]-q\f[R] turns off all output; setting \f[I]-d\f[R] sets
+\f[I]ffs=debug\f[R].
+.SH EXAMPLES
+.PP
+The general workflow is to run \f[I]ffs\f[R], do some work, and then
+unmount the mountpoint using \f[I]umount\f[R].
+It\[aq]s typical to run \f[I]ffs\f[R] in the background, since the
+program will not terminate until the userspace filesystem is unmounted.
+.PP
+By default, \f[I]ffs\f[R] will work off of stdin, in which case you must
+specify a mountpoint with \f[I]-m\f[R].
+If you have a mountpoint/directory \f[I]mnt\f[R], you can download
+information on GitHub commits, work with them, and save the modified
+output to \f[I]commits.json\f[R] by running:
+.IP
+.nf
+\f[C]
+curl https://api.github.com/repos/mgree/ffs/commits | ffs -m mnt -o commits.json 
+\f[R]
+.fi
+.PP
+If you had already downloaded the file to \f[I]commits.json\f[R], you
+could simply run:
+.IP
+.nf
+\f[C]
+ffs -i commits.json
+# do edits in commits directory
+umount commits
+# changes are written back to commits.json (-i is in-place mode)
+\f[R]
+.fi
+.PP
+To mount a JSON file and write back out a YAML file, you could run:
+.IP
+.nf
+\f[C]
+ffs -o output_data.yaml input_data.json
+# do edits in the input_data directory ffs created
+umount input_data
+\f[R]
+.fi
+.PP
+When filenames are present, extensions will be used to infer the format
+being used.
+You can specify the source and target formats explicitly with
+\f[I]--source\f[R] and \f[I]--target\f[R], respectively.
+.SH BUGS
+.PP
+See <https://github.com/mgree/ffs/issues>.
+.SH LICENSE
+.PP
+Copyright 2021 (c) Michael Greenberg.
+GPL-3.0 licensed.
+.SH AUTHORS
+Michael Greenberg.

man/ffs.1.md

@@ -0,0 +1,166 @@
+% FFS(1) Version 0.1.0 | File Filesystem Documentation
+% Michael Greenberg
+
+# NAME
+
+ffs - the file filesystem
+
+# SYNOPSIS
+
+| ffs \[*FLAGS*/*OPTIONS*\] \[*INPUT*\]
+
+# DESCRIPTION
+
+ffs---short for the file filesystem---lets you mount semi-structured
+data as a filesystem, allowing you to work with modern formats using
+familiar shell tools.
+
+## Flags
+
+-d, --debug
+
+: Give debug output on stderr
+
+--exact
+
+: Don't add newlines to the end of values that don't already have them
+  (or strip them when loading)
+
+-i, --in-place
+
+: Writes the output back over the input file
+
+--no-output
+
+: Disables output of filesystem (normally on stdout)
+
+-q, --quiet
+
+: Quiet mode (turns off all errors and warnings, enables
+  *--no-output*)
+
+--readonly
+
+: Mounted filesystem will be readonly
+
+--unpadded
+
+: Don't pad the numeric names of list elements with zeroes; will not
+  sort properly
+
+-h, --help
+
+: Prints help information (and exits)
+
+-V, --version
+
+: Prints version information (and exits)
+
+## Options
+--dirmode *DIRMODE*
+
+: Sets the default mode of directories (parsed as octal; if
+  unspecified, directories will have *FILEMODE*, with execute bits set
+  when read bits are set) [default: 755]
+
+--mode *FILEMODE*
+
+: Sets the default mode of files (parsed as octal) [default: 644]
+
+-g, --gid *GID*
+
+: Sets the group id of the generated filesystem (defaults to current
+  effective group id)
+
+-m, --mount *MOUNT*
+
+: Sets the mountpoint; will be inferred when using a file, but must be
+  specified when running on stdin
+
+-o, --output *OUTPUT*
+
+: Sets the output file for saving changes (defaults to stdout)
+
+--completions *SHELL*
+
+: Generate shell completions and exit [possible values: bash, fish,
+  zsh]
+
+-s, --source *SOURCE_FORMAT*
+
+: Specify the source format explicitly (by default, automatically
+  inferred from filename extension) [possible values: json, toml,
+  yaml]
+
+-t, --target *TARGET_FORMAT*
+
+: Specify the target format explicitly (by default, automatically
+  inferred from filename extension) [possible values: json, toml,
+  yaml]
+
+-u, --uid *UID*
+
+: Sets the user id of the generated filesystem (defaults to current
+  effective user id)
+
+## Arguments
+
+*INPUT*
+
+: Sets the input file (use '-' for stdin) [default: -]
+
+# ENVIRONMENT
+
+RUST_LOG
+
+: Configures tracing output. Use the format *key*=*level*, where *key*
+  should probably be *ffs* and *level* should be one of *error*,
+  *warn*, *info*, *debug*, or *trace*. The default is
+  *ffs=warn*. Setting *-q* turns off all output; setting *-d* sets
+  *ffs=debug*.
+
+# EXAMPLES
+
+The general workflow is to run *ffs*, do some work, and then unmount
+the mountpoint using *umount*. It's typical to run *ffs* in the
+background, since the program will not terminate until the userspace
+filesystem is unmounted.
+
+By default, *ffs* will work off of stdin, in which case you must
+specify a mountpoint with *-m*.  If you have a mountpoint/directory
+*mnt*, you can download information on GitHub commits, work with them,
+and save the modified output to *commits.json* by running:
+
+```
+curl https://api.github.com/repos/mgree/ffs/commits | ffs -m mnt -o commits.json 
+```
+
+If you had already downloaded the file to *commits.json*, you could simply run:
+
+```
+ffs -i commits.json
+# do edits in commits directory
+umount commits
+# changes are written back to commits.json (-i is in-place mode)
+```
+
+To mount a JSON file and write back out a YAML file, you could run:
+
+```
+ffs -o output_data.yaml input_data.json
+# do edits in the input_data directory ffs created
+umount input_data
+```
+
+When filenames are present, extensions will be used to infer the
+format being used. You can specify the source and target formats
+explicitly with *--source* and *--target*, respectively.
+
+# BUGS
+
+See
+[https://github.com/mgree/ffs/issues](https://github.com/mgree/ffs/issues).
+
+# LICENSE
+
+Copyright 2021 (c) Michael Greenberg. GPL-3.0 licensed.

src/cli.rs

@@ -46,14 +46,14 @@ pub fn app() -> App<'static, 'static> {
         )
         .arg(
             Arg::with_name("FILEMODE")
-                .help("Sets the default mode of files (parsed as octal; defaults to 644; if unspecified, directories will have this mode with execute bits set when read bits are set)")
+                .help("Sets the default mode of files (parsed as octal)")
                 .long("mode")
                 .takes_value(true)
                 .default_value("644")
         )
         .arg(
             Arg::with_name("DIRMODE")
-                .help("Sets the default mode of directories (parsed as octal; defaults to 755; )")
+                .help("Sets the default mode of directories (parsed as octal; if unspecified, directories will have FILEMODE with execute bits set when read bits are set)")
                 .long("dirmode")
                 .takes_value(true)
                 .default_value("755")
@@ -119,7 +119,7 @@ pub fn app() -> App<'static, 'static> {
         )
         .arg(
             Arg::with_name("INPUT")
-                .help("Sets the input file (defaults to '-', meaning STDIN)")
+                .help("Sets the input file ('-' means STDIN)")
                 .default_value("-")
                 .index(1),
         )