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@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:
- Convert texinfo to some suitable html / wiki format and cache it.
- 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!