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.
- 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.
- 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)
- 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.
- 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@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:
- Convert texinfo to some suitable html / wiki format and cache it.
- 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@iro.umontreal.ca https://webmail.iro.umontreal.ca/mailman/listinfo/gambit-list