From bug-request at octave dot org Fri Mar  3 11:07:35 2006
Subject: Re: See also: gampdf, gamcdf, gaminv, gamrnd
From: "Keith Goodman" <kwgoodman at gmail dot com>
To: "John W. Eaton" <jwe at bevo dot che dot wisc dot edu>
Cc: "William Poetra Yoga Hadisoeseno" <williampoetra at gmail dot com>,         bug@octave.org
Date: Fri, 3 Mar 2006 09:05:56 -0800

On 3/2/06, John W. Eaton <jwe at bevo dot che dot wisc dot edu> wrote:
> On 16-Feb-2006, William Poetra Yoga Hadisoeseno wrote:
>
> | On 2/16/06, John W. Eaton <jwe at bevo dot che dot wisc dot edu> wrote:
> | >
> | > It would be nice to make the usage of the  at seealso{} macro
> | > consistent.  Should they appear before or after the  at end deftypefn
> | > line?  I think they should be formatted as part of the function
> | > description, so that probably means inside.  But I'm not sure whether
> | > that is always formatted correctly in all output formats (HTML, Info,
> | > PDF, etc.).
> | >
> |
> | I think it would be better outside. I just think it's nicer to look at
> | (from the octave prompt), so this might or might not be a valid
> | point...
>
> At the command prompt, should the output look like this ( at seealso
> before  at end defXXX):
>
>  -- Function File:  BAR = frob (FOO)
>      Frob foo to produce BAR.
>
>      See also: sprand.
>
> or this ( at seealso after @end defXXX):
>
>  -- Function File:  BAR = frob (FOO)
>      Frob foo to produce BAR.
>
> See also: sprand.

I think the "see also" should be indented. That's one of the
suggestions I had for changes to the doc string format

http://www.octave.org/octave-lists/archive/help-octave.2005/msg02109.html

So I'd be happy to try making a patch.

Should I also try to deal with "and" in the same patch? Some "see
also" sections contain an "and" before the final function (See also:
func1, func2, and func3); some don't. I think the "and" adds clutter,
does no work.

In your example you leave out the path of the m-file. I think the path
information gets in the way of a quick reading of the doc string and
is better handled by the which function. Are you proposing to not
print the path?



-------------------------------------------------------------
Octave is freely available under the terms of the GNU GPL.

Octave's home on the web:  http://www.octave.org
How to fund new projects:  http://www.octave.org/funding.html
Subscription information:  http://www.octave.org/archive.html
-------------------------------------------------------------