From bug-request at octave dot org Wed Mar 15 15:28:12 2006 Subject: Re: Extra documentation From: "John W. Eaton" To: =?ISO-8859-1?Q?S=F8ren?= Hauberg Cc: bug at octave dot org Date: Wed, 15 Mar 2006 16:27:32 -0500 On 22-Oct-2005, Søren Hauberg wrote: | fre, 23 09 2005 kl. 12:19 -0400, skrev John W. Eaton: | > On 25-Jul-2005, Søren Hauberg wrote: | > | > | John W. Eaton wrote: | > | > On 25-Jul-2005, Søren Hauberg wrote: | > | (snip) | > | > | A simple solution to this is, if the user types 'help -i a_function': | > | > | *) Find the directory in which 'a_function' lives. | > | > | *) Check if a file called doc.info exist in that directory. | > | > | - if it does, tell info to use that file | > | > | - if it doesn't tell info to use INFO_FILE | > | (snip) | > | > OK, but this seems to be just a slight modification of what help -i | > | > already does, so it might be better to change the help function. Or, | > | > we could make help -i call the doc function that is in the .m file. | > | > Either way, I think it would be best for help -i and doc to do the | > | > same thing. | > | Yes, it is only a slight modification (I thought it might be easier to | > | get the change in if it was small). I don't mind doing it in 'help' if | > | that's what you prefer. My personal opinion is that such a simple thing | > | is better to do in the Octave language. So I think it would be better to | > | remove 'help -i' (perhaps let it call doc for a while) and call it 'doc' | > | (like matlab) instead. But that's just my opinion. | > | Should I do it in help (and hence C++) instead? | > | > OK, perhaps it would be better if you wrote the doc function as a .m | > file and then we could have "help -i" call the doc function. | > | > Please take a look at the help_from_info and try_info functions in | > src/help.cc so that we don't lose any functionality when you implement | > the doc function. | I think I've done what you said, but I'm not quite sure as I don't really know the sources | that well. The attached patch (I'm using 2.9.3) should implement this. | I'm also attaching doc.m OK, I installed the following changes, adapted from the code and patch you sent. The following code will only work correctly for the current version of system which returns the status as the first output. It also requires a small bug fix for the recent changes to the system function. Thanks, jwe scripts/ChangeLog: 2006-03-15 John W. Eaton * miscellaneous/doc.m: New file. From Soren Hauberg . src/ChangeLog: 2006-03-15 John W. Eaton * help.cc (help_from_info): Simplify. (try_info): Use feval to call doc instead of executing info program. (additional_help_message): Point users to doc instead of help -i. From Soren Hauberg . * toplev.cc (Fsystem): Return output if nargout > 1, not 0. Index: src/help.cc =================================================================== RCS file: /cvs/octave/src/help.cc,v retrieving revision 1.150 diff -u -r1.150 help.cc --- src/help.cc 15 Mar 2006 02:51:40 -0000 1.150 +++ src/help.cc 15 Mar 2006 21:23:54 -0000 at @ -453,7 +453,7 @@ os << "\ Additional help for built-in functions, operators, and variables\n\ is available in the on-line version of the manual. Use the command\n\ -`help -i ' to search the manual index.\n\ +`doc ' to search the manual index.\n\ \n\ Help and information about Octave is also available on the WWW\n\ at http://www.octave.org and via the help at octave dot org\n\ at @ -568,45 +568,18 @@ static int try_info (const std::string& nm) { - int status = 0; - - OSSTREAM cmd_buf; - -#if __MINGW32__ - cmd_buf << Vinfo_prog << " --file \"" << Vinfo_file << "\""; -#else - cmd_buf << "\"" << Vinfo_prog << "\" --file \"" << Vinfo_file << "\""; -#endif - - std::string directory_name = Vinfo_file; - size_t pos = directory_name.rfind ('/'); - - if (pos != NPOS) - { - directory_name.resize (pos + 1); - cmd_buf << " --directory \"" << directory_name << "\""; - } - - if (nm.length () > 0) - cmd_buf << " --index-search " << nm; + int retval = -1; - cmd_buf << OSSTREAM_ENDS; + warning ("please use `doc' instead of `help -i'"); - volatile octave_interrupt_handler old_interrupt_handler - = octave_ignore_interrupts (); + octave_value_list args; + args(0) = nm; + octave_value_list result = feval ("doc", args, 1); - status = system (OSSTREAM_C_STR (cmd_buf)); + if (result.length () > 0) + retval = result(0).int_value (); - OSSTREAM_FREEZE (cmd_buf); - - octave_set_interrupt_handler (old_interrupt_handler); - - if (WIFEXITED (status)) - status = WEXITSTATUS (status); - else - status = 127; - - return status; + return retval; } static void at @ -620,20 +593,11 @@ { int status = try_info (argv[i]); - if (status) - { - if (status == 127) - { - error ("help: unable to find info"); - error ("help: you need info 2.18 or later (texinfo 3.12)"); - break; - } - else - { - message ("help", "`%s' is not indexed in the manual", - argv[i].c_str ()); - } - } + if (status == 127) + break; + else if (status != 0) + message ("help", "`%s' is not indexed in the manual", + argv[i].c_str ()); } } } at @ -929,7 +893,7 @@ \n\ Once the GNU Info browser is running, help for using it is available\n\ using the command at kbd{C-h} dot \n\ - at seealso{which, lookfor}\n\ + at seealso{doc, which, lookfor}\n\ at end deffn") { octave_value_list retval; Index: src/toplev.cc =================================================================== RCS file: /cvs/octave/src/toplev.cc,v retrieving revision 1.174 diff -u -r1.174 toplev.cc --- src/toplev.cc 10 Mar 2006 15:35:21 -0000 1.174 +++ src/toplev.cc 15 Mar 2006 21:23:54 -0000 at @ -438,7 +438,7 @@ if (nargin > 0 && nargin < 4) { - bool return_output = (nargout > 0 || nargin > 1); + bool return_output = (nargout > 1 || nargin > 1); std::string cmd_str = args(0).string_value (); ## Copyright (C) 2005 Soren Hauberg ## ## This program is free software; you can redistribute it and/or modify ## it under the terms of the GNU General Public License as published by ## the Free Software Foundation; either version 2 of the License, or ## (at your option) any later version. ## ## This program is distributed in the hope that it will be useful, ## but WITHOUT ANY WARRANTY; without even the implied warranty of ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ## GNU General Public License for more details. ## ## You should have received a copy of the GNU General Public License ## along with this program; if not, write to the Free Software ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA ## -*- texinfo -*- ## at deftypefn {Command} doc @var{function_name} ## Displays documentation for the function at var{function_name} dot ## For example, if you want to see the documentation for the Octave ## random number generator at code{rand}, type ## at example ## at code{doc rand} ## at end example ## at seealso{help} ## at end deftypefn ## Author: Soren Hauberg ## Adapted-by: jwe function retval = doc (fname) if (nargin != 1 || ! ischar (fname)) usage ("doc function_name") endif ## Get the directory where the function lives. ## XXX FIXME XXX -- maybe we should have a better way of doing this. x = exist (fname); if (x == 2) ffile = file_in_loadpath (strcat (fname, ".")); elseif (x == 3) ffile = file_in_loadpath (strcat (fname, ".")); else ffile = ""; endif if (! isempty (ffile)) info_dir = fileparts (ffile); else info_dir = octave_config_info ("infodir"); endif ## Determine if a file called doc.info exist in the same ## directory as the function. info_file = fullfile (info_dir, "doc.info"); if (! isstruct (stat (info_file))) info_file = INFO_FILE; endif cmd = sprintf ("\"%s\" --directory \"%s\" --file \"%s\" --index-search %s", INFO_PROGRAM, info_dir, info_file, fname); status = system (cmd); if (status == 127) warning ("unable to find info program `%s'", INFO_PROGRAM); endif if (nargout > 0) retval = status; endif endfunction ------------------------------------------------------------- Octave is freely available under the terms of the GNU GPL. Octave's home on the web: http://www.octave.org How to fund new projects: http://www.octave.org/funding.html Subscription information: http://www.octave.org/archive.html -------------------------------------------------------------