[gambit-list] Adding docs to wiki?

Jonathan Arkell jonnay at jonnay.net
Mon Dec 1 23:26:12 EST 2008


On 1-Dec-08, at 11:46 AM, Marc Feeley wrote:
>
> 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.

I like Special_form and Procedure_ prefixes. You might need some  
other prefixes as well. If you categorize all the documentation  
pages, you can automagickally have indexes and tables of contents  
built up with mediawiki.

> 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.

Why not Documentation_of_debugging, and Documentation_of_I/O?

Again, the General Index and Concept Indexes should be handled via  
categories.

> 3) How should hyperlinks work within the wiki?

I am not sure I understand this question.  Why not handle them as  
wiki links?

> 4) Can the HTML's prettiness be improved?

Yes. I can even try and take a stab at this if you like.  I'm an okay  
designer, and rock solid web developer.

> 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.  I guess the real question then becomes: how do you export a  
chaotic batch of wiki pages into an ordered manual?

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.





More information about the Gambit-list mailing list