I agree with the points being made, and I struggled with many of the same
problems before. I pushed through mostly by reading the code in Yi, and
using a ghci a lot to look up functions.
Here are some specific documentation and organisational problems which have
caused me grief, even now that I am familiar with (parts of) the yi
codebase. In most cases, a solution is pretty clear, but involves breaking
changes and a considerable investment of time - things I intend to do later,
but not right now. Here's a few points:
- a number of things are in surprising places. This happens both on the
level of individual functions and types, as well as modules. Some examples:
- the module Yi.Keymap has all kinds of important things not related
to keymaps -- such as the YiM monad, and the YiAction class.
- similarly, Yi.Buffer.Misc defines the BufferM monad (this should be
in Yi.Buffer, at least) and the Mode type (this should be in
something like
Yi.Mode). In general, I find that there are too many modules in
Yi.Buffer,
and I never know where to look for buffer operations.
- some modules are at the base of the Yi hierarchy (which suggests
they are important or fundamental to yi) but are actually modes or other
extensions. For example: Yi.IReader, Yi.Dired, Yi.Tag, Yi.Hoogle,
Yi.History.
- I would like to see the yi modules broken up into the following
categories: internal yi core, public yi core, yi plugins. The last category
contains all modules which could be implemented as plugins (i.e. in the
user's config file), including: all modes, parsers, and utilities like
Yi.History. This category appears to include around 60% of the yi modules.
The remaining modules are "core" yi modules, and I would like to see more of
these be classified as internal modules, such as Yi.Process, Yi.Main and
parts of Yi.Core, Yi.Editor.
- a few modules appear to have become "sin bins" for all kinds of useful
functions. At the least, it would be useful to break these (typically rather
large) modules up into usefully-named sections, to make it faster to find
things when looking through Haddocks. Examples: Yi.Editor, Yi.Buffer.Misc,
Yi.Keymap, Yi.Syntax, Yi.Prelude. Beyond adding sections, it would also be
very useful to fatten the documentation for these key modules - a task which
could take a considerable time.
As I said, I intend to make changes along these lines, and some (vague)
point in the future.
Cheers,
Reiner
On 1 September 2011 09:06, Malte Harder <malte.har...@googlemail.com> wrote:
> I recently looked at yi again after having some trouble installing it
> a year ago. I think that the lack of documentation is a real problem,
> there is a lot of functionality already available somewhere deep down
> in the modules, but it took me quite a few hours to get the haddock
> documentation for the latest version, which then explained why my
> configuration wasn't working in the latest version, because the API
> was changed a bit from the last online available haddock.
>
> I think that it already makes a very good Haskell editor and probably
> also a good general purpose text editor. But configuring or writing
> small extensions to it still needs more time than it should,
> especially if caveats for installation/documentation generation are
> not written down in the Wiki and/or are outdated, if sample
> configuration files are kept to a bare minimum and are hidden in the
> repository.
>
> I liked the tutorials I found on
> http://www.nobugs.org/developer/yi/example-helloworld.html
> but they are also for an older version. If you want to join the
> development team a report of the architecture might be a good first
> read. If you want start hack your new editor, you might be more
> interested in some nice tutorials and a lot of examples, and some
> documentation what to expect to be broken with the next update.
>
> That said, I'm not even intending any critique on anybody actually
> dedicating time to develop yi, it's a great effort you're doing. It's
> more explaining what in my experience stopped me actually using it,
> and thus also stopped me from contributing. I think that it has the
> potential to get a much broader user basis and therefore automatically
> a lot more contributers. If I get some progress with my configuration
> I might write some tutorials for the latest version and post them
> somewhere.
>
> Best,
> Malte
>
> On Aug 28, 12:13 pm, Jean-Philippe Bernardy <berna...@chalmers.se>
> wrote:
> > On Sun, Aug 28, 2011 at 12:15 PM, Erik de Castro Lopo
> >
> > <mle...@mega-nerd.com> wrote:
> > > Hi all,
> >
> > > I am having a look a Yi and was wondering if there was any
> documentation.
> >
> > > Specifically, Yi depends on a relatively large number of somewhat
> > > obscure Haskell libraries (eg fingertree, pointedlist, rosezipper
> > > etc). What are these libraries used for?
> >
> > * fingertree: the buffer is stored in a fingertree of bytestrings
> (utf8-encoded)
> > * pointedlist: can't remember (but a pointed list is a simple
> > structure; it's not a "big" dependency)
> > * rosezipper: as far as I remember this is used for the "ide" part of
> > Yi, which I am afraid has become
> > dead wood.
> >
> > > Yi is also supposed to be configurable. Is there any documentation
> > > on that?
> > > Finally is there any design documentation that explains how this
> > > thing is put together?
> >
> > The basics are outlined in my old report:
> http://publications.lib.chalmers.se/cpl/record/index.xsql?pubid=72549
> >
> > Details have changed, but the overall picture remains.
> >
> > Cheers,
> > JP.
>
> --
> Yi development mailing list
> yi-devel@googlegroups.com
> http://groups.google.com/group/yi-devel
>
--
Yi development mailing list
yi-devel@googlegroups.com
http://groups.google.com/group/yi-devel
