finish writing first iteration of manpage

2 files changed, 221 insertions, 53 deletions

diff --git a/extra/fatcat-cli.1 b/extra/fatcat-cli.1
index fada073..ddf0ef6 100644
--- a/extra/fatcat-cli.1
+++ b/extra/fatcat-cli.1
@@ -4,7 +4,7 @@
 .nh
 .ad l
 .\" Begin generated content:
-.TH "fatcat-cli" "1" "2021-02-11" "Fatcat API Tool Manual Page"
+.TH "fatcat-cli" "1" "2021-02-15" "Fatcat API Tool Manual Page"
 .P
 .SH NAME
 .P
@@ -24,64 +24,122 @@ Many commands will work out-of-the-box, but all editing actions require authenti
 .P
 .SH COMMANDS
 .P
-.RS 4
-\fBchangelog\fR
-.P
-\fBhelp\fR
-.P
-\fBstatus\fR
-.P
-.RE
 .SS Search Commands
 .P
 .RS 4
-\fBsearch\fR <QUERY>...
+\fBsearch\fR <ENTITY-TYPE> <QUERY>...
+.RS 4
+Query the search index for entities of a specified type. Currently `release`, `container`, and `file` indexes are searchable. By default prints a table with a subset of metadata, but `--index-json` will output the search engine JSON document, or `--entity-json` will do an API fetch for each result and print the full entity JSON.
 .P
 .RE
+.RE
 .SS Single Entity Commands
 .P
 Most commands for interacting with individual catalog entities take a "specifier" which imples an entity type. These can be fatcat-specific "idents", which are an entity type followed by an underscore, then 26 character hash, such as "release_hsmo6p4smrganpb3fndaj2lon4". Or they can be an external identifier type, followed by a colon and the identifier, 
 .P
 .RS 4
-\fBget\fR <SPECIFIER> [--expand <FIELDS>] [--hide <FIELDS>]
+\fBget\fR <SPECIFIER> [--expand <FIELDS>] [--hide <FIELDS>] [--json/--toml]
+.RS 4
+Simply fetches the specified entity or other object from the API and prints to stdout. Currently pretty-prints JSON, but this behavior may change.
 .P
-\fBcreate\fR [--input-file <PATH>]
+.RE
+\fBcreate\fR [-i/--input-file <PATH>] [-e/--editgroup-id <id>]
+.RS 4
+Reads entity from file (or stdin), and adds to the editgroup specified by argument or environment variable.
 .P
-\fBupdate\fR <SPECIFIER> [<FIELD>=<VALUE> ...] [--input-file <PATH>]
+.RE
+\fBupdate\fR <SPECIFIER> [<FIELD>=<VALUE> ...] [-i/--input-file <PATH>] [-e/--editgroup-id <id>]
+.RS 4
+Can operate in two ways. If no input file is given, will fetch the specified entity, apply the given mutations (updating field values), and push the update to the specified editgroup. If an input file is given, that will be used instead of fetching from the API.
+If there is an edit to the same entity in the current editgroup, will delete the current edit ("update the edit"). Note this behavior could result in loss of the current edit if there is a problem updating.
 .P
-\fBdelete\fR <SPECIFIER>
+.RE
+\fBdelete\fR <SPECIFIER> [-e/--editgroup-id <id>]
+.RS 4
+Deletes the specified entity, as part of the specified editgroup.
 .P
-\fBedit\fR <SPECIFIER>
+.RE
+\fBedit\fR <SPECIFIER> [-e/--editgroup-id <id>] [--toml] [--editing-command <EDITOR>]
+.RS 4
+Helper command to edit the given entity using a local text editor. Fetches the entity, opens `$EDITOR` to modify it, then pushes the saved version as part of the given editgroup.
 .P
-\fBdownload\fR <SPECIFIER>
+.RE
+\fBdownload\fR <SPECIFIER> [-o/--output-dir <path>]
+.RS 4
+Downloads a publicly accessibly full-text version of the given entity to disk, if one exists. Currently works with file and release entities. Most files are PDF.
 .P
-\fBhistory\fR <SPECIFIER>
+.RE
+\fBhistory\fR <SPECIFIER> [-n/--limit <count>] [--json]
+.RS 4
+Displays the (accepted) edit history for the given entity.
 .P
 .RE
+.RE
 .SS Batch Commands
 .P
+Batch editing commands will operate on a stream of entities by automatically create new editgroups of a fixed batch size. Please be careful with these commands! Start small, and test against the QA API environment (api.qa.fatcat.wiki).
+.P
 .RS 4
 \fBbatch update\fR [<FIELD>=<VALUE> ...]
+.RS 4
+Same as the `update` command, but operates on a stream of JSON entities (one per line).
 .P
+.RE
 \fBbatch create\fR
+.RS 4
+Same as the `create` command, but operates on a stream of JSON entities (one per line).
 .P
-\fBbatch download\fR [--jobs=N]
+.RE
+\fBbatch download\fR [-j/--jobs=N]
+.RS 4
+Same as `download`, but operates on a stream of entities. A tab-separated log of {entity, status, path} will be printed to stdout. The jobs argument can be used to download multiple files in parallel, up to a reasonable limit.
 .P
 .RE
+.RE
 .SS Editgroup Commands
 .P
 .RS 4
-\fBeditgroups list\fR
+\fBeditgroups list\fR [-n/--limit <count>] [-e/--editor-id <ident>] [--json]
+.RS 4
+Prints a simple table of editgroups created by the current user (requires authentication).
 .P
-\fBeditgroups reviewable\fR
+.RE
+\fBeditgroups reviewable\fR [--json]
+.RS 4
+Prints a table of "submitted" but not "accepted" editgroups, from all editors, which need review
 .P
+.RE
 \fBeditgroups submit\fR <EDITGROUP-ID>
+.RS 4
+Submit the given editgroup for review (requires authentication)
 .P
+.RE
 \fBeditgroups unsubmit\fR <EDITGROUP-ID>
+.RS 4
+Withdraws submission for review, so the editgroup can be further edited (requires authentication)
 .P
+.RE
 \fBeditgroups accept\fR <EDITGROUP-ID>
+.RS 4
+Accepts the editgroup changes into the catalog (requires authentication and admin permissions)
+.P
 .P
 .RE
+.RE
+.SS Other Commands
+.P
+.RS 4
+\fBchangelog\fR [--json]
+.RS 4
+Prints a table of recent changelog entries (accepted editgroups)
+.P
+.RE
+\fBstatus\fR [--json]
+.RS 4
+Summarizes connection and authentication to the API server. Useful for debugging
+.P
+.RE
+.RE
 .SH OPTIONS
 .P
 \fB-h, --help\fR
@@ -106,24 +164,58 @@ By default, it'll only report errors. Passing `-v` one time also prints warnings
 .P
 \fB--search-host <search-host>\fR [env: FATCAT_SEARCH_HOST] [default: https://search.fatcat.wiki]
 .P
-.SH EXAMPLES
+.SS Search Options
 .P
-Query the catalog:
+\fB-count\fR
+.RS 4
+Just print the number of search results matching the query, instead of displaying the results themselves.
 .P
+.RE
+\fB-n, --limit <count>\fR
 .RS 4
-fatcat-cli search releases author:phillips metadata year:2014
+Maximum number of search rows to be printed. Set to 0 to print all results (this is not the default behavior).
 .P
 .RE
-Fetch metadata for a specific work:
+\fB--expand <fields>\fR
+.RS 4
+When output is expanded entity JSON objects (`--entity-json`), this argument will be forwarded as the 'expand' paramter in API fetches. Multiple expansions can be separated by commas, with no space. For example, `--expand files,filesets`.
 .P
+.RE
+\fB--hide <fields>\fR
 .RS 4
-fatcat-cli get doi:10.1002/spe.659
+Same as `--expand`, but for hiding fields/sub-entities.
 .P
 .RE
-Download 100 papers from a specific journal, as PDF:
+\fB--expand-json\fR
+.RS 4
+For each search result row, do an API fetch for the entity and print the entity as JSON. Because there is an API call for each row, this is much slower than the default table output, or the `--index-json` output.
 .P
+.RE
+\fB--index-json\fR
+.RS 4
+For each search result row, print the search engine (Elasticsearch) indexed "document", as JSON.
+.P
+.RE
+.SS Batch Options
+.P
+\fB-i, --input-file\fR
+.RS 4
+JSON lines file to read entities from. Defaults to stdin; "-" can also be passed to explicitly use stdin.
+.P
+.RE
+\fB-n, --limit <count>\fR
+.RS 4
+Only operate on the given number of entities. By default, no limit. Good to use defensively to prevent large accidental edits.
+.P
+.RE
+\fB--batch-size <count>\fR
 .RS 4
-fatcat-cli search releases journal:"first monday" --entity-json --expand files | fatcat-cli batch download --limit 100
+For editing batch commands, how many entity edits should be bundled into each editgroup.
+.P
+.RE
+\fB--auto-accept\fR
+.RS 4
+For editing batch commands, this argument will result in each editgroup being accepted without review. Requires admin permissions.
 .P
 .RE
 .SH EDITING
@@ -160,4 +252,25 @@ To check in on the status of recent editgroups, or to "submit" them for review:
 .RS 4
 fatcat-cli editgroups list
 fatcat-cli editgroups submit <editgroup_id>
+.P
+.P
+.RE
+.SH EXAMPLES
+.P
+Query the catalog:
+.P
+.RS 4
+fatcat-cli search releases author:phillips metadata year:2014
+.P
+.RE
+Fetch metadata for a specific work:
+.P
+.RS 4
+fatcat-cli get doi:10.1002/spe.659
+.P
+.RE
+Download 100 papers from a specific journal, as PDF, to current folder:
+.P
+.RS 4
+fatcat-cli search releases journal:"first monday" --entity-json --expand files -n0 | fatcat-cli batch download --limit 100
 .RE
diff --git a/extra/fatcat-cli.1.scdoc b/extra/fatcat-cli.1.scdoc
index f414852..a3dedb5 100644
--- a/extra/fatcat-cli.1.scdoc
+++ b/extra/fatcat-cli.1.scdoc
@@ -10,61 +10,81 @@ fatcat-cli [OPTIONS] <COMMAND> <ARGS>
 
 # DESCRIPTION
 
-NOTE: this manual page is a work-in-progress
-
 This is simple command-line interface to the fatcat catalog API. Fatcat (https://fatcat.wiki) is an open bibliographic catalog of scholarly works, with a focus on access and preservation.
 
 Many commands will work out-of-the-box, but all editing actions require authentication. Create an account on https://fatcat.wiki, then generate an API token (a long string of random characters) from the account page, and export to your shell environment (read below for the env variable to use).
 
 # COMMANDS
 
-	*changelog*
-
-	*help*
-
-	*status*
-
 ## Search Commands
 
-	*search* <QUERY>...
+	*search* <ENTITY-TYPE> <QUERY>...
+		Query the search index for entities of a specified type. Currently `release`, `container`, and `file` indexes are searchable. By default prints a table with a subset of metadata, but `--index-json` will output the search engine JSON document, or `--entity-json` will do an API fetch for each result and print the full entity JSON.
 
 ## Single Entity Commands
 
 Most commands for interacting with individual catalog entities take a "specifier" which imples an entity type. These can be fatcat-specific "idents", which are an entity type followed by an underscore, then 26 character hash, such as "release_hsmo6p4smrganpb3fndaj2lon4". Or they can be an external identifier type, followed by a colon and the identifier, 
 
-	*get* <SPECIFIER> [--expand <FIELDS>] [--hide <FIELDS>]
+	*get* <SPECIFIER> [--expand <FIELDS>] [--hide <FIELDS>] [--json/--toml]
+		Simply fetches the specified entity or other object from the API and prints to stdout. Currently pretty-prints JSON, but this behavior may change.
 
-	*create* [--input-file <PATH>]
+	*create* [-i/--input-file <PATH>] [-e/--editgroup-id <id>]
+		Reads entity from file (or stdin), and adds to the editgroup specified by argument or environment variable.
 
-	*update* <SPECIFIER> [<FIELD>=<VALUE> ...] [--input-file <PATH>]
+	*update* <SPECIFIER> [<FIELD>=<VALUE> ...] [-i/--input-file <PATH>] [-e/--editgroup-id <id>]
+		Can operate in two ways. If no input file is given, will fetch the specified entity, apply the given mutations (updating field values), and push the update to the specified editgroup. If an input file is given, that will be used instead of fetching from the API.
+		If there is an edit to the same entity in the current editgroup, will delete the current edit ("update the edit"). Note this behavior could result in loss of the current edit if there is a problem updating.
 
-	*delete* <SPECIFIER>
+	*delete* <SPECIFIER> [-e/--editgroup-id <id>]
+		Deletes the specified entity, as part of the specified editgroup.
 
-	*edit* <SPECIFIER>
+	*edit* <SPECIFIER> [-e/--editgroup-id <id>] [--toml] [--editing-command <EDITOR>]
+		Helper command to edit the given entity using a local text editor. Fetches the entity, opens `$EDITOR` to modify it, then pushes the saved version as part of the given editgroup.
 
-	*download* <SPECIFIER>
+	*download* <SPECIFIER> [-o/--output-dir <path>]
+		Downloads a publicly accessibly full-text version of the given entity to disk, if one exists. Currently works with file and release entities. Most files are PDF.
 
-	*history* <SPECIFIER>
+	*history* <SPECIFIER> [-n/--limit <count>] [--json]
+		Displays the (accepted) edit history for the given entity.
 
 ## Batch Commands
 
+Batch editing commands will operate on a stream of entities by automatically create new editgroups of a fixed batch size. Please be careful with these commands! Start small, and test against the QA API environment (api.qa.fatcat.wiki).
+
 	*batch update* [<FIELD>=<VALUE> ...]
+		Same as the `update` command, but operates on a stream of JSON entities (one per line).
 
 	*batch create*
+		Same as the `create` command, but operates on a stream of JSON entities (one per line).
 
-	*batch download* [--jobs=N]
+	*batch download* [-j/--jobs=N]
+		Same as `download`, but operates on a stream of entities. A tab-separated log of {entity, status, path} will be printed to stdout. The jobs argument can be used to download multiple files in parallel, up to a reasonable limit.
 
 ## Editgroup Commands
 
-	*editgroups list*
+	*editgroups list* [-n/--limit <count>] [-e/--editor-id <ident>] [--json]
+		Prints a simple table of editgroups created by the current user (requires authentication).
 
-	*editgroups reviewable*
+	*editgroups reviewable* [--json]
+		Prints a table of "submitted" but not "accepted" editgroups, from all editors, which need review
 
 	*editgroups submit* <EDITGROUP-ID>
+		Submit the given editgroup for review (requires authentication)
 
 	*editgroups unsubmit* <EDITGROUP-ID>
+		Withdraws submission for review, so the editgroup can be further edited (requires authentication)
 
 	*editgroups accept* <EDITGROUP-ID>
+		Accepts the editgroup changes into the catalog (requires authentication and admin permissions)
+		
+
+## Other Commands
+
+	*changelog* [--json]
+		Prints a table of recent changelog entries (accepted editgroups)
+
+	*status* [--json]
+		Summarizes connection and authentication to the API server. Useful for debugging
 
 # OPTIONS
 
@@ -84,19 +104,39 @@ Most commands for interacting with individual catalog entities take a "specifier
 
 *--search-host <search-host>* [env: FATCAT_SEARCH_HOST] [default: https://search.fatcat.wiki]
 
-# EXAMPLES
+## Search Options
 
-Query the catalog:
+*-count*
+	Just print the number of search results matching the query, instead of displaying the results themselves.
 
-	fatcat-cli search releases author:phillips metadata year:2014
+*-n, --limit <count>*
+	Maximum number of search rows to be printed. Set to 0 to print all results (this is not the default behavior).
 
-Fetch metadata for a specific work:
+*--expand <fields>*
+	When output is expanded entity JSON objects (`--entity-json`), this argument will be forwarded as the 'expand' paramter in API fetches. Multiple expansions can be separated by commas, with no space. For example, `--expand files,filesets`.
 
-	fatcat-cli get doi:10.1002/spe.659
+*--hide <fields>*
+	Same as `--expand`, but for hiding fields/sub-entities.
+
+*--expand-json*
+	For each search result row, do an API fetch for the entity and print the entity as JSON. Because there is an API call for each row, this is much slower than the default table output, or the `--index-json` output.
+
+*--index-json*
+	For each search result row, print the search engine (Elasticsearch) indexed "document", as JSON.
+
+## Batch Options
 
-Download 100 papers from a specific journal, as PDF:
+*-i, --input-file*
+	JSON lines file to read entities from. Defaults to stdin; "-" can also be passed to explicitly use stdin.
 
-	fatcat-cli search releases journal:"first monday" --entity-json --expand files | fatcat-cli batch download --limit 100
+*-n, --limit <count>*
+	Only operate on the given number of entities. By default, no limit. Good to use defensively to prevent large accidental edits.
+
+*--batch-size <count>*
+	For editing batch commands, how many entity edits should be bundled into each editgroup.
+
+*--auto-accept*
+	For editing batch commands, this argument will result in each editgroup being accepted without review. Requires admin permissions.
 
 # EDITING
 
@@ -125,3 +165,18 @@ To check in on the status of recent editgroups, or to "submit" them for review:
 
 	fatcat-cli editgroups list
 	fatcat-cli editgroups submit <editgroup_id>
+
+
+# EXAMPLES
+
+Query the catalog:
+
+	fatcat-cli search releases author:phillips metadata year:2014
+
+Fetch metadata for a specific work:
+
+	fatcat-cli get doi:10.1002/spe.659
+
+Download 100 papers from a specific journal, as PDF, to current folder:
+
+	fatcat-cli search releases journal:"first monday" --entity-json --expand files -n0 | fatcat-cli batch download --limit 100