[gambit-list] Adding docs to wiki?

Marc Feeley feeley at iro.umontreal.ca
Mon Dec 1 13:46:17 EST 2008


I looked into what was necessary to write a Texinfo plugin for  
MediaWiki (which is used by the Gambit wiki).  It turns out to be  
simpler than I thought.  So I wrote a plugin which handles  
<texinfo> ...Texinfo document... </texinfo> in any wiki page.  The  
plugin calls up texi2html to convert the Texinfo document to HTML  
(currently everytime the page is accessed).

Here are 3 pages written with the <texinfo> tag:

http://dynamo.iro.umontreal.ca/~gambit/wiki/index.php/Procedure_getenv
http://dynamo.iro.umontreal.ca/~gambit/wiki/index.php/Procedure_current-time
http://dynamo.iro.umontreal.ca/~gambit/wiki/index.php/Special_form_time

Go to one of these pages and click on "edit" to see what the source  
document looks like.  The Texinfo document is wrapped inside <texinfo>  
and </texinfo> tags.

I'd like to get some feedback on these pages before I put the rest of  
the Gambit manual on the wiki.  Some issues:

1) What name should the pages have?  I use the Procedure_ and  
Special_form_ prefixes so that a name can easily be found.  But  
perhaps it is better to have a unique prefix (Documentation_of_ or  
simply nothing, but this might cause a name clash) so that the page  
can be accessed directly without knowing if the name refers to a  
procedure or a special form.  This would make the wiki documentation  
easy to access from an IDE.  I can easily imagine the IDE adding to  
the error messages a hyperlink to the wiki documentation of the  
procedure which raised the exception.

2) Where should the documentation which is outside the Texinfo @deffn  
forms be put?  For example, general discussion of I/O, or debugging,  
or the compiler, general index, concept index, etc.

3) How should hyperlinks work within the wiki?

4) Can the HTML's prettiness be improved?

5) How can the wiki documentation be copied back to the Gambit  
manual?  When should this happen?

Marc


On 30-Nov-08, at 2:31 PM, Ali wrote:

> 2008/11/30 Marc Feeley <feeley at iro.umontreal.ca>
> 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.
>
> Yeah making a copy of the docs is clearly a bad idea looking back at  
> it. The impression I got from this thread is that it would be a nice  
> thing to have some website written using Gambit which had 2 basic  
> functions:
> 1) Convert texinfo to some suitable html / wiki format and cache it.
> 2) Allow users to edit the html / wiki format, which then gets  
> converted back to texinfo format and committed to the docs and  
> regenerated again using (1).
>
> The trick here would be making sure the texinfo -> wiki -> texinfo  
> conversion cycle did not change texinfo to something different, but  
> hopefully this could be done using html attributes.
>
> I didn't "bagsie" this myself because I don't know whether this is  
> beyond me and I can't put an eta on learning all of the stuff behind  
> it, but I'd like to have a go at it some time if no one has by that  
> point.
>
> 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
>
> Similar to JavaDoc? I like the idea, and I'm optimistic that the  
> tools could be written, but this involves questions of file size and  
> what type of docs would be in the source, so I'm not really inclined  
> to comment!
>
> ps. Playing around with Gambit a bit more now has only made me  
> happier, I've been very pleasantly surprised by some things. Thanks  
> for the good work, keep it up!
>




More information about the Gambit-list mailing list