I looked into what was necessary to write a Texinfo plugin for MediaWiki (which is used by the Gambit wiki). It turns out to be simpler than I thought. So I wrote a plugin which handles <texinfo> ...Texinfo document... </texinfo> in any wiki page. The plugin calls up texi2html to convert the Texinfo document to HTML (currently everytime the page is accessed).
Here are 3 pages written with the <texinfo> tag:
http://dynamo.iro.umontreal.ca/~gambit/wiki/index.php/Procedure_getenv http://dynamo.iro.umontreal.ca/~gambit/wiki/index.php/Procedure_current-time http://dynamo.iro.umontreal.ca/~gambit/wiki/index.php/Special_form_time
Go to one of these pages and click on "edit" to see what the source document looks like. The Texinfo document is wrapped inside <texinfo> and </texinfo> tags.
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.
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.
3) How should hyperlinks work within the wiki?
4) Can the HTML's prettiness be improved?
5) How can the wiki documentation be copied back to the Gambit manual? When should this happen?
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!
Afficher les réponses par date
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
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.
On 1-Dec-08, at 11:26 PM, Jonathan Arkell wrote:
- 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
On Mon, Dec 01, 2008 at 01:46:17PM -0500, Marc Feeley wrote:
- What name should the pages have? I use the Procedure_ and
Or going in a slightly different direction, what namespace should the pages be in? (Does the Gambit wiki's MediaWiki installation support namespaces?)
I'll come clean... I have ulterior motives for asking the question. I use the "All pages" special page a lot, partly because it gives a one-screen overview of the wiki, partly because I have been maintaining a "Release notes" page which nothing links to. Having "All pages" suddenly grow to contain the documentation would make it much less convenient.
- 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.
Do you mean a naming convention for Wiki pages or the organization of the contents into pages? About a naming convention, if the documentation gets its own namespace, there shouldn't be any problem just using the Texinfo node names -- perhaps with a prefix like Section_ -- as the Wiki page names. As metadata rather than nodes, the table of contents and indices should not get any prefix though.
About organizing the contents, is anything irretrievably wrong with the Texinfo organization? Specifically, using one node per Wiki page and having a small number of automatically-updated summary pages, like a table of contents, and multinode-view pages, like "this chapter in one page".
I have been thinking about the question for a while but I don't have a complete answer. The nodes are well-written but finding which node I need can be a problem. There's no explicit organization by audience (Gambit user, installer, developer) or part of the system (language, extensions, FFI, command line options, REPL, editor). Some topics are not in the manual at all.
The Wiki's ability to generate pages automatically (if programmed, and if the building blocks are labeled in the Texinfo file) could be a very nice solution to the problem of organization. Is there a way to stick extra data in the Texinfo sources so that texinfo itself will ignore it? Like giving every node a "part of the system" keyword.
- Can the HTML's prettiness be improved?
Yes. Don't put different sizes or styles of text close together. For example, I don't understand why the input in code boxes looks so different than the output. Bold monospaced would be fine, but bold sans- serif?
Also consider using color. The syntax specs for procedures might be a good place to experiment. Or syntax-highlight the code examples.
In the static texi2html output, the table of contents comes after section 1.1. This is annoying. texi2html may be mysterious and give different output with every version, so I understasnd, but I hope the wiki won't repeat the mistake.
-- Derek
-
Derek Peschel -
Jonathan Arkell -
Marc Feeley -
vasil