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!
|
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.
|
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...
|
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.
|
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!!
|
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.
|
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.
|
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
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?
|
Mon 13 Oct 2014 07:18:40 AM UTC, comment #17:
|
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.
|
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
|
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)
|
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.
|
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?
|
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.
|
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.
|
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
|
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.
|
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.
|
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.
|
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))"?
|
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)
|
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.
|
Wed 10 Sep 2014 11:29:09 PM UTC, comment #2:
This bug fix has been waiting ince 10 June.
Just a reminder.
|
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
|
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.
|