[gambit-list] Adding docs to wiki?

vasil vasil.s.d at gmail.com
Mon Dec 1 16:03:22 EST 2008


Greetings!

I am very interested in Gambit-C, because of using it in my project.
Very like it for the relative simplicity and good design.
And I would like to support it according to my abilities.

> 1) What name should the pages have?...
type_of_described_object___object_name - is reasonable for the
first-time choice. Procedure_getenv - sounds good. And thoughts about
integration with IDE are good too.

> 3) How should hyperlinks work within the wiki?
It will be great if whole documentation have strong hierarchical
structure. For instance:
	|---Data types
	|        |
	|        |-----Numbers
        |        |         |---Intro
	|        |         |---Exact/Inexact
	|        |         |---Fixnum/Flonum
	|        |         |---Numeric functions
	|        |                    |---Conversion
	|        |                    |---Math operations
	|        |-----Lists
	|        |-----Vectors
... and so on

So, IMHO navigation through pages should consist of next links:
same level articles navigation:      << prev next >> (Intro <->
Exact/Inexact<->Fixnum/Flonum)
Up level:            ^Up
Jump to topic:       ^Numbers
Jump to root:        ^Contents
Links to relative information:       See also: <a> <b> <c>
Links to some other stuff like discussion threads.

Some good ideas of navigation could be found in CLHS ( Common Lisp
HyperSpec)

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

There are few things I'd like to point to:
May be introduce different fonts for different items, to improve
readability? For instance:

in "...(getenv name [default]).."  I suggest to use italic font for
variables and optional values and to make text size larger of other text.

And it will be good to use some tags for color marking of text pieces.
This will help to make accents on important information.

> 5) How can the wiki documentation be copied back to the Gambit  
> manual?  When should this happen?

I think there must be only one, who is responsive for decision which
documentation to copy back. Try to guess, who... :)
And I also think, that every change in documentation, source code and so
on, should go to the final version of Gambit-C via main developer.
Main developer is responsive for keeping good and simple design of
project, including documentation and build system. Take look what is
happening with sbcl now: enormously big, weird and very hard to
understood and maintain. And there is no vector to simplify it and
reduce its complexity, because of absence of main architect.

> Marc
> 
> 
> On 30-Nov-08, at 2:31 PM, Ali wrote:
> 
>> 2008/11/30 Marc Feeley <feeley at iro.umontreal.ca>
>> Having the documentation on the wiki or some user editable place  
>> would be useful.  However, I think the documentation should be  
>> written in one "universal" markup language so that all forms of the  
>> documentation can be generated from it (.pdf, .html, .info, and  
>> "wiki" editable).  Currently that markup language is texinfo.
>>
>> Yeah making a copy of the docs is clearly a bad idea looking back at  
>> it. The impression I got from this thread is that it would be a nice  
>> thing to have some website written using Gambit which had 2 basic  
>> functions:
>> 1) Convert texinfo to some suitable html / wiki format and cache it.
>> 2) Allow users to edit the html / wiki format, which then gets  
>> converted back to texinfo format and committed to the docs and  
>> regenerated again using (1).
>>
>> The trick here would be making sure the texinfo -> wiki -> texinfo  
>> conversion cycle did not change texinfo to something different, but  
>> hopefully this could be done using html attributes.
>>
>> I didn't "bagsie" this myself because I don't know whether this is  
>> beyond me and I can't put an eta on learning all of the stuff behind  
>> it, but I'd like to have a go at it some time if no one has by that  
>> point.
>>
>> Moreover, eventually I would like the documentation for the  
>> procedures and special forms to be inside the source code and the  
>> examples in the documentation should be tested for consistency when  
>> the regression tests are run.  I'm unsure how all of this can work.   
>> Is there a documentation maintenance system that supports all of  
>> this?  Otherwise can one be built?
>>
>> Marc
>>
>> Similar to JavaDoc? I like the idea, and I'm optimistic that the  
>> tools could be written, but this involves questions of file size and  
>> what type of docs would be in the source, so I'm not really inclined  
>> to comment!
>>
>> ps. Playing around with Gambit a bit more now has only made me  
>> happier, I've been very pleasantly surprised by some things. Thanks  
>> for the good work, keep it up!
>>
> 
> _______________________________________________
> Gambit-list mailing list
> Gambit-list at iro.umontreal.ca
> https://webmail.iro.umontreal.ca/mailman/listinfo/gambit-list
> 




More information about the Gambit-list mailing list