[Orgmode] Request for opinions: [ANN] List improvement v.2o

[Carsten Dominik]

On Jul 22, 2010, at 11:08 PM, Nicolas Goaziou wrote:

Hello,

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

improvement in Org Mode.

Table of Contents

=================

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

===========================

 `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

================

 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

====================

 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 *

                  as a bullet when cycling a list at column 0 or Org

                  would have taken them for headings.

                  I extended the idea. Now, * bullet will be changed

                  to - if you outdent it to column 0. This and the

                  fact that LaTeX exporter now recognizes such lists

                  as valid make *-lists very usable.

                  In the same register, cycling items of a

                  description list will not offer 1. or 1), as

                  ordered and description lists are incompatible.

 Checkbox rule: It replaces `org-provide-checkbox-statistics'

                    which has become obsolete.

 Indent rule: This set prevents user from breaking his list by

                  inadvertence, when indenting or outdenting items

                  and sub-trees. Only moves that keep list integrity

                  are allowed.

                  The main advantage of it is when you insert a new

                  item and immediately press one or more TAB,

                  positions offered will all be meaningful. Quick

                  and efficient.

                  As a special case, moving the top item of the list

                  will move the whole list with it.

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

                  items cannot be inserted inside a special block in

                  the middle of a list. With this rule activated,

                  item will be insert right before that special

                  block. If not, Org will only throw an error.

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

                    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'

========================

 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)))

                  ;; Take care of any sublist first

                  (count (if (not (org-item-has-children-p))

                             count

                           (goto-char body-end)

                           (org-apply-on-list search-and-check count))))

             ;; Tests and checking if the formers are successful

             (if (and (save-excursion (re-search-forward regexp body-end t))

                      (org-at-item-checkbox-p)

                      (equal (match-string 1) "[ ]"))

                 (progn (org-toggle-checkbox) (1+ count))

               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:

address@hidden: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.

address@hidden

http://lists.gnu.org/mailman/listinfo/emacs-orgmode

- Carsten