Design documentation is absent

Bug #580058 reported by Dino Chiesa on 2010-05-13
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
nXhtml
Wishlist
Unassigned

Bug Description

I like the idea of mumamo, but the design documentation is completely absent.

how does it work?
how does it determine where a chunk starts and where it ends?
WHEN does it do those checks? with every change? every cursor movement? once?

How is it possible to add a new mode? (for jsp, or ruby, or whatever). Why and When should that be done?
Which are available now?

and so on.

Open source is great idea, but to make it real, the stuff has to be usable.
"Figure it out, read the source code" is a really poor answer.

Dino Chiesa (dpchiesa) wrote :

Also, the comments in mumamo.el say,

;; The dividing into chunk is not that simple as I first thought. I
;; have not gone through the logic of this very carefully. Perhaps
;; that is needed. The current logic is mainly in
;; `mumamo-get-chunk-at' and `mumamo-find-possible-chunk'. (Some
;; other routines tries to behave like `mumamo-find-possible-chunk'
;; too: `mumamo-chunk-attr=' and `mumamo-quick-static-chunk'.)
;;

Why? Why was there a need to have these four separate defuns?
Why do the defuns "try to behave like" mumamo-find-possible-chunk, and
exactly what does that mean, anyway?

Also, why is mumamo part of nxhtml? Should it be?

Design docs would describe that depencency, as well.

lborgman (lennart-borgman) wrote :

Hi Dino,

I am glad for your thoughts. You are right the docs could be better. I just tried to enhance them - just a little bit. Maybe you want to have a look at mumamo.el again and see if the answers to your questions are more easy to find now?

Note that a big problem with mumamo.el is that I have not had time to clean up everything that is not used any more. The chunk dividing routines where very complex from the beginning (and that did not pay back .. ;-). And the way I did it was a mistake. So looking at mumamo might be confusing. Also there is a lot of details that it tries to take care of that you do not have to know about just to write chunk dividing routines now. In fact I guess for most cases just using `mumamo-quick-chunk-forward' is enough.

If you install the latest beta 2.09 from the repositories there are some convenient ways to find out which multi major modes that are defined in your Emacs. In the menus open the submenu

   nXhtml / Multi Major Modes

At the bottom there are two alternatives

  List Defined Multi Major Modes
  Find a Multi Major Mode

The first just shows a list (which you can narrow with a regexp against the name).

The second tries to be a little bit more fun and guess from what you have in the buffer. (It only looks at the chunks.)

The words "try to behave like" refers to my inability to code them right. I am really not a coder.

The design is quite a bit ad hoc since the problem was really too complex for me. I did not realize from the beginning what was needed and how to cooperate with other parts of Emacs. I still don't do, but it seems to work. Part of the work has been and is how to find a good working design. (Cleaning up is not on my favorite list.)

The design of the chunk dividing routines are driven mostly be the need to save as much work as possible when changing the buffer. Therefore the routines to search for chunks and creating them are separate. Reuse chunks if possible. (Actually those routines are much simpler now that they create chunks from the top to the bottom all the time.)

Mumamo is part of nXhtml today since that is the easiest way to manage and distribute it. Since so many things could go wrong from the beginning this was easiest. The goal is just to include it in Emacs.

I see no reason and possibility to split it out from nXhtml now. There is no good enough system for distribution yet. (I tried to include one in nXhtml but it was by some believed to be dangerous, unfortunately.) At the moment I think most users benefits from having it all in one bundle, but I know some heavy users disagree.

I myself thinks that coordination is the most difficult part for free software.

Now I am a bit curious. Most users just try out the software. It looks to me like you tried to read it instead. Have you tried to use nXhtml?

Changed in nxhtml:
importance: Undecided → Medium
status: New → In Progress
Changed in nxhtml:
importance: Medium → Wishlist
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers