{"id":13870080,"url":"https://github.com/dgerosa/filltex","last_synced_at":"2025-12-30T00:54:54.073Z","repository":{"id":13081711,"uuid":"73505895","full_name":"dgerosa/filltex","owner":"dgerosa","description":"Automatic queries to ADS and INSPIRE databases to fill LaTex bibliography","archived":false,"fork":false,"pushed_at":"2024-08-21T17:40:38.000Z","size":156,"stargazers_count":21,"open_issues_count":6,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-31T11:04:25.792Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://davidegerosa.com/filltex","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dgerosa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-11T19:35:48.000Z","updated_at":"2024-05-01T11:48:19.000Z","dependencies_parsed_at":"2024-06-14T10:06:37.972Z","dependency_job_id":null,"html_url":"https://github.com/dgerosa/filltex","commit_stats":{"total_commits":147,"total_committers":9,"mean_commits":"16.333333333333332","dds":0.3605442176870748,"last_synced_commit":"82a299642fb19a5618d27512ee63ee63e39ee99e"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgerosa%2Ffilltex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgerosa%2Ffilltex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgerosa%2Ffilltex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgerosa%2Ffilltex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dgerosa","download_url":"https://codeload.github.com/dgerosa/filltex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226068184,"owners_count":17568709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-05T20:01:27.914Z","updated_at":"2025-12-30T00:54:54.067Z","avatar_url":"https://github.com/dgerosa.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# filltex\r\n\r\n#### Automatic queries to ADS and INSPIRE databases to fill LaTex bibliography\r\n\r\n`filltex` is a simple tool to fill LaTex reference lists with records from the [ADS](http://adsabs.harvard.edu) and [INSPIRE](http://inspirehep.net)  databases. [ADS](http://adsabs.harvard.edu) and [INSPIRE](http://inspirehep.net) are the most common databases used among the astronomy and theoretical physics scientific communities, respectively. `filltex` automatically looks for all citation labels present in a tex document and, by means of web-scraping, downloads  all the required citation records from either of the two databases. `filltex` significantly speeds up the LaTex scientific writing workflow, as all required actions (compile the tex file, fill the bibliography, compile the bibliography, compile the tex file again) are automated in a single command. We also provide an integration of `filltex` for the macos LaTex editor [TexShop](http://pages.uoregon.edu/koch/texshop).\r\n\r\nIf you use `filltex` for your research, please drop a citation to [this paper](http://joss.theoj.org/papers/10.21105/joss.00222):\r\n\r\n- *filltex: Automatic queries to ADS and INSPIRE databases to fill LaTex bibliography*,\r\nDavide Gerosa, Michele Vallisneri, The Journal of Open Source Software 2 (2017) 13.\r\n\r\nOf course, you can use `filltex` to cite `filltex`! Just put `\\cite{2017JOSS....2..222G}` in your tex file!\r\n\r\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.596848.svg)](https://doi.org/10.5281/zenodo.596848)\r\n\r\n\r\n## Installation\r\n\r\n`filltex` can be installed from the python package index [Pypi](https://pypi.python.org/pypi):\r\n    \r\n    pip install filltex\r\n\r\nIf you're a [TexShop](http://pages.uoregon.edu/koch/texshop) user and want to use this feature, run\r\n\r\n    filltex install-texshop\r\n\r\n\u003c!-- The script requires the program `realpath`. This should be there by default on most linux distributions. On mac, you can get if from [Homebrew](http://brew.sh/)--\u003e\r\n\u003c!--   brew install coreutils --\u003e\r\n\r\nIf you want to give it a try, you can run it on the `example.tex` file provided in this repository:\r\n\r\n    git clone https://github.com/dgerosa/filltex.git\r\n    cd filltex/example\r\n    filltex example\r\n\r\nand you should get a filled `.bib` file and a finished `.pdf`.\r\n\r\n## What's about?\r\n\r\nWhat happens when you compile a LaTex file? How's bibliography handled?\r\n\r\n  1. Run `pdflatex` and all requested citation keys are dumped into a `.aux` file.\r\n  2. You **should** have the required entries in you `.bib` file.\r\n  3. Run `bibtex`, which looks for citations inside the `.bib` file and writes the results into a `.bbl`.\r\n  4. Run `pdflatex` again, which processes the `.bbl` into the compiled paper, and dumps the citation records into `.aux`.\r\n  5. Finally run `pdflatex` again, which puts the correct citation records into the paper.\r\n\r\nThe commands you need to run are: `pdflatex`, `bibtex`, `pdflatex`, `pdflatex`. These, of course can be put into a script or a makefile and done in one goal.\r\n`filltex` is meant to automatically solve the second point as well: look for citations on [ADS](http://adsabs.harvard.edu), [INSPIRE](http://inspirehep.net) or both.\r\n\r\nSo, here is the deal:\r\n\r\n  - The `fillbib` python script queries both databases and creates/updates a `.bib` file without getting each record manually.\r\n  - The `filltex` bash script puts everything together to go from a `.tex` (and no `.bib`) into a `.pdf`.\r\n  - I also provide [TexShop](http://pages.uoregon.edu/koch/texshop) engines for mac users\r\n\r\nOf course, all of this works if your citations are specified in the [ADS](http://adsabs.harvard.edu) or [INSPIRE](http://inspirehep.net) format, e.g. `\\cite{2016PhRvL.116f1102A}`, `\\cite{Abbott:2016blz}`. If you use your personal keys `\\cite{amazing_paper}`there's no way to get them from a database.\r\n\r\n## Usage\r\n\r\n### fillbib (script)\r\n\r\n***`fillbib`*** has two working modes. It can either look for citations into a `.aux` file and create/update a bibtex file with the records found on ADS and INSPIRE, or it can fetch a list of bibtex entries specified from the command line from ADS or INSPIRE.\r\n\r\nThe first argument specifies the subcommand to run.\r\n\r\n* `tex` will produce a bibtex file given an `.aux` file\r\n* `list` will print a bibtex file given a list of keys from CLI\r\n\r\nThe help for the two subcommands can be obtained with\r\n\r\n    fillbib.py {tex,list} --help\r\n\r\nWhen working in `tex` mode it is possible to specify the name of the bibtex file using the option `--bibtex`. Otherwise, the code will scan the `.aux` file to guess the name of your bibliography file.  Arguments can be typed with or without extension, and the script is smart enough to figure it out. You need to have `.aux` file already, not just the `.tex`. If you don't have it, run `pdflatex` once.\r\n\r\n`fillbib.py` contains two short unit tests, to make sure the web-scarping part is done correctly. You can run them from the `filltex` directiory using\r\n\r\n    python\r\n    \u003e import fillbib\r\n    \u003e fillbib.test_ads()\r\n    \u003e fillbib.test_inspire()\r\n\r\nor simply using [`pytest`](https://docs.pytest.org/en/latest/contents.html#toc)\r\n\r\n    pytest fillbib\r\n    \r\n`fillbib` supports both python 2 (2.6 or higher) and python 3.\r\n\r\n### filltex (script)\r\n\r\n***`filltex`*** does the whole thing: compiles LaTex, fills the bibliography and gives you the final `.pdf`. Usage:\r\n\r\n    filltex \u003ctex file\u003e\r\n\r\nArgument can be with or without extension, and the script is smart enough to figure it out.\r\n\r\n\r\nThe script will replace some journal name with their [ISO4](https://en.wikipedia.org/wiki/ISO_4) abbreviations. You can disable this with the `journals` flag. Please send me pull requests with new journals that should be added here! ADS bibliography items contain some journal macros, which are also replaced in favour of ISO4. If you disable the ISO4 conversion, you'll need to use [`aas_macros.sty`](http://doc.adsabs.harvard.edu/abs_doc/aas_macros.sty).\r\n\r\nBy default, the script will also change your `.tex` file if an ADS arXiv entry has been published (see below). You can disable this by turning off `updatepublished`, see the help page.  \r\n\r\nAt the end, `filltex` also runs [TexCount](http://app.uio.no/ifi/texcount) which counts the words in your document. \r\n\n### ADS token\n\n*This is optional but strongly recommended.* The ADS API has a daily request limit, and with this script you might hit it quickly. You should create an account on [ADS](http://adsabs.harvard.edu), then go to `Settings`, then `API Token`, and generate a token. Copy that string into an environment variable called `ADS_TOKEN` and make it system-wide available. The easiest way is to add the following to your `.bashrc` file:\n\n```export ADS_TOKEN=....```\n\n`filltex` will check if a token is available and use it. If not, it will default back to a simpler scraping implementation.\n\r\n### TexShop\r\n\r\nI use the [TexShop](http://pages.uoregon.edu/koch/texshop) editor, so I wrote an implementation of `filltex` for it. If you copied the `filltex.engine` file as specified above, just open your paper with [TexShop](http://pages.uoregon.edu/koch/texshop) and select ***filltex*** from the drop menu on the left. Now automagically compile your paper with `Typeset` or cmd-T. \r\n\u003c!-- The [TexShop](http://pages.uoregon.edu/koch/texshop) engine will work only if the path is updated in your `.bashrc`, see above. --\u003e\r\n\r\n### Example\r\n\r\nA short `example.tex` file is provided, where you can try this new way of writing papers!\r\n\r\n## More details\r\n\r\n  - Treating arXiv e-prints with ADS is tricky. When an e-print gets published they change the database key, but make the old key point to the new version! For instance, the key switches from `2016arXiv160203837T` to `2016PhRvL.116f1102A`.  If you're citing an e-print which is not yet published, everything is fine: only the arXiv key (e.g. `2016arXiv160203837T`) is available and your reference list will show the arXiv version. If you're citing a paper that is published, both the e-print key (e.g. `2016arXiv160203837T`) and the published-version key (e.g. `2016PhRvL.116f1102A`) are available. When used, they will both point to the same published version! If you write a document with citations to both, this will cause the same record to appear twice in your reference list (see the example file). To avoid the issue, `filltex` tries to update the pre-print key in your tex file if it finds a new version. In general, always use the published-paper key if a published version is out. INSPIRE doesn't have this problem, because they don't change the citation key when a paper gets published.\r\n\r\n  - Multiple bibliographies are not allowed, only one `.bib` file per paper. I don't plan to implement multiple bibliographies in here, because you're not going to need them with this script: one paper, one bibliography, that's all.\r\n\r\n\r\n### Manual installation from repository\r\n\r\nIf you don't like pip (but why wouldn't you?), you can install the code manually:\r\n\r\n    git clone https://github.com/dgerosa/filltex.git # Clone repo\r\n    cd filltex\r\n    chmod +x bin/* # Make bin content executable\r\n    PATH=$PATH:$(pwd)/bin # Add bin directory to path\r\n    echo \"PATH=$PATH:$(pwd)/bin\" \u003e\u003e ${HOME}/.bashrc # To add the new path to your .bashrc    \r\n    cp filltex.engine ~/Library/TeXshop/Engines/filltex.engine # To install the Texshop engine\r\n\r\n`filltex` uses [TexCount](http://app.uio.no/ifi/texcount), which is included in most Tex distribution. In case it's not in yours, [here](http://app.uio.no/ifi/texcount/faq.html#setup) you can find installation instruction.\r\n\r\n## References to filltex\r\n\r\n  - `filltex` is included in the [suggested tools](https://inspirehep.net/info/hep/tools/index) from the INSPIRE team.\r\n  - `filltex` is included the [official v3.80 release](http://pages.uoregon.edu/koch/texshop/changes_3.html) of Texshop.\r\n\r\n\r\n## Credits\r\nThe code is developed and maintained by [Davide Gerosa](www.davidegerosa.com). If you find bugs, want to contribute to this project (any help is welcome!) or need help with it, just open an issue here on GitHub.\r\n\r\nThe idea started from [this](http://www.vallis.org/salon/) `python` course taught by [Michele Vallisneri](http://www.vallis.org/) at Caltech (and in particular from [this example](http://www.vallis.org/salon/summary-2.html)) and was later developed with key contributions from [David Radice](https://github.com/dradice). We also thank [Lars Holm Nielsen](https://github.com/lnielsen), reviewer for [The Journal of Open Software](http://joss.theoj.org/), for several suggestions which improved `filltex`. [TexCount](http://app.uio.no/ifi/texcount) is developed by Einar Andreas Rodland. Useful info on the INSPIRE and ADS APIs are available [here](https://inspirehep.net/info/hep/pub_list) and [here](https://github.com/adsabs/adsabs-dev-api).\r\n\r\n## Changes\r\n**v1.0**: Initial release, main functionalities.\r\n\r\n**v1.1**: Version accepted in JOSS.\r\n\r\n**v1.2**: Uploaded on pip.\r\n\r\n**v1.3**: Compatible with new ADS \"Bumblebee\".\r\n\r\n**v1.4**: Compatible with new INSPIRE API.\r\n\r\n**v1.5**: New `tex` and `list` subcommands.\r\n\r\n**v1.7**: New treatment of journal names, converting to ISO4 when available.\r\n\r\n\r\n\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdgerosa%2Ffilltex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdgerosa%2Ffilltex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdgerosa%2Ffilltex/lists"}