# HG changeset patch
# User Rik <rik@octave.org>
# Date 1398396228 25200
# Node ID 7bccc182e2f7df37c17d6888cd3d091e87df36dc
# Parent  3994a1c2b9941157f4fb777f0c1dedc1b68f3371
doc: Update pause documentation and add seealso links between related functions.

* input.cc (Finput): Put first sentence description on its own line.  Add
seealso links.
* input.cc (Fyes_or_no):Put first sentence description on its own line.  Add
seealso links.
* input.cc (Fkeyboard): Add seealso link to dbstop.
* input.cc (Fkeyboard): Add seealso link to dbstop.

* sysdep.cc (Fkbhit): Add seealso link to pause.
* sysdep.cc (Fpause): Rewrite docstring.  Add seealso links.
* sysdep.cc (Fsleep): Add seealso links to usleep, pause.
* sysdep.cc (Fusleep): Add seealso links to sleep, pause.
* sysdep.cc (Fhave_window_system): Correct bad phrasing in docstring.

* listdlg.m: Add seealso link to menu

* menu.m: Add seealso link to listdlg.

diff -r 3994a1c2b994 -r 7bccc182e2f7 libinterp/corefcn/input.cc
--- a/libinterp/corefcn/input.cc	Thu Apr 24 09:22:38 2014 -0700
+++ b/libinterp/corefcn/input.cc	Thu Apr 24 20:23:48 2014 -0700
@@ -731,7 +731,9 @@
        "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {@var{ans} =} input (@var{prompt})\n\
 @deftypefnx {Built-in Function} {@var{ans} =} input (@var{prompt}, \"s\")\n\
-Print a prompt and wait for user input.  For example,\n\
+Print @var{prompt} and wait for user input.\n\
+\n\
+For example,\n\
 \n\
 @example\n\
 input (\"Pick a number, any number! \")\n\
@@ -761,7 +763,7 @@
 a good idea to always call @code{fflush (stdout)} before calling\n\
 @code{input}.  This will ensure that all pending output is written to\n\
 the screen before your prompt.\n\
-@seealso{yes_or_no, kbhit}\n\
+@seealso{yes_or_no, kbhit, pause, menu, listdlg}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -799,12 +801,13 @@
 DEFUN (yes_or_no, args, ,
        "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {@var{ans} =} yes_or_no (\"@var{prompt}\")\n\
-Ask the user a yes-or-no question.  Return logical true if the answer is yes\n\
-or false if the answer is no.  Takes one argument, @var{prompt}, which is\n\
-the string to display when asking the question.  @var{prompt} should end in\n\
-a space; @code{yes-or-no} adds the string @samp{(yes or no) } to it.  The\n\
-user must confirm the answer with @key{RET} and can edit it until it has\n\
-been confirmed.\n\
+Ask the user a yes-or-no question.\n\
+\n\
+Return logical true if the answer is yes or false if the answer is no.\n\
+Takes one argument, @var{prompt}, which is the string to display when asking\n\
+the question.  @var{prompt} should end in a space; @code{yes-or-no} adds the\n\
+string @samp{(yes or no) } to it.  The user must confirm the answer with\n\
+@key{RET} and can edit it until it has been confirmed.\n\
 @seealso{input}\n\
 @end deftypefn")
 {
@@ -888,7 +891,7 @@
 \n\
 If @code{keyboard} is invoked without arguments, a default prompt of\n\
 @samp{debug> } is used.\n\
-@seealso{dbcont, dbquit}\n\
+@seealso{dbstop, dbcont, dbquit}\n\
 @end deftypefn")
 {
   octave_value_list retval;
diff -r 3994a1c2b994 -r 7bccc182e2f7 libinterp/corefcn/sysdep.cc
--- a/libinterp/corefcn/sysdep.cc	Thu Apr 24 09:22:38 2014 -0700
+++ b/libinterp/corefcn/sysdep.cc	Thu Apr 24 20:23:48 2014 -0700
@@ -641,7 +641,7 @@
 @noindent\n\
 is identical to the above example, but doesn't wait for a keypress,\n\
 returning the empty string if no key is available.\n\
-@seealso{input}\n\
+@seealso{input, pause}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -667,12 +667,16 @@
 
 DEFUN (pause, args, ,
        "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} pause (@var{seconds})\n\
-Suspend the execution of the program.  If invoked without any arguments,\n\
-Octave waits until you type a character.  With a numeric argument, it\n\
-pauses for the given number of seconds.  For example, the following\n\
-statement prints a message and then waits 5 seconds before clearing the\n\
-screen.\n\
+@deftypefn  {Built-in Function} {} pause ()\n\
+@deftypefnx {Built-in Function} {} pause (@var{n})\n\
+Suspend the execution of the program for @var{n} seconds.\n\
+\n\
+@var{n} is a positive real value and may be a fraction of a second.\n\
+If invoked without an input arguments then the program is suspended until a\n\
+character is typed.\n\
+\n\
+The following example prints a message and then waits 5 seconds before\n\
+clearing the screen.\n\
 \n\
 @example\n\
 @group\n\
@@ -681,6 +685,7 @@
 clc;\n\
 @end group\n\
 @end example\n\
+@seealso{kbhit, sleep}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -736,6 +741,7 @@
        "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} sleep (@var{seconds})\n\
 Suspend the execution of the program for the given number of seconds.\n\
+@seealso{usleep, pause}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -776,6 +782,7 @@
 microseconds.  On systems where it is not possible to sleep for periods\n\
 of time less than one second, @code{usleep} will pause the execution for\n\
 @code{round (@var{microseconds} / 1e6)} seconds.\n\
+@seealso{sleep, pause}\n\
 @end deftypefn")
 {
   octave_value_list retval;
@@ -915,8 +922,8 @@
 DEFUN (have_window_system, , ,
   "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} have_window_system ()\n\
-Return true if Octave a window system is available (X11, Windows,\n\
-or Apple OS X) and false otherwise.\n\
+Return true if a window system is available (X11, Windows, or Apple OS X)\n\
+and false otherwise.\n\
 @end deftypefn")
 {
   return octave_value (display_info::display_available ());
diff -r 3994a1c2b994 -r 7bccc182e2f7 scripts/gui/listdlg.m
--- a/scripts/gui/listdlg.m	Thu Apr 24 09:22:38 2014 -0700
+++ b/scripts/gui/listdlg.m	Thu Apr 24 20:23:48 2014 -0700
@@ -74,7 +74,7 @@
 ## @end group
 ## @end example
 ##
-## @seealso{errordlg, helpdlg, inputdlg, msgbox, questdlg, warndlg}
+## @seealso{menu, errordlg, helpdlg, inputdlg, msgbox, questdlg, warndlg}
 ## @end deftypefn
 
 function [sel, ok] = listdlg (varargin)
diff -r 3994a1c2b994 -r 7bccc182e2f7 scripts/miscellaneous/menu.m
--- a/scripts/miscellaneous/menu.m	Thu Apr 24 09:22:38 2014 -0700
+++ b/scripts/miscellaneous/menu.m	Thu Apr 24 20:23:48 2014 -0700
@@ -24,7 +24,7 @@
 ## programs.  There is no limit to the number of options that may be passed
 ## in, but it may be confusing to present more than will fit easily on one
 ## screen.
-## @seealso{disp, printf, input}
+## @seealso{input, listdlg}
 ## @end deftypefn
 
 ## Author: jwe