Display entites as UTF8 characters

Based on code by Eric Schulte

doc/ChangeLog

@@ -1,3 +1,10 @@
+2010-05-16  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org.texi (Special symbols): Document the key to dislpay
+	entities as UTF8 characters.
+	(In-buffer settings): Document the new keywords for pretty
+	entity display.
+
 2010-05-15  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.texi (Tables in LaTeX export): Document the multicolumn

doc/org.texi

@@ -8726,6 +8726,19 @@ La@TeX{}, see the variable @code{org-entities} for the complete list.
 @samp{...} are all converted into special commands creating hyphens of
 different lengths or a compact set of dots.
 
+If you'd like to see entities displayed as utf8 characters, use the following
+command@footnote{You can urn this on by default bu setting the variable
+@code{prg-pretty-entities}, or on a per-file base with the @code{#+STARTUP}
+option @code{entitiespretty}.}:
+
+@table @kbd
+@kindex C-c C-x \
+@item C-c C-x \
+Toggle display of entities as UTF8 characters.  This does not change the
+buffer content which remains plain ASCII, but it overlays the UTF8 character
+for display purposes only.
+@end table
+
 @node Subscripts and superscripts, LaTeX fragments, Special symbols, Embedded LaTeX
 @subsection Subscripts and superscripts
 @cindex subscript
@@ -11004,6 +11017,15 @@ To hide blocks on startup, use these keywords. The corresponding variable is
 hideblocks   @r{Hide all begin/end blocks on startup}
 nohideblocks @r{Do not hide blocks on startup}
 @end example
+@cindex org-pretty-entities
+The the display of entities as UTF8 characters is governed by the variable
+@code{org-pretty-entities} and the keywords
+@cindex @code{entitiespretty}, STARTUP keyword
+@cindex @code{entitiesplain}, STARTUP keyword
+@example
+entitiespretty  @r{Show entities as UTF8 characters where possible}
+entitiesplain   @r{Leave entities plain}
+@end example
 @item #+TAGS:  TAG1(c1) TAG2(c2)
 @vindex org-tag-alist
 These lines (several such lines are allowed) specify the valid tags in

doc/orgcard.tex

@@ -704,6 +704,7 @@ some other place.
 \key{export visible part only}{C-c C-e v}
 \key{insert template of export options}{C-c C-e t}
 \key{toggle fixed width for entry or region}{C-c :}
+\key{toggle display of entities as UTF8 chars}{C-c C-x {\tt\char`\\}}
 
 %{\bf HTML formatting}
 
@@ -744,10 +745,8 @@ some other place.
 
 {\bf Comments: Text not being exported}
 
-Text before the first headline is not considered part of the document
-and is therefore never exported.
-Lines starting with \kbd{\#} are comments and are not exported.
-Subtrees whose header starts with COMMENT are never exported.
+Lines starting with \kbd{\#} and subtrees starting with COMMENT are
+never exported.
 
 \key{toggle COMMENT keyword on entry}{C-c ;}
 

lisp/ChangeLog

@@ -83,6 +83,12 @@
 	functions.
 	(org-mode): Install the `org-beginning-of-defun' and
 	`org-end-of-defun' functions.
+	(org-pretty-entities): New option.
+	(org-toggle-pretty-entities): New command.
+	(org-fontify-entities): New function.
+	(org-startup-options): New keywords for pretty entities.
+	(org-set-font-lock-defaults): Call the pretty entities
+	function.
 
 	* org-latex.el (org-export-latex-keywords-maybe): Protect the
 	TODO markup.

lisp/org.el

@@ -3151,6 +3151,12 @@ org-level-* faces."
   :group 'org-appearance
   :type 'boolean)
 
+(defcustom org-pretty-entities nil
+  "Non-nil means show entities as UTF8 characters.
+When nil, the \\name form remains in the buffer."
+  :group 'org-appearance
+  :type 'boolean)
+
 (defvar org-emph-re nil
   "Regular expression for matching emphasis.")
 (defvar org-verbatim-re nil
@@ -3990,7 +3996,9 @@ After a match, the following groups carry important information:
     ("noptag" org-tag-persistent-alist nil)
     ("hideblocks" org-hide-block-startup t)
     ("nohideblocks" org-hide-block-startup nil)
-    ("beamer" org-startup-with-beamer-mode t))
+    ("beamer" org-startup-with-beamer-mode t)
+    ("entitiespretty" org-pretty-entities t)
+    ("entitiesplain" org-pretty-entities nil))
   "Variable associated with STARTUP options for org-mode.
 Each element is a list of three items: The startup options as written
 in the #+STARTUP line, the corresponding variable, and the value to
@@ -5176,6 +5184,7 @@ For plain list items, if they are matched by `outline-regexp', this returns
 				     (2 'org-footnote t)))
 	   '("^&?%%(.*\\|<%%([^>\n]*?>" (0 'org-sexp-date t))
 	   '(org-hide-wide-columns (0 nil append))
+	   '(org-fontify-entities)
 	   ;; TODO lines
 	   (list (concat "^\\*+[ \t]+" org-todo-regexp "\\([ \t]\\|$\\)")
 		 '(1 (org-get-todo-face 1) t))
@@ -5231,6 +5240,37 @@ For plain list items, if they are matched by `outline-regexp', this returns
 		   '(org-font-lock-keywords t nil nil backward-paragraph))
     (kill-local-variable 'font-lock-keywords) nil))
 
+(defun org-toggle-pretty-entities ()
+  "Toggle the compostion display of entities as UTF8 characters."
+  (interactive)
+  (org-set-local 'org-pretty-entities (not org-pretty-entities))
+  (org-restart-font-lock)
+  (if org-pretty-entities
+      (message "Entities are displayed as UTF8 characers")
+    (save-restriction
+      (widen)
+      (decompose-region (point-min) (point-max))
+      (message "Entities are displayed plain"))))
+
+(defun org-fontify-entities (limit)
+  "Find an entity to fontify."
+  (let (ee)
+    (when org-pretty-entities
+      (catch 'match
+	(while (re-search-forward "\\\\\\([a-zA-Z][a-zA-Z0-9]*\\)[^[:alnum:]]"
+				  limit t)
+	  (if (and (setq ee (org-entity-get (match-string 1)))
+		   (= (length (nth 6 ee)) 1))
+	      (progn
+		(add-text-properties
+		 (match-beginning 0) (match-end 1)
+		 (list 'font-lock-fontified t))
+		(compose-region (match-beginning 0) (match-end 1)
+				(nth 6 ee) nil)
+		(backward-char 1)
+		(throw 'match t))))
+	nil))))
+
 (defun org-fontify-like-in-org-mode (s &optional odd-levels)
   "Fontify string S like in Org-mode"
   (with-temp-buffer
@@ -15748,6 +15788,7 @@ BEG and END default to the buffer boundaries."
 (org-defkey org-mode-map "\C-c\C-x\C-u" 'org-dblock-update)
 (org-defkey org-mode-map "\C-c\C-x\C-l" 'org-preview-latex-fragment)
 (org-defkey org-mode-map "\C-c\C-x\C-v" 'org-toggle-inline-images)
+(org-defkey org-mode-map "\C-c\C-x\\"   'org-toggle-pretty-entities)
 (org-defkey org-mode-map "\C-c\C-x\C-b" 'org-toggle-checkbox)
 (org-defkey org-mode-map "\C-c\C-xp"    'org-set-property)
 (org-defkey org-mode-map "\C-c\C-xe"    'org-set-effort)