refactor space-doc, add to the FAQ.

doc/FAQ.org

@@ -40,6 +40,7 @@
    - [[#try-spacemacs-without-modifying-my-existing-emacs-configuration][Try Spacemacs without modifying my existing Emacs configuration?]]
    - [[#make-copypaste-working-with-the-mouse-in-x11-terminals][Make copy/paste working with the mouse in X11 terminals?]]
    - [[#use-helm-ag-to-search-only-in-files-of-a-certain-type][Use =helm-ag= to search only in files of a certain type?]]
+   - [[#modify-spacemacs-documentation-look-space-doc-mode][Modify spacemacs documentation look (space-doc-mode)]]
    - [[#remap-paste-key-to-be-able-to-paste-copied-text-multiple-times][Remap paste key to be able to paste copied text multiple times]]
  - [[#windows][Windows]]
    - [[#why-do-the-fonts-look-crappy-on-windows][Why do the fonts look crappy on Windows?]]
@@ -494,6 +495,25 @@ some expressions to the search input:
 This is possible because =helm-ag= is treating the search input as command-line
 arguments of the =ag= program.
 
+** Modify spacemacs documentation look (space-doc-mode)
+You can modify the list of visual enhancements applied by the =space-doc-mode=:
+#+BEGIN_SRC emacs-lisp
+(setq spacemacs-space-doc-modificators
+      '(spacemacs//space-doc-org-indent-mode
+        spacemacs//space-doc-view-mode
+        spacemacs//space-doc-hide-line-numbers
+        spacemacs//space-doc-emphasis-overlays
+        spacemacs//space-doc-meta-tags-overlays
+        spacemacs//space-doc-link-protocol
+        spacemacs//space-doc-org-block-line-face-remap
+        spacemacs//space-doc-org-kbd-face-remap
+        spacemacs//space-doc-resize-inline-images
+        spacemacs//space-doc-advice-org-do-emphasis-faces)
+#+END_SRC
+It's the default value of the variable with all enhancements.
+Each function in the list represents some modification.
+You can make a modification deferred by moving it to =spacemacs-space-doc-modificators-deferred= list.
+
 ** Remap paste key to be able to paste copied text multiple times
 In vim and evil, pasting over a text would cause it to be copied, hence making it impossible to paste
 the same text multiple times.

layers/+spacemacs/spacemacs-org/local/space-doc/space-doc.el

@@ -38,40 +38,45 @@ keeping their content visible.
   :init-value nil
   :lighter " SD"
   (if (derived-mode-p 'org-mode)
-      (dolist (modificator spacemacs--space-doc-modificators)
+      (dolist (modificator (append '(spacemacs//space-doc-set-cache
+                                     spacemacs//space-doc-runs-deferred)
+                                   spacemacs-space-doc-modificators))
         (funcall modificator space-doc-mode))
     (message (format "space-doc-mode error:%s isn't an org-mode buffer"
                      (buffer-name)))
     (setq space-doc-mode nil)))
 
-(defvar spacemacs--space-doc-modificators
+;; NOTE: Dont forget to update Spacemacs FAQ if you modify this list!
+(defvar spacemacs-space-doc-modificators
   '(spacemacs//space-doc-org-indent-mode
     spacemacs//space-doc-view-mode
-    spacemacs//space-doc-set-cache
     spacemacs//space-doc-hide-line-numbers
-    spacemacs//space-doc-modf-emphasis-overlays
+    spacemacs//space-doc-emphasis-overlays
-    spacemacs//space-doc-modf-meta-tags-overlays
+    spacemacs//space-doc-meta-tags-overlays
-    spacemacs//space-doc-modf-link-protocol
+    spacemacs//space-doc-link-protocol
-    spacemacs//space-doc-modf-org-block-line-face-remap
+    spacemacs//space-doc-org-block-line-face-remap
-    spacemacs//space-doc-modf-org-kbd-face-remap
+    spacemacs//space-doc-org-kbd-face-remap
-    spacemacs//space-doc-modf-resize-inline-images
+    spacemacs//space-doc-resize-inline-images
-    spacemacs//space-doc-modf-advice-org-do-emphasis-faces
+    spacemacs//space-doc-advice-org-do-emphasis-faces)
-    (lambda (flag) (spacemacs//space-doc-run-modfs-deferred
+  "List of `space-doc' modificator functions for `org-mode' buffers.
-               '()
-               flag )))
-  "List of `space-doc' modificators for `org-mode' buffers.
 The functions work with a current buffer and accept ENABLE(flag) argument.
 If the argument has non-nil value - enable the modifications introduced
 by the function. Otherwise - disable.")
 
+;; NOTE: Dont forget to update Spacemacs FAQ if you modify this list!
+(defvar spacemacs-space-doc-modificators-deferred
+  '()
+  "Same as `spacemacs-space-doc-modificators' but the modificators will
+be run deferred.")
+
 (defun spacemacs//space-doc-org-indent-mode (&optional flag)
   "Enable `org-indent-mode' if flag is non nil, disable it otherwise.
-This functions is aimed to be used with `spacemacs--space-doc-modificators'."
+This functions is aimed to be used with `spacemacs-space-doc-modificators'."
   (org-indent-mode (if flag 1 -1)))
 
 (defun spacemacs//space-doc-view-mode (&optional flag)
   "Enable `view-mode' if flag is non nil, disable it otherwise.
-This functions is aimed to be used with `spacemacs--space-doc-modificators'."
+This functions is aimed to be used with `spacemacs-space-doc-modificators'."
   (view-mode (if flag 1 -1)))
 
 (cl-defstruct spacemacs--space-doc-cache-struct
@@ -85,7 +90,7 @@ It is set by `spacemacs//space-doc-set-cache'.")
 
 (defun spacemacs//space-doc-set-cache (&optional flag)
   "Set `spacemacs--space-doc-cache'.
-This functions is aimed to be used with `spacemacs--space-doc-modificators'."
+This functions is aimed to be used with `spacemacs-space-doc-modificators'."
   (setq spacemacs--space-doc-cache
         (if flag
             (let* ((kbd-bg (or (face-background 'org-kbd)
@@ -105,7 +110,6 @@ This functions is aimed to be used with `spacemacs--space-doc-modificators'."
                     (dolist (el org-emphasis-alist)
                       (when (member 'org-kbd el)
                         (return (car el))))))
-
               (make-spacemacs--space-doc-cache-struct
                :marker-face     marker-face
                :btn-marker-face btn-marker-face
@@ -113,14 +117,14 @@ This functions is aimed to be used with `spacemacs--space-doc-modificators'."
 
 (defun spacemacs//space-doc-hide-line-numbers (&optional enable)
   "If ENABLE is non-nil then toggle off the line numbers.
-This functions is aimed to be used with `spacemacs--space-doc-modificators'."
+This functions is aimed to be used with `spacemacs-space-doc-modificators'."
   (if enable
       (spacemacs/toggle-line-numbers-off)
     (when dotspacemacs-line-numbers
       (spacemacs/toggle-line-numbers-on))))
 
 (defun spacemacs//space-doc-org-do-emphasis-faces-advice (found)
-  "If FOUND has non-nil value - modify emphasized regions
+  "If FOUND has non-nil value then modify emphasized regions
 appearances in the current buffer. The function uses
 `match-data' set by `org-do-emphasis-faces' function."
   ;; `org-do-emphasis-faces' returns non-nil value when it
@@ -138,13 +142,13 @@ appearances in the current buffer. The function uses
      (match-end 2)))
   found)
 
-(defun spacemacs//space-doc-modf-advice-org-do-emphasis-faces (&optional enable)
+(defun spacemacs//space-doc-advice-org-do-emphasis-faces (&optional enable)
   "Advise org-do-emphasis-faces.
 If ENABLE is non-nil, add advice `org-do-emphasis-faces' function with
 `spacemacs//space-doc-org-do-emphasis-faces-advice'.
 NOTE: `org-do-emphasis-faces' is lazy and will emphasize only part of the
 current buffer so piggybacking it should be pretty performant solution.
-This functions is aimed to be used with `spacemacs--space-doc-modificators'."
+This functions is aimed to be used with `spacemacs-space-doc-modificators'."
   (when enable
     (advice-add 'org-do-emphasis-faces
                 :after
@@ -195,30 +199,30 @@ The character should be one of the markers from `org-emphasis-alist'."
     (overlay-put ending-marker-overlay
                  'space-doc-emphasis-overlay t)))
 
-(defun spacemacs//space-doc-modf-emphasis-overlays (&optional enable)
+(defun spacemacs//space-doc-emphasis-overlays (&optional enable)
   "Emphasis overlays.
 If ENABLE is non-nil, overlay regions which have already been emphasized by
 `org-do-emphasis-faces'in the current buffer.
 Otherwise remove all overlays with property `space-doc-emphasis-overlay'.
-This functions is aimed to be used with `spacemacs--space-doc-modificators'."
+This functions is aimed to be used with `spacemacs-space-doc-modificators'."
   ;; Remove overlays.
   (dolist (overlay (overlays-in (point-min) (point-max)))
     (when (overlay-get overlay 'space-doc-emphasis-overlay)
       (delete-overlay overlay)))
   (when enable
-      (dolist (emphasized-region
+    (dolist (emphasized-region
-               (spacemacs//space-doc-find-regions-by-text-property
+             (spacemacs//space-doc-find-regions-by-text-property
-                'org-emphasis t))
+              'org-emphasis t))
-        (spacemacs//space-doc-emphasis-region
+      (spacemacs//space-doc-emphasis-region
-         (car  emphasized-region)
+       (car  emphasized-region)
-         (cadr emphasized-region)))))
+       (cadr emphasized-region)))))
 
-(defun spacemacs//space-doc-modf-org-kbd-face-remap (&optional enable)
+(defun spacemacs//space-doc-org-kbd-face-remap (&optional enable)
-  "Remove boxes for key bindings.
+  "Remove boxes from key bindings.
 If ENABLE is non-nil, removes boxes from the `org-kbd'face in the current
 `org-mode' buffer.
 Otherwise, reverts them to default.
-This functions is aimed to be used with `spacemacs--space-doc-modificators'."
+This functions is aimed to be used with `spacemacs-space-doc-modificators'."
   (if enable
       (set (make-local-variable
             'spacemacs--space-doc-org-kbd-face-remap-cookie)
@@ -227,10 +231,10 @@ This functions is aimed to be used with `spacemacs--space-doc-modificators'."
     (face-remap-remove-relative
      spacemacs--space-doc-org-kbd-face-remap-cookie)))
 
-(defun spacemacs//space-doc-modf-resize-inline-images (&optional enable)
+(defun spacemacs//space-doc-resize-inline-images (&optional enable)
   "Resize inline images.
 If ENABLE is non nil then resize inline images.
-This functions is aimed to be used with `spacemacs--space-doc-modificators'."
+This functions is aimed to be used with `spacemacs-space-doc-modificators'."
   ;; resizing is always performed even when the image is smaller
   ;; so we don't resize in README.org buffers for now
   (let ((org-image-actual-width
@@ -239,12 +243,12 @@ This functions is aimed to be used with `spacemacs--space-doc-modificators'."
               600)))
     (org-display-inline-images)))
 
-(defun spacemacs//space-doc-modf-meta-tags-overlays (&optional enable)
+(defun spacemacs//space-doc-meta-tags-overlays (&optional enable)
   "Modify meta tag appearance.
 If ENABLE is non-nil, modify `org-mode' meta tags appearance in the current
 buffer.
 Otherwise, disable modifcations.
-This functions is aimed to be used with `spacemacs--space-doc-modificators'."
+This functions is aimed to be used with `spacemacs-space-doc-modificators'."
   (if enable
       ;; TODO add more types of tags or meta-line if needed.
       (let* ((invisible-org-meta-tags-list
@@ -291,13 +295,13 @@ This functions is aimed to be used with `spacemacs--space-doc-modificators'."
       (when (overlay-get overlay 'space-doc-tag-overlay)
         (delete-overlay overlay)))))
 
-(defun spacemacs//space-doc-modf-org-block-line-face-remap (&optional enable)
+(defun spacemacs//space-doc-org-block-line-face-remap (&optional enable)
   "Hide drawers.
 If ENABLE is non-nil, hide text of the code block meta lines in the current
 buffer. If the blocks have background color text won't be masked because it
 makes them look ugly with some themes.
 If ENABLE has nil, revert to the default.
-This functions is aimed to be used with `spacemacs--space-doc-modificators'."
+This functions is aimed to be used with `spacemacs-space-doc-modificators'."
   (if enable
       (let* ((default-bg (or (face-background 'default)
                              'unspecified))
@@ -330,12 +334,12 @@ This functions is aimed to be used with `spacemacs--space-doc-modificators'."
       (face-remap-remove-relative
        spacemacs--space-doc-org-block-end-line-face-remap-cookie))))
 
-(defun spacemacs//space-doc-modf-link-protocol (&optional enable)
+(defun spacemacs//space-doc-link-protocol (&optional enable)
   "Open HTTPS links in the curren buffer.
 If ENABLE is non-nil, use `spacemacs//space-doc-open' to open HTTPS links
 in the current `org-mode' buffer.
 Otherwise open them in the browser(default behavior).
-This functions is aimed to be used with `spacemacs--space-doc-modificators'."
+This functions is aimed to be used with `spacemacs-space-doc-modificators'."
   (if enable
       (progn
         ;; Make `space-doc' https link opener buffer local
@@ -366,14 +370,15 @@ Open all other links with `browse-url'."
                                  'subtree)
       (browse-url (concat "https://" path)))))
 
-(defun spacemacs//space-doc-run-modfs-deferred (modfs &optional flag)
+(defun spacemacs//space-doc-runs-deferred (&optional flag)
-  "Run each modf function from the MODFS list in the `run-with-idle-timer'
+  "Run each modificator function from the
-callback. This way heavy modfs won't affect document opening time.
+`spacemacs-space-doc-modificators-deferred' list
-FLAG is passed through."
+in the next command loop. This way heavy modificator functions
-  (run-with-idle-timer 0 nil (lambda (modfs flag)
+won't affect document opening time. FLAG is passed through."
-                               (dolist (modf modfs)
+  (run-with-idle-timer 0 nil (lambda (flag)
+                               (dolist (modf spacemacs-space-doc-modificators-deferred)
                                  (funcall modf flag)))
-                       modfs flag))
+                       flag))
 
 (defun spacemacs//space-doc-find-regions-by-text-property
     (property value &optional start end)
@@ -381,7 +386,6 @@ FLAG is passed through."
 the current buffer. If START or END has non-nil value - use them as
 boundaries.
 NOTE: It can find only fontified regions."
-
   (let ((p-min (or start (point-min)))
         (p-max (or end (point-max)))
         (r-end nil)