branch: master
commit 58b88d8be65c77130d856a59e1c4d8c636e6e997
Merge: 3d7cafc d364425
Author: Noam Postavsky <npost...@users.sourceforge.net>
Commit: Noam Postavsky <npost...@users.sourceforge.net>
Merge: doc style improvements
---
Rakefile | 4 ++
doc/nav-menu.html.inc | 4 +-
doc/snippet-expansion.org | 8 ++--
doc/snippet-menu.org | 2 +-
doc/snippet-organization.org | 7 ++--
doc/stylesheets/manual.css | 33 ++++++++++------
doc/stylesheets/styles.css | 93 --------------------------------------------
doc/yas-doc-helper.el | 78 ++++++++++++++++++++++++++++++-------
yasnippet.el | 5 ++-
9 files changed, 104 insertions(+), 130 deletions(-)
diff --git a/Rakefile b/Rakefile
index 83c6257..c63d269 100644
--- a/Rakefile
+++ b/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 .'
diff --git a/doc/nav-menu.html.inc b/doc/nav-menu.html.inc
index 2a3f0a1..3e74cf8 100644
--- a/doc/nav-menu.html.inc
+++ b/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>
diff --git a/doc/snippet-expansion.org b/doc/snippet-expansion.org
index a14ce15..a699d57 100644
--- a/doc/snippet-expansion.org
+++ b/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:
diff --git a/doc/snippet-menu.org b/doc/snippet-menu.org
index 272ea16..fee3a19 100644
--- a/doc/snippet-menu.org
+++ b/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.
diff --git a/doc/snippet-organization.org b/doc/snippet-organization.org
index 746cff0..22d3e46 100644
--- a/doc/snippet-organization.org
+++ b/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]]
diff --git a/doc/stylesheets/manual.css b/doc/stylesheets/manual.css
index 9580347..74bfe16 100644
--- a/doc/stylesheets/manual.css
+++ b/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. */
diff --git a/doc/stylesheets/styles.css b/doc/stylesheets/styles.css
deleted file mode 100644
index a158012..0000000
--- a/doc/stylesheets/styles.css
+++ /dev/null
@@ -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;
- }
-
-
-
-
-}
\ No newline at end of file
diff --git a/doc/yas-doc-helper.el b/doc/yas-doc-helper.el
index e272e41..f48628f 100644
--- a/doc/yas-doc-helper.el
+++ b/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"
diff --git a/yasnippet.el b/yasnippet.el
index 11bc270..0d41241 100644
--- a/yasnippet.el
+++ b/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))))
