bugGNU Octave - Bugs: bug #50034, "help ./" causes some...

 
 

bug #50034: "help ./" causes some extraneous printout of path info

Submitter:  Dan Sebald <sebald>
Submitted:  Wed 11 Jan 2017 11:16:22 PM UTC
   
 
Category:  Documentation Severity:  2 - Minor
Priority:  3 - Low Item Group:  Incorrect Result
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * dev Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Sun 15 Jan 2017 03:44:37 PM UTC, comment #10: 

I don't think so.  When used in the command form, the Octave interpreter will strip off whitespace and everything will work fine.  When a user chooses quotes, it's because they want to specifically control how the interpreter will handle the string.  In particular, by using single quotes the user is saying that they want to see exactly what they typed with absolutely no interference from Octave (no breaking tokens at spaces, no interpolation of special escape sequences like \n, etc.).  If a user has typed


help (' sin')


then the interpreter should respect that and assume the programmer has a good reason for requiring a space where it was placed.


Rik <rik5>
Group administrator
Sun 15 Jan 2017 03:00:07 AM UTC, comment #9: 

OK.

Just a clarification.  I was going to suggest applying strtrim(name) to remove any white space first.  But it seems that isn't necessary as help() doesn't seem to do such a thing.  Should it?


octave:12> help  sin
'sin' is a built-in function from the file libinterp/corefcn/mappers.cc

 -- sin (X)
     Compute the sine for each element of X in radians.

     See also: asin, sind, sinh.
octave:13> help('sin')
'sin' is a built-in function from the file libinterp/corefcn/mappers.cc

 -- sin (X)
     Compute the sine for each element of X in radians.

     See also: asin, sind, sinh.
octave:14> help(' sin')
error: help: ' sin' not found


Dan Sebald <sebald>
Sun 15 Jan 2017 02:25:05 AM UTC, comment #8: 

I checked in a cset to specifically look for './' and '.\' and avoid those (http://hg.savannah.gnu.org/hgweb/octave/rev/1b4a16ce14c2).

Rik <rik5>
Group administrator
Thu 12 Jan 2017 06:03:18 PM UTC, comment #7: 

OH, I see.  which() is the part that prints out info at the front of help output:

octave:10> help which
'which' is a function from the file /usr/local/share/octave/4.3.0+/m/help/which.m

OK, so my last comment is maybe more pertinent than I originally thought.  If one were to do the following:


octave:11> sin = 1;
[all kinds of other code...]
octave:97> sin(0.4)
error: sin(0.4): subscripts must be either integers 1 to (2^31)-1 or logicals
[hey, what is wrong with sin(0.4)?!]
octave:97> help sin
'sin' is a variable

 -- sin (X)
     Compute the sine for each element of X in radians.

     See also: asin, sind, sinh.


It might be better to just stop with


octave:97> help sin
'sin' is a variable


and not print the help for the sin() function.  That way it would become immediately clear what went wrong.

But, again, I gave a link to an alternate approach to solving this inattentive-programmer issue that prints a over-shadow warning at the point of the error message which would be far more helpful.

I was going to suggest on the mailing list that the first line of help:


octave:10> help which
'which' is a function from the file /usr/local/share/octave/4.3.0+/m/help/which.m


be dropped, but I thought there'd be too much objection.  The "which" routine is listed in "help help" see-also, so the user should be able to track down any "duplicate function name in my path" problems at a reasonable rate.

Dan Sebald <sebald>
Thu 12 Jan 2017 05:40:14 PM UTC, comment #6: 

In the case you point out regarding the creation of a variable with the same name as an existing function, it's almost helpful having that little message

'sin' is a variable

because not realizing having done such a thing is very easy to do when concentrating on programming.  Here's an example and an approach to addressing that ancillary issue:

https://savannah.gnu.org/bugs/?46852#comment4

Dan Sebald <sebald>
Thu 12 Jan 2017 04:47:50 PM UTC, comment #5: 

Anything which confuses 'which' is going to have this issue.  If I define a variable with the same name as a function, then I also get unexpected output.  See this session log:


octave:5> sin = 1
sin =  1
octave:6> help sin
'sin' is a variable

 -- sin (X)
     Compute the sine for each element of X in radians.

     See also: asin, sind, sinh.



Rik <rik5>
Group administrator
Thu 12 Jan 2017 02:56:12 PM UTC, comment #4: 

Yep.  I see what you're seeing. 


Look at help.m at the end


    if (nargout == 0)
      evalin ("caller", ['which ("' undo_string_escapes(name) '")']);
      printf ("\n%s\n%s", text, __additional_help_message__ ());
    else
      retval = text;
    endif


It is the call to evalin which is adding the extra output.  I checked and the value of 'text' is correct.  You can see this also by using a return argument to help which then takes the else branch above.


s = help ("./")




Rik <rik5>
Group administrator
Thu 12 Jan 2017 07:42:55 AM UTC, comment #3: 

That's because "." is always in the path, and both "." and "./" are valid file names which refer to current directory, which is in the load path.

The help function unconditionally calls which(name), which is where that first line comes from. If which(name) prints nothing, then you get nothing, which is what you normally see for all operators. But because which("./") prints that it is the current directory, you get that misleading first line.

Some logic could be added to help.m to see if the given name is an operator and not run which on it.

Mike Miller <mtmiller>
Group Member
Thu 12 Jan 2017 01:32:42 AM UTC, comment #2: 

OK, I see where you are going, but I still see the blurb about the current directory:


octave:1> help "./"
'./' is the file /home/sebald/audio/data

 -- ./
     Element by element right division operator.

     See also: /, .\, rdivide, mrdivide.
<etc>


I don't see a problem with the given example either.

help +
help "+"

look exactly the same.

This does seem like the source of the issue though.

Dan Sebald <sebald>
Thu 12 Jan 2017 01:15:36 AM UTC, comment #1: 

Try 'help help'


-- help NAME
 -- help '--list'
 -- help '.'
 -- help
     Display the help text for NAME.

     For example, the command 'help help' prints a short message
     describing the 'help' command.

     Given the single argument '--list', list all operators, keywords,
     built-in functions, and loadable functions available in the current
     session of Octave.

     Given the single argument '.', list all operators available in the
     current session of Octave.

     If invoked without any arguments, 'help' displays instructions on
     how to access help from the command line.

     The help command can provide information about most operators, but
     NAME must be enclosed by single or double quotes to prevent the
     Octave interpreter from acting on NAME.  For example, 'help "+"'
     displays help on the addition operator.


The last sentence in particular was added because all operators need to be enclosed by quotes.  If you try


help "./"


you will get only the correct text.

Rik <rik5>
Group administrator
Wed 11 Jan 2017 11:16:22 PM UTC, original submission:  

When doing a "help ./" to see the documentation for element-by-element division, something is mistaking that './' for a path to the current directory and prints out a little blurb.  There may be some other aspect of "help" pertaining to the contents of scripts in a directory, and maybe this can't be prevented, but it seems strange:


octave:1> help ./
'./' is the file /home/sebald/audio/data

 -- ./
     Element by element right division operator.

     See also: /, .\, rdivide, mrdivide.

Additional help for built-in functions and operators is
available in the online version of the manual.  Use the command
'doc <topic>' to search the manual index.

Help and information about Octave is also available on the WWW
at http://www.octave.org and via the help@octave.org
mailing list.


"help .\" is OK, at least on unix, but I'm not sure what would happen in Windows where the backward slash is used for directory specification.

Dan Sebald <sebald>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by mtmiller (Posted a comment)
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by sebald (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only group members can vote.

     

    Follow 5 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2017-01-15 rik5 StatusConfirmed Fixed
        Open/ClosedOpen Closed
    2017-01-12 rik5 StatusNone Confirmed
    2017-01-12 rik5 Severity3 - Normal 2 - Minor
        Priority5 - Normal 3 - Low

    Back to the top

    Powered by Savane 3.13-758e.
    Corresponding source code