On 06/18/2011 03:00:20 PM, Peter TB Brett wrote: > 1) API documentation sources *must* be in the same repository as the > code, so that a single commit that changes the behaviour & the unit > tests also updates the docs. This is *essential*.
Sure. However, this is no contradiction to using dokuwiki. See my previous post. > 2) The gEDA wiki continues to be hideous and unnavigable, Like I said before, this is in no way an inherent property of wiki style software, or dokuwiki in particular. See my wiki at bibo.iqo.uni-hannover.de or any of the examples offered at http://www.dokuwiki.org/Template I volunteered to morph the look and feel of the geda wiki into something more usable. The response by the geda devs was nil. Yes, this put me off. > Moving the documentation from being in-tree to a separate wiki is > still a decision that I completely fail to comprehend. Why not reclaim it by putting the documentation part of the homepage under git control of the respective source? > 3) Just to be make it entirely clear: we're not talking about the whole > project documentation here, we're talking about API documentation that > will be only of interest to potential developers. The C API docs aren't > on the wiki: why should the Scheme API docs be? Because it lowers the barrier to contribute for everyone. And because it blends perfectly into the rest of the geda website. It is a widely used mark-up system. Comprehensive online help mailing lists and even an IRC channel is available. > I'm not any sort of guru at Dokuwiki I wouldn't call myself a guru, either. But I sure am an experienced dokuwiki admin who knows, what can be done easily. > and neither do I have access to configure the server, so expecting me to > fix these issues is not realistic. Neither does Ales have time to do > so, as far as I can tell. Then delegate the task to someone else. Has there been any effort to try and find a dedicated admin for the website? > At the moment, I can either spend hours (more likely days or weeks) > fighting the wiki, No need. Basic dokuwiki mark-up is straight forward and pretty simple. See http://www.dokuwiki.org/syntax If you want something more fancy like e.g syntax highlighted code snippets, chances are that there is a plug-in available. If you want to see how the mark-up is rendered: 1) install dokuwiki (is included in every major distro) 2) let a symlink in /var/lib/dokuwiki/data/pages/ point to the directory where your documentation sits. 3) point your www browser to http://localhost/dokuwiki.php Does that sound like weeks of fighting? It certainly wasn't to me, when I started with dokuwiki years ago. > and spend the rest of time writing documentation. Dokuwiki > is not a viable option. Well, it is not because you don't like it. Since you are the author, this is a perfectly valid reason. BTW, I am glad the lack of scheme api documentation is about to be relieved. ---<)kaimartin(>--- -- Kai-Martin Knaak Email: [email protected] Öffentlicher PGP-Schlüssel: http://pool.sks-keyservers.net:11371/pks/lookup?search=0x6C0B9F53 _______________________________________________ geda-user mailing list [email protected] http://www.seul.org/cgi-bin/mailman/listinfo/geda-user
