Re: gEDA-user: Documentation for scheme API

[Kai-Martin Knaak <kmk@xxxxxxxxxxxx>]

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: kmk@xxxxxxxxxxxxxxx
Ãffentlicher PGP-SchlÃssel:
http://pool.sks-keyservers.net:11371/pks/lookup?search=0x6C0B9F53




_______________________________________________
geda-user mailing list
geda-user@xxxxxxxxxxxxxx
http://www.seul.org/cgi-bin/mailman/listinfo/geda-user