Fixes #4399 - Spacemacs documentation improvements and fixes.

core/core-documentation.el

@@ -13,6 +13,9 @@
 (require 'ox-publish)
 (require 's)
 (require 'dash)
+(require 'f)
+(require 'toc-org)
+(require 'org-id)
 
 (defvar spacemacs--category-names
   '(("config-files" . "Configuration files")
@@ -87,18 +90,101 @@
         (format "%s\n%s%s" beginning-of-content toc-string rest-of-content)
       content)))
 
+(defun spacemacs//toc-org-unhrefify-toc ()
+  "Make TOC classical org-mode TOC."
+  (let ((toc-org-hrefify-default "org"))
+    (toc-org-insert-toc)))
+
+(defun spacemacs//org-heading-annotate-custom-id ()
+  "Annotate headings with the indexes that GitHub uses for linking.
+`org-html-publish-to-html' will use them instead of the default #orgheadline{N}.
+This way the GitHub links and the http://spacemacs.org/ links will be compatible."
+  (progn (goto-char (point-min))
+         (goto-char (point-min))
+         (while (re-search-forward "^[\\*]+\s\\(.*\\).*$" nil t)
+           (let ((heading (match-string 1)))
+             (progn (move-end-of-line nil)
+                    (open-line 1)
+                    (next-line 1)
+                    (insert (format (concat "  :PROPERTIES:\n"
+                                            "  :CUSTOM_ID: %s\n"
+                                            "  :END:\n")
+                                    (substring (toc-org-hrefify-gh
+                                                (replace-regexp-in-string
+                                                 toc-org-tags-regexp
+                                                 ""
+                                                 heading))
+                                               ;; Remove # prefix added by `toc-org-hrefify-gh'.
+                                               1))))))))
+
+(defun spacemacs//reroot-links ()
+  "Find the links that start with https://github.com/syl20bnr/spacemacs/blob/
+and end with .org{#an-optional-heading-link} (i.e the links between the local org files).
+Change their root to http://spacemacs.org/ so the links will point at files located on the site.
+For the file to file links to work properly the exported org files should be processed with
+the `spacemacs//org-heading-annotate-custom-id' function."
+  (let ((git-url-root-regexp
+         (concat "\\[\\[[\\s]*\\(https\\:\\/\\/github\\.com\\/syl20bnr"
+                 "\\/spacemacs\\/blob\\/[^/]+\\/\\)[^]]+\\(\\.org\\).*$"))
+        (site-url "http://spacemacs.org/")
+        (site-doc-postf ".html"))
+    (progn (goto-char (point-min))
+           (while (re-search-forward git-url-root-regexp nil t)
+             (progn (replace-match site-url nil t nil 1)
+                    (replace-match site-doc-postf nil t nil 2))))))
+
+(defun spacemacs//add-org-meta-readtheorg-css (filename)
+  (let* ((head-css-extra-readtheorg-head (concat
+                                          "#+HTML_HEAD_EXTRA:"
+                                          "<link rel=\"stylesheet\" "
+                                          "type=\"text/css\" "
+                                          "href=\""))
+         (head-css-extra-readtheorg-tail "css/readtheorg.css\" />\n"))
+    (progn (goto-char (point-min))
+           (delete-matching-lines "\\+HTML_HEAD_EXTRA\\:.*\\/css\\/readtheorg\\.css")
+           (goto-char (point-min))
+           (if (search-forward "#+TITLE:" nil t nil)
+               (beginning-of-line 2)
+             (error (format "Can't find #+TITLE: in %s"
+                            (buffer-file-name))))
+           (insert (concat head-css-extra-readtheorg-head
+                           (f-relative user-emacs-directory
+                                       (file-name-directory filename))
+                           head-css-extra-readtheorg-tail)))))
+
+(defun spacemacs//pub-doc-html-advice (origfunc &rest args)
+  "Wrapper for `org-html-publish-to-html' use it to insert
+preprocessors for the exported .org files."
+  (save-current-buffer
+    (save-excursion
+      (let* ((filename (car (nthcdr 1 args)))
+             (visitingp (find-buffer-visiting filename)))
+        ;; Temporary "unvisit" the visited org files.
+        (when visitingp (with-current-buffer visitingp (setq buffer-file-name nil)))
+        (with-temp-buffer
+          (save-match-data
+            (insert-file-contents filename t)
+            ;; ===========Add preprocessors here===============
+            (spacemacs//add-org-meta-readtheorg-css filename)
+            (spacemacs//toc-org-unhrefify-toc)
+            (spacemacs//reroot-links)
+            (spacemacs//org-heading-annotate-custom-id)
+            (apply origfunc args)
+            (not-modified)))
+        ;; Restore `buffer-file-name' for the buffers that previously visited the org files.
+        (when visitingp (with-current-buffer visitingp (setq buffer-file-name filename)))))))
+
 (defun spacemacs/publish-doc ()
-  "Publishe the documentation to doc/export/."
+  "Publish the documentation to doc/export/."
   (interactive)
   (advice-add 'org-html-toc :filter-return #'spacemacs//format-toc)
   (advice-add 'org-html-template :filter-return #'spacemacs//format-content)
+  (advice-add 'org-html-publish-to-html :around #'spacemacs//pub-doc-html-advice)
   (let* ((header
           "<link rel=\"stylesheet\" type=\"text/css\"
                  href=\"http://www.pirilampo.org/styles/readtheorg/css/htmlize.css\"/>
           <script src=\"https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js\"></script>
           <script src=\"https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js\"></script>
-          <script type=\"text/javascript\"
-                  src=\"http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js\"></script>
           <script type=\"text/javascript\"
                   src=\"http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js\"></script>
           <script>
@@ -148,6 +234,7 @@
              :publishing-function org-publish-attachment))))
     (org-publish-project "spacemacs"))
   (advice-remove 'org-html-toc #'spacemacs//format-toc)
-  (advice-remove 'org-html-template #'spacemacs//format-content))
+  (advice-remove 'org-html-template #'spacemacs//format-content)
+  (advice-remove 'org-html-publish-to-html #'spacemacs//pub-doc-html-advice))
 
 (provide 'core-documentation)

core/core-funcs.el

@@ -171,11 +171,30 @@ Supported properties:
   (find-file file)
   (org-indent-mode)
   (view-mode)
+
+  ;; Enable `space-doc-mode' if defined.
+  (when (and (boundp 'space-doc-mode)
+             (fboundp 'space-doc-mode))
+    (space-doc-mode))
+
   (goto-char (point-min))
 
   (when anchor-text
-    (re-search-forward anchor-text))
-  (beginning-of-line)
+    ;; If `anchor-text' is GitHub style link.
+    (if (string-prefix-p "#" anchor-text)
+        ;; If the toc-org package is loaded.
+        (if (configuration-layer/package-usedp 'toc-org)
+            ;; For each heading. Search the heading that corresponds to `anchor-text'.
+            (while (and (re-search-forward "^[\\*]+\s\\(.*\\).*$" nil t)
+                        (not (string= (toc-org-hrefify-gh (match-string 1))
+                                      anchor-text))))
+          ;; This is not a problem because without the space-doc package
+          ;; those links will be opened in the browser.
+          (message (format "Can't follow the GitHub style anchor: '%s' without the org layer." anchor-text)))
+
+      (re-search-forward anchor-text)))
+
+(beginning-of-line)
 
   (cond
    ((eq expand-scope 'subtree)

core/templates/README.org.template

@@ -1,13 +1,12 @@
 #+TITLE: %LAYER_NAME% layer
-#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../css/readtheorg.css" />
 
 # The maximum height of the logo should be 200 pixels.
 [[img/%LAYER_NAME%.png]]
 
-* Table of Contents                                        :TOC_4_org:noexport:
- - [[Decsription][Description]]
- - [[Install][Install]]
- - [[Key bindings][Key bindings]]
+* Table of Contents                                        :TOC_4_gh:noexport:
+ - [[#decsription][Description]]
+ - [[#install][Install]]
+ - [[#key-bindings][Key bindings]]
 
 * Description
 This layer does wonderful things:

doc-fmt/run.bash

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+if ! [ -d "./.git" ]
+	then
+		echo "Should be executed from the repo root."
+		exit 1
+fi
+
+#rm #+HTML_HEAD_EXTRA: ... readtheorg.css" /> in the doc.
+find ./doc    -name "*.org" -type f -exec sed -i '/#+HTML_HEAD_EXTRA.*readtheorg.css.*/d' {} \;
+
+#rm #+HTML_HEAD_EXTRA: ... readtheorg.css" /> in the layers.
+find ./layers -name "*.org" -type f -exec sed -i '/#+HTML_HEAD_EXTRA.*readtheorg.css.*/d' {} \;
+
+
+
+#replace :TOC_4_org: with :TOC_4_gh: in the doc.
+find ./doc    -name "*.org" -type f -exec sed -i 's/:TOC_4_org:/:TOC_4_gh:/' {} \;
+
+#replace :TOC_4_org: with :TOC_4_gh: in the layers.
+find ./layers -name "*.org" -type f -exec sed -i 's/:TOC_4_org:/:TOC_4_gh:/' {} \;
+
+
+
+#apply toc-org to doc.
+find ./doc    -name "*.org" -type f -exec emacs -batch -l ./doc-fmt/toc-org-apply.el '{}' -f toc-apply \;
+
+#apply toc-org to layers.
+find ./layers -name "*.org" -type f -exec emacs -batch -l ./doc-fmt/toc-org-apply.el '{}' -f toc-apply \;
+

doc-fmt/test.org

@@ -0,0 +1,29 @@
+#+TITLE: FOO
+
+* Table of Contents                                         :TOC_4_gh:noexport:
+ - [[#links][Links]]
+ - [[#foo][FOO]]
+ - [[#bar][BAR]]
+ - [[#baz][BAZ]]
+
+* Links
+
+[[https://github.com/syl20bnr/spacemacs/blob/master/doc/FAQ.org#os-x][Link to FAQ "OS X" heading]]
+
+[[https://www.google.com][Link to www.google.com]]
+
+[[https://github.com/syl20bnr/spacemacs/blob/master/doc/VIMUSERS.org#sessions]]
+
+[[https://github.com/syl20bnr/spacemacs/blob/master/layers/%2Bfun/emoji/README.org][Link to Emoji layer README.org]]
+
+* FOO
+
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. Integer tincidunt. Cras dapibus. Vivamus elementum semper nisi. Aenean vulputate eleifend tellus. Aenean leo ligula, porttitor eu, consequat vitae, eleifend ac, enim. Aliquam lorem ante, dapibus in, viverra quis, feugiat a, tellus. Phasellus viverra nulla ut metus varius laoreet. Quisque rutrum. Aenean imperdiet. Etiam ultricies nisi vel augue. Curabitur ullamcorper ultricies nisi. Nam eget dui. Etiam rhoncus. Maecenas tempus, tellus eget condimentum rhoncus, sem quam semper libero, sit amet adipiscing sem neque sed ipsum. Nam quam nunc, blandit vel, luctus pulvinar, hendrerit id, lorem. Maecenas nec odio et ante tincidunt tempus. Donec vitae sapien ut libero venenatis faucibus. Nullam quis ante. Etiam sit amet orci eget eros faucibus tincidunt. Duis leo. Sed fringilla mauris sit amet nibh. Donec sodales sagittis magna. Sed conseq
+
+* BAR
+
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. Integer tincidunt. Cras dapibus. Vivamus elementum semper nisi. Aenean vulputate eleifend tellus. Aenean leo ligula, porttitor eu, consequat vitae, eleifend ac, enim. Aliquam lorem ante, dapibus in, viverra quis, feugiat a, tellus. Phasellus viverra nulla ut metus varius laoreet. Quisque rutrum. Aenean imperdiet. Etiam ultricies nisi vel augue. Curabitur ullamcorper ultricies nisi. Nam eget dui. Etiam rhoncus. Maecenas tempus, tellus eget condimentum rhoncus, sem quam semper libero, sit amet adipiscing sem neque sed ipsum. Nam quam nunc, blandit vel, luctus pulvinar, hendrerit id, lorem. Maecenas nec odio et ante tincidunt tempus. Donec vitae sapien ut libero venenatis faucibus. Nullam quis ante. Etiam sit amet orci eget eros faucibus tincidunt. Duis leo. Sed fringilla mauris sit amet nibh. Donec sodales sagittis magna. Sed conseq
+
+* BAZ
+
+Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. Integer tincidunt. Cras dapibus. Vivamus elementum semper nisi. Aenean vulputate eleifend tellus. Aenean leo ligula, porttitor eu, consequat vitae, eleifend ac, enim. Aliquam lorem ante, dapibus in, viverra quis, feugiat a, tellus. Phasellus viverra nulla ut metus varius laoreet. Quisque rutrum. Aenean imperdiet. Etiam ultricies nisi vel augue. Curabitur ullamcorper ultricies nisi. Nam eget dui. Etiam rhoncus. Maecenas tempus, tellus eget condimentum rhoncus, sem quam semper libero, sit amet adipiscing sem neque sed ipsum. Nam quam nunc, blandit vel, luctus pulvinar, hendrerit id, lorem. Maecenas nec odio et ante tincidunt tempus. Donec vitae sapien ut libero venenatis faucibus. Nullam quis ante. Etiam sit amet orci eget eros faucibus tincidunt. Duis leo. Sed fringilla mauris sit amet nibh. Donec sodales sagittis magna. Sed conseq

doc-fmt/toc-org-apply.el

@@ -0,0 +1,4 @@
+(load-file  "./doc-fmt/toc-org.el")
+(defun toc-apply ()
+  (toc-org-insert-toc)
+  (save-buffer 0))