Merge: doc style improvements

Rakefile

@@ -50,6 +50,10 @@ task :release => [:package, 'doc:archive'] do
   raise "Not implemented for github yet!"
 end
 
+# rake doc[../htmlize]
+#
+# To do this interactively, load doc/yas-doc-helper, open one of the
+# org files, and do `C-c C-e P'.
 desc "Generate document"
 task :doc, [:htmlize] do |t, args|
   load_path = '-L .'

doc/nav-menu.html.inc

@@ -3,8 +3,8 @@
     <li> <a href="index.html">Overview</a>
     <li> <a href="https://github.com/joaotavora/yasnippet/blob/master/README.mdown">
         Intro and Tutorial</a>
-    <li class="center">Snippet
-      <ul>
+    <li class="center border">Snippet
+      <ul class="nopad">
         <li> <a href="snippet-organization.html">Organization</a>
         <li> <a href="snippet-expansion.html">Expansion</a>
         <li> <a href="snippet-development.html">Development</a>

doc/snippet-expansion.org

@@ -21,7 +21,7 @@
 
      - Using hippie-expand
 
-   - Call [[sym:yas-insert-snippet][=yas-insert-snippet=]] (use =M-x yas-insert-snippet== or its
+   - Call [[sym:yas-insert-snippet][=yas-insert-snippet=]] (use =M-x yas-insert-snippet= or its
      keybinding =C-c & C-s=).
 
    - Use m2m's excellent auto-complete
@@ -77,7 +77,7 @@ obsolete.
 
 ** Insert at point
 
-The command [[#yas-insert-snippet][=yas-insert-snippet=]] lets you insert snippets at point
+The command [[sym:yas-insert-snippet][=yas-insert-snippet=]] lets you insert snippets at point
 /for your current major mode/. It prompts you for the snippet key
 first, and then for a snippet template if more than one template
 exists for the same key.
@@ -94,7 +94,7 @@ The prompting methods used are again controlled by
 It's often useful to inject already written text in the middle of a
 snippet.  The variable [[sym:yas-wrap-around-region][=yas-wrap-around-region=]] when to t substitute
 the region contents into the =$0= placeholder of a snippet expanded by
-[[#yas-insert-snippet][=yas-insert-snippet=]].  Setting it to a character value (e.g. =?0=)
+[[sym:yas-insert-snippet][=yas-insert-snippet=]].  Setting it to a character value (e.g. =?0=)
 will insert the contents of corresponding register.
 
 Older (versions 0.9.1 and below) of Yasnippet, supported a setting of
@@ -169,7 +169,7 @@ In particular, the following things matter:
 
 -  Buffer-local list of extra modes
 
-   Use [[#yas-activate-extra-mode][=yas-activate-extra-mode=]] to
+   Use [[sym:yas-activate-extra-mode][=yas-activate-extra-mode=]] to
    consider snippet tables whose name does not correspond to a major
    mode. Typically, you call this from a minor mode hook, for example:
 

doc/snippet-menu.org

@@ -24,7 +24,7 @@ In this menu, you can find
 Invoking "Load snippets..." from the menu invokes [[sym:yas-load-directory][=yas-load-directory=]]
 and prompts you for a snippet directory hierarchy to load.
 
-Also useful is the "Reload everything" item to invoke [[#yas-reload-all][=yas-reload-all=]]
+Also useful is the "Reload everything" item to invoke [[sym:yas-reload-all][=yas-reload-all=]]
 which uncondionally reloads all the snippets directories defined in
 [[sym:yas-snippet-dirs][=yas-snippet-dirs=]] and rebuilds the menus.
 

doc/snippet-organization.org

@@ -4,8 +4,9 @@
 
 * Basic structure
 
-   Snippet collections can be stored in plain text files. They are arranged by
-   sub-directories naming *snippet tables*. These mostly name Emacs major names.
+   Snippet collections can be stored in plain text files. They are
+   arranged by sub-directories naming *snippet tables*.  These mostly
+   name Emacs major mode names.
 
    #+begin_example
    .
@@ -81,7 +82,7 @@
 
    If you place an empty plain text file =.yas-make-groups= inside one
    of the mode directories, the names of these sub-directories are
-   considered groups of snippets and [[snippet-menu.org][the menu]] is organized much more
+   considered groups of snippets and [[file:snippet-menu.org][the menu]] is organized much more
    cleanly:
 
    [[./images/menu-groups.png]]

doc/stylesheets/manual.css

@@ -1,5 +1,14 @@
-nav > ul > li.center > ul {
-    padding: 0;
+.center { margin-left: auto; margin-right: auto; text-align: center; }
+.current {
+    font-weight: bold;
+    background-color: #E0E8F0;
+}
+
+body { background-color:  #E4F0F4 }
+div#content {
+    max-width: 20cm;
+    margin-left: auto;
+    margin-right: auto;
 }
 
 nav li {
@@ -9,20 +18,22 @@ nav li {
     list-style-type: none;
     padding: 0.5em;
 }
-
 nav > ul > li {
     display: inline-block;
 }
-
-/* match org's css for <pre> */
-code {
-    background-color: #F3F5F7;
-    font-family: courier, monospace;
+.nopad {
+    padding: 0;
+}
+li.border {
+    border: solid;
+    border-width: 1px;
 }
 
-#content {
-    margin-left: 5%;
-    margin-right: 10%;
+pre, code{ background-color: #F3F5F7; }
+code {
+    /* http://neugierig.org/software/chromium/notes/2009/09/monospace-fonts-workaround.html */
+    font-family: WorkAroundWebKitAndMozilla, monospace;
+    white-space: nowrap;
 }
 
 /* Styles for htmlize.el fontification.  */

doc/stylesheets/styles.css

@@ -1,93 +0,0 @@
-@media all
-{
-    body {
-        margin: 1em auto;
-        /*margin: 10px 18% 10px 18%;*/
-        font-family: Arial;
-        /*text-align: justify;*/
-        font-size: 14pt;
-        padding: 10px;
-        line-height: 1.2em;
-        max-width: 600pt;
-    }
-
-    div#table-of-contents {
-        position: fixed;
-        left: 0%;
-        right: 0%;
-        top: 0px;
-        z-index: 100;
-        background: black;
-    }
-
-    div#table-of-contents h2 {
-        display: none;
-    }
-
-    div#table-of-contents a {
-        text-decoration: none;
-        color: white;
-    }
-
-    div#table-of-contents a:visited {
-        color: white;
-    }
-
-    div#table-of-contents a:hover {
-        color: orange;
-    }
-
-    div.outline-2 h2{
-        padding-top: 50px;
-    }
-
-    div#text-table-of-contents {
-        text-color: white;
-        text-align: center;
-        margin-left: 30%;
-        margin-right: 30%;
-    }
-
-    div#text-table-of-contents ul {
-        height: 2em;
-        width: 500px;
-        list-style: none;
-        margin: auto;
-    }
-
-    div#text-table-of-contents ul li {
-        float: left;
-        margin-left:auto;
-        margin-right: auto;
-        padding-left: 10px;
-    }
-
-    div#postamble{
-        position: fixed;
-        width: 800px;
-        height: 250px;
-        left: 50%;
-        right: 50%;
-        margin:-75px 0 0 -400px;
-        bottom: -20px;
-        font-size: 10pt;
-        color: grey;
-        background: url('siscog-bottom-logo.png') no-repeat;
-        /* background-size: 100% 100%; */
-    }
-
-    div#postamble *{
-        display: none;
-    }
-
-    div#postamble p.date{
-        position: relative;
-        bottom: -200px;
-        text-align: center;
-        display: block;
-    }
-
-
-
-
-}

doc/yas-doc-helper.el

@@ -31,13 +31,14 @@
     (require 'ox-publish))
 (require 'yasnippet) ; docstrings must be loaded
 
-(defun yas--org-raw-html (tag content)
+(defun yas--org-raw-html (tag content &optional attrs)
   ;; in version 8.0 org-mode changed the export syntax, see
   ;; http://orgmode.org/worg/org-8.0.html#sec-8-1
   (format (if (version< org-version "8.0.0")
               "@<%s>%s@</%s>"                ; old: @<tag>
             "@@html:<%s>@@%s@@html:</%s>@@") ; new: @@html:<tag>@@
-          tag content tag))
+          (concat tag (if attrs " ") attrs)
+          content tag))
 
 (defun yas--document-symbol (symbol level)
   (let* ((stars (make-string level ?*))
@@ -45,14 +46,17 @@
                     (mapcar #'symbol-name (help-function-arglist symbol t))))
          (heading (cond ((fboundp symbol)
                          (format
-                          "%s =%s= (%s)" stars symbol
+                          "%s %s (%s)\n" stars (yas--org-raw-html "code" symbol "class='function'")
                           (mapconcat (lambda (a)
                                        (format (if (string-prefix-p "&" a)
-                                                   "/%s/" "=%s=") a))
+                                                   "/%s/" "=%s=")
+                                               a))
                                      args " ")))
                         (t
-                         (format "%s =%s=\n" stars symbol))))
+                         (format "%s %s\n" stars
+                                 (yas--org-raw-html "code" symbol "class='variable'")))))
          (after-heading (format ":PROPERTIES:\n:CUSTOM_ID: %s\n:END:" symbol))
+         (text-quoting-style 'grave)
          (body (or (cond ((fboundp symbol)
                           (let ((doc-synth (car-safe (get symbol 'function-documentation))))
                             (if (functionp doc-synth)
@@ -64,10 +68,17 @@
                           (format "*WARNING*: no symbol named =%s=" symbol)))
                    (format "*WARNING*: no doc for symbol =%s=" symbol)))
          (case-fold-search nil))
-    ;; do some transformations on the body:
+    ;; Do some transformations on the body:
     ;; ARGxxx becomes @<code>arg@</code>xxx
     ;; FOO becomes /foo/
     ;; `bar' becomes [[#bar][=bar=]]
+    ;;    (...) becomes #+BEGIN_SRC elisp (...) #+END_SRC
+    ;; Info node `(some-manual) Node Name' becomes
+    ;; [[https://www.gnu.org/software/emacs/manual/html_node/some-manual/Node-Name.html]
+    ;;  [(some-manual) Node Name]]
+    ;;
+    ;; This is fairly fragile, though it seems to be working for
+    ;; now...
     (setq body (replace-regexp-in-string
                 "\\<\\([A-Z][-A-Z0-9]+\\)\\(\\sw+\\)?\\>"
                 #'(lambda (match)
@@ -82,16 +93,41 @@
                         match1)))
                 body t t 1)
           body (replace-regexp-in-string
-                "`\\([a-z-]+\\)'"
+                "\\\\{[^}]+}"
+                (lambda (match)
+                  (concat "#+BEGIN_EXAMPLE\n"
+                          (substitute-command-keys match)
+                          "#+END_EXAMPLE\n"))
+                body t t)
+          body (substitute-command-keys body)
+          body (replace-regexp-in-string
+                "Info node `(\\([-a-z]+\\)) \\([A-Za-z0-9 ]+\\)'"
+                (lambda (match)
+                  (let* ((manual (match-string 1 match))
+                         (node (match-string 2 match))
+                         (html-node (replace-regexp-in-string " " "-" node t t)))
+                    (format "Info node\
+ [[https://www.gnu.org/software/emacs/manual/html_node/%s/%s.html][(%s) %s]]"
+                            manual html-node manual node)))
+                body t t)
+          body (replace-regexp-in-string
+                "`\\([-a-z]+\\)'"
                 #'(lambda (match)
                     (let* ((name (downcase (match-string 1 match)))
-                           (sym (intern name)))
+                           (sym (intern-soft name)))
                       (if (memq sym yas--exported-syms)
                           (format "[[#%s][=%s=]]" name name)
                         (format "=%s=" name))))
-                body t))
+                body t t)
+          body (replace-regexp-in-string
+                "\n\n    +(.+\\(?:\n    +.+\\)*"
+                (lambda (match)
+                  (concat "\n#+BEGIN_SRC elisp\n"
+                          match
+                          "\n#+END_SRC\n"))
+                body t t))
     ;; output the paragraph
-    (concat heading "\n" after-heading "\n" body)))
+    (concat heading after-heading "\n" body)))
 
 (defun yas--document-symbols (level &rest names-and-predicates)
   (let ((sym-lists (make-vector (length names-and-predicates) nil))
@@ -118,6 +154,22 @@
 ;; This lets all the org files be exported to HTML with
 ;; `org-publish-current-project' (C-c C-e P).
 
+(defun yas--make-preamble (props)
+  "Return contents of nav-menu-html.inc.
+But replace link to \"current\" page with a span element."
+  (with-temp-buffer
+    (let ((dir (file-name-directory (plist-get props :input-file))))
+      (insert-file-contents (expand-file-name "nav-menu.html.inc" dir))
+      (goto-char (point-min))
+      (search-forward (concat "<a href=\""
+                              (file-name-nondirectory
+                               (plist-get props :output-file))
+                              "\">"))
+      (replace-match "<span class='current'>")
+      (search-forward "</a>")
+      (replace-match "</span>")
+      (buffer-string))))
+
 (let* ((dir (if load-file-name (file-name-directory load-file-name)
               default-directory))
        (src-epoch (getenv "SOURCE_DATE_EPOCH"))
@@ -138,10 +190,8 @@
         `(,@(when (fboundp 'org-html-publish-to-html)
               '(:publishing-function org-html-publish-to-html))
           :base-directory ,dir :publishing-directory ,dir
-          :html-preamble
-          ,(with-temp-buffer
-             (insert-file-contents (expand-file-name "nav-menu.html.inc" dir))
-             (buffer-string))
+          :html-preamble yas--make-preamble
+          ;;:with-broken-links mark
           :html-postamble
           ,(concat "<hr><p class='creator'>Generated by %c from "
                    (or rev yas--version) " " date "</p>\n"

yasnippet.el

@@ -237,7 +237,7 @@ nil.
 - To signal that the user quit the prompting process, you can
 signal `quit' with
 
-  (signal \\='quit \"user quit!\")."
+    (signal \\='quit \"user quit!\")"
   :type '(repeat function))
 
 (defcustom yas-indent-line 'auto
@@ -2946,7 +2946,8 @@ Otherwise signal `yas-exception'."
 (defun yas-field-value (number)
   "Get the string for field with NUMBER.
 
-Use this in primary and mirror transformations to tget."
+Use this in primary and mirror transformations to get the text of
+other fields."
   (let* ((snippet (car (yas-active-snippets)))
          (field (and snippet
                      (yas--snippet-find-field snippet number))))