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

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

a general comment (as I am currently working on the tutorial page 2
that you started):

Favor providing compilable code, over providing tables. See my email
where I described the plan for eigen3 documentation: big reference
tables are useful, but can be done as a separate part of the
documentation. In the tutorial it is more useful to provide compilable
code. See above email in this thread for how to do so, and see e.g. my
page 1 for examples.

Benoit

2010/6/26 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
>>>> >>>
>>>> >>>
>>>> >>
>>>> >>
>>>> >
>>>>
>>>>
>>>
>>
>>
>