|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: Sun, 6 Jun 2010 11:55:40 -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=X3Uj8saggSwn3Z8cDf1lOQjotClDq7tmFpDvj6eK5Lo=; b=ZGUrRoUPsDpOGsqkIpZvvn7jitgnV8R7cO2lvXzpdquH9Ycn741zOdXFC5aic6xIvi KTcLnZYDodBFgyNuKJtQ8m5ZA80AYZvTgR7J0JVtwSBdgtZnQ2l/LreLrWbUTPLzkk53 +aBLXJrwlQL0LyK6doIt/L40F8wEVD/uihL70=
- 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=WnYs3idhsQyQIah24aMemTerP2mXGrAfteEVM0wo5orTUXFYZXjZaMsuc2kZZxLyUD rqmZXAdkPim7BA52hc6an6kWiMBox8wC0HQD5S8cAVl3lIsq7kM3MzAh4FdM0VsvWK18 drLPPGaa6YRCIWaog199MKkVva/tQcnwlrjbE=
2010/6/6 Rui Maciel <rui.maciel@xxxxxxxxx>:
> Thomas Capricelli wrote:
>> Yes, i was about to say that. I use exactly this (mediawiki + pdf export)
>> to generate doc on some other projects, and i'm happy with it.
>> Though, still, i'm not sure this would be the right approach for eigen. The
>> use of doxygen has proved quite successful until now, and is of far better
>> quality than the doc on the wiki.
> There's no need to choose between a wiki documentation and a doxygen
> reference. Both scratch different itches and both can and do coexist rather
>> And i dont buy the argument about wiki database file that can be lost, this
>> is easy to backup.. I could do it, and we could setup something on
>> tuxfamily, and we could setup something on Benoit or Gael's own hard disk.
>> I'm very confident we could do something that makes Benoit happy.
> Indeed. I also thought this argument was a bit far-fetched.
OK, I'm very happy to withdraw this argument if Thomas sets up wiki
backups! Personnally, I am a real n00b about all the server knowledge
that would make that easy (key-based auth, rsync...) but I guess it's
the occasion to learn...
>> Last, i agree that writing doc for eigen is technical, and it's not sure
>> that making it 'easy' (on the wiki) would help. You want people writing
>> such technical topic to be fluent in source, hg, and some such easy doc
>> tool as (say) doxygen.
> It's true that in order to produce documentation, the authors need to know
> what they are writing about. Yet, if someone wishes to contribute something
> to the documentation then chances are that person already looked into the
> source code and found something which, from his experience using Eigen and
> fiddling with the source code, he believes deserves to be documented. To put
> it in other words, we aren't talking about some clueless newbie who just
> parachuted into Eigen's world. If someone intends to contribute to the
> documentation then naturally that person already has some experience with it.
OK, so, I agree that there is a use for documentation on both the wiki
and doxygen... which is actually what we are doing right now! Perhaps
all what was needed, was a good clarification of what should go into
doxygen, and what should go into the wiki. It's going to be impossible
to dictate absolute hard rules, but here are some thoughts:
- The doxygen docs are automatically versioned, the wiki isn't, so
wiki pages must be careful to say to which version of Eigen they
- Standard tutorials and API docs should go into doxygen
- Topic-specific pages on the most important/general topics (e.g.
lazy evaluation) should go into doxygen
- Everyone is welcome to create Wiki pages on topics that doxygen
overlooks (e.g. how to use Eigen with compiler X or interplay with
library Y or numeric type Z...). It is possible/easy to later convert
them into doxygen pages, if needed.
> Rui Maciel