Re: function help

[Ben Abbott]

On Feb 24, 2012, at 10:51 PM, Doug Stewart wrote:

> On Fri, Feb 24, 2012 at 10:31 PM, Ben Abbott <address@hidden> wrote:
> 
> On Feb 24, 2012, at 8:45 PM, Doug Stewart wrote:
> 
> > On Fri, Feb 24, 2012 at 2:09 PM, Doug Stewart <address@hidden> wrote:
> >
> >
> > On Fri, Feb 24, 2012 at 11:37 AM, damian.harty <address@hidden> wrote:
> > No problem, I think some small additions along these lines would really 
> > help:
> >
> >
> > 11.1 Defining Functions
> >
> > > The function body consists of Octave statements. It is the most important
> > > part of the definition, because it says what the function should actually
> > > do.
> >
> > + The following examples will work when entered directly from the command
> > prompt. To avoid repeated definition of functions it is convenient to enter
> > those definitions into files for re-use. Some non-intuitive behaviour can
> > occur when performing this - see section 11.9 for detail on including
> > functions inside an m-file. This does not represent a bug and is designed-in
> > behaviour, but is nevertheless a trap for the uninitiated.
> >
> > + Alternatively, individual functions can be stored in their own file of the
> > same name - the function foo can be stored in foo.m - see section 11.8 for
> > the difference between a list of commands, which execute identically to the
> > interactive examples below, and a dedicated /function file/.
> >
> > > For example, here is a function that, when executed, will ring the
> > > bell...etc
> >
> >
> > Any use?
> >
> > Damian
> >
> > I propose an introduction section like this.
> > This would be at the start of the chapter.
> >
> > @node  Introduction to Function and Scipt Files
> > @section  Introduction to Function and Scipt Files
> >
> > There are six different things covered in this section.
> > 1) Typing in a function at the command prompt.
> > 2) Storing a group of commands in a file - called a script file.
> > 3) Storing a function in a file - called a function file.
> > 4) Sub-functions in function files.
> > 5) Multiple functions in one script file.
> > 6) Private functions.
> >
> > Both function files and script files end with an extension of .m
> > If you want more than one independent functions in a file it
> > must be a script file, and to use these functions you must execute
> > the script file before you can use the functions that are in
> > the script file.
> >
> >
> > --
> > DAS
> >
> > https://linuxcounter.net/user/206392.html
> >
> >
> > I have made a patch file for this
> > http://ubuntuone.com/3gQD6bj2JkotmxwfcqR396
> > Would some one please review it and apply it, if it is OK.
> > --
> > DAS
> 
> Doug,
> 
> I noticed that the concepts in question are already present. Perhaps they 
> just need a little clarity ?
> 
> What are your thoughts regarding the attached patch ?
> 
> Ben
> 
> It looks good to me. I think both patches should be applied.
> As a teacher I found  that it is valuable to give an overview of what is to 
> be covered at the start, and then go int details. That is what my patch was 
> trying to do ( give an overview - introduction), and your patch is improving 
> the details.
> 
> Doug

I like your idea of adding a heads-up of sorts in the introduction of 
"Functions and Scripts". My impression is this approach could be used in many 
places. I'd like to think about this more before pushing, as it may make sense 
to propose a template that can be applied to a large number of cases.

I'd propose the major sections should be modified to include a list of the 
section's subsections (hyperlinked) with each accompanied by an introductory 
paragraph giving a brief summary. For example ...

11.1 Defining Functions
        [introductory paragraph]
11.2 Multiple Return Values
        [introductory paragraph]
11.3 Variable-length Argument Lists
        [introductory paragraph]
11.4 Ignoring Arguments
        [introductory paragraph]
11.5 Variable-length Return Lists
        [introductory paragraph]
11.6 Returning form a Function
        [introductory paragraph]
11.7 Default Arguments
        [introductory paragraph]
11.8 Function Files
        [introductory paragraph]
11.9 Script Files
        [introductory paragraph]
11.10 Function Handles, Inline Functions, and Anonymous Functions
        [introductory paragraph]
11.11 Commands
        [introductory paragraph]
11.12 Organization of Functions Distributed with Octave
        [introductory paragraph]

I'm not set on this approach, but I thought it a good idea to discuss this. Any 
thoughts ?

Ben