mirror of
https://github.com/retorquere/zotero-better-bibtex.git
synced 2022-05-23 09:36:29 +03:00
site cleanup
This commit is contained in:
Emiliano Heyns
@@ -32,7 +32,7 @@ have to if you use BibLaTeX, which has fairly good Unicode support). With BBT yo
|
||||
The plugin contains a comprehensive list of LaTeX constructs, so stuff like `\"{o}` or `\"o` will be converted to their unicode equivalents on import (e.g., `\"{o}` to `ö`). If you need
|
||||
literal LaTeX in your export: surround it with `<pre>`...`</pre>` tags.
|
||||
* Set your own, fixed [Citation Keys]({{< ref "/citing" >}}), generate citation keys from [JabRef patterns](https://help.jabref.org/en/BibtexKeyPatterns), drag and drop LaTeX citations, add other custom BibLaTeX fields.
|
||||
* Highly [Customized Exports]({{< ref "/customized-exports" >}}).
|
||||
* Highly [Customized Exports]({{< ref "/exporting" >}}).
|
||||
* Fixes date field exports: export dates like 'forthcoming' as 'forthcoming' instead of empty, but normalize valid dates
|
||||
to unambiguous international format.
|
||||
* [Auto Export]({{< ref "/exporting" >}}) of collections or entire libraries when they change.
|
||||
|
||||
@@ -1,84 +1,86 @@
|
||||
---
|
||||
title: "Push/Pull export"
|
||||
title: Exporting items
|
||||
menuTitle: Exporting
|
||||
weight: 2
|
||||
aliases:
|
||||
- /export
|
||||
- /Customized-Exports
|
||||
- /Push-and-Pull-Export
|
||||
- /pull-export
|
||||
- /push-and-pull
|
||||
tags:
|
||||
- export
|
||||
- overleaf
|
||||
- scripting
|
||||
aliases:
|
||||
- /customized-exports
|
||||
- /Customized-Exports
|
||||
- /Push-and-Pull-Export
|
||||
- /push-and-pull
|
||||
- /export
|
||||
---
|
||||
## Push Export / Auto-Export
|
||||
|
||||
When exporting using Better BibTex you will be offered a new export option: `Keep updated`. Checking this option
|
||||
registers the export for automation; any changes to the collection after you've completed the current export will
|
||||
trigger an automatic re-export to update the bib file. You can review/remove exports from the BBT preferences. While
|
||||
I've gone to some lengths to make sure performance is OK, don't go overboard with the number of auto-exports you have
|
||||
going. Also, exporting only targeted selections over your whole library will get you better performance. You can set up
|
||||
separate exports for separate papers for example if you have set up a collection for each.
|
||||
Better BibTex adds a couple of export formats to Zotero's export dialog and several ways to improve export for plaintext-based authoring.
|
||||
The Better BibTeX [configuration]({{< ref "installation/preferences" >}}) pane can be found under the regular Zotero preferences pane, tab 'Better BibTeX' where you can tweak the exports, such as
|
||||
|
||||
**Both push and pull export really only support local access, that is, the Zotero client must be running on the same system where you compile your LaTeX document.**
|
||||
* [Omitting fields from exports]({{< ref "installation/preferences/export#fields-to-omit-from-export-comma-separated" >}}) to slim down your bib files.
|
||||
* Configuring how [citation keys are generated]({{< ref "citing" >}}).
|
||||
* And really a [ton more]({{< ref "installation/preferences" >}}).
|
||||
|
||||
That said, there are a few ways to get your BBT-generated bib files to other places. If you're thinking of this in the context of Overleaf, here's a TL;DR of the pros and cons:
|
||||
Additionally you can automate exporting (parts of) your library either using [auto-export]({{< ref "auto" >}}) or [pull export]({{< ref "pull" >}}).
|
||||
|
||||
* Auto-export + cloud-sync
|
||||
* pro: gets the full bibtex file to Overleaf, should be seamless
|
||||
* con: have not tested, paid option on overleaf
|
||||
* Auto-export + `git`:
|
||||
* pro: gets the full bibtex file to Overleaf, tested and works
|
||||
* con: requires technical expertise to set up, paid option on overleaf
|
||||
* citekey pinning:
|
||||
* pro: no setup
|
||||
* con: only gets the BBT citekeys, BibTeX is generated by Zotero itself
|
||||
## Pinning (fixating) the citation key
|
||||
|
||||
### DropBox / Google Drive / Box.com / ...
|
||||
By default, BBT will generate citation keys from your items using the [formatting pattern]({{< ref "citing" >}}) you specified. If you want the key to be stable even when you change the item,
|
||||
you can fixate its citation key to a value of your choosing by adding the text `Citation Key: [your citekey]` anywhere in the `extra` field of the item.
|
||||
|
||||
Or any other of the plethora of choices that are available today that will "cloud-sync" your files. Just auto-export your bib file to a cloud-synced folder, and Bob's your uncle. Incidentally, this should work with Overleaf, but I have not tested it personally, as I use...
|
||||
## Add your own BibLaTeX fields
|
||||
|
||||
### git support
|
||||
You can add your own fields to the export which are not derived from regular Zotero item fields by adding them in the `extra` field in Zotero in one of three ways:
|
||||
|
||||
BBT auto-export works nicely with git services (such as Overleaf, which is where I use it myself; the instructions for setting up Overleaf for git can be found [here](https://www.overleaf.com/blog/195-new-collaborate-online-and-offline-with-overleaf-and-git-beta) -- note these instructions are for Overleaf V1 projects, not V2 projects, which will get git support only late 2018), but any git service (gitlab, github, etc) should work exactly the same. I'm toying with various online services [here](https://github.com/retorquere/zotero-better-bibtex/projects/2).
|
||||
### Square brackets []
|
||||
|
||||
**Note that this is more for the technically inclined,** you will need to be comfortable with the command line to set this up. I can't think of a real benefit to using git over cloud-sync unless, like me, you like to keep a backup history in git.
|
||||
|
||||
To activate git support, first clone the repo that holds your article/thesis/whatnot from your provider (github, overleaf, etc), run `git config zotero.betterbibtex.push true` in a command shell in that clone, and set up an auto export to that directory; at each update, BBT will now also push your library to the git service. For the technically curious, that means it does:
|
||||
|
||||
1. `git pull`
|
||||
2. Performs the export
|
||||
3. `git add <your library file>`
|
||||
4. `git commit -m <your library file>`
|
||||
5. `git push`
|
||||
|
||||
Note that the nature of git commit/push is not file-bound; if you made edits to other files, and added those, they will be committed and pushed along. If you want to be super-careful, the best way to go about it is to have a separate clone of your repo that BBT auto-exports to, and then another repo that you do your own edits in. I don't use it myself this way, but you have been warned.
|
||||
|
||||
### Pull Export
|
||||
|
||||
**This will *only* work if you are compiling your document on the same system your Zotero client with BBT runs on**. *Technically* it can be made to work for pulling from other systems, but it's even more arcane to set up than git.
|
||||
|
||||
You can fetch your library as part of your build, using something like `curl`, or with a BibLaTeX remote statement like
|
||||
You can add any field you like by using something like
|
||||
|
||||
```
|
||||
\addbibresource[location=remote]{http://127.0.0.1:23119/better-bibtex/collection?/0/8CV58ZVD.biblatex}
|
||||
bibtex[origdate=1856;origtitle=An Old Title]
|
||||
```
|
||||
|
||||
You can fetch your bibliography on the url http://127.0.0.1:23119/better-bibtex/collection?`[collectionID]`.`[format]`, where collectionID is:
|
||||
This format is very rigid, it has no quoting syntax, so you can't have `=`, `[`, `]` or `;` in your key names or values.
|
||||
|
||||
* the ID you get by right-clicking your collection and selecting "Show collection key"
|
||||
* the path "/[library id]/full/path/to/collection" (the library id is the first number from the key you get in the
|
||||
option above; it's always '0' for your personal library)
|
||||
### JSON5
|
||||
|
||||
or any multiple of those, separated by a '+' sign.
|
||||
If you need more flexibility, you can use the [JSON5](http://json5.org/) format
|
||||
instead:
|
||||
|
||||
The format is either 'bibtex' or 'biblatex', and determines the translator used for export.
|
||||
```
|
||||
bibtex{
|
||||
origdate: 1856,
|
||||
origtitle: "Can contain = and ';' just fine"
|
||||
}
|
||||
```
|
||||
|
||||
You can add options to the export as URL parameters:
|
||||
The marker for these fields can be either `bibtex`, `biblatex` or `biblatexdata` (which are all the same to BBT), but when importing BibTeX files with
|
||||
fields not supported by Zotero, the `bibtex` marker will be used. These fields are assumed to be valid LaTeX, and will
|
||||
be exported exactly as entered.
|
||||
|
||||
* `&exportNotes=[true|false]`
|
||||
* `&useJournalAbbreviation=[true|false]`
|
||||
If you want to have regular text in these fields and have BBT LaTeX-encode them, add an asterisk (`*`) after the marker, so
|
||||
something like
|
||||
|
||||
### Pinning BBT citekeys for Overleaf
|
||||
```
|
||||
bibtex*{
|
||||
origdate: 1856,
|
||||
origtitle: "Things like _ and $ will be escaped"
|
||||
}
|
||||
```
|
||||
|
||||
If you only want BBTs citation keys on Overleaf, you can simply pin them and use the regular Overleaf-Zotero integration. This will get you the pinned keys, but the bibtex is generated by the standard Zotero exporters.
|
||||
### CSL fields
|
||||
|
||||
The final way to add fields is by using CSL fields in the format `{:original-date: 1856}` or `Original Date: 1856` on a line of its own. These fields will not only be
|
||||
exported to Bib(La)TeX, but will also be [picked up](https://forums.zotero.org/discussion/3673/original-date-of-publication/) by the Zotero Bibliography manager, even
|
||||
though not all Zotero styles yet support this.
|
||||
|
||||
Note that the default biblatex styles do not seem to support origdate; you can find possible solutions for this at Stack
|
||||
Exchange
|
||||
[here](http://tex.stackexchange.com/questions/142999/the-proper-way-to-cite-the-earliest-publication-date-in-brackets-followed-by)
|
||||
and
|
||||
[here](http://tex.stackexchange.com/questions/55859/getting-origyear-to-work-in-biblatex).
|
||||
|
||||
### Changing the exported reference type
|
||||
|
||||
If you add a field called `referencetype` using either one of these methods, that value will be used as the reference type
|
||||
instead of the one usually inferred from the Zotero reference type. You can use this to create, for example,
|
||||
`@customa{citekeyhere, ....}` type references.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Advanced
|
||||
weight: 5
|
||||
weight: 7
|
||||
aliases:
|
||||
- /hardcore
|
||||
- /Going-hardcore
|
||||
@@ -9,13 +9,12 @@ aliases:
|
||||
|
||||
If you'd really just rather hand-code your LaTeX constructs, BBT makes that possible:
|
||||
|
||||
* You can add literal LaTeX anywhere in your reference by surrounding it with `<pre>....</pre>` tags. BBT will
|
||||
* You can add literal LaTeX anywhere in your reference by surrounding it with `<pre>...</pre>` (or `<script>...</script>`) tags. BBT will
|
||||
convert to/from unicode and (un)escape where required but will pass whatever is enclosed in the pre tags unchanged.
|
||||
* An entry tagged with `#LaTeX` (case-sensitive!) will have all fields exported as if they're wrapped in
|
||||
`<pre>...</pre>`, so you can include LaTeX markup in your references. <!-- If you enable "Raw BibTeX import" in the preferences, BibTeX imports will not be
|
||||
escaped on import, and will automatically be tagged for raw export. -->
|
||||
|
||||
## Gotchas
|
||||
`<pre>...</pre>`, so you can include LaTeX markup in your references.
|
||||
|
||||
## Recognizing initials in names
|
||||
|
||||
* In names, you can force first names like `Philippe` to be exported to `{\relax Ph}ilippe` (which causes it to get
|
||||
initial `Ph.` rather than `P.` in styles that do initials) by adding a [end of guarded area](http://www.fileformat.info/info/unicode/char/0097/index.htm) character between `Ph` and `ilippe`.
|
||||
|
||||
54
site/content/exporting/auto.md
Normal file
54
site/content/exporting/auto.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: "Automatic export"
|
||||
weight: 4
|
||||
tags:
|
||||
- export
|
||||
- automatic export
|
||||
- overleaf
|
||||
- git
|
||||
---
|
||||
|
||||
When exporting using BBT you will be offered a new export option: `Keep updated`. Checking this option
|
||||
registers the export for automation; any changes to the collection or library you exported after you've completed the current export will
|
||||
trigger an automatic re-export to update the bib file. You can review/remove exports from the BBT preferences. While
|
||||
I've gone to some lengths to make sure performance is OK, don't go overboard with the number of auto-exports you have
|
||||
going. Also, exporting only targeted selections over your whole library will get you better performance. You can set up
|
||||
separate exports for separate papers for example if you have set up a collection for each.
|
||||
|
||||
## Getting your BBT-generated bib(la)tex/citekeys to other places
|
||||
|
||||
You may want to use your BBT generated bib(la)tex on other systems; maybe you use Overleaf (as I do), maybe you have your documents compiled using Travis (as I do). In any case, you want your auto-exported items to show up somewhere else. If you're thinking of this in the context of Overleaf, here's a TL;DR of the pros and cons:
|
||||
|
||||
* Auto-export + cloud-sync
|
||||
* pro: gets the full bibtex file to Overleaf, should be seamless
|
||||
* con: have not tested, paid option on overleaf
|
||||
* Auto-export + `git`:
|
||||
* pro: gets the full bibtex file to Overleaf, tested and works
|
||||
* con: requires technical expertise to set up, paid option on overleaf
|
||||
* citekey pinning:
|
||||
* pro: no setup
|
||||
* con: only gets the BBT citekeys, BibTeX is generated by Zotero itself
|
||||
|
||||
### DropBox / Google Drive / Box.com / ...
|
||||
|
||||
Or any other of the plethora of choices that are available today that will "cloud-sync" your files. Just auto-export your bib file to a cloud-synced folder, and Bob's your uncle. Incidentally, this should work with Overleaf, but I have not tested it personally, as I use...
|
||||
|
||||
### git support
|
||||
|
||||
BBT auto-export works nicely with git services (such as Overleaf, which is where I use it myself; the instructions for setting up Overleaf for git can be found [here](https://www.overleaf.com/blog/195-new-collaborate-online-and-offline-with-overleaf-and-git-beta) -- note these instructions are for Overleaf V1 projects, not V2 projects, which will get git support only late 2018), but any git service (gitlab, github, etc) should work exactly the same. I'm toying with various online services [here](https://github.com/retorquere/zotero-better-bibtex/projects/2).
|
||||
|
||||
**Note that this is more for the technically inclined,** you will need to be comfortable with the command line to set this up. I can't think of a real benefit to using git over cloud-sync unless, like me, you like to keep a backup history in git.
|
||||
|
||||
To activate git support, first clone the repo that holds your article/thesis/whatnot from your provider (github, overleaf, etc), run `git config zotero.betterbibtex.push true` in a command shell in that clone, and set up an auto export to that directory; at each update, BBT will now also push your library to the git service. For the technically curious, that means it does:
|
||||
|
||||
1. `git pull`
|
||||
2. Performs the export
|
||||
3. `git add <your library file>`
|
||||
4. `git commit -m <your library file>`
|
||||
5. `git push`
|
||||
|
||||
Note that the nature of git commit/push is not file-bound; if you made edits to other files, and added those, they will be committed and pushed along. If you want to be super-careful, the best way to go about it is to have a separate clone of your repo that BBT auto-exports to, and then another repo that you do your own edits in. I don't use it myself this way, but you have been warned.
|
||||
|
||||
### Pinning BBT citekeys for Overleaf
|
||||
|
||||
If you only want BBTs citation keys on Overleaf, you can simply pin them and use the regular Overleaf-Zotero integration. This will get you the pinned keys, but the bibtex is generated by the standard Zotero exporters.
|
||||
@@ -1,97 +0,0 @@
|
||||
---
|
||||
title: Customized exports
|
||||
weight: 3
|
||||
tags:
|
||||
- export
|
||||
- scripting
|
||||
aliases:
|
||||
- /customized-exports
|
||||
---
|
||||
|
||||
Better BibTex adds a couple of export formats to Zotero's export dialog. The Better BibTeX configuration pane can be found under the regular Zotero preferences pane, tab 'Better BibTeX'.
|
||||
Through the configuration pane of BBT you can customize the BibTeX file that will be exported:
|
||||
|
||||
* **Automated background exports**. Tick 'keep updated' during export, and that's that.
|
||||
* **Unicode conversion**: the default is to retain unicode characters on export for BibLaTeX, and to convert to LaTeX
|
||||
commands (where possible) for BibTeX. You can specify whether you want to retain this default, or whether you want BBT
|
||||
to always export translating to LaTeX commands, or never to do this translation.
|
||||
* **Recursive collection export**: when exporting a collection, recursive export will include all child collections.
|
||||
Note that this also sets Zotero to display collection contents recursively.
|
||||
* **Omit fields from export**: Should you so wish, you can prevent fields of your choosing from being exported. In the
|
||||
configuration screen, add a comma-separated list of BibTeX fields you do not want to see in your export. The fields
|
||||
are case-sensitive, separated by a comma *only*, no spaces.
|
||||
* **[Configurable citekey generator]({{< ref "citing" >}})**
|
||||
* **[Push-and-Pull-Export]({{< ref "exporting" >}})**: You can fetch your library as part of your build, using something like `curl`, or with a BiblaTeX remote statement like `\addbibresource[location=remote]{http://localhost:23119/better-bibtex/collection?/0/8CV58ZVD.biblatex}`.
|
||||
* Add other custom BibLaTeX fields
|
||||
|
||||
BBT http export uses the general Zotero HTTP facility; please note that disabling this will disable ALL HTTP
|
||||
facilities in Zotero -- including the non-Firefox plugins provided by Zotero.
|
||||
|
||||
## Add your own BibLaTeX fields
|
||||
|
||||
There are three alternative methods:
|
||||
|
||||
### Square brackets []
|
||||
|
||||
You can add any field you like by using something like
|
||||
|
||||
```
|
||||
bibtex[origdate=1856;origtitle=An Old Title]
|
||||
```
|
||||
|
||||
in the `extra` field of your reference. This format is very rigid, it has no quoting syntax, so you can't have `=`, `[`,
|
||||
`]` or `;` in your key names or values.
|
||||
|
||||
### JSON5
|
||||
|
||||
If you need more flexibility, you can use the [JSON5](http://json5.org/) format
|
||||
instead:
|
||||
|
||||
```
|
||||
bibtex{
|
||||
origdate: 1856,
|
||||
origtitle: "Can contain = and ';' just fine"
|
||||
}
|
||||
```
|
||||
|
||||
The marker for these fields can be either `bibtex`, `biblatex` or `biblatexdata`, but when importing BibTeX files with
|
||||
fields not supported by Zotero, the `bibtex` marker will be used. These fields are assumed to be valid LaTeX, and will
|
||||
be exported exactly as entered.
|
||||
|
||||
If you want to have them LaTeX encoded, add an asterisk (`*`) after the marker, so
|
||||
something like
|
||||
|
||||
```
|
||||
bibtex*{
|
||||
origdate: 1856,
|
||||
origtitle: "Things like _ and $ will be escaped"
|
||||
}
|
||||
```
|
||||
|
||||
### CSL fields
|
||||
|
||||
The final way to add fields is by using CSL fields in the format `{:original-date: 1856}`. These fields will not only be
|
||||
exported to Bib(La)TeX, but will also be [picked up](https://forums.zotero.org/discussion/3673/original-date-of-publication/) by the Zotero Bibliography manager, even
|
||||
though not all Zotero styles yet support this.
|
||||
|
||||
### Common notes
|
||||
|
||||
If you add a field called `referencetype` using either of these methods, that value will be used as the reference type
|
||||
instead of the one usually inferred from the Zotero reference type. You can use this to create, for example,
|
||||
`@customa{citekeyhere, ....}` type references.
|
||||
|
||||
You can fix the citation key for a reference to a value of your choosing by adding the text `bibtex: [your citekey]`
|
||||
anywhere in the "extra" field of the reference.
|
||||
|
||||
Note that the default biblatex styles do not seem to support origdate; you can find possible solutions for this at Stack
|
||||
Exchange
|
||||
[here](http://tex.stackexchange.com/questions/142999/the-proper-way-to-cite-the-earliest-publication-date-in-brackets-followed-by)
|
||||
and
|
||||
[here](http://tex.stackexchange.com/questions/55859/getting-origyear-to-work-in-biblatex).
|
||||
|
||||
## You wanted customized...
|
||||
|
||||
You got customized. If you go into the Advanced preferences of BBT, find an edit field labeled `Postscript`, empty by default. In this, you can paste a JavaScript snippet which will be executed for each reference
|
||||
generated in the Bib(La)TeX exporter. In this code, you have access to the reference just before it will be written out
|
||||
and cached. Examples and the documentation-in-progress for the script environment can be found
|
||||
[here]({{< ref "scripting" >}}); feel free to add your own examples.
|
||||
35
site/content/exporting/pull.md
Normal file
35
site/content/exporting/pull.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: "Pull export"
|
||||
weight: 5
|
||||
aliases:
|
||||
- /pull-export
|
||||
tags:
|
||||
- export
|
||||
---
|
||||
|
||||
You can fetch your bibliography on the url http://127.0.0.1:23119/better-bibtex/collection?`[collectionID]`.`[format]`, where collectionID is:
|
||||
|
||||
* the ID you get by right-clicking your collection and selecting "Show collection key"
|
||||
* the path "/[library id]/full/path/to/collection" (the library id is the first number from the key you get in the
|
||||
option above; it's always '0' for your personal library)
|
||||
|
||||
or any multiple of those, separated by a '+' sign.
|
||||
|
||||
The format is either 'bibtex' or 'biblatex', and determines the translator used for export.
|
||||
|
||||
You can add options to the export as URL parameters:
|
||||
|
||||
* `&exportNotes=[true|false]`
|
||||
* `&useJournalAbbreviation=[true|false]`
|
||||
|
||||
You can fetch your library as part of your build, using something like `curl` from your Makefile, or with a BibLaTeX remote statement like
|
||||
|
||||
```
|
||||
\addbibresource[location=remote]{http://127.0.0.1:23119/better-bibtex/collection?/0/8CV58ZVD.biblatex}
|
||||
```
|
||||
|
||||
**Pull export will *only* work if you are compiling your document on the
|
||||
same system your Zotero client with BBT runs on**. *Technically*
|
||||
it can be made to work for pulling from other systems, but it's
|
||||
even more arcane to set up than [git support]({{< ref "auto#git-support" >}}).
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Scripting
|
||||
weight: 4
|
||||
weight: 6
|
||||
tags:
|
||||
- scripting
|
||||
aliases:
|
||||
|
||||
@@ -1,6 +0,0 @@
|
||||
DirectoryPath: public
|
||||
EnforceHTTPS: false
|
||||
CacheExpires: "6h"
|
||||
CheckExternal: false
|
||||
IgnoreDirectoryMissingTrailingSlash: true
|
||||
IgnoreInternalEmptyHash: true
|
||||
@@ -1,4 +1,4 @@
|
||||
DirectoryPath: "public"
|
||||
DirectoryPath: public
|
||||
EnforceHTTPS: false
|
||||
CacheExpires: "6h"
|
||||
CheckExternal: false
|
||||
|
||||
Reference in New Issue
Block a user