org.texi: Remove reference to deleted command
[org-mode.git] / lisp / org-inlinetask.el
1 ;;; org-inlinetask.el --- Tasks independent of outline hierarchy
2
3 ;; Copyright (C) 2009-2012 Free Software Foundation, Inc.
4 ;;
5 ;; Author: Carsten Dominik <carsten at orgmode dot org>
6 ;; Keywords: outlines, hypermedia, calendar, wp
7 ;; Homepage: http://orgmode.org
8
9 ;; This file is part of GNU Emacs.
10
11 ;; GNU Emacs is free software: you can redistribute it and/or modify
12
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation, either version 3 of the License, or
15 ;; (at your option) any later version.
16
17 ;; GNU Emacs is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20 ;; GNU General Public License for more details.
21
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
24
25 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
26 ;;
27 ;;; Commentary:
28 ;;
29 ;; This module implements inline tasks in Org-mode.  Inline tasks are
30 ;; tasks that have all the properties of normal outline nodes, including
31 ;; the ability to store meta data like scheduling dates, TODO state, tags
32 ;; and properties.  However, these nodes are treated specially by the
33 ;; visibility cycling and export commands.
34 ;;
35 ;; Visibility cycling exempts these nodes from cycling.  So whenever their
36 ;; parent is opened, so are these tasks.  This will only work with
37 ;; `org-cycle', so if you are also using other commands to show/hide
38 ;; entries, you will occasionally find these tasks to behave like
39 ;; all other outline nodes, seemingly splitting the text of the parent
40 ;; into children.
41 ;;
42 ;; Export commands do not treat these nodes as part of the sectioning
43 ;; structure, but as a special inline text that is either removed, or
44 ;; formatted in some special way.  This in handled by
45 ;; `org-inlinetask-export' and `org-inlinetask-export-templates'
46 ;; variables.
47 ;;
48 ;; Special fontification of inline tasks, so that they can be immediately
49 ;; recognized.  From the stars of the headline, only the first and the
50 ;; last two will be visible, the others will be hidden using the
51 ;; `org-hide' face.
52 ;;
53 ;; An inline task is identified solely by a minimum outline level, given
54 ;; by the variable `org-inlinetask-min-level', default 15.
55 ;;
56 ;; If you need to have a time planning line (DEADLINE etc), drawers,
57 ;; for example LOGBOOK of PROPERTIES, or even normal text as part of
58 ;; the inline task, you must add an "END" headline with the same
59 ;; number of stars.
60 ;;
61 ;; As an example, here are two valid inline tasks:
62 ;;
63 ;;    **************** TODO a small task
64 ;;
65 ;; and
66 ;;
67 ;;    **************** TODO another small task
68 ;;                     DEADLINE: <2009-03-30 Mon>
69 ;;                     :PROPERTIES:
70 ;;                       :SOMETHING: or other
71 ;;                     :END:
72 ;;                     And here is some extra text
73 ;;    **************** END
74 ;;
75 ;; Also, if you want to use refiling and archiving for inline tasks,
76 ;; The END line must be present to make things work properly.
77 ;;
78 ;; This package installs one new command:
79 ;;
80 ;; C-c C-x t      Insert a new inline task with END line
81
82 ;;; Code:
83
84 (require 'org)
85
86 (defgroup org-inlinetask nil
87   "Options concerning inline tasks in Org mode."
88   :tag "Org Inline Tasks"
89   :group 'org-structure)
90
91 (defcustom org-inlinetask-min-level 15
92   "Minimum level a headline must have before it is treated as an inline task.
93 Don't set it to something higher than `29' or clocking will break since this
94 is the hardcoded maximum number of stars `org-clock-sum' will work with.
95
96 It is strongly recommended that you set `org-cycle-max-level' not at all,
97 or to a number smaller than this one.  In fact, when `org-cycle-max-level' is
98 not set, it will be assumed to be one less than the value of smaller than
99 the value of this variable."
100   :group 'org-inlinetask
101   :type '(choice
102           (const :tag "Off" nil)
103           (integer)))
104
105 (defcustom org-inlinetask-show-first-star nil
106   "Non-nil means display the first star of an inline task as additional marker.
107 When nil, the first star is not shown."
108   :tag "Org Inline Tasks"
109   :group 'org-structure)
110
111 (defcustom org-inlinetask-export t
112   "Non-nil means export inline tasks.
113 When nil, they will not be exported."
114   :group 'org-inlinetask
115   :type 'boolean)
116
117 (defvar org-inlinetask-export-templates
118   '((html "<div class=\"inlinetask\"><b>%s%s</b><br />%s</div>"
119           '((unless (eq todo "")
120               (format "<span class=\"%s %s\">%s%s</span> "
121                       class todo todo priority))
122             heading content))
123     (odt "%s" '((org-odt-format-inlinetask heading content
124                                            todo priority tags)))
125
126     (latex "\\begin\{description\}\n\\item[%s%s]~%s\\end\{description\}"
127            '((unless (eq todo "") (format "\\textsc\{%s%s\} " todo priority))
128              heading content))
129     (ascii "     -- %s%s%s"
130            '((unless (eq todo "") (format "%s%s " todo priority))
131              heading
132              (unless (eq content "")
133                (format "\n         ¦ %s"
134                        (mapconcat 'identity (org-split-string content "\n")
135                                   "\n         ¦ ")))))
136     (docbook "<variablelist>
137 <varlistentry>
138 <term>%s%s</term>
139 <listitem><para>%s</para></listitem>
140 </varlistentry>
141 </variablelist>"
142              '((unless (eq todo "") (format "%s%s " todo priority))
143                heading content)))
144   "Templates for inline tasks in various exporters.
145
146 This variable is an alist in the shape of \(BACKEND STRING OBJECTS\).
147
148 BACKEND is the name of the backend for the template \(ascii, html...\).
149
150 STRING is a format control string.
151
152 OBJECTS is a list of elements to be substituted into the format
153 string.  They can be of any type, from a string to a form
154 returning a value (thus allowing conditional insertion).  A nil
155 object will be substituted as the empty string.  Obviously, there
156 must be at least as many objects as %-sequences in the format
157 string.
158
159 Moreover, the following special keywords are provided: `todo',
160 `priority', `heading', `content', `tags'.  If some of them are not
161 defined in an inline task, their value is the empty string.
162
163 As an example, valid associations are:
164
165 \(html \"<ul><li>%s <p>%s</p></li></ul>\" \(heading content\)\)
166
167 or, with the additional package \"todonotes\" for LaTeX,
168
169 \(latex \"\\todo[inline]{\\textbf{\\textsf{%s %s}}\\linebreak{} %s}\"
170        '\(\(unless \(eq todo \"\"\)
171            \(format \"\\textsc{%s%s}\" todo priority\)\)
172          heading content\)\)\)")
173
174 (defvar org-odd-levels-only)
175 (defvar org-keyword-time-regexp)
176 (defvar org-drawer-regexp)
177 (defvar org-complex-heading-regexp)
178 (defvar org-property-end-re)
179
180 (defcustom org-inlinetask-default-state nil
181   "Non-nil means make inline tasks have a TODO keyword initially.
182 This should be the state `org-inlinetask-insert-task' should use by
183 default, or nil of no state should be assigned."
184   :group 'org-inlinetask
185   :version "24.1"
186   :type '(choice
187           (const :tag "No state" nil)
188           (string :tag "Specific state")))
189
190 (defun org-inlinetask-insert-task (&optional no-state)
191   "Insert an inline task.
192 If prefix arg NO-STATE is set, ignore `org-inlinetask-default-state'."
193   (interactive "P")
194   ;; Error when inside an inline task, except if point was at its very
195   ;; beginning, in which case the new inline task will be inserted
196   ;; before this one.
197   (when (and (org-inlinetask-in-task-p)
198              (not (and (org-inlinetask-at-task-p) (bolp))))
199     (error "Cannot nest inline tasks"))
200   (or (bolp) (newline))
201   (let* ((indent (if org-odd-levels-only
202                      (1- (* 2 org-inlinetask-min-level))
203                    org-inlinetask-min-level))
204          (indent-string (concat (make-string indent ?*) " ")))
205     (insert indent-string
206             (if (or no-state (not org-inlinetask-default-state))
207                 "\n"
208               (concat org-inlinetask-default-state " \n"))
209             indent-string "END\n"))
210   (end-of-line -1))
211 (define-key org-mode-map "\C-c\C-xt" 'org-inlinetask-insert-task)
212
213 (defun org-inlinetask-outline-regexp ()
214   "Return string matching an inline task heading.
215 The number of levels is controlled by `org-inlinetask-min-level'."
216   (let ((nstars (if org-odd-levels-only
217                     (1- (* org-inlinetask-min-level 2))
218                   org-inlinetask-min-level)))
219     (format "^\\(\\*\\{%d,\\}\\)[ \t]+" nstars)))
220
221 (defun org-inlinetask-at-task-p ()
222   "Return true if point is at beginning of an inline task."
223   (save-excursion
224     (beginning-of-line)
225     (and (looking-at (concat (org-inlinetask-outline-regexp)  "\\(.*\\)"))
226          (not (string-match "^end[ \t]*$" (downcase (match-string 2)))))))
227
228 (defun org-inlinetask-in-task-p ()
229   "Return true if point is inside an inline task."
230   (save-excursion
231     (beginning-of-line)
232     (let* ((case-fold-search t)
233            (stars-re (org-inlinetask-outline-regexp))
234            (task-beg-re (concat stars-re "\\(?:.*\\)"))
235            (task-end-re (concat stars-re "END[ \t]*$")))
236       (or (org-looking-at-p task-beg-re)
237           (and (re-search-forward "^\\*+[ \t]+" nil t)
238                (progn (beginning-of-line) (org-looking-at-p task-end-re)))))))
239
240 (defun org-inlinetask-goto-beginning ()
241   "Go to the beginning of the inline task at point."
242   (end-of-line)
243   (let ((case-fold-search t)
244         (inlinetask-re (org-inlinetask-outline-regexp)))
245     (re-search-backward inlinetask-re nil t)
246     (when (org-looking-at-p (concat inlinetask-re "END[ \t]*$"))
247       (re-search-backward inlinetask-re nil t))))
248
249 (defun org-inlinetask-goto-end ()
250   "Go to the end of the inline task at point.
251 Return point."
252   (save-match-data
253     (beginning-of-line)
254     (let* ((case-fold-search t)
255            (inlinetask-re (org-inlinetask-outline-regexp))
256            (task-end-re (concat inlinetask-re "END[ \t]*$")))
257       (cond
258        ((looking-at task-end-re) (forward-line))
259        ((looking-at inlinetask-re)
260         (forward-line)
261         (cond
262          ((looking-at task-end-re) (forward-line))
263          ((looking-at inlinetask-re))
264          ((org-inlinetask-in-task-p)
265           (re-search-forward inlinetask-re nil t)
266           (forward-line))))
267        (t (re-search-forward inlinetask-re nil t)
268           (forward-line)))
269       (point))))
270
271 (defun org-inlinetask-get-task-level ()
272   "Get the level of the inline task around.
273 This assumes the point is inside an inline task."
274   (save-excursion
275     (end-of-line)
276     (re-search-backward (org-inlinetask-outline-regexp) nil t)
277     (- (match-end 1) (match-beginning 1))))
278
279 (defun org-inlinetask-promote ()
280   "Promote the inline task at point.
281 If the task has an end part, promote it.  Also, prevents level from
282 going below `org-inlinetask-min-level'."
283   (interactive)
284   (if (not (org-inlinetask-in-task-p))
285       (error "Not in an inline task")
286     (save-excursion
287       (let* ((lvl (org-inlinetask-get-task-level))
288              (next-lvl (org-get-valid-level lvl -1))
289              (diff (- next-lvl lvl))
290              (down-task (concat (make-string next-lvl ?*)))
291              beg)
292         (if (< next-lvl org-inlinetask-min-level)
293             (error "Cannot promote an inline task at minimum level")
294           (org-inlinetask-goto-beginning)
295           (setq beg (point))
296           (replace-match down-task nil t nil 1)
297           (org-inlinetask-goto-end)
298           (if (eobp) (beginning-of-line) (forward-line -1))
299           (unless (= (point) beg)
300             (replace-match down-task nil t nil 1)
301             (when org-adapt-indentation
302               (goto-char beg)
303               (org-fixup-indentation diff))))))))
304
305 (defun org-inlinetask-demote ()
306   "Demote the inline task at point.
307 If the task has an end part, also demote it."
308   (interactive)
309   (if (not (org-inlinetask-in-task-p))
310       (error "Not in an inline task")
311     (save-excursion
312       (let* ((lvl (org-inlinetask-get-task-level))
313              (next-lvl (org-get-valid-level lvl 1))
314              (diff (- next-lvl lvl))
315              (down-task (concat (make-string next-lvl ?*)))
316              beg)
317         (org-inlinetask-goto-beginning)
318         (setq beg (point))
319         (replace-match down-task nil t nil 1)
320         (org-inlinetask-goto-end)
321         (if (eobp) (beginning-of-line) (forward-line -1))
322         (unless (= (point) beg)
323           (replace-match down-task nil t nil 1)
324           (when org-adapt-indentation
325             (goto-char beg)
326             (org-fixup-indentation diff)))))))
327
328 (defvar org-export-current-backend) ; dynamically bound in org-exp.el
329 (defun org-inlinetask-export-handler ()
330   "Handle headlines with level larger or equal to `org-inlinetask-min-level'.
331 Either remove headline and meta data, or do special formatting."
332   (goto-char (point-min))
333   (let* ((keywords-re (concat "^[ \t]*" org-keyword-time-regexp))
334          (inline-re (concat (org-inlinetask-outline-regexp) ".*")))
335     (while (re-search-forward inline-re nil t)
336       (let ((headline (match-string 0))
337             (beg (point-at-bol))
338             (end (copy-marker (save-excursion
339                                 (org-inlinetask-goto-end) (point))))
340             content)
341         ;; Delete SCHEDULED, DEADLINE...
342         (while (re-search-forward keywords-re end t)
343           (delete-region (point-at-bol) (1+ (point-at-eol))))
344         (goto-char beg)
345         ;; Delete drawers
346         (while (re-search-forward org-drawer-regexp end t)
347           (when (save-excursion (re-search-forward org-property-end-re nil t))
348             (delete-region beg (1+ (match-end 0)))))
349         ;; Get CONTENT, if any.
350         (goto-char beg)
351         (forward-line 1)
352         (unless (= (point) end)
353           (setq content (buffer-substring (point)
354                                           (save-excursion (goto-char end)
355                                                           (forward-line -1)
356                                                           (point)))))
357         ;; Remove the task.
358         (goto-char beg)
359         (delete-region beg end)
360         (when (and org-inlinetask-export
361                    (assq org-export-current-backend
362                          org-inlinetask-export-templates))
363           ;; Format CONTENT, if appropriate.
364           (setq content
365                 (if (not (and content (string-match "\\S-" content)))
366                     ""
367                   ;; Ensure CONTENT has minimal indentation, a single
368                   ;; newline character at its boundaries, and isn't
369                   ;; protected.
370                   (when (string-match "\\`\\([ \t]*\n\\)+" content)
371                     (setq content (substring content (match-end 0))))
372                   (when (string-match "[ \t\n]+\\'" content)
373                     (setq content (substring content 0 (match-beginning 0))))
374                   (org-add-props
375                       (concat "\n\n" (org-remove-indentation content) "\n\n")
376                       '(org-protected nil org-native-text nil))))
377
378           (when (string-match org-complex-heading-regexp headline)
379             (let* ((nil-to-str
380                     (function
381                      ;; Change nil arguments into empty strings.
382                      (lambda (el) (or (eval el) ""))))
383                    ;;  Set up keywords provided to templates.
384                    (todo (or (match-string 2 headline) ""))
385                    (class (or (and (eq "" todo) "")
386                               (if (member todo org-done-keywords) "done" "todo")))
387                    (priority (or (match-string 3 headline) ""))
388                    (heading (or (match-string 4 headline) ""))
389                    (tags (or (match-string 5 headline) ""))
390                    ;; Read `org-inlinetask-export-templates'.
391                    (backend-spec (assq org-export-current-backend
392                                        org-inlinetask-export-templates))
393                    (format-str (org-add-props (nth 1 backend-spec)
394                                    '(org-protected t org-native-text t)))
395                    (tokens (cadr (nth 2 backend-spec)))
396                    ;; Build export string.  Ensure it won't break
397                    ;; surrounding lists by giving it arbitrary high
398                    ;; indentation.
399                    (export-str (org-add-props
400                                    (eval (append '(format format-str)
401                                                  (mapcar nil-to-str tokens)))
402                                    '(original-indentation 1000))))
403               ;; Ensure task starts a new paragraph.
404               (unless (or (bobp)
405                           (save-excursion (forward-line -1)
406                                           (looking-at "[ \t]*$")))
407                 (insert "\n"))
408               (insert export-str)
409               (unless (bolp) (insert "\n")))))))))
410
411 (defun org-inlinetask-get-current-indentation ()
412   "Get the indentation of the last non-while line above this one."
413   (save-excursion
414     (beginning-of-line 1)
415     (skip-chars-backward " \t\n")
416     (beginning-of-line 1)
417     (or (org-at-item-p)
418         (looking-at "[ \t]*"))
419     (goto-char (match-end 0))
420     (current-column)))
421
422 (defvar org-indent-indentation-per-level) ; defined in org-indent.el
423
424 (defface org-inlinetask
425   (org-compatible-face 'shadow '((t (:bold t))))
426   "Face for inlinetask headlines."
427   :group 'org-faces)
428
429 (defun org-inlinetask-fontify (limit)
430   "Fontify the inline tasks down to LIMIT."
431   (let* ((nstars (if org-odd-levels-only
432                      (1- (* 2 (or org-inlinetask-min-level 200)))
433                    (or org-inlinetask-min-level 200)))
434          (re (concat "^\\(\\*\\)\\(\\*\\{"
435                      (format "%d" (- nstars 3))
436                      ",\\}\\)\\(\\*\\* .*\\)"))
437          ;; Virtual indentation will add the warning face on the first
438          ;; star.  Thus, in that case, only hide it.
439          (start-face (if (and (org-bound-and-true-p org-indent-mode)
440                               (> org-indent-indentation-per-level 1))
441                          'org-hide
442                        'org-warning)))
443     (while (re-search-forward re limit t)
444       (if org-inlinetask-show-first-star
445           (add-text-properties (match-beginning 1) (match-end 1)
446                                `(face ,start-face font-lock-fontified t)))
447       (add-text-properties (match-beginning
448                             (if org-inlinetask-show-first-star 2 1))
449                            (match-end 2)
450                            '(face org-hide font-lock-fontified t))
451       (add-text-properties (match-beginning 3) (match-end 3)
452                            '(face org-inlinetask font-lock-fontified t)))))
453
454 (defun org-inlinetask-toggle-visibility ()
455   "Toggle visibility of inline task at point."
456   (let ((end (save-excursion
457                (org-inlinetask-goto-end)
458                (if (bolp) (1- (point)) (point))))
459         (start (save-excursion
460                  (org-inlinetask-goto-beginning)
461                  (point-at-eol))))
462     (cond
463      ;; Nothing to show/hide.
464      ((= end start))
465      ;; Inlinetask was folded: expand it.
466      ((get-char-property (1+ start) 'invisible)
467       (org-show-entry))
468      (t (outline-flag-region start end t)))))
469
470 (defun org-inlinetask-remove-END-maybe ()
471   "Remove an END line when present."
472   (when (looking-at (format "\\([ \t]*\n\\)*\\*\\{%d,\\}[ \t]+END[ \t]*$"
473                             org-inlinetask-min-level))
474     (replace-match "")))
475
476 (eval-after-load "org-exp"
477   '(add-hook 'org-export-preprocess-before-backend-specifics-hook
478              'org-inlinetask-export-handler))
479 (eval-after-load "org"
480   '(add-hook 'org-font-lock-hook 'org-inlinetask-fontify))
481
482 (provide 'org-inlinetask)
483
484 ;;; org-inlinetask.el ends here