Description of max function leaves out important details

[Cormac McGuinness]

To: address@hidden
Cc: cmcguinn
Subject: Description of max function leaves out important details

Bug report for Octave 2.0.13.95 configured for i386-pc-linux-gnu

Description:
-----------

  * The help and also the documentation do not make any mention of an
    important aspect of the max and min functions. Both of these
    functions have the ability to return not only the maximum value of a
    vector but also the index at which the maximum (or minimum) occurs.


Repeat-By:
---------

Type "help max" and you get:

octave:184> help max
max is a builtin function

max (X): maximum value(s) of a vector (matrix)

however if X=[ 1 1 23 1 1]; then [a b]=max(X); gives a=23 and b=3

Fix:
---

  A proper description of the builtin max (and min) functions would be
  helpful and would save poor fools like me from spending 2 hours
  searching for a simple but efficient way of implementing the same.



Configuration (please do not edit this section):
-----------------------------------------------

uname output:     Linux speclab 2.2.12 #1 Thu Oct 14 09:29:24 EST 1999 i586 
unknown
configure opts:   --prefix=/usr --libdir=/usr/lib --libexecdir=/usr/lib 
--with-g77 --enable-dl --enable-shared --enable-lite-kernel --host i386-linux
Fortran compiler: g77
FFLAGS:           -O2
F2C:              
F2CFLAGS:         
FLIBS:            -lg2c -lm -L/usr/lib/gcc-lib/i486-linux/egcs-2.91.60 -lm
CPPFLAGS:         
INCFLAGS:         -I/usr/include -I/usr/include/octave-2.0.13.95
C compiler:       egcc, version 2.7.2.3
CFLAGS:           -DHAVE_CONFIG_H -mieee-fp -O2
CPICFLAG:         -fPIC
C++ compiler:     c++, version 2.91.60 19981201 (egcs-1.1.1 release)
CXXFLAGS:         -DHAVE_CONFIG_H -mieee-fp -fno-rtti -fno-exceptions 
-fno-implicit-templates -O2
CXXPICFLAG:       -fPIC
LDFLAGS:          -s
LIBFLAGS:         -L/usr/lib/octave-2.0.13.95
RLD_FLAG:         -Xlinker -rpath -Xlinker /usr/lib/octave-2.0.13.95
TERMLIBS:         -lncurses
LIBS:             
LEXLIB:           
LIBPLPLOT:        
LIBDLFCN:         
DEFS:

  -DOCTAVE_SOURCE=1 -DSEPCHAR=':' -DSEPCHAR_STR=":" -DUSE_READLINE=1
  -D__NO_MATH_INLINES=1 -DCXX_NEW_FRIEND_TEMPLATE_DECL=1 -DHAVE_LIBM=1
  -DF77_APPEND_UNDERSCORE=1 -DOCTAVE_LITE=1 -DSIZEOF_SHORT=2 -DSIZEOF_INT=4
  -DSIZEOF_LONG=4 -DHAVE_ALLOCA_H=1 -DHAVE_ALLOCA=1 -DNPOS=string::npos
  -DSTDC_HEADERS=1 -DHAVE_DIRENT_H=1 -DTIME_WITH_SYS_TIME=1
  -DHAVE_SYS_WAIT_H=1 -DHAVE_ASSERT_H=1 -DHAVE_CURSES_H=1 -DHAVE_DLFCN_H=1
  -DHAVE_FCNTL_H=1 -DHAVE_FLOAT_H=1 -DHAVE_FNMATCH_H=1 -DHAVE_GLOB_H=1
  -DHAVE_GRP_H=1 -DHAVE_LIMITS_H=1 -DHAVE_MEMORY_H=1 -DHAVE_NAN_H=1
  -DHAVE_NCURSES_H=1 -DHAVE_PWD_H=1 -DHAVE_SGTTY_H=1 -DHAVE_STDLIB_H=1
  -DHAVE_STRING_H=1 -DHAVE_SYS_PARAM_H=1 -DHAVE_SYS_RESOURCE_H=1
  -DHAVE_SYS_SELECT_H=1 -DHAVE_SYS_STAT_H=1 -DHAVE_SYS_TIME_H=1
  -DHAVE_SYS_TIMES_H=1 -DHAVE_SYS_TYPES_H=1 -DHAVE_SYS_UTSNAME_H=1
  -DHAVE_TERMCAP_H=1 -DHAVE_TERMIO_H=1 -DHAVE_TERMIOS_H=1 -DHAVE_UNISTD_H=1
  -DHAVE_VARARGS_H=1 -DHAVE_ATEXIT=1 -DHAVE_BCOPY=1 -DHAVE_BZERO=1
  -DHAVE_DUP2=1 -DHAVE_ENDGRENT=1 -DHAVE_ENDPWENT=1 -DHAVE_EXECVP=1
  -DHAVE_FCNTL=1 -DHAVE_FORK=1 -DHAVE_GETCWD=1 -DHAVE_GETEGID=1
  -DHAVE_GETEUID=1 -DHAVE_GETGID=1 -DHAVE_GETGRENT=1 -DHAVE_GETGRGID=1
  -DHAVE_GETGRNAM=1 -DHAVE_GETHOSTNAME=1 -DHAVE_GETPGRP=1 -DHAVE_GETPID=1
  -DHAVE_GETPPID=1 -DHAVE_GETPWENT=1 -DHAVE_GETPWNAM=1 -DHAVE_GETPWUID=1
  -DHAVE_GETTIMEOFDAY=1 -DHAVE_GETUID=1 -DHAVE_GETWD=1 -DHAVE_LSTAT=1
  -DHAVE_MEMMOVE=1 -DHAVE_MKDIR=1 -DHAVE_MKFIFO=1 -DHAVE_ON_EXIT=1
  -DHAVE_PIPE=1 -DHAVE_PUTENV=1 -DHAVE_RENAME=1 -DHAVE_RINDEX=1
  -DHAVE_RMDIR=1 -DHAVE_SETGRENT=1 -DHAVE_SETPWENT=1 -DHAVE_SETVBUF=1
  -DHAVE_SIGACTION=1 -DHAVE_SIGPENDING=1 -DHAVE_SIGPROCMASK=1
  -DHAVE_SIGSUSPEND=1 -DHAVE_STAT=1 -DHAVE_STRCASECMP=1 -DHAVE_STRDUP=1
  -DHAVE_STRERROR=1 -DHAVE_STRNCASECMP=1 -DHAVE_TEMPNAM=1 -DHAVE_UMASK=1
  -DHAVE_UNLINK=1 -DHAVE_USLEEP=1 -DHAVE_VFPRINTF=1 -DHAVE_VSPRINTF=1
  -DHAVE_WAITPID=1 -DSMART_PUTENV=1 -DHAVE_PROGRAM_INVOCATION_NAME=1
  -DHAVE_LIBDL=1 -DHAVE_DLOPEN=1 -DHAVE_DLSYM=1 -DHAVE_DLERROR=1
  -DHAVE_DLCLOSE=1 -DWITH_DL=1 -DWITH_DYNAMIC_LINKING=1 -DHAVE_FINITE=1
  -DHAVE_ISNAN=1 -DHAVE_ISINF=1 -DHAVE_ACOSH=1 -DHAVE_ASINH=1
  -DHAVE_ATANH=1 -DHAVE_ERF=1 -DHAVE_ERFC=1 -DHAVE_ST_BLKSIZE=1
  -DHAVE_ST_BLOCKS=1 -DHAVE_ST_RDEV=1 -DHAVE_TM_ZONE=1 -DHAVE_GR_PASSWD=1
  -DEXCEPTION_IN_MATH=1 -DRETSIGTYPE=void -DSYS_SIGLIST_DECLARED=1
  -DHAVE_SYS_SIGLIST=1 -DHAVE_POSIX_SIGNALS=1 -DHAVE_GETRUSAGE=1
  -DHAVE_TIMES=1 -DGNUPLOT_HAS_MULTIPLOT=1 -DGNUPLOT_HAS_FRAMES=1

User-preferences (please do not edit this section):
--------------------------------------------------

  EDITOR = "emacs"
  EXEC_PATH = 
":/usr/local/Office50/bin:/usr/local/bin:/usr/bin:/bin:/usr/bin/X11:/usr/games:."
  IMAGEPATH = ".:/usr/share/octave/2.0.13.95/imagelib//"
  INFO_FILE = "/usr/info/octave.info"
  INFO_PROGRAM = "info"
  LOADPATH = ":/usr/local/share/octave/site-m//:"
  PAGER = "less"
  PS1 = "\\s:\\#> "
  PS2 = "> "
  PS4 = "+ "
  auto_unload_dot_oct_files = 0
  automatic_replot = 0
  beep_on_error = 0
  completion_append_char = " "
  default_eval_print_flag = 1
# default_global_variable_value = <no value or error in displaying it>
  default_return_value = []
  default_save_format = "ascii"
  define_all_return_values = 0
  do_fortran_indexing = 0
  echo_executing_commands = 0
  empty_list_elements_ok = "warn"
  fixed_point_format = 0
  gnuplot_binary = "gnuplot"
  gnuplot_has_frames = 1
  gnuplot_has_multiplot = 1
  history_file = "/home/cmcguinn/.octave_hist"
  history_size = 1024
  ignore_function_time_stamp = "system"
  implicit_num_to_str_ok = 0
  implicit_str_to_num_ok = 0
  initialize_global_variables = 0
  max_recursion_depth = 256
  ok_to_lose_imaginary_part = "warn"
  output_max_field_width = 10
  output_precision = 5
  page_output_immediately = 0
  page_screen_output = 1
  prefer_column_vectors = 1
  prefer_zero_one_indexing = 0
  print_answer_id_name = 1
  print_empty_dimensions = 1
  propagate_empty_matrices = 1
  resize_on_range_error = 1
  return_last_computed_value = 0
  save_precision = 15
  saving_history = 1
  silent_functions = 0
  split_long_rows = 1
  string_fill_char = " "
  struct_levels_to_print = 2
  suppress_verbose_help_message = 0
  treat_neg_dim_as_zero = 0
  warn_assign_as_truth_value = 1
  warn_comma_in_global_decl = 1
  warn_divide_by_zero = 1
  warn_function_name_clash = 1
  warn_missing_semicolon = 0
  warn_reload_forces_clear = 1
  warn_variable_switch_label = 0
  whitespace_in_literal_matrix =