bugGNU Octave - Bugs: bug #57138, Categorize graphics properties for...

 
 

bug #57138: Categorize graphics properties for better doc readability

Submitter:  Pantxo Diribarne <pantxo>
Submitted:  Tue 29 Oct 2019 04:49:14 PM UTC
   
 
Category:  Documentation Severity:  2 - Minor
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Open/Closed:  * Closed
Release:  * dev Operating System:  * Any
Fixed Release:  9.1.0 Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Wed 07 Feb 2024 07:59:42 PM UTC, comment #17: 

pushed a fix to
https://hg.savannah.gnu.org/hgweb/octave/rev/360bb7c222c4

to avoid category/property naming collision.  e.g., XREFaxesposition and XREFaxesPosition were property and category names. Not apparent to me on testing but the windows version tried to copy both html redirect files to the same location and they collided since windows is case insensitive for files.

Nicholas Jankowski <nrjank>
Group Member
Tue 30 Jan 2024 01:46:31 AM UTC, comment #16: 

a few more tweaks and pushed the category doc change to stable as
https://hg.savannah.gnu.org/hgweb/octave/rev/ca64468e9710

i think that more that satisfies the original report goals.  closing as fixed.

Nicholas Jankowski <nrjank>
Group Member
Mon 29 Jan 2024 04:08:16 PM UTC, comment #15: 

attached is a slightly modified version.  makes a horizontal list with separators. away from my build machine right now but at least the octave building portion seems ok with this. will test it later.  absent problem will push and can close this.

(file #55640)

Nicholas Jankowski <nrjank>
Group Member
Sun 28 Jan 2024 09:51:17 PM UTC, comment #14: 

thanks. was going to give it a look soon, will start with your patch and work from there.

Nicholas Jankowski <nrjank>
Group Member
Sun 28 Jan 2024 08:43:21 PM UTC, comment #13: 

@nrjank: Thanks. I have no time to help right now, but please find attached a basic  patch that adds links to the categories at the top of the properties pages.

(file #55635)

Pantxo Diribarne <pantxo>
Group Member
Fri 26 Jan 2024 11:09:40 PM UTC, comment #12: 

pushed another update here.
https://hg.savannah.gnu.org/hgweb/octave/rev/25784f22ead3

 Updates property descriptions  for a number of objects, adjusts a number of the categories for uniformity between objects, and puts a number back into the Unused category, esp for root and figure.  the uiXX objects still need property descriptions added. will document that over on bug #65167.
  I think the only thing that might be nice to do to finish this one up would be to add a horizonal category list across the top of these property pages, likely with ref links, so that it's easier to navigate.

Nicholas Jankowski <nrjank>
Group Member
Wed 24 Jan 2024 10:37:26 PM UTC, comment #11: 

What you say for unused vs unimplemented is definitely valid, the latter should stay up in their respective section.

For most objects, if a property is listed, it's because we just haven't gotten around to implementing it yet. So updating these it seems most of what properties that used to be unused were switched to unimplemented, and I'm going through finding more now. e.g., apparently matlab introduced valid children for most, but not all primitives (like lines, patches, etc., but not text and a couple others).  so those I'll switch to unimpl. (and it seems both clipping and clippingstyle for axes should be unimplemented, not unused now that i look at what they mean. clipping in axes affects child objects like an AND gate. child clipping only occurs if axes AND object clipping is ON.)

I'd suggest 'valid' properties like children should stay in the parent/child section for text and the others. but others, like 'buttondownfn' for uimenu (which is only inherited from base, is not even mentioned in any of matlab's help for uimenu or menu objects, but is present in matlab's uimenu property list), and maybe some of the 'root' ones, make sense to kick to an unused section.

Of course, there's still a need in reviewing why they're currently 'unused'.  some aren't actually unused, they just have default values and are read only.  like Root:handlevisibility.  it's always On. it's not unused, it's just read only to 'on' because you can always see the root object. There should probably be a different way to list than rather than 'unused'.  But we also have Visible.  it just plain shouldn't be there.  it's not in matlab's property list. unlike buttondownfn for uimenu, it doesn't even appear in matlab's get(0) list (did it used to?).  why do we have it there?  ideally we'd strip it from the objects and thus remove it from the docs.


Also, I think it might make sense to but a category links at the top of the page to let you jump down to the right section. that would have to be added to the code block you wrote to sort categories. right now, you still just scroll, but we took away the full alphabetization to find something easily. A category list at top would help with that.

Nicholas Jankowski <nrjank>
Group Member
Wed 24 Jan 2024 09:08:54 PM UTC, comment #10: 

Thanks @nrjank for the hard work!

Shouldn't we push actually unused properties into the "Unused" category? I thinks of properties like figure/axes "clipping" that incidentally exist because any graphics objects inherits those, but that make no sense. Those are unused and won't ever be.

On the other hand, for example axes "clippingstyle" is unused because the underlying rendering code has not been implemented. So the doc should say "Not implemented" while the category could still remain "Display".


Pantxo Diribarne <pantxo>
Group Member
Wed 24 Jan 2024 01:55:57 AM UTC, comment #9: 

pushed patch to stable as
https://hg.savannah.gnu.org/hgweb/octave/rev/90c570d578af

category adjustments/other suggestions still welcome. Will be finishing populating the description strings in bug #65167 and may make some tweaks there too.

Nicholas Jankowski <nrjank>
Group Member
Tue 23 Jan 2024 08:08:02 PM UTC, comment #8: 

that looks much better.(see attached screengrab) a bit more cleanup and I'll go ahead and push this so I can go back to the content updates.


Nicholas Jankowski <nrjank>
Group Member
Tue 23 Jan 2024 08:01:40 PM UTC, comment #7: 

that sounds like exactly what I'm looking for. I figured these didn't need to clutter the table of contents. I'll give it a try.

Nicholas Jankowski <nrjank>
Group Member
Tue 23 Jan 2024 07:42:06 PM UTC, comment #6: 

I haven't checked what that would look like. But maybe, you could use `@subsubheading` for the categories?
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040subsubsection.html

Markus Mützel <mmuetzel>
Group administrator
Tue 23 Jan 2024 07:37:38 PM UTC, comment #5: 

working patch against stable attached. the category heading size is wrong but i'm not sure what the better way to do that.

(file #55598)

Nicholas Jankowski <nrjank>
Group Member
Tue 23 Jan 2024 06:28:04 PM UTC, comment #4: 

this got quite stale as expected, I'm in progress for bringing it up to speed with current codebase, hopefully in time to go with the docs for the 9.1 release.

Nicholas Jankowski <nrjank>
Group Member
Wed 10 Nov 2021 09:46:26 PM UTC, comment #3: 

attached is an updated patch against the current default branch. I took the liberty of filling in some categories on new properties.  The updated printdoc function seems ok, the change for categories didn't change much, mainly nesting the main function in another for loop to go through by category. Not too sure how to call/use genpropcod.m, though to test it out.

Also, there are about a dozen properties with no category, as they didn't seem to fit any of the others. they have a ##Uncategorized comment to make it easy for to find and replace them later. I assume they should be defaulted to the Miscellaneous section if I understand the intent correctly.

Small tweaks to this would be easy later, but there are a lot of individual line changes that i suspect would render this patch stale fairly quickly if anyone else makes property changes.   Attached both the updated patch and the modified genpropdoc.m

(file #52234, file #52235)

Nicholas Jankowski <nrjank>
Group Member
Tue 15 Sep 2020 05:47:03 PM UTC, comment #2: 

I think it would be worthwhile doing something like this to make the documentation more useful.
Unfortunately, the patch no longer applies and got incomplete in the meantime.
Could you please rebase the patch on the current default branch?

Markus Mützel <mmuetzel>
Group administrator
Tue 29 Oct 2019 04:50:10 PM UTC, comment #1: 

I attached the patch for testing.

(file #47763)

Pantxo Diribarne <pantxo>
Group Member
Tue 29 Oct 2019 04:49:14 PM UTC, original submission:  

When I have a bug number I'll submit a first draft of a patch that aims at putting every grapĥics properties into a category so that the long lists of graphics properties are split into more readable blocks.

Pantxo Diribarne <pantxo>
Group Member

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #55640:  link_categories_v2.patch added by nrjank (1KiB - application/octet-stream - horizontally listed categories at top of page)
file #55635:  link_categories.patch added by pantxo (1019B - text/x-patch)
file #55599:  properties_headings.png added by nrjank (44KiB - image/png - screenshot of grouping within octave documentation browser)
file #55598:  add_categories_toprops.diff added by nrjank (94KiB - application/octet-stream)
file #52234:  prop_category_v2_bug57138.diff added by nrjank (66KiB - application/octet-stream)
file #52235:  genpropdoc.m added by nrjank (88KiB - text/plain)
file #47763:  prop_category.patch added by pantxo (56KiB - text/x-patch)

 

Depends on the following items: None found

Digest:
   bug dependencies.

 

Carbon-Copy List
  • -email is unavailable- added by nrjank (Updated the item)
  • -email is unavailable- added by mmuetzel (Posted a comment)
  • -email is unavailable- added by pantxo (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 16 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2024-02-10 nrjank Dependencies- bugs #65286 is dependent
    2024-01-30 nrjank Open/ClosedOpen Closed
    2024-01-30 nrjank StatusReady For Test Fixed
        Fixed ReleaseNone 9.1.0
        Planned Release9.1.0 None
    2024-01-29 nrjank Attached File- Added link_categories_v2.patch, #55640
    2024-01-28 pantxo Attached File- Added link_categories.patch, #55635
    2024-01-24 nrjank StatusIn Progress Ready For Test
    2024-01-23 nrjank Attached File- Added properties_headings.png, #55599
    2024-01-23 nrjank Attached File- Added add_categories_toprops.diff, #55598
    2024-01-23 nrjank StatusPatch Submitted In Progress
        Planned ReleaseNone 9.1.0
    2021-11-10 nrjank Attached File- Added prop_category_v2_bug57138.diff, #52234
        Attached File- Added genpropdoc.m, #52235
    2019-10-29 pantxo StatusNone Patch Submitted
    2019-10-29 pantxo Attached File- Added prop_category.patch, #47763

    Back to the top

    Powered by Savane 3.13-3230.
    Corresponding source code