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

 
 

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

Submitted by:  Rik <rik5>
Submitted on:  Tue 29 Sep 2015 04:13:36 PM UTC  
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  None
Status:  Confirmed Assigned to:  None
Originator Name:  Open/Closed:  Open
Release:  dev Operating System:  Any

Add a New Comment(Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

( Jump to the original submission)

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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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.

which in the pdf is translated to

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

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

For reference: bug #44202

Pantxo Diribarne <pantxo>
Project 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:

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>
Project 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>
Project 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>
Project Member
Thu 08 Oct 2015 02:54:57 AM UTC, comment #1:

For starters, how about this for uicontextmenu?

(file #35098)

John Donoghue <lostbard>
Project 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>
Project 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
  •  

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only project members can vote.

     

     

     

    Follow 5 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    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.3