Fix docs for new org mode

* Rakefile: Comment to remind me how to run it.
* doc/snippet-expansion.org:
* doc/snippet-menu.org: It seems org 9.x got a bit stricter about link
formatting.  Cross-file links *must* use the 'file:' prefix.
* doc/yas-doc-helper.el (yas--document-symbol): Org 9.x also got a bit
more strict about empty lines between a node and its property list.
Make sure not to put a blank line between variable nodes and the
property list.

5 files changed, 11 insertions, 7 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/snippet-expansion.org b/doc/snippet-expansion.org
index a14ce15..f0fa029 100644
--- a/doc/snippet-expansion.org
+++ b/doc/snippet-expansion.org
@@ -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..dc49249 100644
--- a/doc/snippet-organization.org
+++ b/doc/snippet-organization.org
@@ -81,7 +81,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/yas-doc-helper.el b/doc/yas-doc-helper.el
index e272e41..8fbee8e 100644
--- a/doc/yas-doc-helper.el
+++ b/doc/yas-doc-helper.el
@@ -45,7 +45,7 @@
                     (mapcar #'symbol-name (help-function-arglist symbol t))))
          (heading (cond ((fboundp symbol)
                          (format
-                          "%s =%s= (%s)" stars symbol
+                          "%s =%s= (%s)\n" stars symbol
                           (mapconcat (lambda (a)
                                        (format (if (string-prefix-p "&" a)
                                                    "/%s/" "=%s=") a))
@@ -91,7 +91,7 @@
                         (format "=%s=" name))))
                 body 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))