bugGNU Octave - Bugs: bug #49373, Visual documentation for all...

 
 

bug #49373: Visual documentation for all plot/image functions

Submitter:  Rik <rik5>
Submitted:  Mon 17 Oct 2016 03:41:07 PM UTC
   
 
Category:  Documentation Severity:  1 - Wish
Priority:  5 - Normal Item Group:  Feature Request
Status:  Confirmed Assigned to:  None
Originator Name:  Open/Closed:  * Open
Release:  * dev Operating System:  * Any
Fixed Release:  None Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Mon 20 Aug 2018 09:33:35 PM UTC, comment #5: 


>> that probably means its my responsibility


That is not what I meant, just that it couldn't be something I can address my self :-). But lets dream, we could have a new macro

  @SHOWDEMO(func_name, demo_number, show_text, show_graphics)

ideally for use in both .txi files (along with @DOCSTRING) and in .m files (like @SEEALSO). This way demos could also be used for documentation purpose and examples such as in [1] could be written once and for all in a demo block.

[1] https://octave.org/doc/interpreter/Printing-and-Saving-Plots.html#Printing-and-Saving-Plots

Pantxo Diribarne <pantxo>
Group Member
Mon 20 Aug 2018 03:28:59 PM UTC, comment #4: 

Oh dear, that probably means its my responsibility since I'm the resident Perl expert.  I'll try and take a look at this when I have some free time.

Rik <rik5>
Group administrator
Mon 20 Aug 2018 12:08:00 PM UTC, comment #3: 

@Rik: The easiest way to handle this would be to modify the behavior of the docstring macro so that it adds the first demo (if any) along with the help content. This looks like a PERL/Build-system expert job.

Pantxo Diribarne <pantxo>
Group Member
Mon 17 Oct 2016 05:07:51 PM UTC, comment #2: 

Both things.  Every visual function should have a %!demo so we can catch differences with the dump_plot_demos script.  But I mostly wanted a picture in the PDF documentation which is the second thing.  It's cool that Octave-Forge has already been hooked up that way, but I was thinking of just one, or maybe two, pictures per function that were for documentation purposes.

Rik <rik5>
Group administrator
Mon 17 Oct 2016 05:00:26 PM UTC, comment #1: 

Hi,

Do you mean that each plotting function should have at least one demo or that demos (all or part of) should appear in the html/pdf versions of the manual. I agree with the former, and the latter seams to have been implemented in the documentation generated in octave-forge. See e.g. http://octave.sourceforge.net/octave/function/contourf.html

Pantxo Diribarne <pantxo>
Group Member
Mon 17 Oct 2016 03:41:07 PM UTC, original submission:  

It would be very helpful if every plot/image function had at least one accompanying image to demonstrate what the function actually does.

In English, we say "A picture is worth a thousand words".  And it is true that it is often very difficult to document in text the output of a function, but quite easy to show it.

As an example, the text for the jet colormap is.


This colormap ranges from dark blue through blue, cyan, green, yellow, red, to dark red.


I'm not sure what that would look like, but the image from


rgbplot (jet, "composite")


is quite clear.


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 pantxo (Posted a comment)
  • -email is unavailable- added by rik5 (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.

     

    No changes have been made to this item

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code