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

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

a few comments:

 - while it's good for the user to know that calling .block(...) by
itself has zero cost, this is not specific to block() but is in
general true for all expressions like a+b ... so no need to mention
that here.

- it is very important to provide some compilable examples. Just see
what is done in page 1 and in the quick start tutorial. By just adding
a file in doc/examples or doc/snippets, you let eigen know that you
want to compile it, run it, and capture its output in a .out text
file, which you can then \verbinclude in the doc. See how we do in
these dox pages.

- it is very important to mention explicitly that .block() and friends
can be used as lvalues, not just as rvalues. As in m.block(...) = foo;
Yes you already give examples for that.

- leftCols() should go in the same section as the corners, rather than
with col().  col() and row(), being specially important, deserve their
own section near the start (just after block() which is the most
important).

- need to mention vector block ops: head(), tail(), segment().

- it is very good that you mention dynamic vs fixed sizes and give
examples for both.

Benoit



2010/6/26 Carlos Becker <carlosbecker@xxxxxxxxx>:
> Ok here it is what I have so far, comments welcomed ;)
> http://carlosbecker.com.ar/eigen/doc/TutorialBlockOperations.html
> I believe that the first subsection on fixed and dynamic-sized objects could
> be presented later on rather than so early in the text. However, it could be
> important to let the reader know this straight away from the beginning so it
> is not ignored.
> Carlos
>
>
> On Sat, Jun 26, 2010 at 11:51 AM, Carlos Becker <carlosbecker@xxxxxxxxx>
> wrote:
>>
>> Ok great! I am glad to know that my contributions are helpful.
>> I am starting to write the Block tutorial, please if anyone else started
>> with this let me know.
>> Carlos
>>
>> On Sat, Jun 26, 2010 at 1:23 AM, Benoit Jacob <jacob.benoit.1@xxxxxxxxx>
>> wrote:
>>>
>>> 2010/6/25 Benoit Jacob <jacob.benoit.1@xxxxxxxxx>:
>>> > Thanks, I have pushed (under your name) your 2 dox pages as-is.
>>> > Indeed, I again didn't have time today :(
>>>
>>> That, and also the fact that your dox pages are actually very good
>>> material as-is. There's work left to do, but they're really useful
>>> already.
>>>
>>> > and didn't want to block
>>> > other people. It's easier to improve these pages now that they are in
>>> > Hg.
>>> >
>>> > I agree with you that the comma-initializer is out of place here.
>>> > Let's add a new page on advanced matrix initialization and
>>> > construction, right after the page on Block... that would also be the
>>> > place to talk about Identity(), Constant(), Random(), LinSpaced()...
>>> >
>>> > It's been a very busy week, but I should really have time this weekend.
>>> >
>>> > Benoit
>>> >
>>> > 2010/6/24 Carlos Becker <carlosbecker@xxxxxxxxx>:
>>> >> Hi Benoit, I have completed my docs but the array part is still
>>> >> incomplete,
>>> >> but I can try to do it for tonight so we can discuss about it.
>>> >> Regarding the matrix algebra tut, I have re-organized things a bit,
>>> >> but I am
>>> >> open to any further changes you may
>>> >>
>>> >> consider: http://carlosbecker.com.ar/eigen/doc/TutorialMatrixArithmetic.html
>>> >> I don't like the idea of introducing the comma initializer in that
>>> >> tutorial
>>> >> since it is not specific to matrix algebra, IMO.
>>> >> Cheers,
>>> >> Carlos
>>> >>
>>> >>
>>> >> On Thu, Jun 24, 2010 at 12:59 PM, Benoit Jacob
>>> >> <jacob.benoit.1@xxxxxxxxx>
>>> >> wrote:
>>> >>>
>>> >>> Hi,
>>> >>>
>>> >>> I think with all the effort that's been going on in the past few
>>> >>> weeks, it would be a pity if we missed our beta1 date this weekend.
>>> >>> Code-wise, we're ready for a beta (though there are some bugs on the
>>> >>> issue tracker that need to be fixed). Documentation is what's
>>> >>> blocking
>>> >>> us. So let's focus on that! Especially the long tutorial.
>>> >>>
>>> >>> - I'll commit my page 1 in a short moment
>>> >>> - Carlos, can you please send us what you have for pages 2-3, if
>>> >>> they're not ready yet then I'll do the work.
>>> >>> - everyone else, write here if you plan to take care of other pages
>>> >>> for the long tutorial, or special topics.
>>> >>>
>>> >>> It would be good to have documentation in a decent state by Saturday.
>>> >>> I'm OK to delay tagging until Sunday. Release a couple of days after
>>> >>> that.
>>> >>>
>>> >>> Benoit
>>> >>>
>>> >>>
>>> >>
>>> >>
>>> >
>>>
>>>
>>
>
>