Re: [eigen] Proposal: documentation for Eigen3

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

Yes, wikis are great to allow people to contribute more easily.
However, I think I still prefer Doxygen, for a few reasons:
 - it makes it much more easy, while writing documentation, to link to
doxygen-generated docs for classes and methods.
 - a wiki can disappear overnight if we do a mistake (rm
eigen_wiki.db) on the server.
 - a wiki can't be read offline
 - some of our users (e.g. willowgarage) embed a build of our dox into
their own dox. A wiki wouldn't allow them to do that easily.
 - it's good  to be able to distribute the dox alongside the software.
 - dox files are actual files, and moreover have a very simple syntax,
they're almost just plain text files. Bonus for the long-term.
 - when one does a modification in the code, having the dox in the
same hg repo allows to adapt them simultaneously, keeping it in sync.
When we branch the code, we automatically branch the dox. With dox on
the wiki, it would be hard to maintain dox for Eigen 2.0, 3.0, 3.1,
...., eventually 4.0.

You are totally right about enabling the community to contribute dox
more easily, though. If people want to do that and find it easier to
do that using the wiki, they are most welcome to do so: it will be
easy to convert that into dox afterwards.

It also isn't hard for the community to contribute dox directly. It is
only slightly more technical than the wiki. See the files *.dox under
doc/. They're very simple, one only needs to know a couple of doxygen
tags and a couple of HTML tags.

Benoit


2010/6/5 FMDSPAM <fmdspam@xxxxxxxxx>:
> Hi (and thank you all for you wonderfull work, by the way),
>
>
> Am 05.06.2010 15:56, schrieb Benoit Jacob:
>>
>> 4) we need a bunch of [] pages on specific topics.
>
> I do have very good (user) experience with wiki's covering "a bunch of
> specific topics".
>
> Certainly, some pages begin as pure playgrounds of personal opinions, but
> (for central topics" they will tend to converge.
> There is a good chance to let the eigen-user-community produce many and high
> quality, topic related pages.
> What do you think, community?
>
> By the way, I'am pearl diving in all eigen news-channels I'am aware of: a)
> this mailing list, b) the Forum, c) the source repository.
> All of them have a clear rasion d'ęrtre formidable. But It is hard to
> recover the pearls if some time is passed by. A Wiki solve this problem.
> I want to encourage the community (including me) to create wiki pages on
> special as well as on ordinary topics.
> How does this fit with the master plan of the eigen nomenclature?
>
> Cheers
> Frank
>
>
>