bugGNU Octave - Bugs: bug #42536, Expand and correct Manual...

 
 

bug #42536: Expand and correct Manual (octave.pdf) Section 15.3.3

Submitter:  Michael Godfrey <godfrey>
Submitted:  Tue 10 Jun 2014 06:49:27 PM UTC
   
 
Category:  Documentation Severity:  3 - Normal
Priority:  5 - Normal Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Godfrey 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 29 Dec 2014 10:52:01 AM UTC, comment #25: 

This, I think, is in pretty good shape and the fact that the
properties are generated from Octave makes that part of
the Manual self-updating: a major step forward!

As always, the Manual can be improved, but it makes
sense to close this report, with congrtulations to
Pantxo for the great work completing the auto generation!

Michael Godfrey <godfrey>
Group Member
Mon 29 Dec 2014 05:35:47 AM UTC, comment #24: 

What more needs to be done for this report?  The automatic documentation script for graphics properties (genpropdoc.m) seems to work fine.

Rik <rik5>
Group administrator
Fri 17 Oct 2014 06:35:22 PM UTC, comment #23: 

OK I get it. Best to focus on moving ahead.
This could even help convince people that doing
all that is needed to make default a release will
happen sooner...

Michael Godfrey <godfrey>
Group Member
Fri 17 Oct 2014 04:52:52 PM UTC, comment #22: 

I have documented some new features: e.g. paperpositionmode now works as in matlab in default branch, but not in gui-release. Back-porting this patch to gui-release would thus require deleting selectively some docstrings. Furthermore, I suspect periodic merging of gui-release to default would become a real pain.

My opinion is that the effort should be concentrated on documenting all the properties that are already implemented in default.

Pantxo Diribarne <pantxo>
Group Member
Fri 17 Oct 2014 01:08:00 PM UTC, comment #21: 

I just built this. It all looks good. Of course,
more can be done. But, it appears that this is
uniformly better than what was there before.

It would be good to keep in mind that before the
next release, the current default should be pushed
to the release branch. (I did not check if this patch
depends on other default patches.)

One very good effect of this implementation is that it
should generate a Manual which more closely matches
the branch that is in effect.

Very good!!

Michael Godfrey <godfrey>
Group Member
Fri 17 Oct 2014 07:40:52 AM UTC, comment #20: 

Hi,

I have pushed a modified changeset at http://hg.savannah.gnu.org/hgweb/octave/rev/1f2a16d41ba2

I'll leave this bug report open as the most part of documentation work remains to be done.

Pantxo Diribarne <pantxo>
Group Member
Mon 13 Oct 2014 09:34:16 AM UTC, comment #19: 

@Pantxo: doc("patch...") is likely better. Key thing is
to inform users how to find what they need.

Is the shared/object specific properties significant for
users? If so, just explain that shared properties are listed, then
object specific ones, otherwise fully sorted would be better.

I agree that devel is the best place to push this for now.

Michael Godfrey <godfrey>
Group Member
Mon 13 Oct 2014 07:19:08 AM UTC, comment #18: 

@Michael: set function, in comment #15 doesn't display all the properties (read-only are omitted). Maybe

doc ("patch properties")'

is a better choice now we have a better documented properties list?
Now about comment #16, the list is split into shared/object specific properties. It would certainly benefit from being sorted alphabetically instead (even though this separation was very convenient for the purpose of development of genpropdoc.m) . What do you think?

Pantxo Diribarne <pantxo>
Group Member
Mon 13 Oct 2014 07:18:40 AM UTC, comment #17: 

@Michael: set function, in comment #15 doesn't display all the properties (read-only are omitted). Maybe +verbatim+doc ("patch properties")'-verbatim- is a better choice now we have a better documented properties list?
Now about comment #16, the list is split into shared/object specific properties. It would certainly benefit from being sorted alphabetically instead (even though this separation was very convenient for the purpose of development of genpropdoc.m) . What do you think?

Pantxo Diribarne <pantxo>
Group Member
Sun 12 Oct 2014 11:09:43 PM UTC, comment #16: 

I did also just notice that within each property the
sort order seems to be in 2 blocks, i.e. a shortblock that ends with _modified_ and then the rest. It would be good
to explain this if it is a serious trouble to produce a full
sort for each type.


Michael Godfrey <godfrey>
Group Member
Sun 12 Oct 2014 10:58:15 PM UTC, comment #15: 

This looks good. I would say that it is certainly good
enough to push it. I may have missed something while
reading through the resulting Sections, but would the
following text still be useful, probably in Section 15.3.3

++verbatim
+hierarchy. The properties of each graphics object with its allowed values
+can be displayed using:
+
+@multitable @columnfractions .2 .6 .1 .1
+@item Root Figure @tab --- @code{set (0)}
+@item Figure      @tab --- @code{set ( gcf())}
+@item Axes        @tab --- @code{set (gca ())} or @code{set (axes)}
+@item Line        @tab --- @code{set (line)}
+@item Text        @tab --- @code{set (text)}
+@item Image       @tab --- @code{set (image)}
+@item Patch       @tab --- @code{set (patch)}
+@item Surface     @tab --- @code{set (surface)}
+@end multitable
+
+The default value for each property is enclosed in @{ @}.
+
--verbatim

In any case, thanks for all the heavy work!

Michael

Michael Godfrey <godfrey>
Group Member
Sun 12 Oct 2014 10:00:32 PM UTC, comment #14: 

Here is an implementation of automatized graphics properties documentation. It's been long and painful ...

All the hard coded documentation is stored in a fat (and a bit uggly, I admit) IF/SWITCH block in getdoc function (genpropdoc.m).

I have tried to copy/paste/adapt the current documentation but there may be losses. I have also documented some more functions in order to test the versatility of getdoc function.

In order to test the patch it is necessary to regenerate the Makefiles: bootstrap and rebuild.



(file #32263)

Pantxo Diribarne <pantxo>
Group Member
Mon 15 Sep 2014 03:25:19 PM UTC, comment #13: 

We did not get to much specific, but the outline
was to run each of the Octave commands and pipe
the output into a suitable editor (sed?) which
would write the correct texinfo syntax and include
blocks of fixed text where they belong.

This is not a lot different in principle from
how the plots are generated. (of course, these
could also be enhanced to cover more cases to
help explain plotting and catch regressions.)

Rik may have had somewhat more specific ideas.
I will check emails for anything useful.

Michael Godfrey <godfrey>
Group Member
Mon 15 Sep 2014 02:43:45 PM UTC, comment #12: 

Yes, generating this part of the documentation would certainly reduce the maintenance effort. Can you point me to the discussion you had with Rik or explain me what was your conclusions?

Pantxo Diribarne <pantxo>
Group Member
Mon 15 Sep 2014 12:53:14 PM UTC, comment #11: 

I definitely agree. Do as you think best.

By the way, I had a longer term idea to
write scripts which would extract the
properties from Octave when the Manual was
being generated. This would substantially
reduce the overhead in keeping the Manual
up to date. Rik thought that this
was a good idea and had some thoughts about
how to do it.

Michael Godfrey <godfrey>
Group Member
Mon 15 Sep 2014 11:05:02 AM UTC, comment #10: 

If you agree, I will amend your patch with the addition of missing  properties, and probably mark them "read-only", e.g "tightinset (read-only):".

I'll then leave this bug report open and periodically submit new patches to document the various properties that are currently simply listed.

Pantxo Diribarne <pantxo>
Group Member
Mon 15 Sep 2014 10:31:28 AM UTC, comment #9: 

Pantxo,

I have a suggestion: Would you be interested in
taking over this update?  Obviously, you know
quite a lot about how the graphics properties
do or are supposed to work.  And, my time is
quite limited.

I have tried to help with octave for a long time,
but this task has grown and may get done sooner
and better if you could take it on.

Michael

Michael Godfrey <godfrey>
Group Member
Mon 15 Sep 2014 08:03:58 AM UTC, comment #8: 

I definitely agree that "hidden" properties should be
hidden from users. Doing this would simplify use of
the visible properties and simplify the documentation.

I hope that I can assume this change in updating
15.3.3.

Michael Godfrey <godfrey>
Group Member
Mon 15 Sep 2014 07:50:09 AM UTC, comment #7: 

My opinion about hidden properties is that they should not be visible at all in the interpreter. The only documentation for those properties should be found in graphics.in.h or better in doxygen.

I have even posted an approach proposal to fix bug #32497, which consists in avoiding hidden properties to be taken into account during abbrev matching. With this approach, the error message after "get (h, "")" would not show hidden properties anymore.  
 
Hiding/Exposing a property is as simple as adding/removing a "h" in libinterp/corefcn/graphics.in.h, so that if a given property happens to become interesting from the user point of view we can show it easily.

Pantxo Diribarne <pantxo>
Group Member
Sun 14 Sep 2014 10:34:52 PM UTC, comment #6: 

Pantxo,

When I started this I did not realize how incomplete and
inaccurate the documentation was. And, I did not realize
that some things that I was told about how it should work
were also not too reliable.

I removed some descriptions which seemed not too informative.
Maybe I over did that in some cases.

I am adding the text of your email to me so that it does not
get lost:
=============================================
Follow-up Comment #3, bug #43208 (project octave):

This difference between set and get was introduced for matlab compatibility
(see bug #41629). It lets you retrieve read-only properties names e.g. as
follows :

 
fld1 = fieldnames (get (gcf ()));
fld2 = fieldnames (set (gcf ()));
idx = @cellfun (@(s) ! any (strcmp (s, fld2)), fld1);
readonly = fld1(idx)


I admit it would be good to document which properties are read-only in the
manual.

As I don't have matlab at home I can't test the output of "get (gcf (), '')",
and I can't say if there is really a bug about this.
========================================
I will do some more work on the patch when I can
find time. Specifically, correcting the read-only
issue.

About "hidden" properties: are these documented anywhere?
How can I, for all of the properties, find out which
are "hidden"?  And, does "hidden" mean that users
should never know that they exist? Or, what?

Thanks for your help.

Michael Godfrey <godfrey>
Group Member
Sun 14 Sep 2014 10:01:51 PM UTC, comment #5: 

Hi Michael,

At first glance I see that you have deleted some properties descriptions (e.g. figure closerequestfcn). Was it intended?

Also, due to the use of "set (h)", read-only properties (e.g. axes tightinset) are not documented (say listed ...) anymore after your patch. Can you add missing properties?

BTW, about "get (h, "")": this syntax currently leads to an error. I am not fond of documenting this erroneous syntax as a way to retrieve all property names. Furthermore the error messages not only lists regular properties but also hidden ones (such as figure _enhanced_ ).
What about "fieldnames (get (h))"?

Pantxo Diribarne <pantxo>
Group Member
Thu 11 Sep 2014 12:50:20 PM UTC, comment #4: 

The attached patch applies correctly
in the current dev branch.

Some additional corrections and formatting improuvements
were made.

But it was also noticed that
h = figure();
get (h,"");

and set (gcf())

do not yield the same results.

Thus, there is a problem to be fixed.

This patch is based on the results of set (gcf()) and the
other calls as described in the patch.
In any case this patch should be applied since it provides
a much more complete and useful description of the graphics
object properties. It is a lot more accurate than the current
documentation.


(file #32059)

Michael Godfrey <godfrey>
Group Member
Thu 11 Sep 2014 10:55:47 AM UTC, comment #3: 

This patch no longer applies to current source.
I am updating it.

New patch will be posted soon.

Michael Godfrey <godfrey>
Group Member
Wed 10 Sep 2014 11:29:09 PM UTC, comment #2: 

This bug fix has been waiting ince 10 June.

Just a reminder.

Michael Godfrey <godfrey>
Group Member
Thu 03 Jul 2014 10:38:53 PM UTC, comment #1: 

This fix would help users to understand the
graphics properties. It could be appled to the 38.2
release as well as gui and dev.

Michael

Michael Godfrey <godfrey>
Group Member
Tue 10 Jun 2014 06:49:27 PM UTC, original submission:  

This is an updated version of the patch to
plot.txi which applies correctly to the current
dev system.

It adds explanation and corrects many errors
in each graphics properties section.

It the corrections apply to current releases
as well as the dev system.

Michael Godfrey <godfrey>
Group Member

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #32263:  generatedoc.patch added by pantxo (67KiB - application/x-download)
file #31533:  Manual_15-3-3-10-June.diff added by godfrey (39KiB - 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 rik5 (Posted a comment)
  • -email is unavailable- added by pantxo (Posted a comment)
  • -email is unavailable- added by godfrey (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 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2014-12-29 rik5 StatusReady For Test Fixed
        Open/ClosedOpen Closed
    2014-10-17 pantxo StatusPatch Submitted Ready For Test
    2014-10-12 pantxo Attached File- Added generatedoc.patch, #32263
    2014-09-14 pantxo StatusNone Patch Submitted
    2014-09-11 godfrey Attached File- Added Upd_15_3_3_11_Sept_2014.diff, #32059
    2014-06-10 godfrey Attached File- Added Manual_15-3-3-10-June.diff, #31533

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code