From edfeae5fa832f68ce40eb098b22b1ebd6ba7e449 Mon Sep 17 00:00:00 2001
From: Robin Haberkorn <robin.haberkorn@googlemail.com>
Date: Fri, 1 Mar 2013 03:46:37 +0100
Subject: 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.
---
 src/cmdline.cpp    |   7 +++
 src/goto.cpp       |  26 +++++++++
 src/parser.cpp     |   4 +-
 src/qregisters.cpp | 124 +++++++++++++++++++++++++++++++++++++++
 src/ring.cpp       |  79 +++++++++++++++++++++++++
 src/search.cpp     | 167 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 405 insertions(+), 2 deletions(-)

diff --git a/src/cmdline.cpp b/src/cmdline.cpp
index ac71548..122712f 100644
--- a/src/cmdline.cpp
+++ b/src/cmdline.cpp
@@ -472,6 +472,13 @@ symbol_complete(SymbolList &list, const gchar *symbol, gchar completed)
  * Command states
  */
 
+/*$
+ * *q -- Save last command line
+ *
+ * Only at the very beginning of a command-line, this command
+ * may be used to save the last command line as a string in
+ * Q-Register <q>.
+ */
 State *
 StateSaveCmdline::got_register(QRegister &reg) throw (Error)
 {
diff --git a/src/goto.cpp b/src/goto.cpp
index 4fed38b..4996122 100644
--- a/src/goto.cpp
+++ b/src/goto.cpp
@@ -139,6 +139,32 @@ StateLabel::custom(gchar chr) throw (Error)
 	return this;
 }
 
+/*$
+ * Olabel$ -- Go to label
+ * [n]Olabel1[,label2,...]$
+ *
+ * Go to <label>.
+ * The simple go-to command is a special case of the
+ * computed go-to command.
+ * A comma-separated list of labels may be specified
+ * in the string argument.
+ * The label to jump to is selected by <n> (1 is <label1>,
+ * 2 is <label2>, etc.).
+ * If <n> is omitted, the sign prefix is implied.
+ *
+ * If the label selected by <n> is does not exist in the
+ * list of labels, the command does nothing.
+ * Label definitions are cached in a table, so that
+ * if the label to go to has already been defined, the
+ * go-to command will jump immediately.
+ * Otherwise, parsing continues until the <label>
+ * is defined.
+ * The command will yield an error if a label has
+ * not been defined when the macro or command-line
+ * is terminated.
+ * In the latter case, the user will not be able to
+ * terminate the command-line.
+ */
 State *
 StateGotoCmd::done(const gchar *str) throw (Error)
 {
diff --git a/src/parser.cpp b/src/parser.cpp
index 69acf9f..344920f 100644
--- a/src/parser.cpp
+++ b/src/parser.cpp
@@ -1871,8 +1871,8 @@ static struct ScintillaMessage {
  *   - In the ED hook macro (register \(lq0\(rq),
  *     when a file is added to the ring, most destructive
  *     operations can be performed since rubbing out the
- *     EB command resulting the hook execution also removes
- *     the buffer from the ring again.
+ *     EB command responsible for the hook execution also
+ *     removes the buffer from the ring again.
  */
 State *
 StateScintilla_symbols::done(const gchar *str) throw (Error)
diff --git a/src/qregisters.cpp b/src/qregisters.cpp
index e65365d..05a3322 100644
--- a/src/qregisters.cpp
+++ b/src/qregisters.cpp
@@ -453,6 +453,12 @@ StateExpectQReg::custom(gchar chr) throw (Error, ReplaceCmdline)
 	return got_register(*reg);
 }
 
+/*$
+ * [q -- Save Q-Register
+ *
+ * Save Q-Register <q> contents on the global Q-Register push-down
+ * stack.
+ */
 State *
 StatePushQReg::got_register(QRegister &reg) throw (Error)
 {
@@ -463,6 +469,19 @@ StatePushQReg::got_register(QRegister &reg) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * ]q -- Restore Q-Register
+ *
+ * Restore Q-Register <q> by replacing its contents
+ * with the contents of the register saved on top of
+ * the Q-Register push-down stack.
+ * The stack entry is popped.
+ *
+ * In interactive mode, the original contents of <q>
+ * are not immediately reclaimed but are kept in memory
+ * to support rubbing out the command.
+ * Memory is reclaimed on command-line termination.
+ */
 State *
 StatePopQReg::got_register(QRegister &reg) throw (Error)
 {
@@ -474,6 +493,21 @@ StatePopQReg::got_register(QRegister &reg) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * EQq$ -- Edit or load Q-Register
+ * EQq[file]$
+ *
+ * When specified with an empty <file> string argument,
+ * EQ makes <q> the currently edited Q-Register.
+ * Otherwise, when <file> is specified, it is the
+ * name of a file to read into Q-Register <q>.
+ * When loading a file, the currently edited
+ * buffer/register is not changed and the edit position
+ * of register <q> is reset to 0.
+ *
+ * Undefined Q-Registers will be defined.
+ * The command fails if <file> could not be read.
+ */
 State *
 StateEQCommand::got_register(QRegister &reg) throw (Error)
 {
@@ -503,6 +537,14 @@ StateLoadQReg::done(const gchar *str) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * ^Uq[string]$ -- Set Q-Register string
+ *
+ * Sets string-part of Q-Register <q> to <string>.
+ * If <q> is undefined, it will be defined.
+ *
+ * String-building is by default disabled for ^U commands.
+ */
 State *
 StateCtlUCommand::got_register(QRegister &reg) throw (Error)
 {
@@ -522,6 +564,13 @@ StateSetQRegString::done(const gchar *str) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * Gq -- Insert Q-Register string
+ *
+ * Inserts the string of Q-Register <q> into the buffer
+ * at its current position.
+ * Specifying an undefined <q> yields an error.
+ */
 State *
 StateGetQRegString::got_register(QRegister &reg) throw (Error)
 {
@@ -544,6 +593,12 @@ StateGetQRegString::got_register(QRegister &reg) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * Qq -> n -- Query Q-Register integer
+ *
+ * Gets and returns the integer-part of Q-Register <q>.
+ * The command fails for undefined registers.
+ */
 State *
 StateGetQRegInteger::got_register(QRegister &reg) throw (Error)
 {
@@ -555,6 +610,15 @@ StateGetQRegInteger::got_register(QRegister &reg) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * [n]Uq -- Set Q-Register integer
+ *
+ * Sets the integer-part of Q-Register <q> to <n>.
+ * If <n> is omitted, the sign prefix is implied.
+ *
+ * The register is defined if it does not exist.
+ */
+/** @bug perhaps it's better to imply 0! */
 State *
 StateSetQRegInteger::got_register(QRegister &reg) throw (Error)
 {
@@ -566,6 +630,13 @@ StateSetQRegInteger::got_register(QRegister &reg) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * [n]%q -> q+n -- Increase Q-Register integer
+ *
+ * Add <n> to the integer part of register <q>, returning
+ * its new value.
+ * <q> will be defined if it does not exist.
+ */
 State *
 StateIncreaseQReg::got_register(QRegister &reg) throw (Error)
 {
@@ -580,6 +651,28 @@ StateIncreaseQReg::got_register(QRegister &reg) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * Mq -- Execute macro
+ * :Mq
+ *
+ * Execute macro stored in string of Q-Register <q>.
+ * The command itself does not push or pop and arguments from the stack
+ * but the macro executed might well do so.
+ * The new macro invocation level will contain its own go-to label table
+ * and local Q-Register table.
+ * Except when the command is colon-modified - in this case, local
+ * Q-Registers referenced in the macro refer to the parent macro-level's
+ * local Q-Register table (or whatever level defined one last).
+ *
+ * Errors during the macro execution will propagate to the M command.
+ * In other words if a command in the macro fails, the M command will fail
+ * and this failure propagates until the top-level macro (e.g.
+ * the command-line macro).
+ *
+ * Note that the string of <q> will be copied upon macro execution,
+ * so subsequent changes to Q-Register <q> from inside the macro do
+ * not modify the executed code.
+ */
 State *
 StateMacro::got_register(QRegister &reg) throw (Error, ReplaceCmdline)
 {
@@ -591,6 +684,16 @@ StateMacro::got_register(QRegister &reg) throw (Error, ReplaceCmdline)
 	return &States::start;
 }
 
+/*$
+ * EMfile$ -- Execute macro from file
+ * :EMfile$
+ *
+ * Read the file with name <file> into memory and execute its contents
+ * as a macro.
+ * It is otherwise similar to the \(lqM\(rq command.
+ *
+ * If <file> could not be read, the command yields an error.
+ */
 State *
 StateMacroFile::done(const gchar *str) throw (Error)
 {
@@ -603,6 +706,27 @@ StateMacroFile::done(const gchar *str) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * [lines]Xq -- Copy into or append to Q-Register
+ * -Xq
+ * from,toXq
+ * [lines]:Xq
+ * -:Xq
+ * from,to:Xq
+ *
+ * Copy the next or previous number of <lines> from the buffer
+ * into the Q-Register <q> string.
+ * If <lines> is omitted, the sign prefix is implied.
+ * If two arguments are specified, the characters beginning
+ * at position <from> up to the character at position <to>
+ * are copied.
+ * The semantics of the arguments is analogous to the K
+ * command's arguments.
+ * If the command is colon-modified, the characters will be
+ * appended to the end of register <q> instead.
+ *
+ * Register <q> will be created if it is undefined.
+ */
 State *
 StateCopyToQReg::got_register(QRegister &reg) throw (Error)
 {
diff --git a/src/ring.cpp b/src/ring.cpp
index 33d8293..1715559 100644
--- a/src/ring.cpp
+++ b/src/ring.cpp
@@ -591,6 +591,51 @@ StateEditFile::do_edit(tecoInt id) throw (Error)
 		throw Error("Invalid buffer id %" TECO_INTEGER_FORMAT, id);
 }
 
+/*$
+ * [n]EB[file]$ -- Open or edit file
+ * nEB$
+ *
+ * Opens or edits the file with name <file>.
+ * If <file> is not in the buffer ring it is opened,
+ * added to the ring and set as the currently edited
+ * buffer.
+ * If it already exists in the ring, it is merely
+ * made the current file.
+ * <file> may be omitted in which case the default
+ * unnamed buffer is created/edited.
+ * If an argument is specified as 0, EB will additionally
+ * display the buffer ring contents in the window's popup
+ * area.
+ * Naturally this only has any effect in interactive
+ * mode.
+ *
+ * <file> may also be a glob-pattern, in which case
+ * all files matching the pattern are opened/edited.
+ *
+ * File names of buffers in the ring are normalized
+ * by making them absolute.
+ * Any comparison on file names is performed using
+ * guessed or actual absolute file paths, so that
+ * one file may be referred to in many different ways
+ * (paths).
+ *
+ * <file> does not have to exist on disk.
+ * In this case, an empty buffer is created and its
+ * name is guessed from <file>.
+ * When the newly created buffer is first saved,
+ * the file is created on disk and the buffer's name
+ * will be updated to the absolute path of the file
+ * on disk.
+ *
+ * File names may also be tab-completed and string building
+ * characters are enabled by default.
+ *
+ * If <n> is greater than zero, the string argument
+ * must be empty.
+ * Instead <n> selects a buffer from the ring to edit.
+ * A value of 1 denotes the first buffer, 2 the second,
+ * ecetera.
+ */
 void
 StateEditFile::initial(void) throw (Error)
 {
@@ -663,6 +708,40 @@ StateEditFile::done(const gchar *str) throw (Error)
 	return &States::start;
 }
 
+/*$
+ * EW$ -- Save or rename current buffer
+ * EWfile$
+ *
+ * Saves the current buffer to disk.
+ * If the buffer was dirty, it will be clean afterwards.
+ * If the string argument <file> is not empty,
+ * the buffer is saved with the specified file name
+ * and is renamed in the ring.
+ *
+ * In interactive mode, EW is executed immediately and
+ * may be rubbed out.
+ * In order to support that, \*(ST creates so called
+ * save point files.
+ * It does not merely overwrite existing files when saving
+ * but moves them to save point files instead.
+ * Save point files are called \(lq.teco-<filename>-<n>\(rq
+ * where <filename> is the name of the saved file and <n> is
+ * a number that is increased with every save operation.
+ * Save point files are always created in the same directory
+ * as the original file to ensure that no copying of the file
+ * on disk is necessary but only a rename of the file.
+ * When rubbing out the EW command, \*(ST restores the latest
+ * save point file by moving (renaming) it back to its
+ * original path - also not requiring any on-disk copying.
+ * \*(ST is impossible to crash, but just in case it still
+ * does it may leave behind these save point files which
+ * must be manually deleted by the user.
+ * Otherwise save point files are deleted on command line
+ * termination.
+ *
+ * File names may also be tab-completed and string building
+ * characters are enabled by default.
+ */
 State *
 StateSaveFile::done(const gchar *str) throw (Error)
 {
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)
 {
-- 
cgit v1.2.3