doc/remembering.1: Add interactive session simulation in examples

1 files changed, 110 insertions, 0 deletions

diff --git a/doc/remembering.1 b/doc/remembering.1
index 8edcf26..859a45e 100644
--- a/doc/remembering.1
+++ b/doc/remembering.1
@@ -60,6 +60,116 @@ $ dmenu_path | remembering -p dmenu-exe -c 'dmenu' | sh
 .P
 Successive invocations will put the frequent choices at the beginning.
 
+.SS Simulation of an interactive session
+
+Below is a simulation of an interactive session, comparing the usage of plain \fBfzf\fR(1) against composing it with \fBremembering\fR:
+
+.RS
+.nf
+$ mkdir -p example/
+$ cd example/
+$ touch a b c d e
+$ ls
+a  b  c  d  e
+$ ls | fzf
+.fi
+.RE
+
+We begin creating a sample directory called "\fCexample/\fR", we cd into it and create 5 empty files: a, b, c, d and e.
+
+\fCls\fR can list the directory for us, in this case in alphabetical order.
+
+When we pipe the output of \fCls\fR into \fBfzf\fR(1), we are give given its prompt to pick one option:
+
+.RS
+.nf
+  e
+  d
+  c
+  b
+> a
+  5/5
+>
+.fi
+.RE
+
+Here \fBfzf\fR(1) lists the items it gets from \fISTDIN\fR in the order that it was given, and starts at the first one, "a".
+
+Once we type "d" and press return, the output of \fBfzf\fR(1) is the choice:
+
+.RS
+.nf
+$ ls | fzf
+d
+.fi
+.RE
+
+Now if we run the same command again, we'll be given the same options, in the same order:
+
+.RS
+.nf
+$ ls | fzf
+
+  e
+  d
+  c
+  b
+> a
+  5/5
+>
+
+$ ls | fzf
+d
+.fi
+.RE
+
+\fBfzf\fR(1) is doing what it is told to: making a prompt with the options given to it from \fISTDIN\fR, in the order it was given.
+
+In order to have our past choices show up in the beginning of the list, we can compose \fBfzf\fR(1) with \fBremembering\fR:
+
+.RS
+.nf
+$ ls | remembering -p tutorial-example -c 'fzf'
+
+  e
+  d
+  c
+  b
+> a
+  5/5
+>
+
+$ ls | remembering -p tutorial-example -c 'fzf'
+d
+.fi
+.RE
+
+So far we get the exact same behaviour, but saying extra things.
+We tell \fBremembering\fR that we want this specific \fIPROFILE\fR to be called "\fCtutorial-example\fR", and we give \fBremembering\fR the \fC'fzf'\fR command to be ran.
+
+From now on if we run the exact same command again, \fBremembering\fR will \fIremember\fR that the last choice was "d", and put it in the beginning of the list, which \fBfzf\fR(1) happily displays in the order it was given:
+
+.RS
+.nf
+$ ls | remembering -p tutorial-example -c 'fzf'
+
+  e
+  c
+  b
+  a
+> d
+  5/5
+>
+
+$ ls | remembering -p tutorial-example -c 'fzf'
+d
+.fi
+.RE
+
+This time the "d" option was already the first one, and we can just press return to get it as the output value from the command.
+
+This example used \fBfzf\fR(1) as the \fICOMMAND\fR given to \fBremembering\fR, but you can give to the \fB-c\fR option anything that reads from \fISTDIN\fR, picks a line and writes to \fBSTDOUT\fR.
+
 
 .SH SEE ALSO