Ali wrote:

Hi there, I'm new to Gambit and it looks like an excellent bit of software.

I was wondering whether or not it would be a good idea to copy the docs onto the wiki system. I'd be more than happy to copy the text across and wiki format it if desired.

As I see it this would have the usual benefits of a wiki, but the disadvantage of having 2 copies of the docs which need to be synchronised.

What will be different from the current possibility to change the documentation, namely using a Gambit Git checkout and a text editor to edit doc/gambit-c.txi in texinfo markup?

* it may be newbie friendlier (web browsers and wiki markup being the tools first used by new computer users nowadays); it may be questionable how much of an advantage inviting newbies is actually, though

* it allows to split the docs into smaller units; but I think the existing texinfo converters can already do that, too

* wikis may have a nicer default layout than the currently offered html output of the texinfo converter: but I suppose that could easily changed too, if it matters at all

* it offers a more informal way of passing over thoughts, i.e. less for changing the actual documentation but for adding comments; I think this would probably be a good thing, but I wonder whether it wouldn't be a better solution to just have an annotation functionality for that; examples for such user annotated documentations: http://www.php.net/manual/en/tutorial.firstpage.php http://dev.mysql.com/doc/refman/5.1/en/apache.html

* the versioning functionality in current wiki systems is much worse than something like Git; not only don't they offer distributed versioning, but also almost no tool access to work with; so merging back changes which happened on the wiki to the Gambit sources will be a manual process just as it will be a manual process to update the wiki documentation with changes happening in the Gambit sources; you should probably be willing to be the manual replacement for good tools for both of these directions.

I've been thinking for some time now that it's time for someone writing a wiki with a Git backend for storage; and optional forking for updates, so each user can work with his own branch [if he wants], [either online or offline], before merging back changes to the canonical location. And if that wiki would support texinfo as markup [or something that offers lossless conversion from/to texinfo, or Gambit moving to a different markup] then it would all become much more workable. Since there are some web frameworks for Gambit out there already, why not start such a wiki implementation? That would really be wonderful, even just for working with "normal" wiki content, not especially documentation. I'd help with the Git interfacing.

Christian.

Having the documentation on the wiki or some user editable place would be useful. However, I think the documentation should be written in one "universal" markup language so that all forms of the documentation can be generated from it (.pdf, .html, .info, and "wiki" editable). Currently that markup language is texinfo. Moreover, eventually I would like the documentation for the procedures and special forms to be inside the source code and the examples in the documentation should be tested for consistency when the regression tests are run. I'm unsure how all of this can work. Is there a documentation maintenance system that supports all of this? Otherwise can one be built?

Marc

On 29-Nov-08, at 8:24 AM, Ali wrote:

Hi there, I'm new to Gambit and it looks like an excellent bit of software.

I was wondering whether or not it would be a good idea to copy the docs onto the wiki system. I'd be more than happy to copy the text across and wiki format it if desired.

As I see it this would have the usual benefits of a wiki, but the disadvantage of having 2 copies of the docs which need to be synchronised.

What do you think? Would such a move bring more disadvantages than advantages?

Ali _______________________________________________ Gambit-list mailing list Gambit-list@iro.umontreal.ca https://webmail.iro.umontreal.ca/mailman/listinfo/gambit-list