documented remaining commands

 * flow control and other structures have not been documented this ways.
   I have not yet decided whether they should be documented in separate
   sections or use the documentation tool.

1 files changed, 167 insertions, 0 deletions

diff --git a/src/search.cpp b/src/search.cpp
index 38aa011..525cb2a 100644
--- a/src/search.cpp
+++ b/src/search.cpp
@@ -51,6 +51,62 @@ namespace States {
  * Command states
  */
 
+/*$
+ * S[pattern]$ -- Search for pattern
+ * [n]S[pattern]$
+ * -S[pattern]$
+ * from,toS[pattern]$
+ * :S[pattern]$ -> Success|Failure
+ * [n]:S[pattern]$ -> Success|Failure
+ * -:S[pattern]$ -> Success|Failure
+ * from,to:S[pattern]$ -> Success|Failure
+ *
+ * Search for <pattern> in the current buffer/Q-Register.
+ * Search order and range depends on the arguments given.
+ * By default without any arguments, S will search forward
+ * from dot till file end.
+ * The optional single argument specifies the occurrence
+ * to search (1 is the first occurrence, 2 the second, etc.).
+ * Negative values for <n> perform backward searches.
+ * If missing, the sign prefix is implied for <n>.
+ * Therefore \(lq-S\(rq will search for the first occurrence
+ * of <pattern> before dot.
+ *
+ * If two arguments are specified on the command,
+ * search will be bounded in the character range <from> up to
+ * <to>, and only the first occurrence will be searched.
+ * <from> might be larger than <to> in which case a backward
+ * search is performed in the selected range.
+ *
+ * After performing the search, the search <pattern> is saved
+ * in the global search Q-Register \(lq_\(rq.
+ * A success/failure condition boolean is saved in that
+ * register's integer part.
+ * <pattern> may be omitted in which case the pattern of
+ * the last search or search and replace command will be
+ * implied by using the contents of register \(lq_\(rq
+ * (this could of course also be manually set).
+ *
+ * After a successful search, the pointer is positioned after
+ * the found text in the buffer.
+ * An unsuccessful search will display an error message but
+ * not actually yield an error.
+ * The message displaying is suppressed when executed from loops
+ * and register \(lq_\(rq is the implied argument for break-commands
+ * so that a search-break idiom can be implemented as follows:
+ * .EX
+ * <Sfoo$; ...>
+ * .EE
+ * Alternatively, S may be colon-modified in which case it returns
+ * a condition boolean that may be directly evaluated by a
+ * conditional or break-command.
+ *
+ * In interactive mode, searching will be performed immediately
+ * (\(lqsearch as you type\(rq) highlighting matched text
+ * on the fly.
+ * Changing the <pattern> results in the search being reperformed
+ * from the beginning.
+ */
 void
 StateSearch::initial(void) throw (Error)
 {
@@ -470,6 +526,44 @@ StateSearch::done(const gchar *str) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * [n]N[pattern]$ -- Search over buffer-boundaries
+ * -N[pattern]$
+ * from,toN[pattern]$
+ * [n]:N[pattern]$ -> Success|Failure
+ * -:N[pattern]$ -> Success|Failure
+ * from,to:N[pattern]$ -> Success|Failure
+ *
+ * Search for <pattern> over buffer boundaries.
+ * This command is similar to the regular search command
+ * (S) but will continue to search for occurrences of
+ * pattern when the end or beginning of the current buffer
+ * is reached.
+ * Occurrences of <pattern> spanning over buffer boundaries
+ * will not be found.
+ * When searching forward N will start in the current buffer
+ * at dot, continue with the next buffer in the ring searching
+ * the entire buffer until it reaches the end of the buffer
+ * ring, continue with the first buffer in the ring until
+ * reaching the current file again where it searched from the
+ * beginning of the buffer up to its current dot.
+ * Searching backwards does the reverse.
+ *
+ * N also differs from S in the interpretation of two arguments.
+ * Using two arguments the search will be bounded between the
+ * buffer with number <from>, up to the buffer with number
+ * <to>.
+ * When specifying buffer ranges, the entire buffers are searched
+ * from beginning to end.
+ * <from> may be greater than <to> in which case, searching starts
+ * at the end of buffer <from> and continues backwards until the
+ * beginning of buffer <to> has been reached.
+ * Furthermore as with all buffer numbers, the buffer ring
+ * is considered a circular structure and it is possible
+ * to search over buffer ring boundaries by specifying
+ * buffer numbers greater than the number of buffers in the
+ * ring.
+ */
 void
 StateSearchAll::initial(void) throw (Error)
 {
@@ -521,6 +615,25 @@ StateSearchAll::done(const gchar *str) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * FK[pattern]$ -- Delete up to occurrence of pattern
+ * [n]FK[pattern]$
+ * -FK[pattern]$
+ * from,toFK[pattern]$
+ * :FK[pattern]$ -> Success|Failure
+ * [n]:FK[pattern]$ -> Success|Failure
+ * -:FK[pattern]$ -> Success|Failure
+ * from,to:FK[pattern]$ -> Success|Failure
+ *
+ * FK searches for <pattern> just like the regular search
+ * command (S) but when found deletes all text from dot
+ * up to but not including the found text instance.
+ * When searching backwards the characters beginning after
+ * the occurrence of <pattern> up to dot are deleted.
+ *
+ * In interactive mode, deletion is not performed
+ * as-you-type but only on command termination.
+ */
 State *
 StateSearchKill::done(const gchar *str) throw (Error)
 {
@@ -559,6 +672,19 @@ StateSearchKill::done(const gchar *str) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * FD[pattern]$ -- Delete occurrence of pattern
+ * [n]FD[pattern]$
+ * -FD[pattern]$
+ * from,toFD[pattern]$
+ * :FD[pattern]$ -> Success|Failure
+ * [n]:FD[pattern]$ -> Success|Failure
+ * -:FD[pattern]$ -> Success|Failure
+ * from,to:FD[pattern]$ -> Success|Failure
+ *
+ * Searches for <pattern> just like the regular search command
+ * (S) but when found deletes the entire occurrence.
+ */
 State *
 StateSearchDelete::done(const gchar *str) throw (Error)
 {
@@ -580,6 +706,27 @@ StateSearchDelete::done(const gchar *str) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * FS[pattern]$[string]$ -- Search and replace
+ * [n]FS[pattern]$[string]$
+ * -FS[pattern]$[string]$
+ * from,toFS[pattern]$[string]$
+ * :FS[pattern]$[string]$ -> Success|Failure
+ * [n]:FS[pattern]$[string]$ -> Success|Failure
+ * -:FS[pattern]$[string]$ -> Success|Failure
+ * from,to:FS[pattern]$[string]$ -> Success|Failure
+ *
+ * Search for <pattern> just like the regular search command
+ * (S) does but replace it with <string> if found.
+ * If <string> is empty, the occurrence will always be
+ * deleted so \(lqFS[pattern]$$\(rq is similar to
+ * \(lqFD[pattern]$\(rq.
+ * The global replace register is \fBnot\fP touched
+ * by the FS command.
+ *
+ * In interactive mode, the replacement will be performed
+ * immediately and interactively.
+ */
 State *
 StateReplace::done(const gchar *str) throw (Error)
 {
@@ -600,6 +747,26 @@ StateReplace_ignore::done(const gchar *str __attribute__((unused))) throw (Error
 	return &States::start;
 }
 
+/*$
+ * FR[pattern]$[string]$ -- Search and replace with default
+ * [n]FR[pattern]$[string]$
+ * -FR[pattern]$[string]$
+ * from,toFR[pattern]$[string]$
+ * :FR[pattern]$[string]$ -> Success|Failure
+ * [n]:FR[pattern]$[string]$ -> Success|Failure
+ * -:FR[pattern]$[string]$ -> Success|Failure
+ * from,to:FR[pattern]$[string]$ -> Success|Failure
+ *
+ * The FR command is similar to the FS command.
+ * It searches for <pattern> just like the regular search
+ * command (S) and replaces the occurrence with <string>
+ * similar to what FS does.
+ * It differs from FS in the fact that the replacement
+ * string is saved in the global replacement register
+ * \(lq-\(rq.
+ * If <string> is empty the string in the global replacement
+ * register is implied instead.
+ */
 State *
 StateReplaceDefault::done(const gchar *str) throw (Error)
 {