[Chicken-users] Wiki (early) spring cleaning!

[Peter Bex]

Hi all,

Our wiki has grown considerably since it was first set up, and I think
it has become a bit unwieldy.  Right now the wiki part of our subversion
tree contains 493 entries (including directories).  The bulk of this is
documentation for eggs; a quick grep tells me that 266 of these entries
are just egg docs.

The cleanup I'm suggesting does not necessarily have to be major, the
immediate proposal of this mail is simply to move all the eggdocs to
a new subdirectory eggref/3, to match eggref/4 and also to match the
egg structure; eggref/X/Y  will be the documentation for  release/X/Y.

This would solve two problems: The first is the massive file creep in
the wiki rootdir, which makes maintenance of the wiki unneccesarily hard.
The second is the impending problem that will be caused by the release
of Chicken version 4.  Right now we have an eggref/4 directory which
contains documentation of Chicken 4 eggs.  Many eggs that were ported
from Chicken 3 to 4 have a radically different API because the exported
symbols no longer need to be globally unique within a program (so no
more prefixing).  Simply clobbering all the existing eggdocs in the
rootdir with those of the corresponding Chicken 4 eggs is not an option,
since people will keep running Chicken 3 for a while and will need to be
able to look up their version's egg documentation.  This reasoning can
also be applied to future versions, of course.

There's another reason the current layout is problematic.  Currently,
when you surf to http://chicken.wiki.br/wmiirc, for example, you get
the Chicken 3 documentation for the wmiirc egg (as you can see by the
prefixed identifiers).  However, wmiirc has been ported to Chicken 4,
so the moment that Chicken 4 is released, it would make more sense to
have that URL point to the documentation for the current release;
http://chicken.wiki.br/eggref/4/wmiirc
But I would still like the old documentation to be available.  This
would require moving the '3' docs, because the redirect would make the
old docs inaccessible.

Implementing this would mean two things are required: first, moving the
egg docs to the directory.  This is very simple and of course I'm
willing to do this.  The other would be to implement something in the
wiki software that causes an automatic redirect.  I noticed that
*sometimes* this already works (and I remember Alejo posted about this
a while back:
http://lists.gnu.org/archive/html/chicken-users/2008-12/msg00012.html)

I'm not sure what the algorithm is, though, because
http://chicken.wiki.br/sxpath  redirects to eggref/4/sxpath, but
http://chicken.wiki.br/uri-common  shows just the 'edit new page'
dialog.  Presumably because the sxpath egg exports an SXPATH identifier
and the uri-common egg does not export an URI-COMMON identifier.
However, going to http://chicken.wiki.br/uri-reference (for example),
which _is_ an identifier exported by the uri-common egg, it does not
redirect either.

In any case, if you type in chicken.wiki.br/<eggname>, I think it should
forward to the egg page even if the egg does not export a symbol of
that name (it _does_ export a module name of that name, usually,
which is apparently not searched either).  This should then be added
to the 404 behaviour of the wiki.

So, what do you think?  Is this a good idea, or am I overlooking
anything important?  Will it break stuff horribly?

Cheers,
Peter
-- 
http://sjamaan.ath.cx
--
"The process of preparing programs for a digital computer
 is especially attractive, not only because it can be economically
 and scientifically rewarding, but also because it can be an aesthetic
 experience much like composing poetry or music."
                                                        -- Donald Knuth

pgpO9m01Q2fg6.pgp
Description: PGP signature