Re: Writing 'help' functions as m-files

[David Bateman]

John W. Eaton wrote:
> The only disadvantage I can see (other than 
> the work needed for the implementation) is that inserting "*/" in a
> doc string would require special treatment, but I don't think we need
> that.
>
> Should we make a change Like this?
>   
This imposes a lot of work adapting the existing code and might make
oct-files that aren't part of Octave incompatible, so even if this
change is made we should support the old way of doing it as well.
Therefore I rather think this is not really the way to go.. Help from an
m-file if the help string in the oct-file is empty makes sense though
(does this work already?)

> Additionally, the list of items for 3.1 includes "handle block
> comments" (for the scripting language).  Given that, we could also
> write doc strings in .m files using
>
> #{
> -*- texinfo -*-
> @deftypefn {Function File} address@hidden =} convn (@var{a}, @var{b}, 
> @var{shape})
> @math{N}-dimensional convolution of matrices @var{a} and @var{b}.
>
> The size of the output is determined by the @var{shape} argument.
> This can be any of the following character strings:
>
> @table @asis
> @item "full"
> The full convolution result is returned. The size out of the output is
> @code{size (@var{a}) + size (@var{b})-1}. This is the default behaviour.
> @item "same"
> The central part of the convolution result is returned. The size out of the
> output is the same as @var{a}.
> @item "valid"
> The valid part of the convolution is returned. The size of the result is
> @code{max (size (@var{a}) - size (@var{b})+1, 0)}.
> @end table
>
> @seealso{conv, conv2}
> @end deftypefn
> #}
>
> and avoid the need for prefixing every line with "##".  Would that be
> helpful when writing the doc strings?  I suppose that with a decent
> editor it is easy enough to strip the comment characters out, edit the
> doc string, and then replace the comment characters, but using block
> comments would still simplify the process.
>   
A comment in a file is a comment and so I'd have thought that support
for block comments would make such a feature automatically available...
Should this syntax be encouraged is something else..

Regards
D.

-- 
David Bateman                                address@hidden
Motorola Labs - Paris                        +33 1 69 35 48 04 (Ph) 
Parc Les Algorithmes, Commune de St Aubin    +33 6 72 01 06 33 (Mob) 
91193 Gif-Sur-Yvette FRANCE                  +33 1 69 35 77 01 (Fax) 

The information contained in this communication has been classified as: 

[x] General Business Information 
[ ] Motorola Internal Use Only 
[ ] Motorola Confidential Proprietary