Metadata-Version: 2.1
Name: flm-citations
Version: 0.2.8
Summary: Support for citations in FLM (see flm-core package)
License: MIT
Author: Philippe Faist
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: PyYAML (>=6.0,<7.0)
Requires-Dist: arxiv (>=1.4.2,<2.0.0)
Requires-Dist: backoff (>=2.1.2,<3.0.0)
Requires-Dist: citeproc-py (>=0.6.0,<0.7.0)
Requires-Dist: flm-core (>=0.3.0a10)
Requires-Dist: requests (>=2.28.1,<3.0.0)
Description-Content-Type: text/markdown

# Extra citations support for FLM

See the [FLM README file](https://github.com/phfaist/flm/blob/main/README.md).

Install with:
```bash
$ pip install flm-citations
```

Use the additional config front matter in your FLM files to enable citations
with automatic citation retrieval from arXiv, DOI, etc.
```yaml
---
$import:
  -  pkg:flm_citations
bibliography:
  - my-csl-bibliography.yaml
---
```

Then process your file as usual with `flm`.

The bibliography file(s) you provide (in the example above,
`my-csl-bibliography.yaml`) should be in CSL JSON or CSL YAML
format.  They can easily be exported from Zotero, for example.

With the default configuration, the following citation keys are
processed:
- `\cite{arXiv:XXXX.YYYYY}` - fetch citation information from
  the [arXiv](https://arxiv.org/), and from its corresponding
  DOI if applicable.
- `\cite{doi:XXX}` - fetch citation information using its DOI
- `\cite{manual:{X et al., Journal of Future Results (2034)}}` -
  manual citation text
- `\cite{bib:BibKey2023}` - use a citation from any of your
  bibliography files specified in your document front matter.
  
### In case `citeproc` chokes on certain entries fetched by DOI

Sometimes automatically generated citeproc/JSON entries fetched
through various available online APIs (doi.org, crossref.org,
arXiv.org, etc.) might not be fully conforming or exactly
matching the structure expected by the
[`citeproc-py` citation formatting library](https://github.com/brechtm/citeproc-py)
that this project uses.  If you run against such issues, you
might consider installing a patched version of the library that
smoothed out some issues I had in the past; you can install it
with
```
> pip install git+https://github.com/phfaist/citeproc-py.git@pr-branch
```
until my [upstream PR](https://github.com/brechtm/citeproc-py/pull/132)
is considered.


### Metadata Fetching

Thank you to [arXiv](https://arxiv.org/) and
[doi.org](https://doi.org/) for use of their open access
interoperability.

