bugGNU Octave - Bugs: bug #52812, Graphic object properties should...

 
 

bug #52812: Graphic object properties should appear in their own index in manual

Submitter:  Rik <rik5>
Submitted:  Fri 05 Jan 2018 07:03:14 AM UTC
   
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Feature Request
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 08 Jan 2018 05:42:40 PM UTC, comment #6: 

I don't see an easy way to get rid of the space ' ' which I used to make the overall "Object Properties" appear first in the index.

However, the index is in the file pr-idx.txi which is processed in to pr-idx.texi.  If you think it would look better you could remove "Figure Properties" et al. from the index by removing the @prindex in plot.txi.  But then add in some default text at the top of pr-idx.txi which has @ref{} to "Figure Properties", and then call @printindex.

Rik <rik5>
Group administrator
Mon 08 Jan 2018 09:59:53 AM UTC, comment #5: 

In this list of the Texinfo manual

https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Command-and-Variable-Index

at the very beginning is a category that seems to have no subheading or white space that might have been left by a "@ " as the first character.  I wonder how that was done.  However, there is a newer version of the manual in which the @ appears and is move later in the list.

Dan Sebald <sebald>
Mon 08 Jan 2018 09:15:14 AM UTC, comment #4: 

Looks great!  Definitely nice to thin out the other indices.  The "@ " in the index leaves a blank line that sort of unbalances the two columns, but that's quibbling.

Dan Sebald <sebald>
Mon 08 Jan 2018 04:04:54 AM UTC, comment #3: 

I created a new pr index in this cset http://hg.savannah.gnu.org/hgweb/octave/rev/2c497be89710.  I was able to use @sortas to get the general categories like "Figure Properties" and "Axes Properties" to appear first which looks nice.  The individual properties are then listed alphabetically in the index.

Rik <rik5>
Group administrator
Sun 07 Jan 2018 03:40:22 PM UTC, comment #2: 

@Dan: There are two "@defindex op" declarations because there are two separate pieces of documentation being produced.  The documentation in doc/liboctave is just for liboctave, i.e, if you just want to link in the octave computational library to your C/C++ programs.  I'm pretty sure that gets used very, very infrequently, but it is there.

There isn't any need to document the graphics properties in liboctave because the graphics system is part of the interpreter.

The graphics properties are neatly organized by graphics object, but to get quickly from the help for the figure object to the list of figure properties requires a link.  That's why I filed bug #52816 (All graphic objects should have an XREF to the description of their properties).

The list of individual properties should be in some kind of index, as it is now.  To go directly to a particular object's property use doc() as in


doc "figure colormap"
doc "axes children"



Rik <rik5>
Group administrator
Sun 07 Jan 2018 12:55:51 AM UTC, comment #1: 

Good point about the properties not really being concepts.

Pre-defined indices are here:

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Predefined-Indices.html#Predefined-Indices

The manner to define new indices is here:

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/New-Indices.html#New-Indices

It's pretty simple to define new indices, so my preference would be to do that, simply as a memory aid.  That is, "@prindex" is easy to associate with "properties", where "@tindex" isn't as easy.

There are two instances where @defindex already appears:

linux@ ~/octave/octave/octave $ grep defindex doc/*/* -s
doc/interpreter/octave.texi:@defindex op
doc/liboctave/liboctave.texi:@defindex op

Why twice?  I don't know.  Placing a "@defindex pr" near there would be good.

One thing I'm wondering about is further use of the property help within Octave itself, either from the command line or from the GUI.  Now, I just looked at the GUI and the documentation window is actually kind of nice for navigating the manual.  Certainly a Property Index link would be an organized and quick reference, but we should think of a layout that is rather efficient in terms of getting to the right graphics object (e.g., image) and then the property very quickly.  And down the road, could there be a way in which the individual help blocks are made available to the GUI so that it might have a property editor and tooltips with the doc for that property.

Dan Sebald <sebald>
Fri 05 Jan 2018 07:03:14 AM UTC, original submission:  

There are so many graphic object properties, and they are not the same as concepts, so they really shouldn't appear in the Concept index (@cindex).

It would be better if they were placed in their own index.  I would vote for using the pre-existing "type index" (@tindex), although if we want something truly unique to Octave we could use @defindex.

This is a simple one-line change in genpropdocs.m once we decide on a style.


Rik <rik5>
Group administrator

 

(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 sebald (Posted a comment)
  • -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 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2018-01-08 rik5 StatusNone Fixed
        Open/ClosedOpen Closed
    2018-01-05 rik5 Carbon-Copy- Added sebald

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code