update manpage (work-in-progress)

2 files changed, 210 insertions, 32 deletions

diff --git a/extra/fatcat-cli.1 b/extra/fatcat-cli.1
index 0831773..fada073 100644
--- a/extra/fatcat-cli.1
+++ b/extra/fatcat-cli.1
@@ -4,32 +4,84 @@
 .nh
 .ad l
 .\" Begin generated content:
-.TH "fatcat-cli" "1" "2020-06-14" "fatcat.wiki CLI Manual Page"
+.TH "fatcat-cli" "1" "2021-02-11" "Fatcat API Tool Manual Page"
 .P
 .SH NAME
 .P
-fatcat-cli - something something
+fatcat-cli - client for fatcat.wiki API
 .P
 .SH SYNOPSIS
 .P
-fatcat-cli [FLAGS] [OPTIONS] <SUBCOMMAND>
+fatcat-cli [OPTIONS] <COMMAND> <ARGS>
 .P
-Subcommands:
+.SH DESCRIPTION
+.P
+NOTE: this manual page is a work-in-progress
+.P
+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.
+.P
+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).
+.P
+.SH COMMANDS
 .P
 .RS 4
-create
-delete
-edit
-editgroup
-get
-help
-search
-status
-update
+\fBchangelog\fR
+.P
+\fBhelp\fR
+.P
+\fBstatus\fR
 .P
 .RE
-.SH DESCRIPTION
+.SS Search Commands
+.P
+.RS 4
+\fBsearch\fR <QUERY>...
+.P
+.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>]
+.P
+\fBcreate\fR [--input-file <PATH>]
+.P
+\fBupdate\fR <SPECIFIER> [<FIELD>=<VALUE> ...] [--input-file <PATH>]
+.P
+\fBdelete\fR <SPECIFIER>
+.P
+\fBedit\fR <SPECIFIER>
+.P
+\fBdownload\fR <SPECIFIER>
+.P
+\fBhistory\fR <SPECIFIER>
+.P
+.RE
+.SS Batch Commands
+.P
+.RS 4
+\fBbatch update\fR [<FIELD>=<VALUE> ...]
+.P
+\fBbatch create\fR
+.P
+\fBbatch download\fR [--jobs=N]
+.P
+.RE
+.SS Editgroup Commands
+.P
+.RS 4
+\fBeditgroups list\fR
+.P
+\fBeditgroups reviewable\fR
 .P
+\fBeditgroups submit\fR <EDITGROUP-ID>
+.P
+\fBeditgroups unsubmit\fR <EDITGROUP-ID>
+.P
+\fBeditgroups accept\fR <EDITGROUP-ID>
+.P
+.RE
 .SH OPTIONS
 .P
 \fB-h, --help\fR
@@ -56,9 +108,56 @@ By default, it'll only report errors. Passing `-v` one time also prints warnings
 .P
 .SH EXAMPLES
 .P
-Some examples of usage will go here, like:
+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:
+.P
+.RS 4
+fatcat-cli search releases journal:"first monday" --entity-json --expand files | fatcat-cli batch download --limit 100
+.P
+.RE
+.SH EDITING
+.P
+Every change to the catalog (an "edit") is made as part of an "editgroup". In some cases the CLI tool with create or guess what the current editgroup you are working on is, but you can also create them explicitly and pass the editgroup identifier on every subsequent edit. It is best to combine small groups of related changes into the same editgroup (so they can be reviewed together), but to split up larger batches into editgroups of 50-100 changes at a time.
+.P
+Create a new editgroup:
+.P
+.RS 4
+fatcat-cli editgroups create --description "demonstration edit"
+.P
+# grab the editgroup_id from the output, eg "uy7qzonuwbcitdhhyuk5vjtsdy"
+.P
+.RE
+Individual entities can be edited from the convenience of your text editor, in either JSON or TOML format:
+.P
+.RS 4
+fatcat-cli get release_hsmo6p4smrganpb3fndaj2lon4 --json > release_hsmo6p4smrganpb3fndaj2lon4.json
+.P
+# whatever editor you prefer
+$EDITOR release_hsmo6p4smrganpb3fndaj2lon4
+.P
+fatcat-cli update release_hsmo6p4smrganpb3fndaj2lon4 -e <editgroup_id> < release_hsmo6p4smrganpb3fndaj2lon4.json
+.P
+.RE
+Or, with a single command:
 .P
 .RS 4
-fatcat-cli get thing
+fatcat-cli edit release_hsmo6p4smrganpb3fndaj2lon4 --toml -e <editgroup_id>
+.P
+.RE
+To check in on the status of recent editgroups, or to "submit" them for review:
 .P
+.RS 4
+fatcat-cli editgroups list
+fatcat-cli editgroups submit <editgroup_id>
 .RE
diff --git a/extra/fatcat-cli.1.scdoc b/extra/fatcat-cli.1.scdoc
index 6a176aa..f414852 100644
--- a/extra/fatcat-cli.1.scdoc
+++ b/extra/fatcat-cli.1.scdoc
@@ -1,26 +1,70 @@
-fatcat-cli(1) "fatcat.wiki CLI Manual Page"
+fatcat-cli(1) "Fatcat API Tool Manual Page"
 
 # NAME
 
-fatcat-cli - something something
+fatcat-cli - client for fatcat.wiki API
 
 # SYNOPSIS
 
-fatcat-cli [FLAGS] [OPTIONS] <SUBCOMMAND>
+fatcat-cli [OPTIONS] <COMMAND> <ARGS>
 
-Subcommands:
+# DESCRIPTION
 
-	create
-	delete
-	edit
-	editgroup
-	get
-	help
-	search
-	status
-	update
+NOTE: this manual page is a work-in-progress
 
-# DESCRIPTION
+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>...
+
+## 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>]
+
+	*create* [--input-file <PATH>]
+
+	*update* <SPECIFIER> [<FIELD>=<VALUE> ...] [--input-file <PATH>]
+
+	*delete* <SPECIFIER>
+
+	*edit* <SPECIFIER>
+
+	*download* <SPECIFIER>
+
+	*history* <SPECIFIER>
+
+## Batch Commands
+
+	*batch update* [<FIELD>=<VALUE> ...]
+
+	*batch create*
+
+	*batch download* [--jobs=N]
+
+## Editgroup Commands
+
+	*editgroups list*
+
+	*editgroups reviewable*
+
+	*editgroups submit* <EDITGROUP-ID>
+
+	*editgroups unsubmit* <EDITGROUP-ID>
+
+	*editgroups accept* <EDITGROUP-ID>
 
 # OPTIONS
 
@@ -42,7 +86,42 @@ Subcommands:
 
 # EXAMPLES
 
-Some examples of usage will go here, like:
+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:
+
+	fatcat-cli search releases journal:"first monday" --entity-json --expand files | fatcat-cli batch download --limit 100
+
+# EDITING
+
+Every change to the catalog (an "edit") is made as part of an "editgroup". In some cases the CLI tool with create or guess what the current editgroup you are working on is, but you can also create them explicitly and pass the editgroup identifier on every subsequent edit. It is best to combine small groups of related changes into the same editgroup (so they can be reviewed together), but to split up larger batches into editgroups of 50-100 changes at a time.
+
+Create a new editgroup:
+
+	fatcat-cli editgroups create --description "demonstration edit"
+
+	# grab the editgroup_id from the output, eg "uy7qzonuwbcitdhhyuk5vjtsdy"
+
+Individual entities can be edited from the convenience of your text editor, in either JSON or TOML format:
+
+	fatcat-cli get release_hsmo6p4smrganpb3fndaj2lon4 --json > release_hsmo6p4smrganpb3fndaj2lon4.json
+
+	# whatever editor you prefer
+	$EDITOR release_hsmo6p4smrganpb3fndaj2lon4
+
+	fatcat-cli update release_hsmo6p4smrganpb3fndaj2lon4 -e <editgroup_id> < release_hsmo6p4smrganpb3fndaj2lon4.json
+
+Or, with a single command:
+
+	fatcat-cli edit release_hsmo6p4smrganpb3fndaj2lon4 --toml -e <editgroup_id>
 
-	fatcat-cli get thing
+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>