Describe the form selection algorithm in a dedicated section.

1 files changed, 28 insertions, 8 deletions

diff --git a/cli/icevault.1 b/cli/icevault.1
index bd58cdf..8aaa76c 100644
--- a/cli/icevault.1
+++ b/cli/icevault.1
@@ -45,10 +45,8 @@ If \fICOMMAND\fR is omitted, \fBfill\fR is assumed.
 If the scheme (resp. hostname) of the active tab of the active window is
 not \fIscheme\fR (resp. \fIhostname\fR) the program assumes a phishing
 attempt and aborts.  Otherwise, the \fIidentity\fR file is decrypted and
-used to fill a visible form on the browser.
-Form selection is done by matching on the base URI; it fallbacks to the
-first form containing a password; and further fallbacks to the first
-form with a non-empty field.
+used to fill a visible form on the browser.  The HTML form selection
+algorithm is described in the \fBHTML FORM SELECTION\fR section.
 Changes to the \fIidentity\fR are detected and can be saved on demand.
 If \fIidentity\fR has a single password whereas the webpage has 2 (resp.
 3), a signup (resp. password changing) page is assumed, and a new
@@ -115,10 +113,8 @@ Signing each commit can be achieved as follows, see \fIgit-config\fR(1):
 .TP
 .B insert\fR [\fB-f\fR, \fB--force\fR] [\fB-s\fR, \fB--socket=\fR\fIPATH\fR] [\fIidentity\fR]
 Create a new \fIscheme\fR://\fIhostname\fR/\fIidentity\fR URI available
-for further commands.
-Store the first visible form on the active tab of the active window which
-contains a password (or the first visible form with a non-empty field if
-no visible form has a password).  If \fIidentity\fR is omitted, it
+for further commands.  The HTML form selection algorithm is described in
+the \fBHTML FORM SELECTION\fR section.  If \fIidentity\fR is omitted, it
 defaults to the value of the last textual value before the first
 password (or the first textual value if the selected form has no
 password).
@@ -238,6 +234,30 @@ respectively expand to the \fIscheme\fR, \fIhostname\fR and
 \fIidentity\fR parts of the URI.
 (Default: "%s/%h/%i.gpg".)
 
+.SH HTML FORM SELECTION
+The HTML form selection for the \fBinsert\fR and \fBfill\fR commands is
+performed in the following order:
+
+.nr step 1 1
+.IP \n[step]. 3
+Consider only the visible forms of the active tab of the active window.
+.IP \n+[step].
+If there is a matching identity in the store, consider only the forms
+with matching action / base URI; and if there is a single match take it
+(\fBfill\fR only).
+.IP \n+[step].
+If one of the considered forms has a password field and a (possibly
+different) non-empty field, take the first one found.
+.IP \n+[step].
+Otherwise (if all forms with a password field are empty), and if there
+is a form with a password field, take the first one found.
+.IP \n+[step].
+Otherwise (if no form has a password field), and if there
+is a non-empty form, take the first one found.
+form.
+.IP \n+[step].
+Otherwise (if all forms are empty), take the first form in the list.
+
 .SH AUTHOR
 Guilhem Moulin <guilhem@fripost.org>
 .SH SEE ALSO