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

 
 

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

Submitted by:  Rik <rik5>
Submitted on:  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

Add a New Comment(Rich Markup)
   

You are not logged in

Please log in, so followups can be emailed to you.

 

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>
Project 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>
Project 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>
Project 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>
Project 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>
Project 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.

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

is quite clear.

Rik <rik5>
Project 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)
  •  

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only project members can vote.

     

     

     

    No changes have been made to this item

    Back to the top


    Powered by Savane 3.3