bugGNU Octave - Bugs: bug #54053, "doc persistent" should...

 
 

bug #54053: "doc persistent" should work in GUI as it does in CLI

Submitter:  Lars Kindermann <larskindermann>
Submitted:  Mon 04 Jun 2018 07:56:55 AM UTC
   
 
Category:  GUI Severity:  1 - Wish
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * dev Operating System:  * GNU/Linux
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Mon 02 Jul 2018 06:54:07 PM UTC, comment #13: 

@Pantxo: Thanks for updating this to work with old versions of Qt (like mine).  I tested back to Qt 5.6.1 and it behaves as expected.  I committed the patch here (http://hg.savannah.gnu.org/hgweb/octave/rev/517c73173011).

Marking as fixed and closing report.

Rik <rik5>
Group administrator
Fri 22 Jun 2018 08:17:19 AM UTC, comment #12: 

I attached an updated cset which compiles fine with Qt5.7 (which has the old API) and I hope with older versions.

(file #44412)

Pantxo Diribarne <pantxo>
Group Member
Thu 21 Jun 2018 09:05:42 AM UTC, comment #11: 

I attached a preliminary cset that implements second solution.
If a match is found in the function index, the documentation browser is shown with the function index tab activated and filtered. Otherwise a full text search is attempted and the search tab is activated. If among the search results, the search string appears in the title, then the first corresponding page is shown in the text browser.

This cset probably won't compile with old versions of Qt (I have 5.9) and it would be useful if someone could test with early Qt5 (5.1, 5.2) and late Qt4 that we support (4.8).

(file #44403)

Pantxo Diribarne <pantxo>
Group Member
Tue 19 Jun 2018 03:32:46 PM UTC, comment #10: 

I guess maybe the second solution would be nicer.  If we create a single Index which includes functions, concepts, and graphic properties then the display under the "Index" tab is going to be messy (think of all the graphics properties).  The search done by info() when using the CLI includes all of these indices so the GUI should too.  I guess that means searching the function index first, and if that fails, attempting a search of the other two indices.

I would hope that this is not a difficult programming problem because the "Search" tab already manages to include the other indices.

Rik <rik5>
Group administrator
Tue 19 Jun 2018 02:31:07 PM UTC, comment #9: 

@Rik: my understanding is that in the GUI, "doc xyz" only works if "xyz" is listed in the "Index" tab of the search pane. This list is basically something we control since it is extracted by your Perl script from the function reference. So we basically have two choices:

  • extend the list of "Index" by parsing also the the concept index, graphics properties index and operator index html pages
  • make the C++ search path a little bit smarter and let it launch a "Search" on the "xyz" if the basic index search did not return any result.
Pantxo Diribarne <pantxo>
Group Member
Tue 19 Jun 2018 05:48:23 AM UTC, comment #8: 

Changing Category to GUI.  This is related to how 'doc' is implemented within the GUI, not the Texinfo documentation or the ordinary doc command in doc.m.

Rik <rik5>
Group administrator
Tue 19 Jun 2018 05:46:56 AM UTC, comment #7: 

It turns out that doc.m has two very different paths.  If the CLI is running then the m-file calls out to the external info program to search its indices and return a match node.  When the GUI is running, Octave calls accross to the Qt thread using _octave_link_show_doc_.  The code is more complicated because it is in C++ and is making use of Qt documentation widgets.  It appears that instead of searching the GUI just attempts to open a node of the given name.  There is a search capability present in texinfo-parser.cc (find_reference).  It might be possible to hook that routine up somewhere along the line.

Rik <rik5>
Group administrator
Tue 19 Jun 2018 02:05:44 AM UTC, comment #6: 

doc and help are different.  help brings up the documentation for a function.  doc brings up the manual where a cross-reference has been set (XREF).  It just so happens that for functions we put an XREF in the manual so that 'doc ls' will take the reader to the point in the manual where the help text for that function exists.


'doc else' takes the reader to the description of the if statement, which is appropriate.  'help else' produces just a minimal string about 'else'.

The only problem I see is that 'doc' in the GUI is behaving differently then in the CLI.  'doc persistent' or 'doc "figure properties" should work.  Note that there is also a search facility in the documentation tab in the GUI.  The search tab was the subject of bug reports and has been modified to work correctly.  One can type "figure properties" (without double quotes) in to the search field and have it find the correct cross-reference.

Re-titling report to reflect this issue.

Rik <rik5>
Group administrator
Fri 15 Jun 2018 11:49:11 PM UTC, comment #5: 

Sorry, the relevant Texinfo command is @cindex. Many things that have a @cindex entry also have a XREF anchor.

'doc persistent' and 'doc keywords' work for me in the command line interpreter. A separate bug should probably be filed that some index entries don't work properly in the GUI documentation browser with the 'doc' command. For example, 'doc "figure properties"' also works in command line mode but not in the GUI.

Mike Miller <mtmiller>
Group Member
Fri 15 Jun 2018 11:25:18 PM UTC, comment #4: 

I was starting to look into the manual sources to add references for the keywords.
I found the XREFpersistent example but


doc persistent


does not work on my system (Ubuntu), neither does


doc keywords


So what has to be done to add "doc" references?

Lars Kindermann <larskindermann>
Mon 04 Jun 2018 05:38:21 PM UTC, comment #3: 

Sure. The help text that is shown at the command line for "help KEYWORD" is a stub documentation that is maintained separately from the user manual. Meanwhile, the user manual has a more pedagogical approach for introducing the keywords.

If some or all keywords should be accessible in the manual with the "doc" command, then manual XREF anchor points will have to be added into the Texinfo manual sources. See for example XREFpersistent, which allows "doc persistent" to work as you would expect.

A list of all keywords can be obtained with "doc keywords" or "__keywords__", and anchors can be added to the relevant place in the Texinfo source.

Mike Miller <mtmiller>
Group Member
Mon 04 Jun 2018 05:16:33 PM UTC, comment #2: 

Right, doc doesn't show help for just the keywords:

global, function, persistent, if, for, end, continue, ...

Basically all from Chapter 10: Statements.


Lars Kindermann <larskindermann>
Mon 04 Jun 2018 04:56:10 PM UTC, comment #1: 

Is "function" a placeholder or are you literally looking for help on the keyword "function"?

"doc axes" and "doc eig" both work for me in terminal mode and in the GUI.

If you are looking for help on the keyword "function", you won't find it in the manual using "doc function" because there is no XREFfunction node in the user manual. One could be added manually if there is a section of the manual that would make the most sense to jump to.

Mike Miller <mtmiller>
Group Member
Mon 04 Jun 2018 07:56:55 AM UTC, original submission:  


doc function


opens the Documentation browser but does not show info about "function" or start a search for "function".

Lars Kindermann <larskindermann>

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #44412:  guidocsearch2.patch added by pantxo (7KiB - text/x-patch)
file #44403:  guidocsearch.patch added by pantxo (6KiB - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by pantxo (Posted a comment)
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by mtmiller (Posted a comment)
  • -email is unavailable- added by larskindermann (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 15 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2018-07-02 rik5 StatusPatch Submitted Fixed
        Open/ClosedOpen Closed
    2018-06-22 pantxo Attached File- Added guidocsearch2.patch, #44412
        StatusIn Progress Patch Submitted
    2018-06-21 pantxo Attached File- Added guidocsearch.patch, #44403
        StatusConfirmed In Progress
    2018-06-19 rik5 CategoryDocumentation GUI
    2018-06-19 rik5 Summarykeywords should have cindex entries so &quot;doc KEYWORD&quot; works "doc persistent" should work in GUI as it does in CLI
    2018-06-15 mtmiller Summarykeywords should have XREF entries so &quot;doc KEYWORD&quot; works keywords should have cindex entries so "doc KEYWORD" works
    2018-06-04 mtmiller CategoryGUI Documentation
        Severity3 - Normal 1 - Wish
        Item GroupNone Documentation
        StatusNeed Info Confirmed
        Summarythe doc command does not show the info page for its argument keywords should have XREF entries so "doc KEYWORD" works
    2018-06-04 mtmiller StatusNone Need Info

    Back to the top

    Powered by Savane 3.13-758e.
    Corresponding source code