[Top][All Lists]

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

Re: [Chicken-users] egg documentation

From: Mario Domenech Goulart
Subject: Re: [Chicken-users] egg documentation
Date: 12 Feb 2008 14:46:30 -0200
User-agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.4

Hi Graham and folks,

On Tue, 12 Feb 2008 11:32:26 -0500 "Graham Fawcett" <address@hidden> wrote:

> Ivan raised a good point on the Hackathon1 page (where he asks that
> people don't move his egg documentation out of the egg and into the
> wiki, because it's a pain to deal with eggs that don't have a copy of
> their docs in the egg directory itself).
> It's good to have the wiki docs, and especially so with Toby's
> excellent site as a search interface. But it doesn't
> address "local" documentation very well. We've done some work on
> wiki->texi conversion, which is good, but it's not integrated with
> chicken-setup in any way, and that's a drawback.
> One can imagine pushing local docs into the wiki upon releasing a new
> egg version; or adding an "include" mechanism to the wiki to pull in
> external docs (though that would make search-indexing harder if not
> done properly). Since the wiki is stored in the svn repository, there
> are opportunities for svn-commit hooks to do some of the work, as well
> as opportunities for a decent inclusion mechanism.
> Before we venture too far into 'wikifying' all of the egg
> documentation, if that's a hackathon goal, we should probably ensure
> that we have a consistent documentation plan that ensures a local copy
> of the docs is preserved in some form.
> Personally, I'd love to have texi documentation, and (optionally) have
> chicken-setup do the necessary work to pull egg docs into the 'info'
> system. I'd never have to leave Emacs to look something up, and that
> would (for me) be more efficient than keeping a browser
> open.

I think the best alternative would be having svnwiki tags to markup
chicken docs (which is possible).

Something like:

  <procedure name="foo" args="bar baz" retval="string">
      <description>This is foo</description>

>From a known format, we can convert the wiki documentation to whatever
format we need and even have an interactive documentation system.  The
current problem with the wiki documentation is that we don't have
semantic markup.

Best wishes,

reply via email to

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