Forget about bibliography management with pure NASA ADS keys!
This drop-in Perl script uses citation keys from the NASA astronomy data service (ADS) so that you can forget about your bibliography management. For citation commands in your document that use ADS keys, such as \cite{1958ZA.....46..108B}, the script automatically fetches and caches the corresponding bibliography entries in a managed bibliography file, normally with extension .adskeys.bib. It also keeps a generated .map sidecar with cached ADS key checks and canonicalization results.
Citations with keys that are not present in the ADS database can be added by providing one or more additional bibliography files, as in \bibliography{paper.adskeys,custom}.
The script is intended for integration with Latexmk, which automates the build process for LaTeX documents.
-
Copy
managed-bibliography.plinto your document directory. Then copy thelatexmkrcfile as well, or merge its content with your existinglatexmkrcfile. For example, run the following command in your document directory:URL="https://github.com/svaberg/managed-bibliography/raw/main/" curl --location --remote-name-all --no-clobber \ "${URL}managed-bibliography.pl" "${URL}latexmkrc"
If you have your own
latexmkrcfile, be sure to include therequire './ managed-bibliography .pl'line. -
Add the managed bibliography file to your
\bibliography{...}command. By default, a documentpaper.texusespaper.adskeys.bib, so a typical setup looks like\bibliography{paper.adskeys,custom}. If you set$managed_bib_fileto another filename, use that basename instead. -
Provide an ADS API token through
ADS_API_TOKEN,ADS_DEV_KEY,$HOME/.ads/token, or$HOME/.ads/dev_key. We recommend not putting tokens directly in a committedlatexmkrc; it is a security risk.
The script uses HTTP::Tiny and JSON::PP. Perl 5.14 or later is a sensible baseline. Then build as usual with latexmk. On the first run the managed bibliography file and its .map sidecar are created automatically.
During a build, the script reads the .aux file to discover which bibliography files are in use and which citation keys were requested. It compares those keys with the managed bibliography file and any user-supplied .bib files already listed in \bibliography{...}.
Keys that are still unresolved are sent to ADS. The script first asks ADS to canonicalize identifiers, then exports the matching BibTeX entries in bulk, rewrites the exported entry keys back to the keys cited in the document, and stores the results in the managed bibliography file. The generated .map sidecar stores cached ADS key checks and canonicalization results so that duplicate warnings and ADS-valid user-bibliography keys can be reported again on later runs without re-querying ADS.
If two cited keys resolve to the same ADS entry, or if a cited key resolves to a canonical ADS key that already exists in another bibliography file, the script reports that. The latexmkrc setting $allow_duplicates controls whether those cases are allowed with a warning or stop the build.
If ADS does not return an entry, the key is left unresolved and LaTeX/BibTeX behaves as it normally would for a missing citation.
By default, latexmk -C also removes the managed bibliography file and its .map sidecar. The next build then performs a fresh ADS lookup, which can refresh stale cached entries.
To build manbib.tex with Latexmk, run:
latexmk -lualatex -bibtex manbib.texThis creates manbib.pdf together with the managed bibliography file manbib.adskeys.bib and the sidecar cache manbib.adskeys.map. To clean up the generated files, run:
latexmk -C manbib.texIf ADS lookups abort immediately with a message about missing Perl HTTPS support, latexmk is probably running under a Perl that does not have the required SSL modules. This often happens when perl on your PATH comes from Conda.
The script uses HTTP::Tiny for ADS requests, and HTTPS support requires the Perl modules IO::Socket::SSL and Net::SSLeay. If those modules are missing, manbib aborts ADS work for that run and reports the active Perl runtime.
If this happens, check which perl in the same shell that runs latexmk. The important point is not which Perl you use, but that the active Perl runtime must have HTTPS support available to HTTP::Tiny.
As a quick test, and often as a practical workaround on macOS, run Latexmk explicitly under the system Perl:
/usr/bin/perl /Library/TeX/texbin/latexmk -lualatex -bibtex manbib.texIf that works while a plain latexmk -lualatex -bibtex manbib.tex does not, the problem is almost certainly that your normal shell environment is selecting a different Perl. In that case, either install the required Perl SSL modules in that Perl environment or continue invoking Latexmk explicitly with a Perl that already has HTTPS support.