[Pkg-octave-devel] Bug#794780: Bug#794780: octave-image: many typos in help strings

[Francesco Potortì]

>Control: tags -1 upstream
>Control: forwarded -1 https://savannah.gnu.org/bugs/index.php?45707
>
>* Francesco Potortì <Potorti at isti.cnr.it> [2015-08-06 15:57]:
>
>> Package: octave-image
>> Version: 2.4.0-1
>> Severity: minor
>>
>> Sorry, for sending this report here, this is much faster for me than 
>> looking for the bug reporting structure of the source, hope you 
>> understand :(
>
>I do understand, but let me tell you that it is very easy (and actually 
>more productive) to generate a changeset that applies to the upstream 
>Mercurial repository (what I did for you, see below):
>
>http://sourceforge.net/p/octave/image/ci/default/tree/
>
>> From tformfwd:
>>
>>     Given to dimensionnal coordinates from one space, returns two
>>     dimensionnal coordinates in the other space, as defined in the
>>     transform structure T.  Input and output coordinates may be gigen
>>     either as a n-by-2 arrays, or as two n-by-1 vectors.
>>
>>
>> Should be:
>>
>>     Given two dimensional coordinates from one space, returns two
>>     dimensional coordinates in the other space, as defined in the
>>     transform structure T.  Input and output coordinates may be given
>>     either as a n-by-2 arrays, or as two n-by-1 vectors.
>
>I generated the said changeset and attached it to the following bug 
>report:
>
>https://savannah.gnu.org/bugs/index.php?45707
>
>> Additionally, the names of the arguments are not consistent with those 
>> used in the cp2tform and maketform functions
>
>I fail to see the inconsistencies.  Could you please elaborate a bit 
>more?

Rafael, thanks for your work.  I am in a hurry now, and going to go on
vacation, so I'll try to answer this quickly.

 -- Function File: T = cp2tform (RW_PT, AP_PT, TRANSTYPE)
 -- Function File: T = cp2tform (RW_PT, AP_PT, TRANSTYPE, OPT)
     Returns a transformation structure T (see "help maketform" for the
     form of the structure) that can be further used to transform
     coordinates from one space (here denoted "RW" for "real world") to
     another (here denoted "AP" for "apparent").  The transform is

As you can read, the two reference systems are called here "real world"
and "apparent".

 -- Function File: T = maketform (TTYPE, TMAT)
 -- Function File: T = maketform (TTYPE, INC, OUTC)
 -- Function File: T = maketform ("custom", NDIMS_IN, NDIMS_OUT,
          FORWARD_FCN, INVERSE_FCN, TDATA)
     Create structure for spatial transformations.

Here no explicit name is given to the two reference systems, but form
the formal argumetns it is apparent that they are intended as "in" and
"out".

 -- Function File: [UV] = tformfwd (T, XY)
 -- Function File: [U, V] = tformfwd (T, X, Y)

     Given to dimensionnal coordinates from one space, returns two
     dimensionnal coordinates in the other space, as defined in the
     transform structure T.  Input and output coordinates may be gigen
     either as a n-by-2 arrays, or as two n-by-1 vectors.

Here the two reference systems are just anonimous, so no semantic is
even suggested, and they are called "one" and "the other".

So we have three different naming conventions for three functions which
are strictly related.  Since maketform is the basis function, and the
one that choses the naming of the fields in the Tform, probebaly the
"in" and "out" convention should be used in all description strings.

Now that I notice it, the tforminv function has the same exact
description as the tformfwd function, which makes no sense.  The typos
are the same, and besides it should at least mention that while the
tformfwd uses the "forward_fcn" matrix inside the Tform, tforminv uses
the "inverse_fcn" matrix in the Tform.

Okay, this has taken longer than I anticipated, but al tleast we now
have a clear overview of the problem.

-- 
Francesco Potortì (ricercatore)        Voice:  +39.050.621.3058
ISTI - Area della ricerca CNR          Mobile: +39.348.8283.107
via G. Moruzzi 1, I-56124 Pisa         Skype:  wnlabisti
(entrance 20, 1st floor, room C71)     Web:    http://fly.isti.cnr.it