On 1-Dec-08, at 11:26 PM, Jonathan Arkell wrote:
- 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