Re: [eigen] Documentation : it's a sprint!!

[Benoit Jacob <jacob.benoit.1@xxxxxxxxx>]

2010/7/8 Jitse Niesen <jitse@xxxxxxxxxxxxxxxxx>:
> Hello,
>
> I think the examples on page 4 of the tutorial (on blocks) are perhaps a bit
> too basic. I would like to add more exciting stuff, like
>
>  m.row(i) += 3 * m.row(j);         (*)

Good idea!

There also is room for improvement in this page. For example, in this sentence:

"The most general block operation in Eigen is called .block() . This
function returns a block of size (p,q) whose origin is at (i,j) by
using the following syntax:"

One thing is that the phrasing can be improved, another thing is that
p,q,i,j haven't been introduced before so they don't have a meaning,
and anyway that part is repeated in the subsequent table. I would
rephrase this as just:

"The most general block-related method is block() :"

Another thing that I think can be improved in this page, is that
currently a very, very long time is spend just on block(). The user
has to scroll down a lot to find other methods. Could we find a way to
compress a bit the block() explanations without losing information?
For example by merging examples together, perhaps putting some
explanations as just 1-line comments inside of the example?

>
> What do you (in particular, Carlos, who is doing great work on the tutorial)
> think? Obviously, many people reading the tutorial are beginners - that's
> what it is for - so we should be careful to keep it simple. Perhaps (*) is
> too hard ?
>
> On page 3 (arrays), perhaps we should mention mat1.cwiseMul(mat2) as an
> alternative to mat1.array() * mat2.array() ?

We totally should! Isn't it cwiseProduct?

>
> And what about other coefficient-wise operations, like array.square() ?
> Or would that make the tutorial too long?

it's good to mention briefly, as it gives the user a better sense of
what kind of stuff is available.

>
> There are some topics which we might consider adding to the tutorial:
> * output, how to change precision (perhaps more obvious now but that used
>  to be a common question), .format() or whatever it's called

This is rather material for a special topic page, I think (also
explain IOFormat...). Then need to find a good place in the tutorial
to link to it from.

> * special matrices (triangular, diagonal, etc)

Yes, we discussed in some e-mail that a tutorial page on triangular
would be cool. It's probably a good idea to make it a 'special
matrices' page with at least diagonal mentioned, and mention near the
end the existence of more kinds of special matrices like BandMatrix
and PermutationMatrix without explaining them.

>
> Again, would these make the tutorial too long?

It's not a very big problem. My biggest concern in that respect is if
it makes people drop off the tutorial before reaching the end and we
put some crucial information at the end. Indeed I think we should end
the tutorial with a page or two on stuff that allows people to use
doxygen documentation efficiently. That involves at least knowing
about MatrixBase, ArrayBase, DenseBase, DenseStorageBase. But the
solution, to make sure that people don't miss important stuff at the
end of the tutorial, is probably to find good places where to link to
it from.

Cheers
Benoit

>
> Of course, I realize that raising these issues may well mean I have to do
> it, but I'm not very certain of them so I thought I'd raise them first.
>
> Cheers,
> Jitse
>
>
>