Re: [ANN] List improvement v.2

From: Carsten Dominik <carsten.dominik@gmail.com>
To: Nicolas Goaziou <n.goaziou@gmail.com>
Cc: Org Mode List <emacs-orgmode@gnu.org>
Subject: Re: [ANN] List improvement v.2
Date: Fri, 27 Aug 2010 10:24:10 +0200	[thread overview]
Message-ID: <BB52D1CA-C17D-4C77-A87D-DF2252331E46@gmail.com> (raw)
In-Reply-To: <87ocdzw7gq.wl%n.goaziou@gmail.com>

Hi,

I am close to merging these changes into the master branch.

Any objections?

- Carsten

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 ?
>
>
> 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:
>
>  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