{"id":16806111,"url":"https://github.com/pkgw/worklog-tools","last_synced_at":"2025-04-11T00:50:34.558Z","repository":{"id":12612752,"uuid":"15283833","full_name":"pkgw/worklog-tools","owner":"pkgw","description":"Framework for generating CV, publications list, etc.","archived":false,"fork":false,"pushed_at":"2023-02-06T14:53:20.000Z","size":353,"stargazers_count":10,"open_issues_count":3,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-24T21:38:47.289Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pkgw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-12-18T13:29:14.000Z","updated_at":"2022-12-06T14:55:35.000Z","dependencies_parsed_at":"2023-02-19T09:00:53.686Z","dependency_job_id":null,"html_url":"https://github.com/pkgw/worklog-tools","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkgw%2Fworklog-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkgw%2Fworklog-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkgw%2Fworklog-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pkgw%2Fworklog-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pkgw","download_url":"https://codeload.github.com/pkgw/worklog-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248322609,"owners_count":21084336,"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-10-13T09:50:09.259Z","updated_at":"2025-04-11T00:50:34.536Z","avatar_url":"https://github.com/pkgw.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"worklog-tools\n=============\n\nThis software is part of a system for recording academic output and reporting\nit in documents like CVs or publication lists.\n\n### “Why do you need software for that?”\n\nTwo reasons:\n\n* I want to have my CV and publications list available in both nicely\n  printable and slick web-native formats … without having to keep two very\n  different documents in sync.\n* I want my CV to include things like my *h*-index, citation counts, total\n  telescope time allocated, and so on. (Oh, by the way: I’m an astronomer.)\n  And I want the computer to be responsible for figuring those out. Because\n  that kind of stuff is why we invented computers.\n\nTo accomplish these things, the worklog tools process simple structured text\nfiles and use the results to fill in LaTeX and HTML templates. There’s\nbuilt-in functionality to fetch citation counts and fill in statistics like\nyour *h*-index.\n\n### “Sounds like a thing. Should I care?”\n\nYes! You can copy the tools and example files to quickly get started\nautomating the generation of your own CV. The log format is flexible and the\nscripts are simple, so the sky’s the limit in terms of what effects you can\nachieve.\n\nAlso, I like to think that my LaTeX templates are pretty nice. Here are [my\nprintable CV](http://newton.cx/~peter/files/cv.pdf) and [my publications\nlist](http://newton.cx/~peter/files/pubs.pdf). Here’s my [online publications\nlist](http://newton.cx/~peter/pubs/).\n\n\nContents\n--------\n\n* [Diving in](#diving-in)\n* [Using the tools for your own documents](#using-the-tools-for-your-own-documents)\n* [Technical details: publication\n  processing](#technical-details-publication-processing)\n* [Technical details: wltool invocation](#technical-details-wltool-invocation)\n* [Technical details: template directives](#technical-details-template-directives)\n* [Technical details: substitution groups](#technical-details-substitution-groups)\n* [Technical details: the ini file format](#technical-details-the-ini-file-format)\n* [System requirements](#system-requirements)\n\n\nDiving in\n---------\n\nThe worklog system has three pieces:\n\n* Simple text files logging academic output\n* LaTeX/HTML templates used to generate output documents\n* Software to fill the latter using data gathered from the former\n\nThe software is in the same directory as this file — the [wltool](wltool)\nscript drives everything from the command line. The [example](example)\nsubdirectory contains sample copies of templates (in `*.tmpl.*`) and log files\n(in [2012.txt](example/2012.txt), [2013.txt](example/2013.txt)).\n\nTo get started, first check out this repository if you haven’t done so\nalready. Go into the [example](example) directory and type `make`. This will\ncreate the outputs: a CV and publication list in PDF and HTML formats.\n(Assuming nothing breaks … the scripts are in Python and have few\ndependencies, so they should be widely portable.) The HTML results have not\nbeen particularly beautified, but I've tried to make the PDFs come out nicely.\n\nNow check out [example/2013.txt](example/2013.txt). Log files are in a basic\n[“ini file”][inifile] format, with records coming in paragraphs headed by a\nword encased in square brackets. A typical record is:\n\n[inifile]: http://en.wikipedia.org/wiki/INI_file\n\n```INI\n[talk]\ndate = 2013 Apr\nwhere = OIR seminar, Harvard/Smithsonian Center for Astrophysics\nwhat = Magnetic Activity Past the Bottom of the Main Sequence\ninvited = n\n```\n\n(The precise file format is [defined among the “Technical\ndetails”](#technical-details-the-ini-file-format) below.) A major point of\nemphasis is that this format is very simple and readable for humans and\ncomputers alike.\n\nThe template files, on the other hand, are complicated since they go to some\neffort to create attractive output. (Well, currently, this is much more true\nof the LaTeX templates than the HTML templates.) Most of this effort is in\ninitialization, so the ends of the files are where the actual content shows\nup. For instance, toward the bottom of\n[example/cv.tmpl.tex](example/cv.tmpl.tex) you’ll find:\n\n```TeX\nFORMAT \\item[|date|] \\emph{|where|} \\\\ ``|what|''\n\n\\section*{Professional Talks --- Invited}\n\\begin{datelist} % this is a custom environment for nice spacing\nRMISCLIST_IF talk invited\n\\end{datelist}\n\n\\section*{Professional Talks --- Other}\n\\begin{datelist}\nRMISCLIST_IF_NOT talk invited\n\\end{datelist}\n```\n\nThe lines beginning with ALL_CAPS trigger actions in the templating scripts.\nThe [RMISCLIST_IF](#rmisclist_if-type1type2-gatefield) directive writes a\nsequence of `[talk]` records in reversed order, filtering for an `invited`\nfield equal to `y`. Each record is LaTeXified using the template specified in\nthe most recent [FORMAT](#format-template-text-) directive. Strings between\npipes (`|what|`) in the [FORMAT](#format-template-text-) are replaced by the\ncorresponding values from each record. (The precise functionalities of the\nvarious directives are also [defined among the “Technical\ndetails”](#technical-details-template-directives) below.)\n\nFinally, the [Makefile](example/Makefile) in the [example](example) directory\nwires up commands to automatically create or update the output files using the\nstandard `make` command.\n\n\nUsing the tools for your own documents\n--------------------------------------\n\nTo get started using this system for yourself, you should copy the script code\nand example files. You can put them all in the same directory and just edit\nthe [Makefile](example/Makefile) to change `toolsdir` to `.` rather than `..`.\nThen there are two things to work on: customizing the templates, and entering\nyour previous accomplishments into log files. You’ll probably edit these\nhand-in-hand as you decide what things to include in your CV and how you want\nto express them in your log files. Obviously, for some things it makes more\nsense just to put them directly in the templates, rather than filling in\nfields from the log files.\n\nUnsurprisingly, the templates get filled by running the [wltool](wltool)\nprogram. It has several subcommands that [are documented\nbelow](#technical-details-wltool-invocation). The `latex` and `html`\nsubcommands are the main ones to use. Of special note, however, are two\nsubcommands. The\n[bootstrap-bibtex](#bootstrap-bibtex-bibtex-file-your-surname-output-dir)\nsubcommand creates a set of log files, seeding them with publication\ninformation gathered from a [NASA ADS] BibTeX file. The `update-cites`\nsubcommand which automatically fetches citation information from [NASA ADS].\n\n[NASA ADS]: http://adsabs.harvard.edu/\n\nI organize my log files by year (e.g. [2012.txt](example/2012.txt)) but you\ncan arrange them any way you want. The [wltool](wltool) reads in data from\nevery file in the current directory whose name ends in `.txt`, processing the\nfiles in alphabetical order.\n\nI recommend that you use `make` to drive the template filling and\n[git](http://git-scm.com/) to version-control your files, but those things are\nup to you.\n\n\n### Generic lists\n\nThe main method for filling the templates with data is a combination of\n[RMISCLIST](#rmisclist-type1type2) and [FORMAT](#format-template-text-)\ndirectives. These provide almost complete flexibility because you can define\nwhatever fields you want in your log files and get them inserted by writing a\n[FORMAT](#format-template-text-) directive.\n\n*Important!* When fields from the logs are inserted into the templates, they\nare escaped for LaTeX and HTML as appropriate. So if you write\n\n```INI\n[foo]\nbar = $x^2$\n```\n\nand insert `|bar|` in a template somewhere, you’ll get dollar signs and\ncarets, not *x²*. We can’t sanely output to both HTML and LaTeX without doing\nthis escaping. To get non-keyboard characters, use [Unicode] — get friendly\nwith http://unicodeit.net/ and [Compose Key] keyboard features. The log files\nare fully Unicode-enabled and Unicode characters will be correctly converted\nto their LaTeX expressions in the output (see the module\n[unicode_to_latex.py](unicode_to_latex.py)).\n\n[Unicode]: http://en.wikipedia.org/wiki/Unicode\n[Compose Key]: http://en.wikipedia.org/wiki/Compose_key\n\nThe main constraint in the list system is in the ability to *filter* and\n*reorder* records. The built-in facilities for doing so are limited, though so\nfar they’ve been sufficient for my needs. The only supported ordering is\n“reversed”, where that’s relative to the order that the data files are read\nin: alphabetically by file name, beginning to end. Since I name my files\nchronologically and append records to them as I do things, this works out to\nreverse chronological order, which is generally what you want.\n\nAs for filtering, the [RMISCLIST](#rmisclist-type1type2) directives select\nlog records of only a certain type, where the “type” is defined by the word\ninside square brackets beginning each record (e.g., `[talk]`). The\n[RMISCLIST_IF](#rmisclist_if-type1type2-gatefield) and\n[RMISCLIST_IF_NOT](#rmisclist_if_not-type1type2-gatefield) directives further\nfilter checking whether a field in each record is equal to `y`, with a missing\nfield being treated as `n`.\n\nTo extend this behavior, you’re going to need to edit\n[worklog.py](worklog.py). See the `cmd_rev_misc_list*` functions and\n`setup_processing`, which activates different directives.\n\n### Publication lists\n\nPublications are listed in `[pub]` records. These follow a more detailed\nformat to allow automatic fetching of citation counts, generation of reference\nlists with links, and computation of statistics such as the *h*-index.\n\nPublication records are read in and then “partitioned” into various groups\n(i.e., “refereed”, “non-refereed”) by the `partition_pubs` function in\n[worklog.py](worklog.py). The [PUBLIST](#publist-group) directive causes one\nof these groups to be output, with the crucial wrinkle that each record is\naugmented with a variety of extra fields to allow various special effects.\nThis augmentation is done in the `cite_info` function in\n[worklog.py](worklog.py).\n\nIf you want to group your publications differently (i.e. “refereed\nfirst-author”), then, you’ll need to edit `partition_pubs`. To change citation\ntext generation or do more processing, you’ll need to dive into `cite_info`.\n\nThe details of publication processing are [documented in the next\nsection](#technical-details-publication-processing).\n\n### Awarded proposals list\n\nProposals can be listed in `[prop]` records. These also follow a somewhat\nspecific format to allow one particular feature: the tools can compute the\ntotal awarded time by each facility. The relevant fields are:\n\n* `mepi` — should be `y` if you were the PI.\n* `accepted` — should be `y` if the proposal was accepted.\n* `facil` — the name of the facility that was proposed to.\n* `request` — the resources that the proposal requested. This should consist\n  of a number followed by a space and then some text specifying the units.\n  Every proposal for the same facility should use the same units.\n* `award` — the resources that were actually awarded. If not specified, it\n  is assumed that the full request was awarded.\n\nProposals are grouped by facility, and the total amount awarded in each\nproposal where both `mepi` and `accepted` are `y` is computed. The totals may\nthen be inserted into the template using [TALLOCLIST](#talloclist) or\n[SPLIT_TALLOCLIST](#split-talloclist).\n\n### Software repositories list\n\nI have attempted to develop a framework for quantifying contributions that\ncome in the form of software. I wouldn’t say that anyone really has any good\nidea of how to do this, but I’ve given it my best shot. Software contributions\nare quantified by tracing contributions to version-control repositories in\n`[repo]` records. These follow a somewhat specific format so that the tools\ncan compute statistics such as total numbers of commits. The relevant fields are:\n\n* `usercommits` — the number of commits you have made to the repository.\n* `allcommits` — the total number of commits in the repository.\n* `lastusercommit` — the date on which you last made a commit, in the form\n  `YYYY/MM/DD`.\n* `forks` — the number of times the repository has been “forked”, if the hosting\n  service happens to allow and track that.\n* `stars` — the number of times the repository has been “starred”, if the\n  hosting service happens to allow and track that.\n\n**TODO**: this feature needs more documentation.\n\n### Public engagement activities list\n\nPublic engagement activities can be listed in `[engagement]` records. These\ncan be quite freeform, but if you give these records a `class` field, the\ntools will be able to count up different types of engagement activities.\nDifferent classes of activity that are tracked are:\n\n* `interview` — a media interview\n* `outreach_event` — a public outreach event\n* `press_release` — a press release\n* `public_talk` — a public lecture\n\nSee the [engagement_stats](#engagement_stats) statistics group that can be\nused with the [BEGIN_SUBST](#begin_subst-group) directive.\n\n\n### Other derived information\n\nThe [BEGIN_SUBST](#begin_subst-group) directive begins a block of text in\nwhich special text fragments can be inserted into the template directly. This\nblock continues until a bare `END` directive is encountered. Different\nsubstitution groups are available:\n\n* [cite_stats](#cite_stats) — statistics regarding refereed publications\n  drawn from [NASA ADS].\n* [engagement_stats](#engagement_stats) — statistics regarding public\n  engagement activities.\n* [repo_stats](#repo_stats) — statistics regarding open-source software\n  contributions.\n* [talk_stats](#talk_stats) — statistics regarding professional talks\n\n### Miscellaneous template directives\n\nThere are also some more specialized templating directives that are [fully\ndocumented below](#technical-details-template-directives). For example,\n[TODAY.](#today), inserts the current date.\n\n\nTechnical details: publication processing\n-----------------------------------------\n\nAs mentioned above, there are two basic wrinkles to the processing of\npublications. First, extra fields are added to the records on the fly.\nSecond, the publications are “partitioned” into various subgroups.\n\nThe automatic processing assumes that all publication records will define\ncertain fields. Some of the key ones are:\n\n* `title` — the title of the publication\n* `authors` — the list of authors, in a special format. Separate authors’\n  names are separated by *semicolons*. Each author’s name should be in\n  first-middle-last order — no commas. Surnames containing multiple words\n  should have the words separated by *underscores* — this is the easiest\n  way to have the software pull out surnames automatically. Initials are OK.\n* `mypos` — your numerical position in the author list, with 1 (sensibly)\n  being first. Negative numbers are treated like Python list indices: -1\n  means that you are the last author, -2 means second-to-last, and so on.\n* `advpos` — a comma-separated list of positions in the author list, again\n  with 1 being first. The corresponding author names will be underlined in\n  the full author list. The intention is to highlight the names of\n  directly-advised students.\n* `pubdate` — the year and month of the publication, in numerical `YYYY/MM`\n  format. The worklog system generally tries not to enforce a particular\n  date format, but here it does.\n* `refereed` — `y` if the publication is refereed, `n` if not.\n* `refpreprint` — `y` if the publication has been submitted to the refereeing\n  process but has not yet been accepted.\n* `informal` — `y` if the publication is informal (e.g., a poster); this\n  affects the partitioning process as described below.\n* `cite` — citation text for the publication. This is free-form. My personal\n  preference is to keep it terse and undecorated. Examples include:\n  * `ApJ 746 L20`\n  * `proceedings of “RFI Mitigation Workshop” (Groningen)`\n  * `The Astronomer’s Telegram #3135`\n  * `MNRAS submitted`\n\nThere are also a set of fields used to create various hyperlinks. As many of\nthese should be defined as exist:\n\n* `arxiv` — the item’s unadorned Arxiv identifier, i.e. `1310.6757`.\n* `bibcode` — the item’s unadorned [NASA ADS] bibcode, i.e. `2006ApJ...649.1020W`.\n* `doi` — the item’s unadorned DOI, i.e. `10.1088/2041-8205/733/2/L20`.\n* `url` — some other relevant URL.\n\nSome fields are optional:\n\n* `adscites` — records [NASA ADS] citation counts. Automatically set by the `wltool\n  update-cites` command.\n* `kind` — a one-word description of the item kind if it is nonstandard (e.g.,\n  `poster`). This is only used for the `other_link` field described below.\n\nThe `cite_info` function uses the above information to create the following fields:\n\n* `abstract_link` — a hyperlink reading “abstract” that leads to the ADS\n  page for the publication, if its `bibcode` is defined.\n* `bold_if_first_title` — a copy of `title`, but with markup to render it in bold\n  if `mypos` is `1`, that is, you are the first author of the item.\n* `citecountnote` — text such as “ [4]” (including a leading space) if the item\n  has 4 ADS citations; otherwise, it is empty.\n* `full_authors` — the full author list, with names separated by commas and\n  non-surnames reduced to initials without punctuation; e.g. “PKG Williams,\n  GC Bower”.\n* `lcite` — a copy of `cite`, but with markup to make it a hyperlink to an\n  appropriate URL for the publication, based on `arxiv`, `bibcode`, `doi`, or\n  `url`.\n* `links_list` — an unordered list containing all the links for this\n  publication: some subset of `abstract_link`, `official_link`, `other_link`, or\n  `preprint_link`, depending on which of those are defined.\n* `month` — the numerical month of publication\n* `official_link` — a hyperlink reading “official” that leads to the DOI\n  page for the publication, if `doi` is defined.\n* `other_link` — a hyperlink leading to the publication’s `url` field. The link\n  text is the value of the `kind` field.\n* `preprint_link` — a hyperlink reading “preprint” that leads to the Arxiv\n  page for the publication, if its `arxiv` is defined.\n* `quotable_title` — a copy of `title` with double quotes replaced with single\n  quotes. This makes it suitable for encasing in double quotes itself. (We don‘t\n  worry about subquotes in the title itself.) Note that the replacement operates\n  on proper typographic left and right quotes; that is, \u003e“\u003c and \u003e”\u003c, but not \u003e\"\u003c.\n* `pubdate` — this is modified to read “{year} {Mon}”, where “{Mon}” is the standard\n  three-letter abbreviation of the month name. The space between the year and the\n  month is nonbreaking.\n* `refereed_mark` — a guillemet (») if the publication has `refereed` equal to `y`;\n  nothing otherwise.\n* `short_authors` — a shortened author list; either “Foo”, “Foo \u0026 Bar”, “Foo,\n  Bar, Baz”, or “Foo et al.”. Only surnames are included. If the\n  [MYABBREVNAME](#myabbrevname-text-) directive has been used, your name (as\n  determined from `mypos`) is replaced with an abbreviated value, so that the\n  author list might read “PKGW \u0026 Bower”.\n* `year` — the numerical year of publication.\n\nThe groups that publications can be sorted into are:\n\n* `all` — absolutely all publications in chronological order\n* `all_rev` — all publications in reverse chronological order\n* `all_formal` — publications without `informal = y`\n* `refereed` — publications with `refereed = y`\n* `refereed_rev` — as above but in reverse chronological order\n* `refpreprint` — publications with `refpreprint = y`\n* `refpreprint_rev` — as above but in reverse chronological order\n* `all_non_refereed` — publications without `refereed = y` *or*\n  `refpreprint = y`\n* `non_refereed` — publications without `refereed = y` *or*\n  `refpreprint = y` *or* `informal = y`\n* `non_refereed_rev` — as above but in reverse chronological order\n* `informal` — publications without `refereed = y` or `refpreprint = y` but\n  with `informal = y`\n* `informal_rev` — as above but in reverse chronological order\n\nIt’s assumed that `refereed = y` and `informal = y` never go together. The\ncombination of `refereed`, `refpreprint`, `non_refereed`, and `informal`\ncaptures all publications.\n\n\nTechnical details: wltool invocation\n------------------------------------\n\nHere are the subcommands supported by the [wltool](wltool) program:\n\n### bootstrap-bibtex {bibtex-file} {your-surname} {output-dir}\n\nThis creates a new set of worklog files, seeding them with publication\ninformation from the BibTeX file `bibtex-file`. You must specify\n`your-surname` so that the system can guess the\n[mypos](#technical-details-publication-processing) field. The output directory\n`output-dir` is created — it may not already exist, to avoid any possibility\nof overwriting existing data.\n\nSearch the created files for `XXX` to find items that will need manual\nattention. Other items should generally be correct, but the output only going\nto be as correct as the input, and things like the `cite` field are generated\nwith crude heuristics.\n\n*Warning:* the tool currently assumes that the BibTeX file in question is of\nthe form generated by [NASA ADS]. Files from other sources will probably not\nparse successfully.\n\n\n### extract {record-type} [datadir=.]\n\nThis is a sort of `grep` for your log files. It merely reads them all in and\nprints out all of the records whose type matches `record-type`. This can be\nuseful for scripting or reminding yourself what fields you used for a certain\nkind of entry.\n\nThe optional argument `datadir` specifies where the log files are; the default\nis the current directory.\n\nExample:\n\n```Shell\n$ ./wltool extract pub\n[pub]\ntitle = An amazing paper\n… lots more output …\n$\n```\n\n### html {template-file} [datadir=.]\n\nFill in the specified `template-file` by processing the directives [described\nbelow](#technical-details-template-directives). The filled-in template is\nprinted to standard output. The output is assumed to be in HTML format; in\nparticular, this means that special characters are encoded in Unicode with\nUTF-8, and certain fancy text effects (making text bold, for instance) are\ndone with HTML tags.\n\nThe optional argument `datadir` specifies where the log files are; the default\nis the current directory.\n\nExample:\n\n```Shell\n$ ./wltool html pubslist.tmpl.html \u003epubslist.html\n$\n```\n\n### latex {template-file} [datadir=.]\n\nOperates exactly as the `html` subcommand, except that the output is assumed\nto be in LaTeX format. Special characters are converted to LaTeX escapes\n(e.g., “α” → “\\alpha”) and text effects are done with LaTeX constructs (e.g.,\n“\\textbf{…}”).\n\nExample:\n\n```Shell\n$ ./wltool html cv.tmpl.tex \u003ecv.tex\n$\n```\n\n### summarize [datadir=.]\n\nPrint out the number of records of each type in your log files.\n\nThe optional argument `datadir` specifies where the log files are; the default\nis the current directory.\n\nExample:\n\n```Shell\n$ ./wltool summarize\n   award: 1\n     job: 2\noutreach: 2\n    prop: 1\n     pub: 10\n    talk: 13\nteaching: 1\n$\n```\n\n### update-cites [datadir=.]\n\nUpdates citation counts for publications from [NASA ADS].\n\nFor each record in the log files with a `bibcode` field, the script connects\nto the ADS API and fetches the number of refereed citations. The log files are\nmodified in-place to have the citation counts inserted into each record in a\nfield called `adscites`. The `adscites` field records the date that citation\ncounts were last checked, and the script won’t update check counts more\nfrequently than once a week.\n\nIn order for this command to work, you must sign up for an ADS account and\n[request an ADS API token](https://github.com/adsabs/adsabs-dev-api#access).\nCreate a plain text file named `ads-token.secret` in the directory containing\nyour `.txt` files and paste your API token into it. This token is a secret, so\nyou should make sure not to track it with any version control system that you\nmay be using. If on a multi-user machine, you should make sure that the file\nis not readable by other users.\n\nAs the updates are conducted, the script will print out each bibcode and the\nchange in the number of citations it has received. Records will be annotated\nwith an asterisk if they’re first-author publications and an “R” if they’re\nrefereed.\n\nThe optional argument `datadir` specifies where the log files are; the default\nis the current directory.\n\nExample:\n\n```Shell\n$ ./wltool update-cites\n2012arXiv1201.5413W *  ... 0 (+0)\n2012PASP..124..624W *R ... 4 (+0)\n2013ApJ...762...85W *R ... 1 (+0)\n2013PASA...30....6M  R ... 12 (+1)\n…\n$\n```\n\n\nTechnical details: template directives\n--------------------------------------\n\nHere are the directives supported by the template processor. Each directive is\nrecognized when it appears at the very beginning of a line in a template. Most\nof the directives take arguments that appear on the same line, separated by\nwhitespace.\n\n### BEGIN_SUBST {group}\n\nMarks the beginning of a region in which text will be substituted. The\nbehavior resembles a [FORMAT](#format-template-text-) directive in that the\nfollowing lines should contain pipe-delimited field names that will be\nsubstituted with computed values. This behavior will continue until a line\ncontaining just the word `END` is encountered.\n\nThe subsitutions are batched into different groups. The available substitution\ngroups [are listed below](#technical-details-substitution-groups).\n\nExample:\n\n```HTML\nBEGIN_SUBST cite_stats\n\u003cp\u003eI may have written only |refpubs| refereed publications, but I assure you\nthat they are all profound.\u003c/p\u003e\nEND\n```\n\n### FORMAT {template text ...}\n\nThis sets the template text that will be used by subsequent\n[PUBLIST](#publist-group), and [RMISCLIST](#rmisclist-type1type2)-variant\ncommands, until a new [FORMAT](#format-template-text-) directive is issued. For\neach record produced by these commands, the template text will be inserted,\nwith field names delimited by pipes (e.g., `|title|`) getting replaced by data\nfrom the records. Missing fields are an error.\n\nNote that this directive (and all others) must appear on a single line, so it\ngets a little awkward if you have a very long piece of template text.\n\nExample:\n\n```TeX\nFORMAT \\item[|date|] |what|\n\n\\begin{enumerate}\nRMISCLIST outreach\n\\end{enumerate}\n```\n\n### MYABBREVNAME {text ...}\n\nThis directive turns on special replacement of your name in short author\nlists; it allows the style of citing your own works as (e.g.) “PKGW \u0026 Bower”\nrather than “Williams \u0026 Bower”. The `text` is this shortened version of your\nname.\n\nThis feature only affects the `short_authors` field of publications;\n`full_authors` is not modified. If you don’t use this directive,\n`short_authors` doesn’t get modified either.\n\nExample:\n\n```\nMYABBREVNAME PKGW\n\n…\n\nFORMAT Short authors: |short_authors|\nPUBLIST all\n```\n\n### PUBLIST {group}\n\nCauses data for a group of publications to be inserted according to the most\nrecently-specified [FORMAT](#format-template-text-) template. The `group` is\none of the “partitions” defined in [the publication processing\nsection](#technical-details-publication-processing). The\n[FORMAT](#format-template-text-) template is inserted once for each\npublication in the specified `group`.\n\nThe template has access to all of the fields defined in your matching `[pub]`\nrecords, as well as the numerous extra fields computed as described in [the\npublication processing section](#technical-details-publication-processing)\n\nExample:\n\n```HTML\nFORMAT \u003cdt\u003e|pubdate|\u003c/dt\u003e\u003cdd\u003e|title|\u003c/dd\u003e\n\n\u003ch1\u003eRefereed publications\u003c/h1\u003e\n\u003cdl\u003e\nPUBLIST refereed_rev\n\u003c/dl\u003e\n```\n\n### TALLOCLIST\n\nCauses information about total resources allocated in proposals to be inserted\naccording to the most recently-specified [FORMAT](#format-template-text-)\ntemplate. The [FORMAT](#format-template-text-) template is inserted once for\neach facility with a successful proposal as PI.\n\nThe fields accessible to the template are:\n\n* `facil` — the facility name, but see below.\n* `total` — the total of the allocations for that facility\n* `unit` — the unit string specified in the proposals for the facility\n\nThe records are sorted alphabetically by `facil`, with the following\nexception. All `facil` names starting with the text `SUMMARY:` are sorted\n*after* the other facilities, and are rendered in italics with the `SUMMARY:`\ntag stripped off. This feature is intended for money awards, which one\ntypically wants to emphasize. A relevant worklog entry might look like:\n\n```\n[prop]\ntitle = My Awesome Science\ndate = 2017/11\npi = P K G Williams\nmepi = y\nfacil = Very Large Array\nrequest = 100 hr\nrequest2 = 100 ks Chandra\naccepted = y\naward3 = 100000 USD SUMMARY:Support funding\n```\n\nExample of the template:\n\n```TeX\nFORMAT |facil| \u0026 |total| \u0026 |unit| \\cr\n\n\\section*{Total Allocations as PI}\n\\begin{tabular}{lrl}\nTALLOCLIST\n\\end{tabular}\n```\n\n### SPLIT_TALLOCLIST {text...}\n\nThis is a giant hack to typeset time allocation lists when space is at a\npremium. It is just like [TALLOCLIST](#talloclist), but you can specify\narbitrary raw text that will be inserted halfway through the list of\nallocations. This can let you break the list of allocations into two\nequal-sized tables, which can then by typeset side-by-side.\n\nExample\n\n```TeX\nFORMAT |facil| \u0026 |total| \u0026 |unit| \\cr\n\n\\section*{Total Allocations as PI}\n\\begin{tabular}{lrl}\nSPLIT_TALLOCLIST \\end{tabular} \\begin{tabular}{lrl}\n\\end{tabular}\n```\n\n### RMISCLIST {type1[,type2,...]}\n\nCauses worklog data to be inserted according to the most recently-specified\n[FORMAT](#format-template-text-) directive. Records matching any of the\ncomma-separated list of `type`s will be output in reversed order, with the\n[FORMAT](#format-template-text-) template being inserted once for each record.\n\nExample:\n\n```TeX\nFORMAT |institution| \u0026 |city| \\cr\n\n\\begin{tabular}{rl}\nRMISCLIST placesilike\n\\end{tabular}\n```\n\n### RMISCLIST_IF {type1[,type2,...]} {gatefield}\n\nThe same as [RMISCLIST](#rmisclist-type1type2), except that matching records\nwill be output only if they have the field named `gatefield` and its value is\nprecisely “y”.\n\nExample:\n\n```TeX\nFORMAT |institution| \u0026 |city| \\cr\n\n\\begin{tabular}{rl}\nRMISCLIST_IF placesilike ilikeit\n\\end{tabular}\n```\n\n### RMISCLIST_IF_NOT {type1[,type2,...]} {gatefield}\n\nThe same as [RMISCLIST](#rmisclist-type1type2), except that matching records\nwill be output only if either they do not have the field named `gatefield`, or\nits value is not precisely “y”.\n\nExample:\n\n```TeX\nFORMAT |institution| \u0026 |city| \\cr\n\n\\begin{tabular}{rl}\nRMISCLIST_IF_NOT placesilike ihateit\n\\end{tabular}\n```\n\n### TODAY.\n\nInserts the current day as “{Mon} {day}, {year}.” Both the directive name and\nthe output include the trailing period! Here `{Mon}` is the three-letter\nabbreviated month name.\n\nExample:\n\n```\nThis document was last updated\nTODAY.\n```\n\n\nTechnical details: substitution groups\n--------------------------------------\n\nHere are the different substitution groups known to the\n[BEGIN_SUBST](#begin_subst-group) directive.\n\n### cite_stats\n\nThese are statistics relating to refereed publications and their citations.\nThe fields within this group are:\n\n* `day` — the numerical day of the month of the median date when citations\n  were updated.\n* `hindex` — your numerical *h*-index.\n* `italich` — a bit of a hack; code for the letter “h” in italics, appropriate\n  for either LaTeX or HTML as needed.\n* `meddate` — the median *Unix time* around which citations were updated.\n* `month` — the numerical month of the median date when citations were updated.\n* `monthstr` — the three-letter abbreviated month of the median date when\n   citations were updated.\n* `refcites` — the total number of citations to refereed publications\n* `reffirstauth` — the total number of refereed first-author publications\n* `refpubs` — the total number of refereed publications\n* `year` — the year of the median date around which citations were updated.\n\n### engagement_stats\n\nThese are statistics relating to public engagement activities. The fields are:\n\n* `n_interviews` — the number of `[engagement]` records with `class = interview`.\n* `n_outreach_events` — the number of `[engagement]` records with `class = outreach_event`.\n* `n_press_releases` — the number of `[engagement]` records with `class = press_release`.\n* `n_public_talks` — the number of `[engagement]` records with `class = public_talk`.\n\n### repo_stats\n\nThese are statistics relating to open-source software contributions. The\nfields within this group are:\n\n* `total_repos` — the total number of tracked repositories.\n* `total_commits` — the total number of commits made by you in all repositories.\n* `primary_author_stars` — the total number of GitHub stars given to repositories\n  in which you are the primary author, which we define as those in which you have\n  made more than 50% of the commits.\n* `primary_author_forks` — the total number of GitHub forks of repositories\n  in which you are the primary author.\n\n### talk_stats\n\nThese are statistics relating to professional talks you have given. The fields\nwithin this group are:\n\n* `n_total` — the total number of talks\n* `n_invited` — the number of talks with `invited = y`\n* `n_conference` — the number of talks with `conference = y`\n\n\nTechnical details: the ini file format\n--------------------------------------\n\nThe [“ini file”][inifile] format is implemented in the\n[inifile.py](inifile.py) module.\n\nEach file is a line-oriented Unicode text file encoded in UTF-8.\n\nAny text in a line at or after a pound sign (`#`) is ignored, except for\nquoted field values as described below.\n\nA line of the form `[.....]{whitespace}` denotes a new record. The text\nbetween the brackets is saved in a field called `section`.\n\nData lines take the form `{field name}{whitespace}={value}`. Field names can be\nanything without spaces, but should take the form of valid Python identifiers.\n\nIf the field value is encased in straight double quotes, the text inside\nthe quotes is stored verbatim. This includes leading and trailing whitespace\nand pound signs.\n\nOtherwise, the field value is constructed from the text after the equals sign,\nplus text on subsequent lines if those lines begin with whitespace. Leading\nand trailing whitespace of the resulting value are removed, and the\nnewline/whitespace combination is replaced with a single space.\n\nExample:\n\n```INI\n# This is a comment\n[pub]\npubdate = 2011/09 # and this\ntitle = This is a somewhat long title and so we wrap it onto\n  the next line\n# But not the next pound sign:\ncite = \"Exciting Committee whitepaper #32\"\nauthors = Peter K. G. Williams\nmyfield = εχαμπλε\nequation = y²×π\n```\n\n\nSystem requirements\n-------------------\n\nThe tools should be broadly portable, but they do have a few requirements:\n\n* Python. Version 2.6 or higher should work. Only standard modules are used.\n* To drive processing with the example [Makefile](example/Makefile), you need\n  command-line access to `pdflatex` and (of course) `make`.\n* The following LaTeX packages are used:\n  * [enumitem](http://www.ctan.org/pkg/enumitem)\n  * [fancyhdr](http://www.ctan.org/pkg/fancyhdr)\n  * [geometry](http://www.ctan.org/pkg/geometry)\n  * [hyperref](http://www.ctan.org/pkg/hyperref)\n  * [lastpage](http://www.ctan.org/pkg/lastpage)\n  * [titlesec](http://www.ctan.org/pkg/titlesec)\n  These should all be available on modern LaTeX installs, and I’ve tried\n  to avoid constructs that aren’t compatible across many versions.\n* To use the GitHub features, you need to install the following Python\n  packages and their dependencies:\n  * httplib2\n  * google-api-python-client\n  * oauth2client\n  * pygithub\n  You also need to generate and save credentials for logging into Google\n  BigQuery, a process I have not yet documented :-(\n\n\nCopyright and license status of this document\n---------------------------------------------\n\nThis work is dedicated to the public domain.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkgw%2Fworklog-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpkgw%2Fworklog-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpkgw%2Fworklog-tools/lists"}