problem with emacs wiki (was: What alternatives are there to learn Emacs?...)

[Xah]

Some personal experineces on emacs tutorial...

i started to use emacs in 1998. Was a full time user and beta tester
for BBEdit for several years before that.

The first tutorial i read is the bundled tutorial (C-h t, M-x help-
with-tutorial).

This tutorial is the way to get you started with emacs from the ground
up. It in written in 1980's mindset, gets you started to learn all the
emacs ways and terminologies. It is not a practicality oriented one
though.

Once you've read the bundled tutorial, you'll know about info (C-h i)
and how to use its navigation shorcuts, which you can read the whole
one-thousand pages of emacs manual. The emacs manual is a bit quaint
in today, but it is very well written and complete. It is systematic,
topics well organized, jargons are well defined and has several
comprehensive index, the writing is clear, is well cross-linked. The
technology used for the manual, the texinfo, is a excellent technology
at the time. It has hyperlinks preceding its popularity in html by
maybe 10 years. (one can think of it as plain-text system with
hyperlinks and document hierachy/paging and navigation shortcuts) The
writing quality and content of emacs manual, is far better than most
OpenSource docs such as perl, python, apache, unix man.

This only drawback today, in my opinion, is that its largely written
in the 1980s, using terms and jargons that today are not used
elsewhere, verbose, and often has sections that discuss systems that
are obsolete for 20 years.

Sometimes in 1999 i also read “Learning GNU Emacs” (O'Reilly) by Debra
Cameron et al.  This book is more practicality oriented (as with most
commercial tutorials), and it did gave me a good intro.

The book now is out dated though. Last edition, the 2nd ed, published
in 1996. Since then, emacs has gone to version 20, 21, and 22. Lots of
features are added, and lots of new computing technologies have become
important that didn't exist in mid 1990s.

The emacs wiki (http://www.emacswiki.org/), started by Alex Schroeder
sometimes in 2005 or before, is great. However, i think it could've
been better.

(1) The wiki software used is Oddmuse, which is a perl script of 4k
lines, using flat files as database. As such, it is not comprehensive
or powerful.

(2) The content, is kinda haphazard. It is somewhat in-between of a
encyclopedia-style treatment like Wikipedia and a chaotic online
forum. Specifically, when you visit a article, half of article will be
dialogues between different users on tips or issues or preferences.

I commented to Alex about these problems. I suggest that it should use
the same software Wikipedia uses, the MediaWiki. So that, it is far
more powerful, with large scale programer support, and the user
interface for the wiki will be one that's widely known to millions of
users world-wide. (note: Oddmuse is something written by Alex himself,
a petlove of sorts)

I also suggested that the writing guidlines should follow Wikipedia's
style. Specifically, the content editing should be one with the goal
of creating a comprehensive, coherent, article that gives readers info
or tutorial about the subject. (as opposed to, maintaining the
coherence of a dialogue and comments between wiki users)

I think there's a lot potential to emacs wiki. It could, for example,
develope into a comprehensive elisp library archive (e.g. CPAN).
Listing packages by category, wich each package come with a article
that discuss its author, purpose, status, caveats, tutorial, similar
packages ...etc. And the packages needs not just be modes... but
libraries as in most languages. (for example, js2 and nxml modes are
both complete parsers for javascript and xml, each of thousands lines
of elisp code. They should actually be several libraries, so that
these parsers can be widely deployed as language modules for many
purposes. Such is largely not done in emacs/elisp community due to
emacs being primarily a text-editor with relatively few elisp
programers... but is slowing happening anyway (it is something that
eventually must happen). A good wiki can be great help in ushering
necessary improvements)

For the above to take shape, the wiki must adopt a style so that
articles aim to be a coherent treatment of the subject (as opposed to
dialogue and random tips). (and this is done by crafting the
contribution guidelines or rules; examplarily done by Wikipedia) Also,
i'd think the wiki's software should adopt MediaWiki, as opposed to
one-man's petlove.

  Xah
∑ http://xahlee.org/

☄



On Jun 10, 2:43 pm, Xah <xah...@gmail.com> wrote:
> On May 11, 5:47 pm, Don Saklad <dsak...@gnu.org> wrote:
>
> > What alternatives to the usual manuals are there to learn Emacs?...
> > especially for new learners who have difficulties with the
> > deficiencies in the usual manual texts and jargon.
>
> > Not all potential new users see themselves as a part of our community!
>
> you might try my tutorial.http://xahlee.org/emacs/emacs.html
>
>   Xah
> ∑http://xahlee.org/
>
> ☄