[gambit-list] Adding docs to wiki?

Derek Peschel dpeschel at eskimo.com
Tue Dec 2 03:49:46 EST 2008


On Mon, Dec 01, 2008 at 01:46:17PM -0500, Marc Feeley wrote:
> 1) 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.

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

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.

> 4) 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



More information about the Gambit-list mailing list