Difference between revisions of "EPrints Glossary"

From EPrints Documentation
Jump to: navigation, search
m (Export plugin)
(Inc file)
Line 216: Line 216:
  
 
=== Inc file ===
 
=== Inc file ===
 +
The ''inc'' file is the critical part of a [[#Flavour|flavour]], which defines the paths that should be included for code and configuration.  It is found in the top-level directory of the flavour (e.g. ''/flavours/pub_lib/inc''). Initially from the first sub-version of [[#EPrints repository software|EPrints]] 3.4 this will be just the path for the flavour (e.g. ''flavours/pub_lib'') but increasingly core [[#Ingredient|ingredients]] will be added to this (e.g. for providing integration with the [[#Bazaar|Bazaar]] or for enabling different JavaScript libraries.  This is the only file outside the [[Archives/ARCHIVEID/|archive's directory structure]] that should need to be modified, unless you have a [[#Site lib|site_lib]].  However, the default inc file will probably not need changing in the case of most [[#Repository|repositories]].
 +
 +
The ordering of paths within the inc file is important, as it determines, which configuration files get loaded an which takes precedence.  If you have a configuration file with the same filename in the ''cfg.d/'' directories for all three paths in the example inc file below, the file in ''site_lib'' will be used in precedence to the other two:
 +
flavours/pub_lib
 +
ingredients/bazaar
 +
site_lib
 +
However, if you also have the same filename is the [[#Archives|archive]]'s ''cfg/cfg.d/'' directory this will take precedence, although only for that archive, if you have a multi-archive repository.
 +
 
=== Indexer ===
 
=== Indexer ===
 
=== Indexer task ===
 
=== Indexer task ===

Revision as of 17:59, 17 March 2022

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

EPrints repository software uses a long list of terminology. Sometimes this terminology overloads existing terminology in similar realms. Other times different terms are used interchangeably to mean the same of similar things. This glossary is intended to help clarify the various terminology you may come across whilst installing, configuring or using EPrints repository software.

A

Abstract page

An abstract page (sometimes referred to as a summary page) is a web page on the repository providing metadata about a particular EPrint (a.k.a publication record). Most prominently it displays the abstract for the publication but also its title, citation links to download associated documents and further metadata in a summary table.

Access

An access is a data object that represent a HTTP request accessing either an abstract page or document.

Admin menu

The admin menu is only accessible to repository admins that provides access to various adminstrative tools to manage their repository.

Advanced search

An advanced search over EPrints in the live archive. Unlike simple search this provides multiple input fields to individually search against particular metadata fields. Advanced search configuration can be found in eprint_search_advanced.pl.

Archive

Often conflated with repository. EPrints repository software provides a repository that can host multiple archives. Commonly a repository will only host a single archive, so the terms are often used interchangeably.

Archive ID

The ID of an archive. This is set by the first input when the archive is created using the bin/epadmin command line tool. This will also be the directory name for the archive under EPrints' archives/ sub-directory. Guides on this wiki often use the placeholder ARCHIVEID.

Archive name

The name of an archive. This is set by an early input when the archive is created using the bin/epadmin command line tool. WHere the value set will be copied as a phrase to the archive's archive_name.xml under archives/ARCHIVEID/cfg/lang/en/phrases/.

B

Bazaar

The Bazaar hosts EPrints packages of functionality (EPMs), which can be installed on a repository via the EPrints Bazaar tool in the Admin web interface.

Bazaar plugin

See EPM.

Box plugin

Branding

Branding refers to the changing of the appearance of the web pages for your repository. Typically to line up with your institutional branding used on its other websites. Advice is available on Branding with confidence. Branding is typically done by editing template configuration files and adding your own bespoke CSS, JavaScript and images/icons. This can be done at an archive level of by creating a theme so it can be applied to multiple archives hosted on the same repository.

Browse view

A browse view is a collection of pages that display menus and listings of for all live archive EPrints in an archive, organised by a particular metadata field. By default these fields are: year, subjects, divisions and creators. All the browse views can be found under the equivalent URL for archive to the following:

https://example.eprints.org/view/

The configuration for browse views can be found in views.pl, which by default is found under flavours/pub_lib/cfg.d/ but should be copied to the archive's cfg/cfg.d/ for editing. See browse views category for more information.

Buffer

Shorthand for Review buffer.

C

Citation

In EPrints repository software a citation means something slightly different from what in means in research publication. For the former it refers to a text string describing a publication, which may more commonly described in research publications as a reference.

EPrints repository software has citation style files, which describe how to generate the text string, not just for EPrints but also other data objects, each of which can have different citation style files for differenyt purposes. These files can be found under lib/citations/. flavours/pub_lib/citations/ and the archive's cfg/citations/ directory.

See here for more information about the citation formats and a training video about citation styles.

Creator

Creator (or creators) is a Metadata field for an EPrint. Sometimes this is alternatively referred to as author but creator is a more generic term better suited to audiovisual/artistic as well as more traditional research publication items.

A creator typically has several separate sub-fields:

  • Given name (a.k.a. first name)
  • Family name (a.k.a. surname)
  • ID (typically email address)

CRUD API

CRUD API (Create, Read, Update Delete Application Programming Interface) refers to a programmatic interface used for the management of data objects. It is often also referred to as the REST API as when it is called over HTTP it meets the requirements of a REST API.

Contact page

This is a static page that is accessible on an archive at the equivalent URL to the following:

https://example.eprints.org/contact.html

This page is intended to provided contact information, so to those accessing the archive can contact those responsible for it to report problems or ask questions.

This page can be found at EPRINTS_PATH/lib/lang/en/static/contact.xpage but should be copied to the archive's cfg/lang/en/static/ directory for editing. The email address displayed on this page comes from the $c->{adminemail} in adminemail.pl.

Contributor

Sometimes an EPrint has a contributor who could not usefully be described as a creator or editor. The contributor metadata field is intended to allow these people to be associated with the EPrint. As well as being able to add the contributor's family and given name, the type of contributor can be specified. This list of types is defined in EPRINTS_PATH/lib/namedsets/contributor_type. If additional types are needed, then this file should be copied to the archive's cfg/namedsets/ directory for editing.

D

Data flavour

As of EPrints 3.4 there are different flavours to service different purposes for a [[#Repository|repository]. The data flavour is intended for repository hosted research data items, as opposed to research publications.

Data object

A data object is a single record made up of metadata fields. EPrints repository software has various types of data object. The most prominent are:

All the data objects of the same type make a dataset.

Dataset

A dataset is all the data objects of a particular type within a single repository. (E.g. eprint, user, document, etc.). Virtual datasets exist for subsets of datasets such as live archive, review buffer, etc.

Depositing user

This is the user who created the EPrint and has deposited it to the review buffer.

Document

A document is a second class Data object in EPrints repository software. Documents must be part of an eprint object. Sometimes the term is used interchangeably with the actual document file (e.g. a PDF, Word document, etc.). To avoid confusion, it is best to refer to a document within EPrints as a "document object". A document object can be associated with multiple file objects. Typically because derived files are generated to provide preview and thumbnail image but also because multiple files can be uploaded for a single document object.

Document content

Document content is a metadata field for the document object. It allow selections of a single value from a pre-defined list (i.e. a namedset) metadata field. The options provided are intended to help describe the version of the document (e.g. draft, submitted version, accepted, updated) within the publication lifecycle or other types of content that may be uploaded (e.g. supplemental, presentation, coverimage, metadata, bibliography, other). These are based on the Versions toolkit for authors but are analogous to other definitions, such as:

  • Author's Original Manuscript (AOM) is equivalent to submitted.
  • Accepted Manuscript (AM) is equivalent to accepted.
  • Version of Record (VoR) is equivalent to published.

Document security

Document security is a metadata field for the document object. It defines who can access document file and any files in derived document objects (e.g. preview images). By default this is one of three values:

If one of the last two option is applied with an embargo that expires on a certain date, then the security value for that document will be updated to public on that date.

Documents directory

This is a directory found under the archive's directory structure, (i.e. EPRINTS_PATH/archives/ARCHIVEID/documents/). This is where the uploaded documents for an eprint are stored under the latter's own sub-directory (e.g. eprint 1234 has documents sub-directory documents/00/00/12/34/). Each document is stored in its own two-digit sub-directory based on its pos metadata field, which is zero-padded if the number is less than 10. The sub-directory also stores derived "documents" for those uploaded (e.g. preview and thumbnail images). It also stores revision files in the eprint's own revisions sub-directory.

E

Editor

On EPrints repository software editor could refer to one of two different things:

  1. A type of EPrints user that has permissions to access some or all publication items in the review buffer to make ammendments and either push the item to the live archive or return it to the user's workarea.
  2. A metadata field in the eprint data object to record editors of the publication, e.g. the editors for a book. Like creator, by default this field has family name, given name and ID (i.e. email address) sub-fields.

Education flavour

Embargo

Documents added to an EPrint can have their access restricted. Sometimes this access need only be restricted for a set amount of time. These documents can be embargoed until a set embargo date. These can then be lifted of this date using thge bin/lift_embargos script. More recently embargoes allow a reason to be chosen from a pre-determined set of options provided by the embargo_reason named set].

EPM

EPM (EPrints Package Manager) is a package of functionality, sometimes referred as a Bazaar plugin, which can be installed in an automated fashion, typically from the Bazaar. It can sometimes refer to the pages for managing the installing of these packages, (e.g. the EPrints Bazaar page available through the Admin web interface).

EPrint

An EPrint is a first class Data object in EPrints repository software. These are often referred to as items or publication records, as they usually hold metadata about a publication of some kind.

EPrint locking

Whilst a user is editing an EPrint it is best that another user does not try to edit it as well. When an EPrint is locked even permitted users will not be able to edit the record unless they remove the edit lock. Locks are automatically released when a user saves or cancels editing an EPrint or (by default) 1 hour after the user started editing the EPrint.

EPrint revision

An EPrint revision is a numbered version of the eprint's metadata stored in the rev_number metadata field. Revisions of eprints metadata are exported as XML revision files and stored under the documents directory of the archive.

EPrint status

The status of an eprint represent the stage it is in the depositing lifecycle. By default in EPrints repository software this can be one of four states:

  1. User workarea - The eprint is still being edited by the depositing user as there is still metadata they need to add or change.
  2. Review buffer - The eprint has been submitted for review by an editor for the archive.
  3. Live archive - The eprint has been reviewed by the editor and they have deposited it into the live archive for public access.
  4. Retired - The eprint has been removed from the live archive as it is not longer appropriate for it to have public access.

EPrint type

This is the type of publication the eprint represents. The available types for a repository are specified in a namedsets file. ( lib/namedsets/eprint or flavours/pub_lib/namedsets/eprint) or can be copied to the archive's archives/ARCHIVEID/cfg/namedsets/ directory to add extra types for a specific archive. By default EPrints' publication flavour has the following type options:

article
book_section
monograph
conference_item
book
thesis
patent
artefact
exhibition
composition
performance
image
video
audio
dataset
experiment
teaching_resource
other

Type is by default presented on the first stage of the EPrint workflow, as the option chosen will affect the fields that can/need to be completed in later stages.

EPrint URI

The URI for an eprint is its globally unique identifier. In a form like:

http://example.eprints.org/id/eprint/1234

Technically, a URI only need be an identifier and therefore not return the resource itself. However, in the case of EPrints repository software, this will return the resource. Prior to EPrints 3.4, this would be by redirecting to the eprint URL but since then the publication flavour uses the same string for the eprints URL and URI with the old style URL redirecting the the longer URI format URL.

EPrint URL

The URL of an eprint is the location it can be found at on the World Wide Web. Historically with [[#EPrints repository software|EPrints repository software] it has taken a form like:

http://example.eprints.org/1234/

However, since EPrints 3.4, it has been possible to configure the URL to take a long format like that of the eprint URI:

http://example.eprints.org/id/eprint/1234

By using the following setting (typically in the archive's cfg/cfg.d/20_baseurls.pl):

$c->{use_long_url_format] = 1;

By making this change the old style URL will still work but will redirect to the new format. The reason for the change was to make it more apparent that the URL represented a publication within EPrints repository. Web crawlers and bots often record links (i.e. URLs) they find on web pages but they don't actually access them. In particular Google Scholar would disregard these URLs without checking them, as there was nothing from the URL to indicate they represented a publication. By adding /id/eprint/ into the URL it makes it the URL distinct from other common URLs of the form http://HOSTNAME/ID, which are mostly not URLs for EPrints abstract pages.

EPrints repository software

Often shortened to just EPrints but not to be confused with multiple EPrint data objects. The actual software that can be used to create Open Access repositories and available as Open Source from GitHub.

EPrints path

The path on your operating system under which EPrints repository software is installed. Guides on this wiki often use the placeholder EPRINTS_PATH to represent this. Typically EPrints path will either be /opt/eprints3/ or /usr/share/eprints/ depending on how installed EPrints repository software was installed.

EPrints release

A release of the EPrints repository software.

EPrints version

Same as EPrints release but with specific reference to a version number.

Event plugin

A type of plugin that generates Indexer tasks to get the indexer to perform some asynchronous and potential long-running task.

Event queue

The event queue contains all generated and yet to be successfully completed indexer tasks. It can be accessed through the admin web interface's System tools tab using the Status button and then clicking on the number next to the Background Task Queue. There is also the Event Queue Object, which is a data object to represent an individual indexer task.

Export plugin

This is a plugin designed to provide a formatted export of a data object's metadata, typically for an eprint. By default, EPrints repository has export plugins for many different formats, which can be found in the perl_lib/EPrints/Plugin/Export/ and flavours/pub_lib/plugins/EPrints/Plugin/Export/ directories. Bespoke export plugins can also be added to the archive's cfg/plugins/EPrints/Plugin/Export/ directory or may be installed from the EPrints Bazaar into the lib/plugins/EPrints/Plugin/Export/ directory.

F

File

A file is a third-order data object. This is because it is a sub-object of a document data object, which in turn is a sub-object of an eprint data object. A file data object store metadata relevant to the file such as its filename, size, MIME type and modified time and a hash (by default Md5) to maintain the integrity of the file. Typically uploading a document to an eprint will only create a single data object but it is possible to add additional files to a document after it is uploaded.

File data objects are also used to capture XML revision files created for the eprint's history.

Flavour

From version 3.4 of EPrints repository software different flavours have been introduced. EPrints was originally designed as a repository for research publications but over the years it has been repurposed for different tasks, which has led to the codebase getting a little messy. So in EPrints 3.4 a separate sub-directory structure was created to store code and configuration that makes EPrints suitable for a particular task, (i.e. a flavour). There are three main flavours but most development has continued to focus on research publication:

  1. Publications flavour - For research publications. Provided in flavours/pub_lib/.
  2. Data flavour - For research data. Provided in flavours/data_lib/.
  3. Education flavour - For Open Education, i.e. teaching materials. Provided in flavours/edu_lib/.

As well as flavours in EPrints 3.4, there are also ingredients, which provide additional functionality, similar to a Bazaar plugin / EPM. Any EPrints flavour has an inc file found in its top-level directory (e.g. flavours/pub_lib/inc). This tells the flavour which paths to include. By default, this would include the flavour itself. It may also contain various ingredients and potential site lib if the [#Repository|repository]] has multiple [#Archive|archives]], which require the same bespoke functionality. However, it is better if this bespoke functionality can be converted into ingredients to separate out discrete parts of functionality.

G

H

History

This page refer to eprint history or user history both make reference to changes between EPrint revisions.

Homepage

The homepage for an archive is found at the top-level URL for a repository. Usually, that is something like:

https://example.eprints.org/

The homepage is a static page although often contains dynamic elements, like the list of latest publications. By default, the file is located at either lib/lang/en/static/index.xpage or flavours/pub_lib/lang/en/static/index.xpage with the latter taking precedence if it exists. Configuration for the archive ensure this page display bespoke information for your archive such as the archive name. However, you will most likely want to make changes to your homepage, so you should copy the appropriate index.xpage to your archive's cfg/lang/en/static/ directory, creating the directory if it does not already exist.

I

Import plugin

This is a plugin designed to provide a formatted import of metadata for a data object, typically for an eprint. By default, EPrints repository has import plugins for numerous different formats, which can be found in the perl_lib/EPrints/Plugin/Import/ and flavours/pub_lib/plugins/EPrints/Plugin/Import/ directories. Bespoke import plugins can also be added to the archive's cfg/plugins/EPrints/Plugin/Import/ directory or may be installed from the EPrints Bazaar into the lib/plugins/EPrints/Plugin/Import/ directory.

Inbox

Same as User workarea.

Inc file

The inc file is the critical part of a flavour, which defines the paths that should be included for code and configuration. It is found in the top-level directory of the flavour (e.g. /flavours/pub_lib/inc). Initially from the first sub-version of EPrints 3.4 this will be just the path for the flavour (e.g. flavours/pub_lib) but increasingly core ingredients will be added to this (e.g. for providing integration with the Bazaar or for enabling different JavaScript libraries. This is the only file outside the archive's directory structure that should need to be modified, unless you have a site_lib. However, the default inc file will probably not need changing in the case of most repositories.

The ordering of paths within the inc file is important, as it determines, which configuration files get loaded an which takes precedence. If you have a configuration file with the same filename in the cfg.d/ directories for all three paths in the example inc file below, the file in site_lib will be used in precedence to the other two:

flavours/pub_lib
ingredients/bazaar
site_lib

However, if you also have the same filename is the archive's cfg/cfg.d/ directory this will take precedence, although only for that archive, if you have a multi-archive repository.

Indexer

Indexer task

Ingredient

Issue

Item

Same as EPrint.

J

K

L

Latest tool

License

Sometimes spelt licence.

Live archive

M

Metadata

Metadata field

N

Named set

O

OAI-PMH

Order key

P

Plugin

These are Perl modules that "Plug in" to the EPrints software to provide a particular piece of functionality. Default plugins for EPrints repository software can be found under the [perl_lib/EPrints/Plugin/] and [flavours/pub_lib/plugins/EPrints/Plugin/]] directories They break down into several categories. The most prominent being:

Other plugin categories include Box, Convert, Event, InputForm, Issues, Search and Storage.

Bespoke plugins can be written for an archive and located in the archive's cfg/plugins/EPrints/Plugin/ directory.

Often the term "Bazaar plugin" is used to refer to a package of functionality (a.k.a. EPM) that can be installed from the Bazaar. Although an EPM can often contain individual plugins, it is a complex set of files rather than a single plugin file. If an EPM does contain individual plugins, they will be installed to the lib/plugins/EPrints/Plugin/ directory.

Phrase

Policies page

Publication flavour

Publication record

Same as EPrint.

Q

R

Repository

Repository admin

Request

Request copy

REST API

Retired

Review buffer

Revision

Often used as shorthand for EPrint revision.

Revision file

S

Saved search

Screen plugin

Simple search

A simple search over EPrints in the live archive. Unlike advanced search this provides a simgle input field to search against multiple metadata fields. Simple search configuration can be found in eprint_search_simple.pl.

Site lib

Staff search

Search across all EPrints whatever their EPrint status. See Admin/Editorial Tools/Search items for more information.

Static page

Subject

Subject tree

Succeeds

Summary page

Same as Abstract page. Sometimes even referred to as the abstract/summary page.

Summary table

A table on an Abstract page that lists the names and values for specific Metadata fields for the EPrint. These can be specified, typically in the archive's cfg/cfg.d/eprint_render.pl, under $c->{summary_page_metadata}.

Sword API

T

Template

Theme

U

User

A User is a first class Data object in EPrints repository software. It represent a user of Repository and provides an account under which that user can login. Storing metadata about that user, such as their username, given and family names, email address, department, etc.

User history

User review scope

User search

A form for searching across the users in a repository. See here for more information.

User profile

A page displaying the metadata about a user. This often links to a page where these metadata can be modified.

User workarea

This is the status of an EPrint whilst it is being edited by the depositing user. This status is often also referred to as Inbox. User workarea can sometimes refer to the Manage deposits page where the current user can see a listing of all the EPrints they have created.

V

Volatile field

W

Workflow

X

Xapian search

Y

Z