From mboxrd@z Thu Jan 1 00:00:00 1970 From: Carsten Dominik Subject: Request for opinions: [ANN] List improvement v.2o Date: Tue, 17 Aug 2010 19:24:43 +0200 Message-ID: References: <87ocdzw7gq.wl%n.goaziou@gmail.com> Mime-Version: 1.0 (Apple Message framework v936) Content-Type: multipart/mixed; boundary="===============1113686222==" Return-path: Received: from [140.186.70.92] (port=36383 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OlPuU-000443-9C for emacs-orgmode@gnu.org; Tue, 17 Aug 2010 13:25:15 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OlPuS-0003hl-OL for emacs-orgmode@gnu.org; Tue, 17 Aug 2010 13:25:14 -0400 Received: from mail-ey0-f169.google.com ([209.85.215.169]:53303) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OlPuS-0003hZ-Ci for emacs-orgmode@gnu.org; Tue, 17 Aug 2010 13:25:12 -0400 Received: by eyg7 with SMTP id 7so2417470eyg.0 for ; Tue, 17 Aug 2010 10:25:11 -0700 (PDT) In-Reply-To: <87ocdzw7gq.wl%n.goaziou@gmail.com> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Nicolas Goaziou Cc: Org Mode List --===============1113686222== Content-Type: text/html; charset=US-ASCII Content-Transfer-Encoding: quoted-printable Hello,

Here is a new, = and probably final feature-wise, suggestion of = list

improvement in Org = Mode.

Table of = Contents

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
1 What is it about again = ?
2 Is that all = ?
  2.1 Preserving = blank lines
  2.2 = Timer lists
  2.3 = Automatic rules
=   2.4 `org-apply-on-list'
3 Where can it be tried ?

Hi = everyone,

I would like to have a discussion about the list = improvements proposed by
Nicolas. I have tested his code now = for a few days (on and off). I like
many things. About = some issues I am not as happy, but maybe we should
accept these in = exchange for the improvements we can get.

With Nicolas' code, we = loose

1. The ability to have several sublists separated by text, = for example

  - item1
=       - subitem A1
=       - subitem A2

=       some text in between the lists, = identified as such by indentation

=       - subitem B1
=       - subitem B2

Such a construct = is no longer possible. The LaTeX exporter already
was not able = to deal with this situation, but the HTML and DocBook
exporters did = handle this correcty (and still do, actually, contrary to
what = Nicolas wrote in one of his messages). In the past
we have had = several requests to upgrade the LaTeX exporter in
this respect, but = that has not happened - it is not easy to do.

2. Some existing = documents will break because we now need an end-of-list
=   that is clearly defined, and not by indentation. = Nicolas proposes a
  double empty line or some = special string to be defined. Breaking existing
=   documents is always bad, of cause. I still hope we can = do something
  about this if we think really hard, like = making text that is less
  indented than the list *also* = terminate a list.

These are, as far as I can see, the most = important disadvantages.

On the other had, using Nicolas' code, = we gain

1. More consistent behavior of line indentation with TAB = in lists.
  Basically, TAB will no longer break list = structure. This was
  something that has bothered me = quite a bit in the past.

2. With org-cycle-include-plaint-lists = set, cycling of list items
  works consistently as far as = I can see, and no longer hides
  text after the end of the = list.

3. Consistent behavior in the different exporters (see the = point
  I made earlier about text between sublists). = More work is needed,
  but basically this is what it = comes down to.

4. A significant list of additional consistency = improvements, as
  detailed by Nicolas in his mail (see = below).

I would like to invite comments, and maybe = clever
proposals on how to maybe get a bit of extra = backward
compatibility. Also, if would be great if more people = could
get his code and test it - lists are complex, and it = is
quite possible that there are hidden problems that show only
up = with wider variety of examples.

1 What is it = about again ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~

I redefined = lists in Org Mode. Lists start, as before, at a = bullet
(whose true regexp is = at `org-item-beginning-re'), and end at = either
`org-list-end-regexp', = a new headline, or, obviously, end of = buffer.

= `org-list-end-regexp' is customizable and defaults to 2 blank = lines,
but = `org-empty-line-terminates-plain-lists' has precedence over = it.
Moreover, any = `org-list-end-regexp' found in special blocks does = not
end list. Here are two = examples of valid lists:

Case 1: = `org-list-end-regexp' is at default value

- First = item

  - = Sub item

=     #+BEGIN_EXAMPLE
    Two blank lines = below

=     Two blank lines = above
=     #+END_SRC

  - = Last sub item

List has ended = at the beginning of this line.

Case 2: = `org-list-end-regexp' is "^[ \t]*___[ = \t]*\n"

- item = 1
- item = 2
  - = sub-item
  - = sub-item 2
- item = 3
= __
List has ended at the = beginning of this line.

Now, Org Mode = knows when a list has ended and how to indent = line
accordingly. In other = words, you can `org-return-indent' three = times
to exit a list and be = at the right column to go on with the text.

This new = definition is also understood by exporters (LaTeX, = DocBook,
HTML or ASCII) and = `org-list-end-regexp' will appear in source as = a
blank line, whatever its = value is (as long as it starts with a caret
and ends with a newline character, as specified in = doc-string).

Another = advantage is that you can have two lists of different = types
in a row like in the = example below:

- = item
- = item

1. = item
2. = item

In this = example, you can move (or cycle, or indent) items in = the
second list without = worrying about changing the first one.

2 Is that all = ?
~~~~~~~~~~~~~~~~

Yes and no. I = tried as much as possible to keep compatibility = with
previous implementation. = But, as I was at it, I made a number of
minor improvements I am now going to = describe.

2.1 Preserving = blank lines
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D

= `org-move-item-up' and `org-move-item-down' will not eat = blank
lines anymore. = You can move an item up and down and stay = assured
list will keep = its integrity.

The same = is true for `org-sort-list' that would previously = collapse
the list being = sorted. Sorting is now safe.

= `org-insert-item', when 'plain-list-item is set to 'auto = in
= `org-blank-before-new-entry' (the default, I think), will work = hard
to guess the = appropriate number of blank lines to insert before = the
item to come. The = function is also much more predictable (in
previous version, trying to insert an item with = point on a blank
line = between 2 items would create a new = headline).

2.2 Timer = lists
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

= There are three improvements in timer lists (C-c C-x = -).

1. When a new item is created, it should be = properly indented and
=     not sticked to column 0 = anymore,

2. When = an item is inserted in a pre-existing timer list, it = will
=     take profit of what has been done to = `org-insert-item',

3. = `org-sort-list' can now sort timer lists with the t and = T
=     commands.

/Note/: = in order to preserve lists integrity, Org Mode will send = an
error if you try to = insert a timer list inside a list of another
type.

2.3 Automatic = rules
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=

I've added sets of rules (applied by default) that = can improve
lists = experience. You can deactivate them individually = by
customizing = `org-list-automatic-rules'.

Bullet = rule: Some may have noticed that you couldn't obtain = *
=             &n= bsp;     as a bullet when cycling a list at = column 0 or Org
=             &n= bsp;     would have taken them for = headings.

=             &n= bsp;     I extended the idea. Now, * bullet = will be changed
=             &n= bsp;     to - if you outdent it to column 0. = This and the
=             &n= bsp;     fact that LaTeX exporter now = recognizes such lists
=             &n= bsp;     as valid make *-lists very = usable.

=             &n= bsp;     In the same register, cycling items of = a
=             &n= bsp;     description list will not offer 1. or = 1), as
=             &n= bsp;     ordered and description lists are = incompatible.

Checkbox = rule: It replaces = `org-provide-checkbox-statistics'
=             &n= bsp;       which has become = obsolete.

Indent = rule: This set prevents user from breaking his list = by
=             &n= bsp;     inadvertence, when indenting or = outdenting items
=             &n= bsp;     and sub-trees. Only moves that keep = list integrity
=             &n= bsp;     are = allowed.

=             &n= bsp;     The main advantage of it is when you = insert a new
=             &n= bsp;     item and immediately press one or more = TAB,
=             &n= bsp;     positions offered will all be = meaningful. Quick
=             &n= bsp;     and = efficient.

=             &n= bsp;     As a special case, moving the top item = of the list
=             &n= bsp;     will move the whole list with = it.

Insert rule: As a consequence of the new = definition of lists,

= &n= bsp; items cannot be inserted inside a = special block in

= &n= bsp; the middle of a list. With this rule = activated,

= &n= bsp; item will be insert right before that = special

= &n= bsp; block. If not, Org will only throw an = error.

Renumber = rule: It replaces = `org-auto-renumber-ordered-lists'

= &n= bsp; which has become = obsolete.

I think = those rules make a sane default behavior (except for = the

indent rule, = perhaps). And they are easy to disable if one = think

they get too much = in the way.

2.4 = `org-apply-on-list'

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D

It's not = much, but I added that small function, inspired = from

= `apply-of-rectangle', that might be of some use. It = basically

applies a = function passed as argument to each item of the = list

(with a possible = return value for functional usage).

As an = illustration, here is a small function that walks through = a

list (and its = sublists, if any), checking every item with a = blank

checkbox whose = body is matched by REGEXP. It returns the number = of

items = checked.

(defun = my-check-o-matic (regexp)

= ;; Function we are going to = apply.

(let = ((search-and-check

= (lambda = (count)

= (let* = ((body-end (save-excursion = (org-end-of-item-text-before-children)))

= &n= bsp; ;; Take care of any sublist = first

= &n= bsp; (count (if (not = (org-item-has-children-p))

= &n= bsp; &nbs= p; count

= = &n= bsp; &nbs= p; (goto-char body-end)

= &n= bsp; &nbs= p; (org-apply-on-list search-and-check = count))))

= &n= bsp;;; Tests and checking if the formers are = successful

= &n= bsp;(if (and (save-excursion (re-search-forward regexp body-end = t))

= &n= bsp; (org-at-item-che= ckbox-p)

= &n= bsp; (equal = (match-string 1) "[ ]"))

= &n= bsp; (progn (org-toggle-checkbox) (1+ = count))

= &n= bsp; count)))))

= ;; Call of `org-apply-on-list': notice initial = value of counter

= (format "%d items checked"(org-apply-on-list = search-and-check 0))))

3 Where can it = be tried ?

~~~~~~~~~~~~~~~~~~~~~~~~~~

The source is = at:

git@github.com:ngz/org-mode-lists.git = branch: end-lists

It is merged = very frequently with git head, and I keep a clone = of

Org Mode master branch at = the same place. So, you can switch from

end-lists to master without too much hassle. It is very = stable

anyway, so you do not = need to be an adventurous type.

Feedback, = suggestions and comments are welcome.

= Regards,

-- = Nicolas

_______________________________________________
Emacs-orgmode mailing = list
Please use `Reply All' to = send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

- Carsten

= --===============1113686222== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Emacs-orgmode mailing list Please use `Reply All' to send replies to the list. Emacs-orgmode@gnu.org http://lists.gnu.org/mailman/listinfo/emacs-orgmode --===============1113686222==--