update packages

lisp/org-ref/org-ref.org

@@ -83,7 +83,7 @@ index:cite
 
 org-ref uses the [[bibliography link]] to determine which bibtex files to get citations from, and falls back to the bibtex files defined in the variable ~reftex-default-bibliography~ or ~org-ref-default-bibliography~ if no bibliography link is found. Note that you *must* include a [[bibliography link]] in your document if you are exporting your document to pdf; ~org-ref-default-bibliography~ is not used by the [[BibTeX users][LaTeX exporter]].
 
-For simple citation needs, org-ref is simple to use. At the point you want to insert a citation, you select the "Org -> org-ref -> Insert citation" menu (or use the key-binding ~C-c ]~ by default), select the reference(s) you want in the helm-bibtex buffer and press enter. The citation will be inserted automatically into your org-file. You "select" an entry by using the arrow keys (or ~C-n~ and ~C-p~) to move up and down to the entry you want. You can also narrow the selection by typing a pattern to match, e.g. author name, title words, year, BibTeX key and entry types. For any other field (e.g. keywords), you will need to add it to the variable ~bibtex-completion-additional-search-fields~. You can select multiple entries by pressing ~C-SPC~ to mark entries in the helm-bibtex buffer.
+For simple citation needs, org-ref is simple to use. At the point you want to insert a citation, you select the "Org -> org-ref -> Insert citation" menu (or use the key-binding ~C-c ]~ by default), select the reference(s) you want in the helm-bibtex buffer and press enter. The citation will be inserted automatically into your org-file. You "select" an entry by using the arrow keys (or ~C-n~ and ~C-p~) to move up and down to the entry you want. You can also narrow the selection by typing a pattern to match, e.g. author name, title words, year, BibTeX key and entry types. If you want to match any other field, you need to add it to the variable ~bibtex-completion-additional-search-fields~; org-ref [[id:5d7a19d3-0411-4964-9154-99af4f281015][does this automatically]] for the ~keywords~ field. You can select multiple entries by pressing ~C-SPC~ to mark entries in the helm-bibtex buffer.
 
 If the cursor is on a citation key, you should see a message in the minibuffer that summarizes which citation it refers to. If you click on a key, you should see a helm selection buffer with some actions to choose, including opening the bibtex entry, opening/getting a pdf for the entry, searching the entry in Web of Science, etc...
 
@@ -262,12 +262,19 @@ Org-ref can also be configured to show bad label,ref and cite links by setting t
 This may be slow in large files, so you can turn it off by setting that variable to nil.
 
 ** org-ref customization of helm-bibtex
+:PROPERTIES:
+:ID:       5d7a19d3-0411-4964-9154-99af4f281015
+:END:
 index:helm-bibtex
 
-org-ref adds a few new features to helm-bibtex. First, we add keywords as a searchable field. Second, org-ref modifies the helm-bibtex search buffer to include the keywords. Since keywords now can have a central role in searching, we add some functionality to add keywords from the helm-bibtex buffer as a new action.
+org-ref adds a few new features to helm-bibtex.
+
+First, we add =keywords= as a searchable field, and modify the helm-bibtex search buffer to include the keywords. Since keywords now can have a central role in searching, we add some functionality to add keywords from the helm-bibtex buffer as a new action.
 
 We change the order of the actions in helm-bibtex to suit our work flow, and add some new actions as well. We define a format function for org-mode that is compatible with the usage defined in section [[#citations]]. Finally, we add some new fallback options for additional scientific search engines.
 
+The =keywords= field is added onto the existing value, such that existing customization wouldn’t be lost; if you still prefer to add the field yourself, set ~org-ref-bibtex-completion-add-keywords-field~ to nil before loading org-ref.
+
 ** Some basic org-ref utilities
 [[index:bibtex!clean entry]]
 
@@ -862,7 +869,7 @@ You will have to incorporate running makeindex into your PDF build command.
 
 This is not supported in anything but LaTeX export.
 
-*** Glossaries
+*** Glossaries and acronyms
 index:glossary
 
 org-ref provides some support for glossary and acronym definitions.
@@ -874,7 +881,11 @@ org-ref provides some support for glossary and acronym definitions.
 - glssymbol :: The symbol term
 - glsdesc :: The description of the term
 
-- acrshort :: Short version of the acroynm
+- ac :: a reference to an acronym
+- Ac :: capitalized reference to an acronym
+- acp :: a plural reference to an acronym
+- Acp :: capitalized plural reference to an acronym
+- acrshort :: Short version of the acronym
 - acrfull :: The full definition of the acronym
 - acrlong :: The full definition of the acronym with (abbrv).
 
@@ -893,15 +904,53 @@ Here is a minimal working example of an org file that makes a glossary.
 #+latex_header: \makeglossaries
 
 #+latex_header_extra: \newglossaryentry{computer}{name=computer,description={A machine}}
+#+latex_header_extra: \newacronym{tla}{TLA}{Three letter acronym}
 
-
-A gls:computer is good for computing. Gls:computer is capitalized. We can also use a bunch of glspl:computer to make a cluster. Glspl:computer are the wave of the future.
+A gls:computer is good for computing. Gls:computer is capitalized. We can also use a bunch of glspl:computer to make a cluster. Glspl:computer are the wave of the future. Don't forget what a ac:TLA is.
 
 \printglossaries
 #+END_EXAMPLE
 
 This is not supported in anything but LaTeX export.
 
+If you have a lot of glossary entries and you want to have them in an external file, you can put them in a tex file, and then include them in the org file like this. Here the glossary entries are saved in a file in the same directory as glossary.tex. This should still work with the tooltips.
+
+#+BEGIN_EXAMPLE
+#+latex_header: \loadglsentries[main]{glossary}
+#+END_EXAMPLE
+
+Finally, you can define the glossary entries in org tables like this. They will be deleted before a LaTeX export.
+
+#+BEGIN_EXAMPLE
+,#+title: Test
+,#+latex_header: \usepackage{glossaries}
+,#+latex_header: \makeglossaries
+
+
+# This will not show in your export. It must be named glossary
+,#+name: glossary
+| label | name  | description   |
+|-------+-------+---------------|
+| tree  | Tree  | A woody plant |
+| shrub | Shrub | A woody bush  |
+
+Checkout how a gls:tree differs from a gls:shrub.
+
+
+,#+name: acronyms
+| Key  | Short | Long                           |
+|------+-------+--------------------------------|
+| mimo |       | multiple-input multiple output |
+| qos  | QoS   | quality-of-service             |
+| bb   | BB    | branch and bound               |
+
+
+First ac:bb. Second ac:bb. First ac:qos. Second ac:qos.
+
+# This is where your glossary and acronym entries will be put.
+,#+latex: \printglossaries
+#+END_EXAMPLE
+
 \glsaddall
 \printglossaries