|Re: [eigen] Proposal: documentation for Eigen3|
[ Thread Index |
| More lists.tuxfamily.org/eigen Archives
- To: eigen@xxxxxxxxxxxxxxxxxxx
- Subject: Re: [eigen] Proposal: documentation for Eigen3
- From: Benoit Jacob <jacob.benoit.1@xxxxxxxxx>
- Date: Sat, 5 Jun 2010 14:53:35 -0400
- Dkim-signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:received:received:in-reply-to :references:date:message-id:subject:from:to:content-type :content-transfer-encoding; bh=ou2yc0I2olpXzNCZf3byb+GlfirJ0gA290gWQt9SHaQ=; b=ev+OnNlqqxsjaShlXJMDoHfHSvmUhVusMbusGBHWJMnnwQBmOELixcssACRW63oe2A L4rdtanHGTfdnuZbZ1RnU+LaECYCfZifzdeSHPLv4ElysiupMXnA0tW4L0ImvoI0cQ9H eeeU3bi6BSc1wkJ69pTEejO3atvMge1fWE41Y=
- Domainkey-signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :content-type:content-transfer-encoding; b=sovJDH6M6yyKAd4XLECmLayVeUS4fMSihsN+P8iA93NuTSlh6VJP9vEKMfMTx4Sd3d FqR6i6RLJFzrKRHp3zCYuE1zcYCb5RwjlXbSHDY7LKlTz46WkwppZEATjIsHT1ac1IzM KyeK49aa4NL8ePWvpO6GbGKOByzeDWJXJVtPE=
2010/6/5 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.
What I means here is that using doxygen here doesn't tie us in a
strong way to doxygen: switching to a different dox system would be
very easy, just replace a few tags. On the other hand, using a wiki
ties us quite strongly to this system.
> - 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.
> 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?