[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