bugGNU Octave - Bugs: bug #50247, add text properties link/info to...

 
 

bug #50247: add text properties link/info to help text for text, title, xlabel, and others

Submitter:  Nicholas Jankowski <nrjank>
Submitted:  Tue 07 Feb 2017 08:36:16 PM UTC
   
 
Category:  Documentation Severity:  2 - Minor
Priority:  3 - Low Item Group:  Documentation
Status:  Fixed Assigned to:  None
Originator Name:  Nick Jankowski Open/Closed:  * Closed
Release:  * 5.1.0 Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Mon 14 Sep 2020 02:59:25 AM UTC, comment #19: 

@Nicholas: I finally got around to reviewing this patch.  Thank you very much for this.  I checked it in here http://hg.savannah.gnu.org/hgweb/octave/rev/9342688e86b4.  I made two small further changes so that the documentation would compile.  See http://hg.savannah.gnu.org/hgweb/octave/rev/10060fb23116.

Marking as fixed and closing report.

Rik <rik5>
Group administrator
Wed 19 Feb 2020 02:38:07 AM UTC, comment #18: 

patch updated and attached.

(file #48448)

Nicholas Jankowski <nrjank>
Group Member
Tue 18 Feb 2020 10:50:26 PM UTC, comment #17: 

That would be nice.  It's easiest to review a patch if it applies cleanly and there are no reject files (.rej).

Rik <rik5>
Group administrator
Tue 18 Feb 2020 09:32:38 PM UTC, comment #16: 

The quick turnaround on bug #57845 means 6-7 of the changes in this patch will be redundant. should I rework the patch?

Nicholas Jankowski <nrjank>
Group Member
Tue 18 Feb 2020 05:29:48 AM UTC, comment #15: 

it appears I forgot bug #56929 already addressed alternate plaintext rendering.

Nicholas Jankowski <nrjank>
Group Member
Tue 18 Feb 2020 02:38:14 AM UTC, comment #14: 

separate bugs created for side tasks:

bug #57845 for the comment #12 suggestion of removing redundant reference arguments from the docs

bug #57846 for the comment #7 suggestion on an alternate plaintext rendering

Nicholas Jankowski <nrjank>
Group Member
Tue 18 Feb 2020 02:12:03 AM UTC, comment #13: 

ok. patch attached.  after grep'ing for a number of prop/val, name/val, @var{property}, etc,etc,etc. variations, I generated a list of functions that had name/value pairs. Most new functions either specified possible values in the help, or referenced the docs. Those that didn't were mostly text and graphics/figure/etc properties. Going through those, I added references to Text Properties, Axes Properties, Patch Properties, etc as appropriate.

Patch attached.

files changed are:

doc/interpreter/plot.txi
scripts/gui/dialog.m
scripts/gui/setappdata.m
scripts/gui/waitbar.m
scripts/image/image.m
scripts/image/imagesc.m
scripts/image/imread.m
scripts/plot/appearance/clabel.m
scripts/plot/appearance/gtext.m
scripts/plot/appearance/legend.m
scripts/plot/appearance/private/__gnuplot_legend__.m
scripts/plot/appearance/text.m
scripts/plot/appearance/xlabel.m
scripts/plot/appearance/ylabel.m
scripts/plot/appearance/zlabel.m
scripts/plot/draw/area.m
scripts/plot/draw/bar.m
scripts/plot/draw/barh.m
scripts/plot/draw/colorbar.m
scripts/plot/draw/fill.m
scripts/plot/draw/fplot.m
scripts/plot/draw/hist.m
scripts/plot/draw/line.m
scripts/plot/draw/mesh.m
scripts/plot/draw/meshc.m
scripts/plot/draw/meshz.m
scripts/plot/draw/patch.m
scripts/plot/draw/plot.m
scripts/plot/draw/plot3.m
scripts/plot/draw/rectangle.m
scripts/plot/draw/scatter.m
scripts/plot/draw/scatter3.m
scripts/plot/draw/stairs.m
scripts/plot/draw/stem.m
scripts/plot/draw/stem3.m
scripts/plot/draw/surf.m
scripts/plot/draw/surface.m
scripts/plot/draw/surfc.m
scripts/plot/draw/surfnorm.m
scripts/plot/draw/tetramesh.m
scripts/plot/draw/trimesh.m
scripts/plot/draw/trisurf.m
scripts/plot/draw/waterfall.m
scripts/plot/util/axes.m
scripts/plot/util/figure.m
scripts/plot/util/hggroup.m
scripts/plot/util/subplot.m


I think this more than takes care of the bug fix (or at least mark it patch submitted pending the 47 file review).  Recommend a second bug be opened regarding going through the docs and removing the duplicative ref arguments metnioned in comment #12, and maybe a third one for changing the way text 'links' are rendered as per comment #7

(file #48438)

Nicholas Jankowski <nrjank>
Group Member
Mon 17 Feb 2020 11:26:24 PM UTC, comment #12: 

as per mailing list discusison [1], absent any objection I'm going to just use single argument references for the links.  e.g.:


## The full list of text object properties is documented at
## @ref{Text Properties}.


rather than the no longer necessary @ref{Text Properties, , Text Properties} seen in a lot of the docs at the moment.

[1] https://octave.1599824.n4.nabble.com/preferred-reference-format-to-help-manual-tp4695752.html

Nicholas Jankowski <nrjank>
Group Member
Mon 17 Feb 2020 04:30:04 PM UTC, comment #11: 

commenting that this issue is still present in the 5.2.0 documentation.

doc "Text Properties" does now work since bug #44202 was closed.

following on comment #10, to get an idea of files that could use better pointers to options, a search on the source produces the following:


$ grep -r 'property/value pairs' .
Binary file ./.hg/store/data/scripts/plot/hggroup.m.i matches
./doc/interpreter/oop.txi:any additional arguments should be property/value pairs.
./etc/OLD-ChangeLogs/scripts-ChangeLog: * plot/plot3.m: Correctly compute offsets for property/value pairs.
./etc/OLD-ChangeLogs/scripts-ChangeLog: * plot/__line__.m: Pass initial property/value pairs to __go_line__.
./etc/OLD-ChangeLogs/scripts-ChangeLog: * plot/surface.m: Pass initial property/value pairs to __go_surface__.
./etc/OLD-ChangeLogs/scripts-ChangeLog: * plot/figure.m: Pass "figure" property/value pairs directly to
./libinterp/corefcn/file-io.cc:The behavior of @code{textscan} can be changed via property/value pairs.
./scripts/gui/waitbar.m:    error ("waitbar: invalid number of property/value pairs");
./scripts/gui/waitbar.m:%!error <invalid number of property/value pairs> waitbar (0.5, "msg", "Name")
./scripts/image/image.m:## Multiple property/value pairs may be specified for the image object, but
./scripts/image/image.m:## and axes.  When the only inputs to @code{image} are property/value pairs
./scripts/image/imagesc.m:## and axes.  When the only inputs to @code{image} are property/value pairs
./scripts/miscellaneous/parseparams.m:## from additional arguments given as property/value pairs of the
./scripts/plot/appearance/clabel.m:## Additional property/value pairs that are valid properties of text objects
./scripts/plot/appearance/legend.m:  ## Fix property/value pairs
./scripts/plot/appearance/private/__gnuplot_legend__.m:  ## Find "location", "orientation", "textposition" property/value pairs
./scripts/plot/appearance/private/__gnuplot_legend__.m:    ## Cell array of labels followed by property/value pairs
./scripts/plot/appearance/text.m:## Optional property/value pairs may be used to control the appearance of the
./scripts/plot/draw/area.m:## Additional property/value pairs are passed directly to the underlying patch
./scripts/plot/draw/bar.m:## Optional property/value pairs are passed directly to the underlying patch
./scripts/plot/draw/bar.m:## property/value pairs.
./scripts/plot/draw/barh.m:## Optional property/value pairs are passed directly to the underlying patch
./scripts/plot/draw/colorbar.m:## Additional property/value pairs are passed directly to the underlying axes
./scripts/plot/draw/fill.m:## Multiple property/value pairs for the underlying patch object may be
./scripts/plot/draw/mesh.m:## Any property/value pairs are passed directly to the underlying surface
./scripts/plot/draw/meshc.m:## Any property/value pairs are passed directly to the underlying surface
./scripts/plot/draw/meshz.m:## Any property/value pairs are passed directly to the underlying surface
./scripts/plot/draw/meshz.m:  ## Find where property/value pairs start
./scripts/plot/draw/patch.m:## require directly manipulating patch property/value pairs.
./scripts/plot/draw/patch.m:## can be created by directly passing the property/value pairs
./scripts/plot/draw/patch.m:## Instead of using property/value pairs, any property can be set by passing a
./scripts/plot/draw/private/__stem__.m:    ## property/value pairs
./scripts/plot/draw/rectangle.m:## Additional property/value pairs are passed to the underlying patch command.
./scripts/plot/draw/scatter.m:## Additional property/value pairs are passed directly to the underlying
./scripts/plot/draw/scatter3.m:## Additional property/value pairs are passed directly to the underlying
./scripts/plot/draw/stairs.m:## Multiple property/value pairs may be specified, but they must appear in
./scripts/plot/draw/stem.m:## Optional property/value pairs may be specified to control the appearance
./scripts/plot/draw/stem3.m:## Optional property/value pairs may be specified to control the appearance
./scripts/plot/draw/surf.m:## Any property/value pairs are passed directly to the underlying surface
./scripts/plot/draw/surfc.m:## Any property/value pairs are passed directly to the underlying surface
./scripts/plot/draw/tetramesh.m:## property/value pairs directly to the patch function as additional arguments.
./scripts/plot/draw/trimesh.m:## Any property/value pairs are passed directly to the underlying patch object.
./scripts/plot/draw/trisurf.m:## Any property/value pairs are passed directly to the underlying patch object.
./scripts/plot/draw/waterfall.m:## Any property/value pairs are passed directly to the underlying surface
./scripts/plot/util/findobj.m:## property/value pairs are specified then only objects meeting all of the
./scripts/plot/util/hggroup.m:## Multiple property/value pairs may be specified for the hggroup, but they
./scripts/plot/util/subplot.m:## Any property/value pairs are passed directly to the underlying axes object.


some of these are text properties, others are figure / axis / whatever properties. I'll to a quick scan through the list and see if any others could have quick link adds to close out the bug of at least having some pointer to the info. 

Personally, the way those pointers appear in the interpreter and CLI interfaces is still unsatisfying. Anything that can't render a link is 'odd'.

E.g., webpage, pdf, and doc browser, you get clickable "Text Properties" link. 

help text gives:

 Programming Note: The full list of properties is documented at
     *note Text Properties: Text Properties.


in the 'doc text' called from Octave CLI - you get teh same thing, except the first * note Text Properties is colored and you can cursor to it and execute a link to the properties page.  What's the value of *note, and why the duplicate Text Properties::Text Properties? (and why is there sometimes one : and other times two :: ?)

I think as mentioned before after adding links to appropriate places, a separate bug could be made for more intuitive Text only info.  (E.g., at the end of every help call it says "use the command 'doc <topic>' to search the manual index." maybe "*note Text Properties:Text Properties" should just be "<Text Properties>.  with the note at the end I'd read that as a doc link indicator.

anyway, TL;DR: will follow up with text link adds.

Nicholas Jankowski <nrjank>
Group Member
Wed 30 Oct 2019 09:22:05 PM UTC, comment #10: 

In general, it would also be nice to have more references to lists of relevant properties so users know where to turn. I've many times found myselve chasing wild geese trying to find what property of what object to modify.

As an example of something with both well-made references and some room for possible additions, the plot function reference has several property-value pairs specific to that function:
https://octave.sourceforge.io/octave/function/plot.html
Are there additional property-value pairs that may be passed through the function? What are they? In this case, the documentation points to "Line Properties". It's hyperlinked in the GUI documentation, but not in the online documentation.

There many plot-related knows that may be tweaked that don't fall under this, though. For example, recently, someone asked how to change the labels on the bottom of their plot. This was done by modifying one of the axes properties, but a user who only read about the plot function would not know about that. Users are likely going to go straight to the plot function reference without first reading about figures and axes and their respective properties, so it would be helpful to add a note stating where additional, related properties could be found and used to modify particular aspects of a plot.

The example I cited in which a user wanted to change axis labels was actually for a bar graph, so that's another page that could use such a reference.

Brett Green <bgreen>
Mon 11 Mar 2019 09:50:27 PM UTC, comment #9: 

I hadn't thought of clabel, but the five functions you mentioned would be enough for me.

Rik <rik5>
Group administrator
Mon 11 Mar 2019 09:45:06 PM UTC, comment #8: 

This issue is still open, and could be fixed in Octave 5.2. Is someone interested in writing a change to apply to the stable branch? Or at least going through the docs and identifying a full list of functions that should include a link to the "Text Properties" section?

Of the functions mentioned in this report so far, "text" already has the link. The "title", "xlabel", "ylabel", and "zlabel" functions do not. Should "clabel" include it? Any others?

Mike Miller <mtmiller>
Group Member
Thu 09 Feb 2017 04:42:07 PM UTC, comment #7: 

We've lived with the current behavior of links in plaintext format for years.  So, I again vote to make that a separate issue report which we may or may not deal with.  The immediate issue is just adding @pxref entries to the docstrings for text, title, etc.  That's just documentation so it could be made on the stable branch.

Rik <rik5>
Group administrator
Wed 08 Feb 2017 11:50:04 PM UTC, comment #6: 

Probably the reason that we don't use the --plaintext option for makeinfo is that hasn't always existed.  Even if I knew about it, I don't know that it would have been clear to me that there was any advantage for using it.  It seems to be the same as Info format with --no-headers, though I guess it does allow you to check for "plaintext" as different from "info".

John W. Eaton <jwe>
Group administrator
Wed 08 Feb 2017 05:18:12 PM UTC, comment #5: 

There are two separate issues here.  One is adding a reference to "Text Properties".  That is the subject of this bug report and should be easy for someone to fix.

The second issue is the display of links in a plaintext environment.  That could be the subject of another bug report, although we have lived with the current behavior for quite a while.  Texinfo does provide conditionals for using different text in different output formats.  The one that would be of most use here is


 '@inlinefmtifelse{FORMAT, THEN-TEXT, ELSE-TEXT}'
      Process the Texinfo THEN-TEXT if FORMAT output is being generated;
      otherwise, process ELSE-TEXT.


However, the tricky thing to resolve is that Octave is running the formatter for 'info' output when producing the text for the terminal.  The file scripts/help__makeinfo__.m would need modification.  I've attached a quick implementation to this report as plaintext.diff, but I haven't checked if it breaks anything.


diff -r 589e7b0f2329 scripts/help/__makeinfo__.m
--- a/scripts/help/__makeinfo__.m        Wed Feb 08 08:46:54 2017 -0800
+++ b/scripts/help/__makeinfo__.m        Wed Feb 08 09:15:01 2017 -0800
@@ -127,10 +127,10 @@ function [retval, status] = __makeinfo__
     ## Take action depending on output type
     switch (lower (output_type))
       case "plain text"
-        cmd = sprintf ("%s --no-headers --no-warn --force --no-validate --output=- %s",
+        cmd = sprintf ("%s --plaintext --no-headers --no-warn --no-validate --force --output=- %s",
                        makeinfo_program (), name);
       case "html"
-        cmd = sprintf ("%s --no-headers --html --no-warn --no-validate --force --output=- %s",
+        cmd = sprintf ("%s --html --no-headers --no-warn --no-validate --force --output=- %s",
                        makeinfo_program (), name);
       otherwise
         error ("__makeinfo__: unsupported output type: '%s'", output_type);
diff -r 589e7b0f2329 scripts/plot/appearance/xlabel.m
--- a/scripts/plot/appearance/xlabel.m        Wed Feb 08 08:46:54 2017 -0800
+++ b/scripts/plot/appearance/xlabel.m        Wed Feb 08 09:15:01 2017 -0800
@@ -24,7 +24,9 @@
 ## Specify the string used to label the x-axis of the current axis.
 ##
 ## An optional list of @var{property}/@var{value} pairs can be used to change
-## the properties of the created text label (@pxref{Text Properties}).
+## the properties of the created text label
+## @inlinefmtifelse{plaintext,
+## (use @w{@code{doc ("Text Properties")}})., (@pxref{Text Properties}).}
 ##
 ## If the first argument @var{hax} is an axes handle, then operate on
 ## this axis rather than the current axes returned by @code{gca}.


If you do carry through on the second bug report, it would be best to create a macro so that one could write


@doclink{Text Properties}


and have it expand out to the longer inlinefmtifelse Texinfo command.

Rik <rik5>
Group administrator
Wed 08 Feb 2017 08:54:03 AM UTC, comment #4: 

I don't understand exactly why the help text displayed in a terminal is still in info format. If it was plain text we could use some conditionals like


...
@ifplaintext
  use @qcode{doc ("Text Properties")}.
@end ifplaintext
@ifnotplaintext
  @pxref{Text Properties}
@end ifnotplaintext


So that pdf, info and html versions would provide a link while the terminal help text would provide a command to be run in the terminal.

Pantxo Diribarne <pantxo>
Group Member
Wed 08 Feb 2017 05:41:56 AM UTC, comment #3: 

The rendering in plain text isn't that great, but that is Texinfos fault.  It would look like this


     An optional list of PROPERTY/VALUE pairs can be used to change the
     properties of the created text label (*note Text Properties::).



Rik <rik5>
Group administrator
Wed 08 Feb 2017 05:27:59 AM UTC, comment #2: 

yeah, that would take care of it in the document.  how would that render for 'help xlabel'?

Nicholas Jankowski <nrjank>
Group Member
Wed 08 Feb 2017 05:11:58 AM UTC, comment #1: 

Why not just put an xref or pxref entry to "text properties"?  This will be a hyperlink in the Info or online documentation.

For example,


diff -r 6edad6ad4da9 scripts/plot/appearance/xlabel.m
--- a/scripts/plot/appearance/xlabel.m        Tue Feb 07 10:30:31 2017 -0800
+++ b/scripts/plot/appearance/xlabel.m        Tue Feb 07 21:10:58 2017 -0800
@@ -24,7 +24,7 @@
 ## Specify the string used to label the x-axis of the current axis.
 ##
 ## An optional list of @var{property}/@var{value} pairs can be used to change
-## the properties of the created text label.
+## the properties of the created text label (@pxref{Text Properties}).
 ##
 ## If the first argument @var{hax} is an axes handle, then operate on
 ## this axis rather than the current axes returned by @code{gca}.



Rik <rik5>
Group administrator
Tue 07 Feb 2017 08:36:16 PM UTC, original submission:  

following from a mailing list discussion [1]

requesting a link or other information be added to the functions text, title, xlabel, ylabel, zlabel, and maybe others that currently contain the text:

"Optional property/value pairs may be used to control the appearance of the text."

There is a page in the manual providing this information [2] but seems to be no way to link to it with "help" or "doc".

This appears to be at least in part a GUI manual limitation, as discussed in bug #44202

Recommend making this bug dependent on bug #44202, then when it's fixed by changing the help text in the subject functions to:

"Optional property/value pairs may be used to control the appearance of the text. Use doc("text properties") to see a list of available options."


[1] http://octave.1599824.n4.nabble.com/property-options-for-text-others-tp4681786.html

[2] https://www.gnu.org/software/octave/doc/interpreter/Text-Properties.html#Text-Properties

Nicholas Jankowski <nrjank>
Group Member

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #48448:  update_doc_TextAndFigRefs_v2.diff added by nrjank (25KiB - application/octet-stream - updated, removing files redundant with other bug)
file #48438:  update_doc_TextAndFigRefs.diff added by nrjank (28KiB - application/octet-stream)
file #39704:  plaintext.diff added by rik5 (2KiB - application/x-download)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by bgreen (Posted a comment)
  • -email is unavailable- added by jwe (Posted a comment)
  • -email is unavailable- added by pantxo (Posted a comment)
  • -email is unavailable- added by rik5 (Posted a comment)
  • -email is unavailable- added by nrjank (Submitted the item)
  • -email is unavailable- added by nrjank
  •  

    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 11 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2020-09-14 rik5 StatusNeed Info Fixed
        Open/ClosedOpen Closed
    2020-02-19 nrjank Attached File- Added update_doc_TextAndFigRefs_v2.diff, #48448
    2020-02-18 nrjank Attached File- Added update_doc_TextAndFigRefs.diff, #48438
    2019-03-11 mtmiller Severity3 - Normal 2 - Minor
        Priority5 - Normal 3 - Low
        Item GroupFeature Request Documentation
        StatusNone Need Info
        Release4.2.0 5.1.0
    2017-02-08 rik5 Attached File- Added plaintext.diff, #39704
    2017-02-07 nrjank Carbon-Copy- Added pantxo

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code