bugGNU Octave - Bugs: bug #42460, Section 15.3.3 required update for...

 
 

bug #42460: Section 15.3.3 required update for current system

Submitter:  Michael Godfrey <godfrey>
Submitted:  Thu 29 May 2014 05:27:31 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

Tue 10 Jun 2014 06:17:34 PM UTC, comment #22: 

Closed.  Will look for new bug report on issue.

Rik <rik5>
Group administrator
Tue 10 Jun 2014 06:15:06 PM UTC, comment #21: 

The patches below are now out of date
with respect to the current dev system.

PLEASE CLOSE THIS BUG REPORT.

I will submit a new patch which is based
on the current dev plot.txi.

Michael Godfrey <godfrey>
Group Member
Wed 04 Jun 2014 07:33:32 AM UTC, comment #20: 

Mike,

I just added the thread below. Yes,
the changeset that will improve the
documentation for the graphics properties
is file #31472:  Manual_15_3_3_final_v2.patch
It also corrects a typo in graphics.in.h.

As I said, I still think it is worth concidering
automating the updating through use of the
set() commands in the doc build. But, this is
a bit of work.

This patch corrects about 20 or 30 errors in the
current doc as well as explaining how to use set(xx)
to find out what properties are available and
what the default setings are.

OK?

Michael Godfrey <godfrey>
Group Member
Wed 04 Jun 2014 07:26:11 AM UTC, comment #19: 

On Tue, Jun 3, 2014 at 17:00:54 +0100, Michael D. Godfrey wrote:

> On 06/03/2014 04:28 PM, Rik wrote:
>
>> I haven't applied anything.  It seemed like Mike Miller was handling that
>> issue report.
>
>
>> I think we do need a little blurb about every property.  These values
>> don't
>> change often so generating them once and putting them in the documentation
>> is probably a worthwhile use of time.  Also, Matlab does a good job of
>> documenting every single property and it does make things clearer.  See,
>> for example,http://www.mathworks.com/help/matlab/ref/figure_props.html.
>>
>> --Rik
>
> Rik,
> I really liked your suggestion:
> ## In Octave
> unlink doctmp
> diary doctmp
> set (0)
> diary off
> exit
>
> ## In a shell
> perl -i.bak -pe 's/([{}])/\@$1/g' doctmp
> ==================
> You say that these things have not been changing much, but when I edited
> the entries for each property group I found lots of errors.  This
> documentation
> may not have been kept up-to-date, but...  Obviously, people who have been
> changing the properties have not bothered to update the documentation
> in plot.txi.
>
> With the automation above being in use then each category could
> be followed by a bock of explanation and examples. This would be clearer
> and easier to maintain.
>
> Anyhow, the current changeset is up-to-date right now, and is a lot
> clearer than the current, so it would be nice if one of you could push it.


Can we move this back onto the bug tracker? I've lost track of the
context a bit. Is this the "final_v2" changeset you're talking about
now?

Thanks,

-- mike

Michael Godfrey <godfrey>
Group Member
Sun 01 Jun 2014 02:36:03 PM UTC, comment #18: 

I just noticed that graphics-props.cc is auto
generated, so it is not needed in the previous
patch : the change to graphics.in.h does it.

Michael Godfrey <godfrey>
Group Member
Sun 01 Jun 2014 02:30:17 PM UTC, comment #17: 

If the Manual description of the graphics properties is
going to be automated using Rik's suggestion, or in any
case, it would be useful to define a property for each called
"description." This should contain a short description
of the property, like what is currently shown for some
of the properties in plot.txi. This would both make the
set(xxx) display more informative (set would maybe optionally)
show the string balue of "description" and would remove the
need for additional description in plot.txi.


Michael Godfrey <godfrey>
Group Member
Sat 31 May 2014 09:50:45 PM UTC, comment #16: 

How do we want to distinguish between read-only properties and modifiable properties?  The original list of properties in the documentation was generated with get (object_type) and included the read-only properties.  For the root object, for example, there was "screenpixelsperinch" which was deleted in the changeset.

Rik <rik5>
Group administrator
Fri 30 May 2014 11:37:04 PM UTC, comment #15: 

The problem with a simple use of the macro is that
there are properties which have text desribing them.

So, I did an edit which put in the { } around the
default value and I did a global replace of the
--Value: with null. So, now the output is just
like what set() produces, plus the extra text.

I also found that in the axes properties,
perspective was spelled perpective, so I fixed
that in graphics-props.cc and graphics.in.h.

A few things came out poorly formatted so I will
do a bit of tidying and post the changeset.

If someone tells me how to do continuation
lines in an @item string I can shorten some long
lines, too.

The resulting changeset is attached:Manual_15_3_3_final_v2.patch



(file #31472)

Michael Godfrey <godfrey>
Group Member
Fri 30 May 2014 09:40:14 PM UTC, comment #14: 

Rik,

OK, then I will use the escape at least so the
strings will be exactly what set() produces.

Michael Godfrey <godfrey>
Group Member
Fri 30 May 2014 08:33:58 PM UTC, comment #13: 

@Michael:  Texinfo supports '{' and '}' but you need to escape them with an '@' symbol.  The perl script I included does that so the results are valid Texinfo.

Rik <rik5>
Group administrator
Fri 30 May 2014 07:29:57 PM UTC, comment #12: 

Mike:

I tried @code{set (gcf)} or @code{set (0)}
and,as I expected, it did not work. Any suggestions?

Michael Godfrey <godfrey>
Group Member
Fri 30 May 2014 07:10:25 PM UTC, comment #11: 

Rik,

I really like your idea. But, the output of
set(xxx) includes things like {on} and texinfo
does not like {}.  Since I know next to nothing
about texinfo I could not find a way to directly
use the output of the set() calls.

Also, the current text has some additional
commentary for some of the properties. I reduced
this a lot, but some of it seemed useful.

Mike:

I will fix your spacing and line length problems.

Michael Godfrey <godfrey>
Group Member
Fri 30 May 2014 04:05:27 PM UTC, comment #10: 

It seems like we should make this as easy as possible on ourselves by taking the output of Octave itself as the documentation. 

This is a quick hack that works for me.


## In Octave
unlink doctmp
diary doctmp
set (0)
diary off
exit

## In a shell
perl -i.bak -pe 's/([{}])/\@$1/g' doctmp


Rik <rik5>
Group administrator
Fri 30 May 2014 03:43:10 PM UTC, comment #9: 

Thanks Rik. My uncertainty was about changes in this patch like the following:



 @item clipping
- --- Values: @qcode{"on"}, @qcode{"off"}
+ --- Values: @code{[ off | on * ]}


I meant I can't comment on which is the best way to represent the enumerated list of values for each graphics property and also flag which one is the default, and whether to mark that up as a @code segment, as a list of @qcode quoted strings, or in some other way.

For reference, here is how Octave represents the same property when I call set(0):


clipping:  [ off | {on} ]


Mike Miller <mtmiller>
Group Member
Fri 30 May 2014 03:11:53 PM UTC, comment #8: 

Responding to an earlier comment, the @qcode macro is used when the entire piece of code is a quoted piece of text.

Example:


Possible line properties:
@item @qcode{"color"}
@item @qcode{"linewidth"}


But if quotes are just an incidental part of the code then use the regular @code macro.


Changing line width:
@code{set (hl, "linewidth", 5)}



Rik <rik5>
Group administrator
Fri 30 May 2014 01:36:21 PM UTC, comment #7: 

No, nothing has been pushed yet.

Re comment #4, the paragraph that starts with "NOTE" has a line of length 102.

Re comment #5, the patch contains the following:


@code{set(gcf())} or @code{set(0)}
@code{set(gca())} or @code{set(axes)}
@code{set(line)}
@code{set(text)}
@code{set(image)}
@code{set(patch)}
@code{set(surface)}


Notice the spacing and parentheses differences between what's in the patch and what I suggest would be more consistent with Octave coding style:


@code{set (gcf)} or @code{set (0)}
@code{set (gca)} or @code{set (axes)}
@code{set (line)}
@code{set (text)}
@code{set (image)}
@code{set (patch)}
@code{set (surface)}


Mike Miller <mtmiller>
Group Member
Fri 30 May 2014 11:03:40 AM UTC, comment #6: 

Mike:  It appears that the patch has not been
pushed. So, if I am going to make changes I will
make a new changeset based on the original
plot.txi.

Please wait for this before pushing anything.

OK?

In addition to your comments, I noticed a number
of other problems that need correction.

Michael Godfrey <godfrey>
Group Member
Fri 30 May 2014 07:34:43 AM UTC, comment #5: 

You said:
@code{set (gcf)} or @code{set (0)}
@code{set (gca)} or @code{set (axes)}
@code{set (line)}
@code{set (text)}
@code{set (image)}
@code{set (patch)}
@code{set (surface)}

But that is exactly what I did. Did something go wrong?

Michael Godfrey <godfrey>
Group Member
Fri 30 May 2014 07:28:17 AM UTC, comment #4: 

Right. I am not a texinfo expert and this was
a kind of bulk change, so some fine tuning will certainly
help. I will work on it.

About the "Should the formatting maybe mimic what set(obj) shows? "
I thought I did that as closely as I could. I ran
set(0), set(axes), etc. and copied and pasted. So, at
least the Manual matches what Octave says (at least
right now).

I do not see the 80 column overflow problem. Can you
point to that somehow? There are a few places where
the formatting is obviously not good, and I will
fix that.

Anyhow, thanks for pushing it.

Michael Godfrey <godfrey>
Group Member
Fri 30 May 2014 02:44:49 AM UTC, comment #3: 

Thanks, this will be a good addition to the manual, I'm often lost looking for plotting properties and their default values.

I can't comment on the use of @code versus @qcode or how best to represent the enumerated set of options and the default. Should the formatting maybe mimic what set(obj) shows?

Couple suggestions I can make:

  • Paragraphs should be wrapped to less than 80 columns. The first hunk of the patch adds two paragraphs that are wider than 80 columns.
  • Use consistent Octave coding style, for example the table showing ways to call set should probably be formatted as



@code{set (gcf)} or @code{set (0)}
@code{set (gca)} or @code{set (axes)}
@code{set (line)}
@code{set (text)}
@code{set (image)}
@code{set (patch)}
@code{set (surface)}


Mike Miller <mtmiller>
Group Member
Fri 30 May 2014 12:21:29 AM UTC, comment #2: 

I finished the editing of Section 15.3.3
The final patch is attached.

Manual_15_3_3_v2.patch

so, please push it.

(file #31467)

Michael Godfrey <godfrey>
Group Member
Thu 29 May 2014 05:50:29 PM UTC, comment #1: 

The previous patch had other patches include.
Use the new one below to just see the plot.txi changes.
(NOT 31465)

(file #31466)

Michael Godfrey <godfrey>
Group Member
Thu 29 May 2014 05:27:31 PM UTC, original submission:  

Section 15.3.3 about graphics object properties has fallen
behind, and had some pretty unclear points, most
prominently explaining how to display the properties
of each set of objects in the hierarchy.

I have made a start on fixing this.

The attached patch is for INFORMATION ONLY.
It does the root, figure, and beginning of the axes
properties.

Comments would be very welcome before I go ahead and
complete the editing.

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 #31472:  Manual_15_3_3_final_v2.patch added by godfrey (39KiB - application/x-download)
file #31467:  Manual_15_3_3_v2.patch added by godfrey (26KiB - application/x-download)
file #31466:  Manual_15_3_3_v1.diff added by godfrey (9KiB - text/x-patch)
file #31465:  Manual_15_3_3_v1.diff added by godfrey (18KiB - 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 siko1056 (Updated the item)
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by mtmiller (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
    2015-09-28 siko1056 StatusPatch Submitted Fixed
    2014-06-10 rik5 Open/ClosedOpen Closed
    2014-05-30 godfrey Attached File- Added Manual_15_3_3_final_v2.patch, #31472
    2014-05-30 mtmiller StatusNone Patch Submitted
    2014-05-30 godfrey Attached File- Added Manual_15_3_3_v2.patch, #31467
    2014-05-29 godfrey Attached File- Added Manual_15_3_3_v1.diff, #31466
    2014-05-29 godfrey Attached File- Added Manual_15_3_3_v1.diff, #31465

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code