(doc): reflect that we now allow multiple refs (#1251)

doc/org-roam.org

@@ -432,29 +432,33 @@ accepts the absolute file path as its argument. See
 
 ** File Refs
 
-Refs are unique identifiers for files. Each note can only have 1 ref.
+Refs are unique identifiers for files. For example, a note for a website may contain a ref:
-For example, a note for a website may contain a ref:
 
 #+BEGIN_SRC org
   #+title: Google
   #+roam_key: https://www.google.com/
 #+END_SRC
 
-These keys come in useful for when taking website notes, using the
+These keys allow references to the key to show up in the backlinks buffer. For instance,
-~roam-ref~ protocol (see [[*Roam Protocol][Roam Protocol]]).
+with the example above, if another file then links to https://www.google.com, that will
+show up as a “Ref Backlink”.
 
-Alternatively, add a ref for notes for a specific paper, using its
+These keys also come in useful for when taking website notes, using the ~roam-ref~ protocol
-[[https://github.com/jkitchin/org-ref][org-ref]] citation key:
+ (see [[*Roam Protocol][Roam Protocol]]).
+
+[[https://github.com/jkitchin/org-ref][org-ref]] citation keys can also be used as refs:
 
 #+BEGIN_SRC org
   #+title: Neural Ordinary Differential Equations
   #+roam_key: cite:chen18_neural_ordin_differ_equat
 #+END_SRC
 
-The backlinks buffer will show any cites of this key: e.g.
-
 #+CAPTION: org-ref-citelink
 [[file:images/org-ref-citelink.png]]
+
+You may assign multiple refs to a single file, for example when you want multiple papers
+in a series to share the same note, or an article has a citation key and a URL at the same
+time.
 * The Templating System
 
 Rather than creating blank files on ~org-roam-insert~ and ~org-roam-find-file~,

doc/org-roam.texi

@@ -647,32 +647,36 @@ accepts the absolute file path as its argument. See
 @node File Refs
 @section File Refs
 
-Refs are unique identifiers for files. Each note can only have 1 ref.
+Refs are unique identifiers for files. For example, a note for a website may contain a ref:
-For example, a note for a website may contain a ref:
 
 @example
 #+title: Google
 #+roam_key: https://www.google.com/
 @end example
 
-These keys come in useful for when taking website notes, using the
+These keys allow references to the key to show up in the backlinks buffer. For instance,
-@code{roam-ref} protocol (see @ref{Roam Protocol}).
+with the example above, if another file then links to @uref{https://www.google.com}, that will
+show up as a “Ref Backlink”.
 
-Alternatively, add a ref for notes for a specific paper, using its
+These keys also come in useful for when taking website notes, using the @code{roam-ref} protocol
-@uref{https://github.com/jkitchin/org-ref, org-ref} citation key:
+ (see @ref{Roam Protocol}).
+
+@uref{https://github.com/jkitchin/org-ref, org-ref} citation keys can also be used as refs:
 
 @example
 #+title: Neural Ordinary Differential Equations
 #+roam_key: cite:chen18_neural_ordin_differ_equat
 @end example
 
-The backlinks buffer will show any cites of this key: e.g.
-
 @float Figure
 @image{images/org-ref-citelink,,,,png}
 @caption{org-ref-citelink}
 @end float
 
+You may assign multiple refs to a single file, for example when you want multiple papers
+in a series to share the same note, or an article has a citation key and a URL at the same
+time.
+
 @node The Templating System
 @chapter The Templating System