/usr/share/doc/xapers/SOURCES.txt is in xapers 0.7.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 | = SOURCES =
A Xapers "source" is a python module that describes how to interact
with a single online journal database, from which document files and
bibliographic data can be retrieved.
Sources are assigned unique prefixes (e.g. "doi"). Online libraries
associate unique document identifiers to individual documents
(e.g. "10.1364/JOSAA.29.002092"). A particular online document is
therefore described by a unique "source identifier", or "sid", which
can take two equivalent forms:
full URL http://dx.doi.org/10.1364/JOSAA.29.002092
<source>:<id> doi:10.1364/JOSAA.29.002092
== CUSTOM SOURCE MODULES ==
Custom source modules may be written to extend the base functionality
of Xapers. A source module is described by a single python module
(although it may import arbitrary other modules). The base name of
the module file is interpreted as the nickname or 'prefix' for the
source (e.g. if the module is named "doi.py" the source nickname will
be "doi").
The module should include the following properties and functions. If
any are missing, some xapers functionality may be undefined.
description: a brief string description of the source, e.g.:
description = "Digital Object Identifier"
url: base URL of source, e.g.:
url = 'http://dx.doi.org/'
url_format: a printf format string that produces a valid source URL
for a specified source identifier string, e.g.:
url_format = 'http://dx.doi.org/%s'
url_regex: a regular expression string that will match the source
identifier string from a given full URL, e.g.:
url_regex = 'http://dx.doi.org/(10\.\d{4,}[\w\d\:\.\-\/]+)'
scan_regex: a regular expression string that will match the source
identifier string in a scan of a documents plain text, e.g.:
scan_regex = '(?:doi|DOI)[\s\.\:]{0,2}' + id_regex
fetch_bibtex(id): a function that will return a bibtex string for a
source document specified by id.
fetch_file(id): a function that will return a (file_name, file_data)
tuple for a source document specified by id. File should be in
PDF format.
If your source does not provide bibliographic data directly in bibtex
format, the xapers.bibtex module has several helper functions for
creating bibtex strings from python dictionaries (data2bib) or json
objects (json2bib).
See existing source module contributed with the xapers source as
examples (lib/xapers/sources/).
== SOURCE MODULE PATH ==
Once a custom source module has been created, place it
~/.xapers/sources. The module path can be overridden with the
XAPERS_SOURCE_PATH environment variable, which can be a
colon-separated list of directories to search for modules.
== TESTING ==
Once a module is in place, use the xapers source* commands (sources,
source2url, source2bib, source2file) to test it's functionality. Your
new module should show up in the source listing with the "sources"
command, and should be able to print the relevant data with the other
commands.
== CONTRIBUTING ==
If you think your module is stable and of general usefulness to the
community, please consider contributing it upstream. Thanks!
|