latexdiffcite Release 1.0.4

Transcription

1 latexdiffcite Release June 08, 2015

2

3 Contents 1 Contents Quick start Installation Usage Configuration file Configuration examples Contributing Authors Changelog i

4 ii

5 latexdiffcite is a wrapper around latexdiff to make citations diff properly: latexdiffcite is a wrapper around latexdiff which, before calling latexdiff, replaces (in temporary files!) citation commands such as \cite{... with written-out formatted references. It does this by looking up references in a corresponding.bib file or.bbl file and formatting them according to a user-specifiable configuration. latexdiff will then properly mark changes in the citations. The citation format can be heavily customized to match what you are already getting from LaTeX/BibTeX. latexdiff is a great tool for highlighting changes in LaTeX documents. Unfortunately, when you use citation commands such as \cite{... in your document, two annoying problems occur: 1. The whole citation command is treated as a single entity, which means that if you add or remove references in a citation command, the whole old line of references [Foo, 2013; Bar, 2012] is marked as removed and the whole new line of references [Foo, 2013; Bar, 2012; Baz, 2014] is marked as inserted, even though only a single reference was changed. 2. Both the old and new references are rendered without linebreaks (in latexdiff s default underline/strikethrough Contents 1

6 style) and may easily extend way off the page if there are many references in the citation command. latexdiffcite aims to rectify this by replacing all citation commands in the files with written-out references in plain text before running latexdiff. For example, \citep{foo2013, bar2012 might be replaced by [\textit{foo, 2013; \textit{bar et~al., 2012]. The format can be customized. Temporary files are used; the original files are kept intact. 2 Contents

7 CHAPTER 1 Contents 1.1 Quick start latexdiff is required, but you of course already have that installed and working, right? :-) Install with pip: pip install latexdiffcite To compare two.tex files on disk, use the file subcommand like this: latexdiffcite file FILE_OLD FILE_NEW To compare two revisions (commit hash, tag, branch, etc.) of a.tex file in a git repository, use the git subcommand like this: latexdiffcite git FILE REV_OLD [REV_NEW] [FILE_NEW] REV_OLD and REV_NEW can be commit hashes, tags, branches, etc. REV_NEW is optional, and defaults to HEAD (the latest committed version). FILE_NEW is optional, and is used when the new filename/path is different than the old For customization of the citation format, see Configuration file and Configuration examples. 1.2 Installation Using pip: pip install latexdiffcite Installing from source: python setup.py install You can also copy src/latexdiffcite/latexdiffcite.py somewhere accessible by Python (on your PATH or PYTHONPATH) and invoke the script with python -m latexdiffcite instead of just latexdiffcite. 3

8 1.3 Usage If properly installed using pip install latexdiffcite (from PyPI) or python setup.py install (from source), the script is invoked with latexdiffcite [args] If you have simply copied latexdiffcite.py to somewhere accessible by Python, you need to use python -m latexdiffcite [args] instead. latexdiffcite has two sub-commands: file for comparing two files on disk, and git for comparing two versions of a file in a git repository Comparing two files on disk To compare two files FILE_OLD and FILE_NEW on disk: latexdiffcite file FILE_OLD FILE_NEW Comparing revisions of a file in a git repository To compare two revisions REV_OLD and REV_NEW of a file FILE in a git repository: latexdiffcite git FILE REV_OLD [REV_NEW] [FILE_NEW] REV_OLD and REV_NEW can be commit hashes, tags, branches, etc. REV_NEW is optional, and defaults to HEAD (the latest committed version). FILE_NEW is optional, and is used when the new filename/path is different than the old Optional arguments The following optional commands are available: -h, --help Show help. -c CONFIG_FILE, --config CONFIG_FILE Path to configuration file, see Configuration file for details. -o FILE_OUT, --output FILE_OUT Output file, default diff.tex in the current directory. -b [BBL_SUBDIR], --bbl [BBL_SUBDIR] Switches to bbl mode instead of bib mode (see.bib vs.bbl). BBL_SUBDIR (optional) is the path to where the.bbl file resides relative to the.tex file (default: same directory as the files). The filename of the.bbl files are assumed to be the same as the.tex files (this is not configurable). --bbl2 [BBL_NEW_SUBDIR] Use this if the compiled.bbl file for the new version is in another subdirectory. -s, --silent Hide info messages from screen (only show warnings). -v, --verbose Show debug log on screen. -l [LOGFILE], --log [LOGFILE] Enable logging to LOGFILE (default filename: latexdiffcite.log). 4 Chapter 1. Contents

9 1.3.4.bib vs.bbl latexdiffcite is very flexible and can construct the written-out references using either BibTeX.bib files (default) or the compiled.bbl files. bbl mode is activated using the -b argument. In bib mode (default), latexdiffcite will look for a \bibliography{ command in the.tex files and read the files specified here. Multiple files are supported, but only a single \bibliography{ command. All the reference keys in the.tex file will be looked up in the.bib files, and latexdiffcite will create author names and years according to the Configuration file. The bib mode is suited for author-year styles or numeric style. In.bbl mode, latexdiffcite ignores \bibliography{ commands and instead reads the compiled.bbl files. You need to supply a configuration file with a regular expression (regex) used to parse the bbl file and return capture groups which you can use in the citation formatting. For more details, see Configuration file and Configuration examples. Note that when you run latexdiff in git mode, the.bbl file naturally needs to be versioned (and exist in the repository for both revisions). For both of these modes, latexdiffcite will include a \nocite{ref1,ref2,... just before \end{document containing all the references, so that the bibliography will be rendered as usual. 1.4 Configuration file Default configuration latexdiffcite will load settings from three places, each one overriding previous ones: 1. Internal hard-coded defaults (provided below) 2. ~/.latexdiffcite.json (in your user folder) if it exists 3. Settings from a file specified using -c CONFIG_FILE This way, you can put your preferred settings in ~/.latexdiffcite.json which will be loaded every time, and override them using -c CONFIG_FILE if necessary. The configuration file is a JSON file which looks like this: { "encoding": "utf-8", "latexdiff_args": "", "git_force_unix_pathsep": true, "ref_single_word": true, "bib": { "max_authors": 2, "sep_authors_first": ", ", "author_serialcomma": true, "sep_authors_last": " and ", "et_al": " et~al.", "bbl": { "regex": "\\\\bibitem\\[{((?:(?!^$).)*?)\\(((?:(?!^$).)*?)(?:{\\\\natexlab{(.?))?\\)((?:(?! "author": "%CG1%", "year": "%CG2%%CG3%", "cmd_format": { "citep": { "cite_start": "[", "author": "\\textit{%author%", 1.4. Configuration file 5

10 "sep_author_year": ", ", "year": "%YEAR%", "sep_same_author_year": ", ", "sep_ref": "; ", "cite_end": "]", "citet": { "cite_start": "", "author": "\\textit{%author%", "sep_author_year": " ", "year": "[%YEAR%]", "sep_same_author_year": ", ", "sep_ref": "; ", "cite_end": "", "cite": { "cite_start": "", "author": "\\textit{%author%", "sep_author_year": " ", "year": "[%YEAR%]", "sep_same_author_year": ", ", "sep_ref": "; ", "cite_end": "" Any of the root-level items (encoding, bib, bbl, etc.) may be skipped if their defaults work for you (but don t rely on latexdiffcite s defaults to stay consistent across versions). You can implement support for other citation commands by adding them alongside the existing citation commands Description of the settings encoding The encoding used to read all files (and decode output from git show). Only change this if you experience encoding problems. latexdiff_args Extra arguments to pass to latexdiff. git_force_unix_pathsep Force usage of / as path separator when extracting files from git. This may be needed when using latexdiffcite git on Windows. ref_single_word If true, each reference will be enclosed in a custom command (\ldiffentity{) that latexdiff has no knowledge of. This makes sure each reference is differenced as a whole, instead of latexdiff mixing author names and years from old and new references in the diff (might happen if you replace a reference with another). The command definition will be added to the preamble (just before \begin{document). bib Contains settings related to formatting author/year from entries in.bib files (these settings are only used when running the script without --bbl). max_authors Maximum number of authors before et_al is used (see below). sep_authors_first If more than two authors, this is the separator between all but the last two authors 6 Chapter 1. Contents

11 author_serialcomma If more than two authors, sep_authors_last, see below). sep_authors_last This is the separator between the two last (or only) authors. add a comma before the last author (before et_al This will be appended to the author name(s) if there are more than max_authors authors. bbl Contains settings related to parsing.bbl files (when using the --bbl option). regex The regex used to search for a given entry in the.bbl file. The regex is performed with flags ms (. matches newlines, and ^/$ matches start/end of lines). Backslashes must be doubly-escaped. %REFKEY% is important it will be replaced by the reference keys as each one are looked up in turn. The regex typically contains capturing groups, which will be available in some other of the other fields as %CG1%, %CG2%, etc. The script fails if nothing is found, so if you for some reason do not want to capture anything in --bbl mode, write e.g. %REFKEY% (which is guaranteed to match). 1 author, year In order to enable joining together consecutive citations where the author name is the same (e.g., Foo et al. (2010, 2011a, b, 2013) instead of Foo et al. (2010), Foo et al. (2011a),...), the script needs to know which of the captured groups are the author and year. Use %CG1%, %CG2% etc. to specify this in these fields. The author and year is then available as %AUTHOR% and %YEAR% in cmd_format (see below). The first four characters of year will be compared in order to determine whether to string together identical years (e.g., 2011a, b instead of 2011a, 2011b). If you do not wish any of this functionality (for example if your citation style is [Foo10, Bar11]), leave these fields blank. 2 cmd_format Contains formatting options for all the citation commands. The built-in supported citation commands are cite, citet and citep. You can implement support for other citation commands by adding them alongside the existing citation commands. cite_start Put at the start of a citation list. sep_prenote Separator between prenote and start of references (example: citep[e.g.][and references therein]{foo2012 becomes [e.g. Foo, 2012, and references therein]). author Author name(s). Available tokens: %AUTHOR% Will be replaced by author name for a given reference (e.g. Foo, Foo and Bar, Foo et al.). %NUMERIC% Will be replaced by the reference number (in order of appearance in the document). %CG1%, %CG2%,... Will be replaced by the corresponding capture groups from the regex (only if using --bbl mode) sep_author_year Separator between the author and the year. year Formatting for the reference s year. Available tokens: %YEAR% Will be replaced by the year (e.g. 2011, 2013a). %CG1%, %CG2%,... Will be replaced by the corresponding capture groups from the regex (only if using --bbl mode) sep_same_author_year Separator between years when the author name is the same for consecutive references (the separator between the years in [Foo et al., 2012, 2013a, b]). 1 Tip: Use regex101 to create and check your regex. Paste the contents of your.bbl file into test string, and remember to select flavor python and flags ms. Use a real reference key for testing, not %REFKEY%. A single reference should be matched, no matter which reference key you put in. The capture groups are displayed to the right. Remember to double all the backslashes when you use the regex in the configuration file. 2 Side note: The default regex matches entries of the form \bibitem[{\textit{foo et al.(2010)\textit{foo, Bar and Baz]{foo2010 or \bibitem[{\textit{foo(2011{\natexlab{a)]{foo2011. In the default configuration, %AUTHOR% would be \textit{foo et al. and \textit{foo, while %YEAR would be 2010 and 2011a. See the example confiuration files and corresponding.bbl files for other examples Configuration file 7

12 sep_ref Separator between references (when consecutive author names are not identical). If the separator is ;, then \citep{foo2012, bar2013 might become [Foo, 2012; Bar et al., 2013]. sep_postnote Separator between end of references and postnote (see sep_prenote). cite_end Put at the end of a citation list. 1.5 Configuration examples These configuration examples can serve as a starting point for your own configuration file. The examples include a configuration.json file, an input.bib or.bbl file, an input.tex file, and an output.tex file. The output is how the LaTeX markup looks after the citation commands have been replaced with writtenout references by latexdiffcite. The examples are verified by the testing suite and should work Author-year AGU (bbl) This configuration parses.bbl files in the style created by the American Geophysical Union s LaTeX Formatting Toolkit and renders written-out citations the same way BibTeX does using the AGU templates. The output is exactly the same as Author-year AGU (bib). There are three capture groups: 1. The author string (including \textit{ and et al.) 2. The year (only the digits) 3. A letter after the year if the year occurs more than once for this author string (empty if there is no letter) Note: ref_single_word is set to false to keep the example output simple, but it should preferably be set to true when actually using the example (see Description of the settings). config.json { "ref_single_word": false, "bbl": { "regex": "\\\\bibitem\\[{((?:(?!^$).)*?)\\(((?:(?!^$).)*?)(?:{\\\\natexlab{(.?))?\\)((?:(?! "author": "%CG1%", "year": "%CG2%%CG3%", "cmd_format": { "citep": { "cite_start": "[", "author": "%AUTHOR%", "sep_author_year": ", ", "year": "%YEAR%", "sep_same_author_year": ", ", "sep_ref": "; ", "cite_end": "]", "citet": { 8 Chapter 1. Contents

13 "cite_start": "", "author": "%AUTHOR%", "sep_author_year": " ", "year": "[%YEAR%]", "sep_same_author_year": ", ", "sep_ref": "; ", "cite_end": "", "cite": { "cite_start": "", "author": "%AUTHOR%", "sep_author_year": " ", "year": "[%YEAR%]", "sep_same_author_year": ", ", "sep_ref": "; ", "cite_end": "" input.bbl \bibitem[{\textit{foo(2010)]{foo2010 \bibitem[{\textit{foo and Bar(2011{\natexlab{a)]{foo2011lorem \bibitem[{\textit{foo and Bar(2011{\natexlab{b)]{foo2011ipsum \bibitem[{\textit{foo et~al.(2011)\textit{foo, Bar, and Baz]{foo2011dolor \bibitem[{\textit{foo and Bar(2012)]{foo2012 \bibitem[{\textit{bar and Baz(2013)]{bar2013 input.tex \documentclass{article \begin{document Same-author references are cool \citep{foo2010, foo2011lorem, foo2011ipsum, foo2012, foo2011dolor, ba citet is pretty awesome too, according to \citet{foo2010 (and later confirmed by \cite{bar2013). Prenote only \citep[e.g.][]{foo2011lorem. Pre- and postnote \citep[e.g.][and references therein]{foo2011ipsum, foo2011dolor. Postnote only \citep[and references therein]{foo2010. \bibliography{input \end{document 1.5. Configuration examples 9

14 output.tex \documentclass{article \begin{document Same-author references are cool [\textit{foo, 2010; \textit{foo and Bar, 2011a, b, 2012; \textit{fo citet is pretty awesome too, according to \textit{foo [2010] (and later confirmed by \textit{bar and Prenote only [e.g. \textit{foo and Bar, 2011a]. Pre- and postnote [e.g. \textit{foo and Bar, 2011b; \textit{foo et~al., 2011, and references therei Postnote only [\textit{foo, 2010, and references therein]. \bibliography{input \nocite{foo2010,foo2011lorem,foo2011ipsum,foo2012,foo2011dolor,bar2013 \end{document Author-year AGU (bib) This configuration parses.bib files and creates written-out citations in the same style BibTeX does using the American Geophysical Union s LaTeX Formatting Toolkit. The output is exactly the same as Author-year AGU (bbl). Note: ref_single_word is set to false to keep the example output simple, but it should preferably be set to true when actually using the example (see Description of the settings). config.json { "ref_single_word": false, "bib": { "max_authors": 2, "sep_authors_first": ", ", "author_serialcomma": true, "sep_authors_last": " and ", "et_al": " et~al.", "cmd_format": { "citep": { "cite_start": "[", "author": "\\textit{%author%", "sep_author_year": ", ", "year": "%YEAR%", "sep_same_author_year": ", ", "sep_ref": "; ", "cite_end": "]", "citet": { "cite_start": "", "author": "\\textit{%author%", "sep_author_year": " ", "year": "[%YEAR%]", "sep_same_author_year": ", ", "sep_ref": "; ", 10 Chapter 1. Contents

15 "cite_end": "", "cite": { "cite_start": "", "author": "\\textit{%author%", "sep_author_year": " ", "year": "[%YEAR%]", "sep_same_author_year": ", ", "sep_ref": "; ", "cite_end": "" author = {Foo, M, year = author = {Foo, M and Bar, G, year = author = {Foo, M and Bar, G, year = author = {Foo, M and Bar, G and Baz, S, year = author = {Foo, M and Bar, G, year = author = {Bar, G and Baz, S, year = 2013 input.tex \documentclass{article \begin{document Same-author references are cool \citep{foo2010, foo2011lorem, foo2011ipsum, foo2012, foo2011dolor, ba citet is pretty awesome too, according to \citet{foo2010 (and later confirmed by \cite{bar2013). Prenote only \citep[e.g.][]{foo2011lorem. Pre- and postnote \citep[e.g.][and references therein]{foo2011ipsum, foo2011dolor. Postnote only \citep[and references therein]{foo2010. \bibliography{input \end{document 1.5. Configuration examples 11

16 output.tex \documentclass{article \begin{document Same-author references are cool [\textit{foo, 2010; \textit{foo and Bar, 2011a, b, 2012; \textit{fo citet is pretty awesome too, according to \textit{foo [2010] (and later confirmed by \textit{bar and Prenote only [e.g. \textit{foo and Bar, 2011a]. Pre- and postnote [e.g. \textit{foo and Bar, 2011b; \textit{foo et~al., 2011, and references therei Postnote only [\textit{foo, 2010, and references therein]. \bibliography{input \nocite{foo2010,foo2011lorem,foo2011ipsum,foo2012,foo2011dolor,bar2013 \end{document Author-year short (bbl) This configuration outputs references in the form [Foo11, Bar13] where the last name is abbreviated and joined together with the year. latexdiffcite currently has no way of doing that in bib mode, so this is a configuration for bbl mode and thus requires that the.bbl file have more or less the exact format shown below in order to match the regex. Even if your.bbl file is not exactly like the one here, you might be able to adjust the regex to suit your needs. Note: ref_single_word is set to false to keep the example output simple, but it should preferably be set to true when actually using the example (see Description of the settings). config.json { "ref_single_word": false, "bbl": { "regex": "\\\\bibitem\\[((?:(?!^$).)*?)\\]{%refkey%", "author": "", "year": "", "cmd_format": { "citep": { "cite_start": "[", "author": "%CG1%", "sep_author_year": "", "year": "", "sep_same_author_year": "", "sep_ref": ", ", "cite_end": "]", "citet": { "cite_start": "[", "author": "%CG1%", "sep_author_year": "", "year": "", "sep_same_author_year": "", "sep_ref": ", ", "cite_end": "]", 12 Chapter 1. Contents

17 "cite": { "cite_start": "[", "author": "%CG1%", "sep_author_year": "", "year": "", "sep_same_author_year": "", "sep_ref": ", ", "cite_end": "]" input.bbl \bibitem[foo10]{foo2010 \bibitem[foo11a]{foo2011lorem \bibitem[foo11b]{foo2011ipsum \bibitem[not12]{notused \bibitem[foo11c]{foo2011dolor \bibitem[foo12]{foo2012 \bibitem[bar13]{bar2013 input.tex \documentclass{article \begin{document Same-author references are cool \citep{foo2010, foo2011lorem, foo2011ipsum, foo2012, foo2011dolor, ba citet is pretty awesome too, according to \citet{foo2010 (and later confirmed by \cite{bar2013). Prenote only \citep[e.g.][]{foo2011lorem. Pre- and postnote \citep[e.g.][and references therein]{foo2011ipsum, foo2011dolor. Postnote only \citep[and references therein]{foo2010. \bibliography{input \end{document output.tex \documentclass{article \begin{document 1.5. Configuration examples 13

18 Same-author references are cool [Foo10, Foo11a, Foo11b, Foo12, Foo11c, Bar13]. citet is pretty awesome too, according to [Foo10] (and later confirmed by [Bar13]). Prenote only [e.g. Foo11a]. Pre- and postnote [e.g. Foo11b, Foo11c, and references therein]. Postnote only [Foo10, and references therein]. \bibliography{input \nocite{foo2010,foo2011lorem,foo2011ipsum,foo2012,foo2011dolor,bar2013 \end{document Numeric This configuration outputs references in the form [1, 2]. latexdiffcite has built-in support for this by way of the %NUMERIC% token, which will be replaced by the reference s number (in order of appearance in the document). Note: ref_single_word is set to false to keep the example output simple. It has no practical effect in this style, since each reference is just a single number. config.json { "ref_single_word": false, "cmd_format": { "citep": { "cite_start": "[", "author": "%NUMERIC%", "sep_author_year": "", "year": "", "sep_same_author_year": "", "sep_ref": ", ", "cite_end": "]", "citet": { "cite_start": "[", "author": "%NUMERIC%", "sep_author_year": "", "year": "", "sep_same_author_year": "", "sep_ref": ", ", "cite_end": "]", "cite": { "cite_start": "[", "author": "%NUMERIC%", "sep_author_year": "", "year": "", "sep_same_author_year": "", "sep_ref": ", ", "cite_end": "]" 14 Chapter 1. Contents

19 input.tex \documentclass{article \begin{document Same-author references are cool \citep{foo2010, foo2011lorem, foo2011ipsum, foo2012, foo2011dolor, ba citet is pretty awesome too, according to \citet{foo2010 (and later confirmed by \cite{bar2013). Prenote only \citep[e.g.][]{foo2011lorem. Pre- and postnote \citep[e.g.][and references therein]{foo2011ipsum, foo2011dolor. Postnote only \citep[and references therein]{foo2010. \bibliography{input \end{document output.tex \documentclass{article \begin{document Same-author references are cool [1, 2, 3, 4, 5, 6]. citet is pretty awesome too, according to [1] (and later confirmed by [6]). Prenote only [e.g. 2]. Pre- and postnote [e.g. 3, 5, and references therein]. Postnote only [1, and references therein]. \bibliography{input \nocite{foo2010,foo2011lorem,foo2011ipsum,foo2012,foo2011dolor,bar2013 \end{document 1.6 Contributing Bug reports, feature suggestions and other contributions are greatly appreciated! While I can t promise to implement everything, I will always respond in a timely manner Short version Submit bug reports and feature requests at GitHub Make pull requests to the develop branch Bug reports When reporting a bug please include: your operating system name and version any details about your local setup that might be helpful in troubleshooting detailed steps to reproduce the bug, which could include: log file (use the -l option, check that it doesn t contain personal details) the problematic part of your.tex file,.bib file and/or.bbl file 1.6. Contributing 15

20 1.6.3 Documentation improvements Feel free to add additional configuration examples. This should include, in the style of the existing examples, a minimal working example (no more than the bare minimum to get it working and show how the configuration behaves). You must include: the configuration file (include all relevant settings don t rely on latexdiffcite s defaults to stay consistent across versions) an example.bib file or.bbl file an example.tex file the output latexdiffcite would produce after replacing citation commands Please run your JSON through a JSON validator and formatter before adding it to the docs Feature requests and feedback The best way to send feedback is to file an issue at GitHub. If you are proposing a feature: Explain in detail how it would work. Keep the scope as narrow as possible, to make it easier to implement. Remember that this is a volunteer-driven project, and that contributions are welcome :) Development To set up latexdiffcite for local development: 1. Fork latexdiffcite on GitHub. 2. Clone your fork locally: git clone git@github.com:your_name_here/latexdiffcite.git 3. Create a branch for local development: git checkout -b name-of-your-bugfix-or-feature Now you can make your changes locally. If you add functionality, also add a test in tests/test_latexdiffcite.py. The tests are run with py.test and can be written as normal functions (starting with test_) containing a standard assert statement for testing output. 4. When you re done making changes, run all the checks, doc builder and spell checker with tox: 3 tox 5. Commit your changes and push your branch to GitHub: git add. git commit -m "Brief description of your changes." git push origin name-of-your-bugfix-or-feature 6. Submit a pull request through the GitHub website. Pull requests should be made to the develop branch. 3 If you don t have all the necessary python versions available locally you can rely on Travis it will run the tests for each change you add in the pull request. It will be a bit slower than testing locally, though. 16 Chapter 1. Contents

21 Pull Request Guidelines If you need some code review or feedback while you re developing the code, just make a pull request. For merging, you should: 1. Write passing tests for new functionality (run tox) Update/add documentation if relevant. 3. Add yourself to AUTHORS.rst. Tips To run a subset of tests: tox -e envname -- py.test -k test_myfeature To run all the test environments in parallel (you need to pip install detox): detox 1.7 Authors Christer van der Meeren Changelog ( ) Minor readme/doc changes ( ) First release on PyPI Authors 17