> This is not so easy to achieve, mostly because of the static nature of > Haskell. > Basically we'd have to annotate all the functions with a runtime > docstring, which is a pain.
I'm sorry, I didn't really make it clear what I meant, I was in quite a hurry. Here's the actual idea: Vim (and Emacs, I think) come with a special editor mode for documentation. That means, there are some plain text files, which follow a certain markup standard, and are indexed by the editor's online help system. When you search for something, the editor opens up the relevant file in a new buffer, at the relevant line, and maybe highlights what you've been looking for. In Vim at least, (I wouldn't know about Emacs) it already works this way for things like `gq` or `G`. This decoupling of functionality/documentation certainly has its drawbacks, but I think it's overall a good idea. First of all, keeping the user (!) docs in the code is foolish. That would require people to learn Haskell (at least the comment system/haddock guidelines) to edit spelling errors in the documentation. I think people should be able to work on the docs without even looking at the code. Of course this method will place us in danger of the typical docs/code race, but that's always the case when you add documentation: keeping the docs up-to-date becomes a major issue. This is quite a big undertaking (we'd have to add the indexing functionality, and in a better way than Vim does it currently, too) and maybe not very realistic for 0.7, but maybe we could start working on it and target a usable system for 0.8. Having online docs is a major feature of every modern editor, and as yi begins to mature and bring in its own functionality, this will become more and more important, as one can't simply look up the relevant command in Vim's or Emacs' docs anymore. Plus, some commands already work differently from their originals. Some ideas for a realization: - use markdown for the documentation (Using the pandoc package, we could even display html pages in the browser.) since it's widely known and rather easy to parse (we'd have to use a subset of md, since a terminal can't show all the possible markups. I'm mainly thinking about code samples and links.) - create a syntax mode for those help files, that allows the user to jump on links (similar to Vim's help system or info pages.) - create an indexing system (is there some haskell package that already does that?) and make it searchable via some function. But that's just an idea, and I know it's not easy to realize. I'm open to any kind of suggestions, and/or better ideas. I'd say, though, that we *do* need a user documentation system. > More realistically, I'd like to have the Haddock documentation > generated on Hackage. Haddock docs would be *great*. Aleks --~--~---------~--~----~------------~-------~--~----~ Yi development mailing list yi-devel@googlegroups.com http://groups.google.com/group/yi-devel -~----------~----~----~----~------~----~------~--~---
