# HG changeset patch
# User Jaroslav Hajek <highegg@gmail.com>
# Date 1264596422 -3600
# Node ID ea0d83b4470bcae8fdbf4de0c232961911dedb39
# Parent  c54ee101d13c5e04cf7731ca7ea82331182f062a
document use of ~ placeholders in the manual

diff --git a/doc/ChangeLog b/doc/ChangeLog
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2010-01-27  Jaroslav Hajek  <highegg@gmail.com>
+
+	* interpreter/expr.txi: Document using dummy outputs.
+	* interpreter/func.txi: Document using dummy inputs.
+
 2010-01-20  John W. Eaton  <jwe@octave.org>
 
 	* interpreter/munge-texi.cc: Delete Emacs local-variable settings.
diff --git a/doc/interpreter/expr.txi b/doc/interpreter/expr.txi
--- a/doc/interpreter/expr.txi
+++ b/doc/interpreter/expr.txi
@@ -992,6 +992,21 @@
 @end group
 @end example
 
+The symbol @code{~} may be used as a placeholder in the list of lvalues,
+indicating that the corresponding return value should be ignored and not stored
+anywhere:
+
+@example
+@group
+[~, s, v] = svd (a);
+@end group
+@end example
+
+This is cleaner and more efficient than using a dummy variable.
+It is not recommended, however, to reuse such an assignment statement as a right-hand side
+in another expression. Currently, this works as expected, but may cease to work in future
+releases of Octave. The @code{nargout} value for the right-hand side expression is not affected.
+
 @opindex +=
 A very common programming pattern is to increment an existing variable
 with a given value, like this
diff --git a/doc/interpreter/func.txi b/doc/interpreter/func.txi
--- a/doc/interpreter/func.txi
+++ b/doc/interpreter/func.txi
@@ -32,6 +32,7 @@
 * Defining Functions::          
 * Multiple Return Values::      
 * Variable-length Argument Lists::  
+* Ignoring Arguments::  
 * Variable-length Return Lists::  
 * Returning From a Function::   
 * Default Arguments::   
@@ -436,6 +437,23 @@
 
 @DOCSTRING(parseparams)
 
+@node Ignoring Arguments
+@section Ignoring Arguments
+
+In the formal argument list, it is possible to use the dummy placeholder @code{~}
+instead of a name. This indicates that the corresponding argument value should be ignored
+and not stored to any variable.
+
+@example
+@group
+function val = pick2nd (~, arg2)
+  val = arg2;
+endfunction
+@end group
+@end example
+
+The value of @code{nargin} is not affected by using this declaration.
+
 @node Variable-length Return Lists
 @section Variable-length Return Lists
 @cindex variable-length return lists