acl-anthology

ACL Anthology

This repository contains:

• Metadata for all papers, authors, and venues on the ACL Anthology website.
• Code and instructions for generating the website.
• A Python package for accessing the metadata, also available on PyPI.

The official home of this repository is https://github.com/acl-org/acl-anthology.

Using the acl-anthology Python package

Please see the separate README for the Python package for detailed information.

Generating the Anthology website

These are basic instructions on generating the ACL Anthology website as seen on https://aclanthology.org/.

Prerequisites

To build the Anthology website, you will need:

• uv, the Python package manager
• Hugo 0.160.0 or higher (can be downloaded directly from their repo; the extended version is required!)
• Dart Sass, a CSS extension that is needed by Hugo.
• bibutils for creating non-BibTeX citation formats (not strictly required to build the website, but without them you need to invoke the build steps manually as laid out in the detailed README)

Building and deployment with GitHub

There is a GitHub actions action performing deployment directly from GitHub. To use this, you need to define this variable in your repository settings (web interface: settings -> secrets):

• PUBLISH_SSH_KEY: the secret key in standard pem format for authentication (without a passphrase)

GitHub will then automatically build and deploy the current master whenever the master branch changes. This is done via the upload target in the Makefile.

Cloning

Clone the Anthology repo to your local machine:

$ git clone https://github.com/acl-org/acl-anthology

Generating

Provided you have correctly installed all requirements, building the website should be as simple running make from the directory to which you cloned the repo.

The fully generated website will be in build/anthology afterwards. If any errors occur during this step, you can consult the detailed README for more information on the individual steps performed to build the site. You can see the resulting website by launching a local webserver with make serve, which will serve it at http://localhost:8000.

Note that building the website is quite a resource-intensive process; particularly the last step, invoking Hugo, uses about 18~GB of system memory. Building the anthology takes about 10 minutes on a laptop with an SSD.

(Note: This does not mean you need this amount of RAM in your system; in fact, the website builds fine on a laptop with 8 GB of RAM. The system might temporarily slow down due to swapping, however. The figure of approx. 18 GB is the maximum RAM usage reported when running hugo --minify --stepAnalysis.)

The anthology can be viewed locally by running hugo server in the hugo/ directory. Note that it rebuilds the site and therefore takes about a minute to start.

Hosting a mirror of the ACL anthology

First, creating a mirror is slow and stresses the ACL Anthology infrastructure because on initial setup you have to download every single file of the Anthology from the official webserver. This can take up to 8 hours no matter how fast your connection is. So please don’t play around with this just for fun.

If you want to host a mirror, you have to set two environment variables:

• ANTHOLOGY_PREFIX the http prefix your mirror will be reachable under e.g. https://example.com/my-awesome-mirror or http://aclanthology.lst.uni-saarland.de (Notice that there is no slash at the end!)
• ANTHOLOGYFILES the directory under which papers, attachments etc. will reside on your webserver. This directory needs to be readable by your webserver (obviously) but should not be a subdirectory of the anthology mirror directory.

With these variables set, you run make to create the pages and make mirror to mirror all additional files into the build/anthology-files directory. If you created a mirror before already, it will only download the missing files.

If you want to mirror the papers but not all attachments, you can run make mirror-no-attachments instead.

You then rsync the build/website/ directory to your webserver or, if you serve the mirror in a subdirectory FOO, you mirror build/website/FOO. The build/anthology-files directory needs to be rsync-ed to the ANTHOLOGYFILES directory of your webserver.

As you probably want to keep the mirror up to date, you can modify the shell script bin/acl-mirror-cronjob.sh to your needs.

You will need this software on the server

• rsync
• git
• python3 > 3.11.0
• hugo >= 0.160.0
• python3-venv

Note that generating the anthology takes quite a bit of RAM, so make sure it is available on your machine.

PDF Watermark / Footer Tool

The Anthology includes a tool at https://aclanthology.org/watermark.html for adding an ACL-style first-page footer and optional page numbers to a PDF.

Components:

• hugo/content/watermark.md and hugo/layouts/_default/watermark.html render the client interface at /watermark.html.
• hugo/static/js/watermark.js handles the preview, upload, and download.
• hugo/static/cgi-bin/watermark.cgi validates the request and invokes the PDF processor.
• hugo/static/cgi-bin/add_footer_to_pdf.py adds the footer and page numbers. It supports multi-line centered text and inline italics using <i>…</i>. bin/add_footer_to_pdf.py is a symlink to it, for command-line use.

Setup:

1. Create a Python 3.11 or newer virtual environment at /opt/venv/watermark.
2. Install the service dependencies with /opt/venv/watermark/bin/pip install -r bin/requirements-watermark.txt.
3. Configure the web server to execute hugo/static/cgi-bin/watermark.cgi as CGI. add_footer_to_pdf.py sits beside the CGI script; set WATERMARK_ADD_FOOTER to an explicit path when using another deployment layout.

A file-only development server such as python -m http.server can display the page but cannot process its form; POST requests will receive HTTP 501. End-to-end testing requires a CGI-capable server.

Usage:

1. Upload a PDF and enter the first-page footer. Press Enter for new lines and use <i>…</i> for italics.
2. Optionally set the first page number and adjust the bottom offset, font sizes, or line spacing to match the original proceedings.
3. Select Generate PDF to download *.watermarked.pdf.

Server / security notes:

• The client and server enforce a 25 MB PDF limit.
• The CGI endpoint accepts only bounded multipart/form-data requests, checks the PDF header, validates all numeric options, and limits footer text to 2,000 characters and eight lines.
• Footer markup is restricted to balanced <i> tags and text supported by the PDF font.
• Each request uses a temporary directory that is removed on success or error; uploaded and generated PDFs are not retained.
• Processing diagnostics are written to the server log. Public errors do not include command lines or subprocess output.

Contributing

If you’d like to contribute to the ACL Anthology, please take a look at:

• our Github issues page
• the detailed README which contains more in-depth information about generating and modifying the website.

History

This repo was originally wing-nus/acl and has been transferred over to acl-org as of 5 June 2017.

License

The code for building the ACL Anthology is distributed under the Apache License, v2.0.