fix(cli): name the ECMA-427 identity grammar in the usage text

changes/unreleased/help-identity-grammar.fixed.md

@@ -0,0 +1 @@
+- `syspi -h` names the ECMA-427 identity grammar and the two input spellings it normalises, instead of the refused `pkg:<vcs>/<host>/<path>` form.

cmd/syspi/main.go

@@ -39,8 +39,12 @@ Commands:
   bundle    build a deterministic .kpar from a project directory
   version   print the version
 
-A package is any git, svn or hg repository with .project.json at a tag:
-  pkg:<vcs>/<host>/<path>[@<version>][#<subpath>]
+A package is any git, svn or hg repository with .project.json at a tag, identified by an
+ECMA-427 Package-URL (vcs: git, svn, hg; transports per Annex B.3.5, plus file):
+  pkg:generic/<name>?vcs_url=<vcs>%2B<transport>:%2F%2F<host>%2F<path>[%40<version>][%23<subpath>]
+Accepted as input and normalised to it:
+  pkg:git/<host>/<path>[@<version>][#<subpath>]
+  <vcs>+<transport>://<host>/<path>[@<version>][#<subpath>]
 Run "syspi <command> -h" for the flags of a command.
 `
 

internal/lock/lock.go

@@ -27,8 +27,8 @@ const (
 
 // Entry is one locked package.
 type Entry struct {
-	// Resource is the canonical, version-free identity (pkg:<vcs>/<host>/<path>[#<subpath>],
-	// an archive URL or path, a standard IRI).
+	// Resource is the canonical, version-free identity (pkg:generic/<name>?vcs_url=… without
+	// the %40<version>, an archive URL or path, a standard IRI).
 	Resource  string `json:"resource"`
 	Kind      string `json:"kind"`
 	Publisher string `json:"publisher,omitempty"`