README

An ARCHE dissemination service providing mapping of resource's metadata to the BibLaTeX and CSL-JSON bibliographic entries.

Installation

Run in the webserver docroot:

composer require acdh-oeaw/arche-biblatex
ln -s vendor/acdh-oeaw/arche-biblatex/index.php index.php
cp vendor/acdh-oeaw/arche-biblatex/config-sample.yaml config.yaml

Adjust config.yaml

Usage

http://deploymentUrl/?id=url-encoded-arche-resource-identifier

Optional query parameters:

lang=two-letters-language-code - preferred labels language, e.g. lang=en
override=biblatex-bibliographic-entry-or-csl-json-entry - allows to manually override and/or add output fields. The format is autodetected and is independent of the output format (e.g. you can provided a CSL-JSON override while requesting the entry in the BibLaTeX format).
format=desired-reponse-format - application/x-bibtex - default, application/vnd.citationstyles.csl+json or application/json

Override rules

The base entry is created in the CSL according to the mapping provided in the config.yaml. The mapping is chosen based on the ARCHE resource RDF class.
Then overrides comming from the ARCHE resource metadata property specified by the config.yaml->biblatex->overrideProperty configuration option are applied. If the override is provided in the BibLaTeX format, it is first converted to the CSL according to the config.yaml->biblatex->biblatexToCsl mapping rules.
Finally overrides comming from the override request parameter are applied. If the override is provided in the BibLaTeX format, it is first converted to the CSL according to the config.yaml->biblatex->biblatexToCsl mapping rules.

Details

All bibliographic entry information including entry type and citation key are overriden. If you want to provide override values in the BibLaTeX format but preserve the entry type and/or citation key use the following syntax:
- either use the "magic" NOOVERRIDE type/citation key value, e.g.
```
@NOOVERRIDE{NOOVERRIDE,
  fieldToOverride = {overriding value},
}
```
- or provide just BibLaTeX fields skipping the bibliographic entry header (and the final curly bracket), e.g.
```
fieldToOverride = {overriding value},
```
If you want a field to be skipped from the output, override it with an empty value.

Example

Compare the output for the sample resource (https://hdl.handle.net/21.11115/0000-000E-753C-C).
(please note the same data which are provided in the override request parameter below can be also provided in the "custom citation" resource metadata property)

Default: https://arche-biblatex.acdh.oeaw.ac.at/?lang=en&id=https%3A%2F%2Fhdl.handle.net%2F21.11115%2F0000-000E-753C-C`
With entry type set to book but citation key preserved, author field overrided with a new value as well as booktitle and bookauthor fields removed: https://arche-biblatex.acdh.oeaw.ac.at/?lang=en&id=https%3A%2F%2Fhdl.handle.net%2F21.11115%2F0000-000E-753C-C&override=%40book%7BNOOVERRIDE%2C%0A%20%20author%20%3D%20%7BDoe%2C%20John%7D%0A%2C%20%20booktitle%20%3D%20%7B%7D%2C%20bookauthor%20%3D%20%7B%7D%2C%0A%7D
The non-URL-encoded override parameter value () used here is:
```
@book{NOOVERRIDE,
  author = {Doe, John},
  booktitle = {},
  bookauthor = {},
}
```
With author field overrided with a new value as well as booktitle and bookauthor fields removed. As automatically created entry type and citation key are to be kept, a short syntax skipping the BibLaTeX entry header is used. https://arche-biblatex.acdh.oeaw.ac.at/?lang=en&id=https%3A%2F%2Fhdl.handle.net%2F21.11115%2F0000-000E-753C-C&override=author%20%3D%20%7BDoe%2C%20John%7D%0A%2Cbooktitle%20%3D%20%7B%7D%2Cbookauthor%20%3D%20%7B%7D%2C The non-URL-encoded override parameter value () used here is:
```
author = {Doe, John},  
booktitle = {}, 
bookauthor = {},
```

Docker deployment

The build/docker directory contains a Dockerfile defining a runtime environment for the service.

It takes one build argument VARIANT which can be either production or development and affects the PHP ini settings - see the Configuration section of the https://hub.docker.com/_/php.

It expects all the service files (including composer libraries and the desired config.yaml) to be provided in build/docroot during the build time.

For a live development you can just build it with an empty build/docroot directory and mount service files during docker run.

Examples:

Creating a production image

# install dependencies skipping development ones and optimizing autoloader
composer update --no-dev -o
# prepare the docroot using build/config/arche.yaml as the config.yaml
mkdir build/docroot && cp -R index.php src vendor build/docroot/ && cp build/config/arche.yaml build/docroot/config.yaml
# build the image
docker build --rm -t acdhch/arche-biblatex --build-arg VARIANT=production build
# try to run it locally
docker run -d --name arche-biblatex -p 80:80 acdhch/arche-biblatex
# check if it works locally
curl -i 'http://127.0.0.1/?id=https%3A%2F%2Fid.acdh.oeaw.ac.at%2Fgtrans'
# push the image to the registry
docker push acdhch/arche-biblatex
# redeploy on ACDH Kubernetes
curl -X POST 'https://rancher.acdh-dev.oeaw.ac.at/v3/project/{pathToDesiredWorkload}?action=redeploy' -H 'Authorization: Bearer {myRancherApiToken}'

Creating a development image and running it locally

# install dependencies
composer update
# prepare an empty docroot
mkdir build/docroot
# build the image
docker build --rm -t acdhch/arche-biblatex:dev --build-arg VARIANT=development build
# run the image using current directory as a docroot making it available on local port 8080
docker run -d --name arche-biblatex -p 8080:80 -v `pwd`:/var/www/html acdhch/arche-biblatex:dev
# check if it works
curl -i 'http://127.0.0.1:8080/?id=https%3A%2F%2Fid.acdh.oeaw.ac.at%2Fgtrans'

acdh-oeaw / arche-biblatex

Maintainers

Details

README

Installation

Usage

Override rules

Details

Example

Docker deployment