--- a/libinterp/op-kw-docs	Thu Apr 08 21:19:10 2021 +0200
+++ b/libinterp/op-kw-docs	Thu Apr 08 15:35:28 2021 -0700
@@ -23,17 +23,6 @@
 ##
 ########################################################################
 
-## FIXME: Can't have duplicate DOCSTRING entries.  The function properties
-##        already has a docstring which overrides this keyword definition.
-##        If this is ever fixed this entry can be re-inserted after the
-##        keyword "persistent".
-## properties
-##  libinterp/parse-tree/oct-parse.yy
-## -*- texinfo -*-
-## @deftypefn {} {} properties
-## Begin a properties block in a classdef definition.
-## @end deftypefn
-
 !
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
@@ -100,8 +89,9 @@
 @deftypefn {} {} #@{
 Begin block comment.
 
-There must be no other characters, other than whitespace, on the line before
-and after @code{#@{}.  It is possible to nest block comments.
+The sequence @code{#@{} must appear alone on a line with no other characters,
+other than whitespace, before or after it.  It is possible to nest block
+comments.
 @seealso{%@\{, #@\}, #}
 @end deftypefn
 %{
@@ -110,8 +100,9 @@
 @deftypefn {} {} %@{
 Begin block comment.
 
-There must be no other characters, other than whitespace, on the line before
-and after @code{%@{}.  It is possible to nest block comments.
+The sequence @code{%@{} must appear alone on a line with no other characters,
+other than whitespace, before or after it.  It is possible to nest block
+comments.
 @seealso{#@\{, %@\}, %}
 @end deftypefn
 #}
@@ -120,8 +111,9 @@
 @deftypefn {} {} #@}
 Close block comment.
 
-There must be no other characters, other than whitespace, on the line before
-and after @code{#@}}.  It is possible to nest block comments.
+The sequence @code{#@}} must appear alone on a line with no other characters,
+other than whitespace, before or after it.  It is possible to nest block
+comments.
 @seealso{%@\}, #@\{, #}
 @end deftypefn
 %}
@@ -130,8 +122,9 @@
 @deftypefn {} {} %@}
 Close block comment.
 
-There must be no other characters, other than whitespace, on the line before
-and after @code{%@}}.  It is possible to nest block comments.
+The sequence @code{%@}} must appear alone on a line with no other characters,
+other than whitespace, before or after it.  It is possible to nest block
+comments.
 @seealso{#@\}, %@\{, %}
 @end deftypefn
 ...
@@ -140,21 +133,22 @@
 @deftypefn {} {} ...
 Continuation marker.
 
-Joins current line with following line before parsing.
+Joins current line with following line before parsing.  This can be used to
+improve the human-readability of Octave code, without affecting interpretation.
 @end deftypefn
 &
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} &
-Element by element logical 'and' operator.
-@seealso{&&, and}
+Element-by-element logical 'and' operator.
+@seealso{and, &&}
 @end deftypefn
 &&
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} &&
 Logical 'and' operator (with short-circuit evaluation).
-@seealso{&, and}
+@seealso{&}
 @end deftypefn
 '
 @c libinterp/parse-tree/oct-parse.yy
@@ -168,7 +162,7 @@
 sequences within single-quoted strings are not expanded.  I.e., '\n' is a
 2-character string '\' and 'n' rather than "\n" which is a single character
 representing a newline.
-@seealso{.', transpose, "}
+@seealso{ctranspose, .', "}
 @end deftypefn
 (
 @c libinterp/parse-tree/oct-parse.yy
@@ -187,7 +181,7 @@
 -*- texinfo -*-
 @deftypefn {} {} *
 Multiplication operator.
-@seealso{.*, times}
+@seealso{mtimes, .*}
 @end deftypefn
 **
 @c libinterp/parse-tree/oct-parse.yy
@@ -224,7 +218,8 @@
 @deftypefn {} {} ++
 Increment operator.
 
-As in C, may be applied as a prefix or postfix operator.
+Add 1 to existing value of variable.  As in C, may be applied as a prefix
+(@code{++x}) or postfix (@code{x++}) operator.
 @seealso{--}
 @end deftypefn
 ,
@@ -246,7 +241,8 @@
 @deftypefn {} {} --
 Decrement operator.
 
-As in C, may be applied as a prefix or postfix operator.
+Subtract 1 from existing value of variable.  As in C, may be applied as a
+prefix (@code{--x}) or postfix (@code{x--}) operator.
 @seealso{++}
 @end deftypefn
 .'
@@ -257,57 +253,57 @@
 
 For complex matrices, computes the transpose, @emph{not} the complex conjugate
 (Hermitian) transpose.
-@seealso{', transpose}
+@seealso{transpose, '}
 @end deftypefn
 .*
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} .*
-Element by element multiplication operator.
-@seealso{*, times}
+Element-by-element multiplication operator.
+@seealso{times, *}
 @end deftypefn
 .**
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} .**
-Element by element power operator.
+Element-by-element power operator.
 
 If several complex results are possible, returns the one with smallest
 non-negative argument (angle).  Use @code{realpow}, @code{realsqrt},
 @code{cbrt}, or @code{nthroot} if a real result is preferred.
-@seealso{**, ^, .^, power, realpow, realsqrt, cbrt, nthroot}
+@seealso{power, .^, **, ^, realpow, realsqrt, cbrt, nthroot}
 @end deftypefn
 .^
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} .^
-Element by element power operator.
+Element-by-element power operator.
 
 If several complex results are possible, returns the one with smallest
 non-negative argument (angle).  Use @code{realpow}, @code{realsqrt},
 @code{cbrt}, or @code{nthroot} if a real result is preferred.
-@seealso{.**, ^, **, power, realpow, realsqrt, cbrt, nthroot}
+@seealso{power, .**, ^, **, realpow, realsqrt, cbrt, nthroot}
 @end deftypefn
 ./
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} ./
-Element by element right division operator.
-@seealso{/, .\\, rdivide, mrdivide}
+Element-by-element right division operator.
+@seealso{rdivide, /, mrdivide, .\\}
 @end deftypefn
 /
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} /
 Right division operator.
-@seealso{./, \\, rdivide, mrdivide}
+@seealso{mrdivide, ./, rdivide, \\}
 @end deftypefn
 .\
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} .\
-Element by element left division operator.
-@seealso{\\, ./, rdivide, mrdivide}
+Element-by-element left division operator.
+@seealso{ldivide, \\, mldivide, ./}
 @end deftypefn
 \
 @c libinterp/parse-tree/oct-parse.yy
@@ -317,13 +313,17 @@
 
 Within double-quoted strings, @samp{\} is the line continuation marker used
 to join the current line with the following line.
-@seealso{.\\, /, ldivide, mldivide}
+@seealso{mldivide, .\\, ldivide, /}
 @end deftypefn
 :
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} :
-Select entire rows or columns of matrices.
+Select all elements in the specified dimension when indexing.
+
+@example
+x(2, :)   # selects 2nd row, all columns
+@end example
 @end deftypefn
 ;
 @c libinterp/parse-tree/oct-parse.yy
@@ -391,15 +391,15 @@
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} |
-Element by element logical 'or' operator.
-@seealso{||, or}
+Element-by-element logical 'or' operator.
+@seealso{or, ||}
 @end deftypefn
 ||
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} ||
 Logical 'or' (with short-circuit evaluation) operator.
-@seealso{|, or}
+@seealso{|}
 @end deftypefn
 @
 @c libinterp/parse-tree/oct-parse.yy
@@ -417,8 +417,8 @@
 @end group
 @end example
 
-(Note: @@ also finds use in creating classes.  See manual chapter titled
-Object Oriented Programming for detailed description.)
+(Note: @@ also finds use in creating classes.  See the manual chapter titled
+Object Oriented Programming for a detailed description.)
 @seealso{function, functions, func2str, str2func}
 @end deftypefn
 break
@@ -485,14 +485,21 @@
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} else
-Alternate action for an if block.  See @code{if} for  an example.
+Alternate action for an if block.
+
+See @code{if} for an example.
 @seealso{if}
 @end deftypefn
 elseif
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
-@deftypefn {} {} elseif (@var{condition})
-Alternate conditional test for an if block.  See @code{if} for an example.
+@deftypefn {} {} elseif (@var{cond})
+Alternate conditional test for an if block.
+
+The conditional @var{cond} is true if it is not empty and if @emph{all} values
+are nonzero.
+
+See @code{if} for an example.
 @seealso{if}
 @end deftypefn
 end_try_catch
@@ -534,7 +541,9 @@
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} endfor
-Mark the end of a for loop.  See @code{for} for an example.
+Mark the end of a for loop.
+
+See @code{for} for an example.
 @seealso{for}
 @end deftypefn
 endfunction
@@ -548,7 +557,9 @@
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} endif
-Mark the end of an if block.  See @code{if} for an example.
+Mark the end of an if block.
+
+See @code{if} for an example.
 @seealso{if}
 @end deftypefn
 endmethods
@@ -562,7 +573,9 @@
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} endparfor
-Mark the end of a parfor loop.  See @code{parfor} for an example.
+Mark the end of a parfor loop.
+
+See @code{parfor} for an example.
 @seealso{parfor}
 @end deftypefn
 endproperties
@@ -583,14 +596,18 @@
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} endswitch
-Mark the end of a switch block.  See @code{switch} for an example.
+Mark the end of a switch block.
+
+See @code{switch} for an example.
 @seealso{switch}
 @end deftypefn
 endwhile
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} endwhile
-Mark the end of a while loop.  See @code{while} for an example.
+Mark the end of a while loop.
+
+See @code{while} for an example.
 @seealso{do, while}
 @end deftypefn
 enumeration
@@ -627,8 +644,9 @@
 @deftypefnx {} {} function {} function_name (@var{input}, @dots{})
 @deftypefnx {} {} function @var{outputs} = function_name
 Begin a function body with name @code{function_name}, with @var{outputs} as
-results, and with @var{inputs} as parameters.  The function can later be
-invoked in Octave using the syntax
+results, and with @var{inputs} as parameters.
+
+The function can later be invoked in Octave using the syntax
 
 @example
 [@var{output1}, @var{output2}, @dots{}] = function_name (@var{input1}, @var{input2}, @dots{})
@@ -661,6 +679,9 @@
 @deftypefnx {} {} if (@var{cond}) @dots{} elseif (@var{cond}) @dots{} else @dots{} endif
 Begin an if block.
 
+The conditional @var{cond} is true if it is not empty and if @emph{all} values
+are nonzero.
+
 @example
 @group
 x = 1;
@@ -675,7 +696,7 @@
 @end example
 @seealso{switch}
 @end deftypefn
-@c ## FIXME: Can't have duplicate DOCSTRING entries.  The function methods
+@c ## FIXME: Can't have duplicate DOCSTRING entries.  The function methods()
 @c ##        already has a docstring which overrides this keyword definition.
 @c #methods
 @c #@c libinterp/parse-tree/oct-parse.yy
@@ -732,6 +753,14 @@
 elsewhere.
 @seealso{global}
 @end deftypefn
+@c ## FIXME: Can't have duplicate DOCSTRING entries.  The function properties()
+@c ##        already has a docstring which overrides this keyword definition.
+@c ## properties
+@c ##  libinterp/parse-tree/oct-parse.yy
+@c ## -*- texinfo -*-
+@c ## @deftypefn {} {} properties
+@c ## Begin a properties block in a classdef definition.
+@c ## @end deftypefn
 return
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
@@ -794,14 +823,20 @@
 
 If an error occurs within a try block, then the catch code will be run and
 execution will proceed after the catch block (though it is often recommended to
-use the lasterr function to re-throw the error after cleanup is completed).
+use the @code{lasterr} function to re-throw the error after cleanup is
+completed).
 @seealso{catch, unwind_protect}
 @end deftypefn
 until
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
 @deftypefn {} {} until (@var{cond})
-End a do-until loop.  See @code{do} for an example.
+End a do-until loop.
+
+The conditional @var{cond} is true if it is not empty and if @emph{all} values
+are nonzero.
+
+See @code{do} for an example.
 @seealso{do}
 @end deftypefn
 unwind_protect
@@ -841,9 +876,12 @@
 while
 @c libinterp/parse-tree/oct-parse.yy
 -*- texinfo -*-
-@deftypefn {} {} while
+@deftypefn {} {} while (@var{cond})
 Begin a while loop.
 
+The conditional @var{cond} is true if it is not empty and if @emph{all} values
+are nonzero.
+
 @example
 @group
 i = 0;