Re: [eigen] Proposal: documentation for Eigen3

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

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.

Benoit


>  - 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
>>
>>
>>
>