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