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: Mario Domenech Goulart
Subject: Re: [Chicken-users] Comprehensive documentation rewrite
Date: 12 Feb 2008 17:02:30 -0200
User-agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.4

Hi Graham and folks,

On Tue, 12 Feb 2008 13:34:02 -0500 "Graham Fawcett" <address@hidden> wrote:

> On 12 Feb 2008 15:54:32 -0200, Mario Domenech Goulart
> <address@hidden> wrote:
> > Hi Tobia,
> >
> > On Tue, 12 Feb 2008 18:37:36 +0100 Tobia Conforto <address@hidden> wrote:
> >
> > > Mario Domenech Goulart wrote:
> > > > Would it be integrated to the wiki system?
> > >
> > > How much and what kind of integration do we need?
> >
> > It would be nice if a regular user could edit the documentation like
> > he/she would do with the current wiki system.
> 
> 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. Personally, I've never modified the documentation
> of someone else's egg; perhaps if I saw a typo, but even then I would
> contact the author, in case they kept the documentation in a secondary
> form.

I think the wiki system has a great value and it is one of the reasons
why chicken has such a rich documentation and a nice user base.

There are other things besides documentation of eggs and chicken that
are also on the wiki (e.g., tips and tricks, code snippets, users
pages etc).  Those pages are not necessarily edited by developers and
are very important for the project.

If we want non-developers to edit pages, they'd need an svn
account. This would either be impractical (an svn account for each
contributing user) or would be another barrier for contributions.

Eliminating one way of editing chicken docs (i.e., via web-browser)
doesn't add anything, but makes contributions more difficult and less
practical. I do frequently use the web interface for editing the wiki,
for example -- specially when I'm using a machine with no svn client
(most computers have a web-browser) or I when I just don't want to
checkout the wiki tree, open a text editor, commit etc.

It's true that developers are able to edit and probably would feel
more confortable editing sexprs, but unfortunately (as far as I know),
svnwiki doesn't understand sexprs as input language.

A simple solution for those who want to edit sexprs locally would be
implementing a simple sexpr->wiki translator and use it to generate
input files for svnwiki.  It would be a nice egg, BTW (maybe an output
format eggdoc could generate).

Best wishes,
Mario




reply via email to

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