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:
- 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.
- 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.
- How should hyperlinks work within the wiki?
I am not sure I understand this question. Why not handle them as wiki links?
- 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.
- 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.