chicken-users
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Chicken-users] Comprehensive documentation rewrite


From: Tobia Conforto
Subject: Re: [Chicken-users] Comprehensive documentation rewrite
Date: Tue, 12 Feb 2008 20:55:07 +0100

Graham Fawcett wrote:
In our audience, a regular user might not be averse to editing a sexpr. I really like the wiki philosophy, but I confess I'd much rather do semantic markup with sexprs than somewhat arbitrary wiki tags. I have good tools for navigating sexprs. ;-)

Most developers are already working in the svn repo. I would be more inclined to edit my egg's wiki page in the repo, rather than through the Web interface. Given that, the wiki really becomes more of a place for comments and typographic corrections, which might be better suited to a formal "comments" section at the bottom of the egg's documentation page.

Well said.

This is exactly the spirit I was trying to express.

A semantically rich sexpr-based documentation format that could be updated with your text editor and committed through svn, following branches, tags, etc.

Imagine an online (and partly offline) help system where every symbol is a hyperlink, every procedure is tagged by interest (so you may browse at all the lambdas that have something to do with ports, and then with threads, filter out some unwanted eggs...) No more drowning in the sea of SRFI and was this in extra or in posix?

Also, every page, both indexes and detail pages alike, would be browsable by Chicken version (svn branch, that is.) Was this there in the old times of 3.0? Was the API different?

Every procedure and/or every egg might have a comment section at the bottom.

All the rest of the documentation that's not strictly API reference (such as tips & tricks, examples, users' pages, generic docs...) they can stay where they are, but we can make the wiki and the new hyperdoc as seamless as possible, with matching visual styles, the same site navigation and facilities for cross-linking.


Tobia




reply via email to

[Prev in Thread] Current Thread [Next in Thread]