bugGNU Octave - Bugs: bug #46076, Documentation needed for ui*...

 
 

bug #46076: Documentation needed for ui* family of GUI building functions

Submitter:  Rik <rik5>
Submitted:  Tue 29 Sep 2015 04:13:36 PM UTC
   
 
Category:  Documentation Severity:  2 - Minor
Priority:  3 - Low Item Group:  Documentation
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

Mon 11 Mar 2019 06:42:51 PM UTC, comment #24: 

I changed genpropdoc.m to output a header line at the top of the list of graphics properties which includes a cross-reference to the function (such as figure(), axes()) that is being documented.  See https://hg.savannah.gnu.org/hgweb/octave/rev/83774c2a1b92.

Marking as fixed and closing report.

Rik <rik5>
Group administrator
Sun 03 Mar 2019 06:13:23 PM UTC, comment #23: 

@Mike: Yes, it would be desirable to implement your comment #22 and put a cross-reference from each fundamental graphic type (line, surface, uicontrol, etc.) to its list of properties.  This could be done on stable.

Rik <rik5>
Group administrator
Fri 01 Mar 2019 05:16:13 AM UTC, comment #22: 

Is the only thing remaining on this bug report to add a xref from the properties sections to the functions for each control type?

For example something like this


--- a/doc/interpreter/plot.txi
+++ b/doc/interpreter/plot.txi
@@ -1596,7 +1596,7 @@ The @code{uimenu} properties are:
 @subsubsection Uibuttongroup Properties
 @prindex @sortas{@ Uibuttongroup Properties} Uibuttongroup Properties

-The @code{uibuttongroup} properties are:
+The @xref{XREFuibuttongroup,,uibuttongroup} properties are:

 @include plot-uibuttongroupproperties.texi


Should we do the same for all plot objects (e.g. figure, axes, line), not just UI types?

Mike Miller <mtmiller>
Group Member
Tue 13 Oct 2015 06:47:03 AM UTC, comment #21: 

@John: in response to comment #19, maybe genpropdoc can handle this automatically. At the beginning of each list of properties there could be something like

"Properties of _objname_ objects (ref_to_object_doc):"

Pantxo Diribarne <pantxo>
Group Member
Mon 12 Oct 2015 11:12:55 PM UTC, comment #20: 

Pushed refs to properties in default branch - http://hg.savannah.gnu.org/hgweb/octave/rev/93d96da9ff3e

John Donoghue <lostbard>
Group Member
Mon 12 Oct 2015 05:05:22 PM UTC, comment #19: 

Im doing the updates to the docs.

Perhaps in the XXXX Properties, there should be a see also that goes back to the object the properties are for?

John Donoghue <lostbard>
Group Member
Sat 10 Oct 2015 11:53:46 PM UTC, comment #18: 

I needed to merge stable to default for another serious bug so I did that today.

Rik <rik5>
Group administrator
Sat 10 Oct 2015 10:38:13 PM UTC, comment #17: 

Pushed documention to stable
http://hg.savannah.gnu.org/hgweb/octave/rev/7890893a0e69


Will need to update docs to reference the properties when it is next merged to default

John Donoghue <lostbard>
Group Member
Sat 10 Oct 2015 09:56:17 AM UTC, comment #16: 

Ok so I pushed the patch on default:

http://hg.savannah.gnu.org/hgweb/octave/rev/3af34e1ef330

Pantxo Diribarne <pantxo>
Group Member
Sat 10 Oct 2015 01:38:34 AM UTC, comment #15: 

Even if the properties dont get added to stable, the uiXXXXX documents probably still can. The refs to the properties could be added in default.

John Donoghue <lostbard>
Group Member
Sat 10 Oct 2015 12:08:54 AM UTC, comment #14: 

If it's  going to be painful then just document it on default.

Rik <rik5>
Group administrator
Fri 09 Oct 2015 11:07:57 PM UTC, comment #13: 

Doesn't it mean a maintenance burden due to the differences in the build system of default and stable?
In the patch, I modified module.mk for building on default, while it should be Makefile.am and graphics_properties.mk on stable.
 
Do we have to write two separate versions and maintain them in parallel?

Pantxo Diribarne <pantxo>
Group Member
Fri 09 Oct 2015 10:35:46 PM UTC, comment #12: 

It's documentation, so if you can do it on stable everyone will benefit much earlier when there is a point release of 4.0.1.  The release of 4.2 is probably a year away.

Rik <rik5>
Group administrator
Fri 09 Oct 2015 10:29:14 PM UTC, comment #11: 

I attached a patch: uixx properties are in the manual and genpropdoc.m is essentially ready ... to be filled :-).   

The references to all uixx functions were already in place in the "GUI Development" section except uimenu which was in "Interacting with plots". For consistency I moved the orphan with his clan.

Do we want to work on stable or default?

(file #35129)

Pantxo Diribarne <pantxo>
Group Member
Fri 09 Oct 2015 06:52:19 AM UTC, comment #10: 

Thanks John, I'll look into introducing uixxx help strings and properties in the manual this week end.

Pantxo Diribarne <pantxo>
Group Member
Fri 09 Oct 2015 01:01:19 AM UTC, comment #9: 

Updated patch - it will need the refs for the properties to be added, but will need to wait for the node entries.



(file #35113)

John Donoghue <lostbard>
Group Member
Thu 08 Oct 2015 04:29:29 PM UTC, comment #8: 

I might take a look at QT assistant at some stage

In the mean time, thanks Rik for the @ref hints - I will use them.

John Donoghue <lostbard>
Group Member
Thu 08 Oct 2015 03:17:23 PM UTC, comment #7: 

@Pantxo: Yes, I think using QtAssistant would be good, but as you said I'm busy doing many other things on Octave.  Also, I have to say that I'm a CLI guy and so I'm just not as motivated to work on GUI-only issues.

Rik <rik5>
Group administrator
Thu 08 Oct 2015 03:13:28 PM UTC, comment #6: 

@John: To make a hyperclick link that points off to another portion of the manual you can use @ref, @xref, or @pxref.  The @xref variants automatically add "See " to the front of the reference and are used most often in Octave.

For an example, look at plot.txi.


The documentation about a specific graphics object can be displayed
using @code{doc} function, e.g., @code{doc ("axes properties")} will show
@ref{Axes Properties}.


which in the pdf is translated to


The documentation about a specific graphics object can be displayed using doc function, e.g., doc ("axes properties") will show Section 15.3.3.3 [Axes Properties], page 371.


The reference needs to point to an @node entry.  For the Axes Properties example, the reference points to


@node Axes Properties
@subsubsection Axes Properties
@cindex axes properties



Rik <rik5>
Group administrator
Thu 08 Oct 2015 12:15:25 PM UTC, comment #5: 

For reference: bug #44202

Pantxo Diribarne <pantxo>
Group Member
Thu 08 Oct 2015 11:24:03 AM UTC, comment #4: 

@John: In --no-gui mode, where the "doc" function directly calls "info" program, the following lets you look at e.g. axes properties:


doc ("axes properties")
## or point to a specific property
doc ("axes deletefcn")


Unfortunately, AFAICS in the GUI the "doc" function calls the doc browser which in turn only looks for function names in the info file, not sections and anchors.
So basically the doc browser doesn't do much more than the "help" function in those cases (Except being able to look at the manual for what purpose I still prefer to use a pdf viewer).

I looked at this once but got lost too fast :-).

@Rik: There once was a discussion on the eventuality to turn our html doc into Qt Help format so that we could use Qt assistant capabilities to search through the manual, and replace the current doc browser. Did you get a chance to look at this (between the huge amount of tasks you do for Octave :-))?

Pantxo Diribarne <pantxo>
Group Member
Thu 08 Oct 2015 10:27:29 AM UTC, comment #3: 

So basically remove the properties table uicontextmenu help?

Is there a way to link it so that from the uicontextmenu help I can have "For a list of properties see XXXXXX" ?

John Donoghue <lostbard>
Group Member
Thu 08 Oct 2015 08:13:58 AM UTC, comment #2: 

@John: there is a central place, genpropdocs.m, where we currently document the properties like "deletefcn" that any graphics object features. It would be easy to add "uicontextmenu" ("uimenu" and "uipanel" also) to the list of "base" graphics objects that are handled by genpropdoc.m. For the case of "uicontrol" it is another story as there is no 0 argument (default) interface, and this is actually what genpropdoc.m relies on.
So to be clear I think that the help string should only mention important properties that are specific to each uixxx object, and leave details for the manual.

If you agree with this approach I'll look into modifying genpropdoc.m to include uixxx objects.

Pantxo Diribarne <pantxo>
Group Member
Thu 08 Oct 2015 02:54:57 AM UTC, comment #1: 

For starters, how about this for uicontextmenu?



(file #35098)

John Donoghue <lostbard>
Group Member
Tue 29 Sep 2015 04:13:36 PM UTC, original submission:  

The uiXXX family of functions in scripts/gui/ are almost entirely undocumented.  It would be nice if someone who uses these functions regularly could add some text to the m-files there to help out the rest of us.  It appears that most of the core developers don't do GUI development and therefore are unable to perform this task.

Rik <rik5>
Group administrator

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #35129:  uixxproperties.patch added by pantxo (12KiB - application/x-download)
file #35113:  uixxxx_docs.patch added by lostbard (12KiB - text/x-patch)
file #35098:  uicontextmenu.patch added by lostbard (4KiB - 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 lostbard (Updated the item)
  • -email is unavailable- added by rik5
  • -email is unavailable- added by rik5 (Submitted the item)
  • -email is unavailable- added by rik5
  •  

    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 10 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2019-03-11 rik5 StatusConfirmed Fixed
        Open/ClosedOpen Closed
    2019-03-01 mtmiller Severity3 - Normal 2 - Minor
        Priority5 - Normal 3 - Low
        Item GroupNone Documentation
    2015-10-09 pantxo Attached File- Added uixxproperties.patch, #35129
    2015-10-09 lostbard Attached File- Added uixxxx_docs.patch, #35113
    2015-10-08 lostbard Attached File- Added uicontextmenu.patch, #35098
    2015-09-29 rik5 Carbon-Copy- Added pantxo
    2015-09-29 rik5 Carbon-Copy- Added gyom

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code