org-annotate-file.el 5.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158
  1. ;;; org-annotate-file.el --- Annotate a file with org syntax
  2. ;; Copyright (C) 2008-2014 Philip Jackson
  3. ;; Author: Philip Jackson <phil@shellarchive.co.uk>
  4. ;; Version: 0.2
  5. ;; This file is not currently part of GNU Emacs.
  6. ;; This program is free software; you can redistribute it and/or
  7. ;; modify it under the terms of the GNU General Public License as
  8. ;; published by the Free Software Foundation; either version 2, or (at
  9. ;; your option) any later version.
  10. ;; This program is distributed in the hope that it will be useful, but
  11. ;; WITHOUT ANY WARRANTY; without even the implied warranty of
  12. ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  13. ;; General Public License for more details.
  14. ;; You should have received a copy of the GNU General Public License
  15. ;; along with this program ; see the file COPYING. If not, write to
  16. ;; the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17. ;; Boston, MA 02111-1307, USA.
  18. ;;; Commentary:
  19. ;; This is yet another implementation to allow the annotation of a
  20. ;; file without modification of the file itself. The annotation is in
  21. ;; org syntax so you can use all of the org features you are used to.
  22. ;; To use you might put the following in your .emacs:
  23. ;;
  24. ;; (require 'org-annotate-file)
  25. ;; (global-set-key (kbd "C-c C-l") 'org-annotate-file) ; for example
  26. ;;
  27. ;; To change the location of the annotation file:
  28. ;;
  29. ;; (setq org-annotate-file-storage-file "~/annotated.org")
  30. ;;
  31. ;; Then when you visit any file and hit C-c C-l you will find yourself
  32. ;; in an org buffer on a headline which links to the file you were
  33. ;; visiting, e.g:
  34. ;; * ~/org-annotate-file.el
  35. ;; Under here you can put anything you like, save the file
  36. ;; and next time you hit C-c C-l you will hit those notes again.
  37. ;;
  38. ;; To put a subheading with a text search for the current line set
  39. ;; `org-annotate-file-add-search` to non-nil value. Then when you hit
  40. ;; C-c C-l (on the above line for example) you will get:
  41. ;; * ~/org-annotate-file.el
  42. ;; ** `org-annotate-file-add-search` to non-nil value. Then whe...
  43. ;; Note that both of the above will be links.
  44. ;;; Code:
  45. (require 'org)
  46. (defgroup org-annotate-file nil
  47. "Org Annotate"
  48. :group 'org)
  49. (defcustom org-annotate-file-storage-file "~/.org-annotate-file.org"
  50. "File in which to keep annotations."
  51. :group 'org-annotate-file
  52. :type 'file)
  53. (defcustom org-annotate-file-add-search nil
  54. "If non-nil, add a link as a second level to the actual file location."
  55. :group 'org-annotate-file
  56. :type 'boolean)
  57. (defcustom org-annotate-file-always-open t
  58. "If non-nil, always expand the full tree when visiting the annotation file."
  59. :group 'org-annotate-file
  60. :type 'boolean)
  61. (defun org-annotate-file-ellipsify-desc (string &optional after)
  62. "Return shortened STRING with appended ellipsis.
  63. Trim whitespace at beginning and end of STRING and replace any
  64. characters that appear after the occurrence of AFTER with '...'"
  65. (let* ((after (number-to-string (or after 30)))
  66. (replace-map (list (cons "^[ \t]*" "")
  67. (cons "[ \t]*$" "")
  68. (cons (concat "^\\(.\\{" after
  69. "\\}\\).*") "\\1..."))))
  70. (mapc (lambda (x)
  71. (when (string-match (car x) string)
  72. (setq string (replace-match (cdr x) nil nil string))))
  73. replace-map)
  74. string))
  75. ;;;###autoload
  76. (defun org-annotate-file ()
  77. "Visit `org-annotate-file-storage-file` and add a new annotation section.
  78. The annotation is opened at the new section which will be referencing
  79. the point in the current file."
  80. (interactive)
  81. (unless (buffer-file-name)
  82. (error "This buffer has no associated file!"))
  83. (switch-to-buffer
  84. (org-annotate-file-show-section org-annotate-file-storage-file)))
  85. ;;;###autoload
  86. (defun org-annotate-file-show-section (storage-file &optional annotated-buffer)
  87. "Add or show annotation entry in STORAGE-FILE and return the buffer.
  88. The annotation will link to ANNOTATED-BUFFER if specified,
  89. otherwise the current buffer is used."
  90. (let ((filename (abbreviate-file-name (or annotated-buffer
  91. (buffer-file-name))))
  92. (line (buffer-substring-no-properties (point-at-bol) (point-at-eol)))
  93. (annotation-buffer (find-file-noselect storage-file)))
  94. (with-current-buffer annotation-buffer
  95. (org-annotate-file-annotate filename line))
  96. annotation-buffer))
  97. (defun org-annotate-file-annotate (filename line)
  98. "Add annotation for FILENAME at LINE using current buffer."
  99. (let* ((link (org-make-link-string (concat "file:" filename) filename))
  100. (search-link (org-make-link-string
  101. (concat "file:" filename "::" line)
  102. (org-annotate-file-ellipsify-desc line))))
  103. (unless (eq major-mode 'org-mode)
  104. (org-mode))
  105. (goto-char (point-min))
  106. (widen)
  107. (when org-annotate-file-always-open
  108. (show-all))
  109. (unless (search-forward-regexp
  110. (concat "^* " (regexp-quote link)) nil t)
  111. (org-annotate-file-add-upper-level link))
  112. (beginning-of-line)
  113. (org-narrow-to-subtree)
  114. ;; deal with a '::' search if need be
  115. (when org-annotate-file-add-search
  116. (unless (search-forward-regexp
  117. (concat "^** " (regexp-quote search-link)) nil t)
  118. (org-annotate-file-add-second-level search-link)))))
  119. (defun org-annotate-file-add-upper-level (link)
  120. "Add and link heading to LINK."
  121. (goto-char (point-min))
  122. (call-interactively 'org-insert-heading)
  123. (insert link))
  124. (defun org-annotate-file-add-second-level (link)
  125. "Add and link subheading to LINK."
  126. (goto-char (point-at-eol))
  127. (call-interactively 'org-insert-subheading)
  128. (insert link))
  129. (provide 'org-annotate-file)
  130. ;;; org-annotate-file.el ends here