Mentions légales du service

Skip to content
Snippets Groups Projects
Select Git revision
  • master default
  • singlefile
  • biblatex
  • licencelist
  • review-contribs
  • moranegg
  • bltx-v1.2-6
  • bltx-v1.2-5
  • bltx-v1.2-4
  • bltx-v1.2-3
  • bltx-v1.2-2
  • bltx-v1.2-1
  • bltx-v1.2
  • bltx-v1.1
  • bltx-v1.0
  • bltx-v0.9
  • bltx-v0.8
  • premerge
  • bltx-v0.7
  • usedatamodel
  • bltx-v0.6
  • bltx-v0.5
  • bltx-v0.4
  • bltx-v0.3
  • bltx-v0.2
  • sentforreview
26 results
Blame Permalink
swentry.org 11.42 KiB

Proposal for software entries for BibTeX/BibLaTeX\therevision

Motivation

BibTeX is used widely in the scholarly world as a format for storing and exchanging bibliographic data that can be used to produce bibliographic references: several platforms propose a BibTeX export of their metadata, including HAL, and at Inria, for example, this is used to generate activity reports for all the teams.

This working document contains a proposition for the creation of BibTeX entries for software artifacts.

Entry types

There are four entry types, corresponding to different granularities in the identification of the (part of) software artifacts that one whishes to cite. They are listed below in order of granularity.

software

Computer software.

Required fields: author / editor, title, url, year

Optional fields: abstract, date, doi, file, hal_id, institution, license, month, note, organization, publisher, related, relatedtype, relatedstring, repository, swhid, urldate, version

softwareversion

A specific version of a software. Inherits values of missing fields from the entry mentioned in the crossref field.

Required fields: author / editor, title, url, version, year

Optional fields: abstract, crossref, date, doi, file, hal_id, institution, introducedin, license, month, note, organization, publisher, related, relatedtype, relatedstring, repository, swhid, subtitle, urldate

softwaremodule

A specific module of a larger software project. Inherits values of missing fields from the entry mentioned in the crossref field.

Required fields: author, subtitle, url, year

Optional fields: abstract, crossref, date, doi, editor, file, hal_id, institution, introducedin, license, month, note, organization, publisher, related, relatedtype, relatedstring, repository, swhid, title, urldate, version

codefragment

A code fragment (e.g. a specific algorithm in a program or library). Inherits values of missing fields from the entry mentioned in the crossref field.

Required fields: url

Optional fields: author, abstract, crossref, date, doi, file, hal_id, institution, introducedin, license, month, note, organization, publisher, related, relatedtype, relatedstring, repository, swhid, subtitle, title, urldate, version, year

The softwareversion, softwaremodule and codefragment entries can inherit the missing fields from another entry designated by the crossref field, which is expected to be higher in the granularity hierarchy: softwareversion may inherit from a software entry, softwaremodule may inherit from a softwareversion or a software entry, and codefragment may inherit from all other entries.

Field description

The field description is based on the biblatex documentation

Data fields

abstract
field (literal). This field is intended for recording abstracts in a bib file, to be printed by a special bibliography style. It is not used by all standard bibliography styles.
author
list (name). The authors of the title.
date [biblatex only]
field (date). The date of creation or release in ISO format.
editor
list (name). The coordinator(s) of large modular software projects.
file
field (verbatim). A local link to a version of the work. Not used by the standard bibliography styles. Replaces PDF.
doi
field (verbatim). The Digital Object Identifier of the work.
hal_id [not in biblatex]
field (verbatim). A digital identifier for the software record including its description and metadata on HAL.
license [not in biblatex]
list (literal). The license/s of the title in SPDX format.
month
field (literal). The month of creation or release. In BibLaTeX, this must be an integer, not an ordinal or a string. For compatibility with BibTeX, one can also use the three letter abbreviations jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec, which must be given without any braces or quotes.
note
field (literal). Release note of the cited version.
institution
field (literal). The institution(s) that took part in the software project.
introducedin [not in biblatex]
field (literal). If this is a software module or fragment, the version of the containing project where it has been first introduced.
organization
field (literal). The organization(s) that took part in the software project.
publisher
list (literal). The name(s) of the publisher(s) of the software record (we need to define the notion of a research software publisher, see issue #2).
related [biblatex only]
field (separated values). Citation keys of other entries which have a relationship to this entry.
relatedtype [biblatex only]
field (identifier).
relatedstring [biblatex only]
field (literal).
repository [not in biblatex]
field (uri). The url of the code repository (e.g on GitHub, GitLab).
swhid [not in biblatex]
field (verbatim). The identifier of the digital object (a.k.a the software artifact itself). The intrinsic identifier of the item is an swh-id (swh:cnt for a content, swh:dir for a directory, swh:rev for a revision, swh:rel for a release, etc.). See the SWH-ID specification.
subtitle
field (literal). The title of a component of the software artifact.
title
field (literal). The title of the software artifact.
url
field (uri). The url of an online resource (e.g the project’s official webpage).
urldate
field (date). The access date of the address specified in the url field.
version
field (literal). The revision number of a piece of software, a manual, etc.
year
field (literal). The year of creation or release.

Special fields

crossref
field (entry key). This field holds an entry key for the cross-referencing feature. Child entries with a crossref field inherit data from the parent entry specified in the crossref field.

Examples

Here are a few example of use of the proposed entries.

software and softwareversion

This is an example description of a software release using a single @software entry.

@software {delebecque:hal-02090402,
  title = {{Scilab 1.1}},
  author = {Delebecque, Fran{\c c}ois and Gomez, Claude and Goursat, Maurice 
    and Nikoukhah, Ramine and Steer, Serge and Chancelier, Jean-Philippe},
  url = {https://hal.inria.fr/hal-02090402},
  year = {1994},
  month = jan,
  file = {https://hal.inria.fr/hal-02090402/file/scilab-1.1.tar.gz},
  institution = {Inria},
  license = {Scilab license},
  hal_id = {hal-02090402},
  swhid = {swh:1:dir:1ba0b67b5d0c8f10961d878d91ae9d6e499d746a},
  version = {1.1},
  note = {First Scilab version. It was distributed by anonymous ftp.},
  repository= {https://github.com/scilab/scilab},
  abstract = {Software for Numerical Computation freely distributed.}
}

The same information can also be represented using a @software / @softwareversion pair that factors out the general information in the @software entry, so for other versions only the changes need to be added in a new @softwareversion entry:

@software {delebecque:hal-02090402,
  title = {Scilab},
  author = {Delebecque, Fran{\c c}ois and Gomez, Claude and Goursat, Maurice 
    and Nikoukhah, Ramine and Steer, Serge and Chancelier, Jean-Philippe},
  year = {1994},
  institution = {Inria},
  license = {Scilab license},
  hal_id = {hal-02090402},
  url = {https://www.scilab.org/},
  abstract = {Software for Numerical Computation freely distributed.},
  repository= {https://github.com/scilab/scilab},
}

@softwareversion {delebecque:hal-02090402v1,
  version = {1.1},
  year = {1994},
  month = jan,
  file = {https://hal.inria.fr/hal-02090402/file/scilab-1.1.tar.gz},
  swhid = {swh:1:dir:1ba0b67b5d0c8f10961d878d91ae9d6e499d746a;
           origin=https://hal.inria.fr/hal-02090402},
  note = {First Scilab version. It was distributed by anonymous ftp.},
  crossref = delebecque:hal-02090402
}

softwaremodule

For highly modular software projects, like CGAL, one may need to reference specifically a particular module, that has distinguished authors, and may heve been introduced in the project at a later time.

The following example uses the informations in the existing BibTeX entries for CGAL that currently refer to the user manual, to create the corresponding software entries.

@software {cgal,
 title = {The Computational Geometry Algorithms Library},
 author = {{The CGAL Project}},
 editor = {{CGAL Editorial Board}},
 year = 1996,
 url = {https://cgal.org/}
}

@softwareversion{cgal:5-0-2,
 crossref = cgal,
 version = {{5.0.2}},
 url = {https://docs.cgal.org/5.02},
 year = 2020,
 swhid = {swh:1:rel:636541bbf6c77863908eae744610a3d91fa58855;
          origin=https://github.com/CGAL/cgal/}
}

@softwaremodule{cgal:lp-gi-20a,
 crossref = cgal:5-0-2,
 author = {Menelaos Karavelas},
 subtitle = {{2D} Voronoi Diagram Adaptor},
 license = {GPL},
 introducedin = cgal:3-1,
 url = {https://doc.cgal.org/5.0.2/Manual/packages.html#PkgVoronoiDiagram2},
}

Of course, it is always be possible to use only one entry to get an equivalent result; here one would use just @softwaremodule with all the needed data fields as follows:

@softwaremodule{cgal:lp-gi-20a,
 title = {The Computational Geometry Algorithms Library},
 subtitle = {{2D} Voronoi Diagram Adaptor},
 author = {Menelaos Karavelas},
 editor = {{CGAL Editorial Board}},
 license = {GPL},
 version = {{5.0.2}},
 introducedin = cgal:3-1,
 year = 2020,
 swhid = {swh:1:rel:636541bbf6c77863908eae744610a3d91fa58855;
          origin=https://github.com/CGAL/cgal/},
 url = {https://doc.cgal.org/5.0.2/Manual/packages.html#PkgVoronoiDiagram2},
}

codefragment

Finally, if one wants to have a particular code fragment appear in the bibliography, we can do this as follows:

@software {parmap,
  title = {The Parmap library},
  author = {Di Cosmo, Roberto and Marco Danelutto},
  year = {2020},
  version = {1.1.1},
  institution = {Inria},
  license = {LGPL-2.0},
  url = {https://rdicosmo.github.io/parmap/},
  repository= {https://github.com/rdicosmo/parmap},
}

@codefragment {simplemapper,
  subtitle = {Core mapping routine},
  swhid = {swh:1:cnt:43a6b232768017b03da934ba22d9cc3f2726a6c5;lines=192-228;
      origin=https://github.com/rdicosmo/parmap},
  crossref = parmap
}