| Re: [eigen] Proposal: documentation for Eigen3 |
[ Thread Index |
Date Index
| More lists.tuxfamily.org/eigen Archives
]
- To: eigen@xxxxxxxxxxxxxxxxxxx
- Subject: Re: [eigen] Proposal: documentation for Eigen3
- From: Rui Maciel <rui.maciel@xxxxxxxxx>
- Date: Sat, 5 Jun 2010 22:53:01 +0100
- Dkim-signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:received:from:to:subject:date :user-agent:references:in-reply-to:mime-version:content-type :content-transfer-encoding:message-id; bh=GcJYVWKM4l2Qffr6qWSkOTSIv6Bj9nFkmrQKRUvtucw=; b=rsqMEGZcE24BBtiBuDHA/Ye5EyOF+6XYBygcxAxToViZTYQllw9Rk1eDRWbPI6q+BD aYQMpmb7xIsIzAKkdDFqdyq8zZYMEIJ3IjKsTDeNAMEv4Cw+xfgCB/Ob8S75NE2hJeZ+ T67jdnvsHKyMsCUvsUVKe/erH0we8DaGRo1xo=
- Domainkey-signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=from:to:subject:date:user-agent:references:in-reply-to:mime-version :content-type:content-transfer-encoding:message-id; b=ZlKZkA+h3aQ7+cGKxXvZTK1CCCtwBLu9wHZlsl/nQOAsXk3KlhAaxIC0GCw5p6purB wbu1aDmdg9g56mVWb0pssnuek6qRq5MwrdHcfqPrcMTO/pMomfmua43+ODbFuwWIkrP2 UN2+RRtz+VSMbIMEFVvtzM+2NJI9NKr0xJMag=
Benoit Jacob wrote:
> 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.
Isn't it possible to have it both ways? Nowadays Eigen's wiki and doxygen
documentation coexist rather nicely.
> - a wiki can disappear overnight if we do a mistake (rm
> eigen_wiki.db) on the server.
I believe there would be a fair number of users who would gladly store backups
for Eigen's wiki.
> - a wiki can't be read offline
I believe that's possible, provided some steps are taken. For example, the
following mediawiki extensions appears to be very promising.
http://www.mediawiki.org/wiki/Extension:Pdf_Book
http://www.mediawiki.org/wiki/Extension:Collection
http://www.mediawiki.org/wiki/Extension:Pdf_Export
> - 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.
Using a wiki for the documentation doesn't take that away.
> - 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.
With enough users you could simply let the wiki "ferment" over time. I
believe there is a considerable number of users who are more than willing to
contribute to the project and editing a wiki is a terribly easy way to do just
that. Moreover, it would make it possible for the documentation to cover
corner cases which otherwise would remain undocumented.
Rui Maciel