[gambit-list] Adding docs to wiki?

Marc Feeley feeley at iro.umontreal.ca
Tue Dec 2 01:04:59 EST 2008


On 1-Dec-08, at 11:26 PM, Jonathan Arkell wrote:

>>
>> 5) How can the wiki documentation be copied back to the Gambit
>> manual?  When should this happen?
>
> I guess that depends on how easy it is to copy back.  Something  
> occurred to me however.  Most user-level comments, questions, and  
> additions to the documentation would probably live outside of the  
> texinfo section--by virtue of being harder to understand then normal  
> wiki content, whereas the texinfo sections might be reserved for  
> documentation that would actually make it into the Gambit manual.   
> As wiki content gets accepted into the manual, it would move into  
> the texinfo sections.  This should make exporting those sections a  
> little easier.

That's a very good point!  So what I will do is settle on a formatting  
convention that will allow the official an unofficial parts of the  
documentation to be distinguished.  A <texinfo> ... </texinfo> section  
can appear in both parts, and that should be the norm so that it is  
easy to move stuff from the unofficial to the official section.  In  
other words the page will have this form

   <texinfo>
     ...documentation from, or suggested for inclusion in, the Gambit  
manual
   </texinfo>

   == Feedback ==

   <texinfo>
     ...general comments, questions, bug warnings, usage tricks,  
annotations, and stuff to be considered for inclusion in the official  
part
   </texinfo>


>  I guess the real question then becomes: how do you export a chaotic  
> batch of wiki pages into an ordered manual?

I have written a script to export the Gambit manual Texinfo sections  
to wiki pages, using the wiki page title to indicate what this page  
refers to in the manual.  It shouldn't be too hard to write a script  
to "merge" the official part of the wiki documentation pages with the  
Gambit manual.  I'll probably run those scripts on a regular basis to  
see what has changed on the wiki, and view those changes as suggested  
changes to the documentation.  So the structure of the manual is still  
only determined by the structure of the doc/gambit-c.txi document in  
the distribution, but the content of the sections of the manual can be  
edited indirectly on the wiki.

> Overall, i must say that I applaud the movement towards a wiki.  It  
> is a great way to foster contribution and community. Posting a  
> little code snippet or example on a wiki is easy to do, and has a  
> relatively low barrier to entry.  Lord knows, I'll do my best to  
> write documentation and help out.

Great!

Marc




More information about the Gambit-list mailing list