Re: manual chapter about diagonal and permutation matrices

[Jaroslav Hajek]

On Mon, Feb 23, 2009 at 5:27 PM, Søren Hauberg <address@hidden> wrote:
> man, 23 02 2009 kl. 13:57 +0100, skrev Jaroslav Hajek:
>> I have written a new chapter of the manual, discussing use of diagonal
>> and permutation matrices in Octave:
>> http://hg.savannah.gnu.org/hgweb/octave/rev/fcba62cc4549
>>
>> I would be glad if someone reviews the contents, as well as style,
>> because I don't know much of texinfo yet.
>
> I haven't had the time to read this properly, but a few quick comments:
>
> 1) In the beginning of your newly added file you have
>
>   address@hidden
>   address@hidden htmltex
>   address@hidden ifhtml
>   address@hidden
>   address@hidden htmltex
>   address@hidden iftex
>
>   I don't know what this does, but I don't think we do it anywhere
>   else. If we should have these lines, shouldn't they be in
>   'octave.texi'?
>

I copied this from the header of sparse.txi, but obviously I don't
need it, so I deleted it, thanks.
If you think this should not be in sparse.txi either, then please fix it.

> 2) You reference Wikipedia twice. In general we try to avoid linking to
>   online stuff since the manual is also printed. If we should link to
>   online stuff then I think it requires some discussion. In this
>   specific case, I don't really think the links add much information,
>   so I think they should simply be removed.

Since I only provide basic definitions of what diagonal and
permutation matrix is, I wanted to refer the reader to more
information. I regard Wikipedia as reliable online source and I don't
think references to internet sources are becoming increasingly common
even in printed papers. Note that Wikipedia is easily accessible
worldwide, which you can't say for many textbooks.

> 3) I don't really understand the text that describes how to create
>   permutation matrices. I think it would be nice to have a more
>   explicit example.

OK, can you clarify this? The text shows the exact code for 3 ways of
creating a permutation matrix - by indexing the (diagonal) identity
matrix. I'm not sure how "more explicit" it could be.

I should note that I chose to override an existing syntax here rather
than just create a new built-in function, say, permmatrix or pmatrix,
for two reasons:

1. I thought this way of creating may clarify the connection between
row/column permutation matrices and permutation vectors - see the
examples in "Expressions" (I may have been wrong here).
2. So that it is possible to write code compatible with Matlab, as it
is with diagonal matrices. It will work (save for the NaN issues),
just will run much faster in Octave.
Of course, in Matlab you can't index an expression so you need to
decompose the permutation matrix creation like this:

Id = eye (n); P = Id (p,:);

I think point 2 alone justifies this choice. Maybe it could be noted
in the manual? I was not sure whether or not I should refer to Matlab
in Octave's manual.


> 4) Since we print the manual we try to use TeX commands when describing
>   math. So, instead if writing
>
>   address@hidden != j}
>
>   you might want to consider writing
>
>   address@hidden
>    $i \neq j$
>   address@hidden
>   address@hidden
>   address@hidden != j}
>   address@hidden
>
>   And perhaps similar changes in other places. It makes the Texinfo
>   code harder to read, but the end result looks better.

OK, thanks for the hint. I replaced some instances by this dual
expression. If you find more, fell free to adjust them.

> 5) Is a separate chapter needed for this? Would it be better to write
>   this text as part of matrix.txi ?

I think it fits well (after all, they're something as lightweight
sparse matrices, which also have a separate chapter).
But it can certainly be merged if it's generally agreed upon.

> I apologize for not having more well-thought comments, but I'm short on
> time...

thank you.

-- 
RNDr. Jaroslav Hajek
computing expert
Aeronautical Research and Test Institute (VZLU)
Prague, Czech Republic
url: www.highegg.matfyz.cz