summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/biblatex-contrib/biblatex-software/software-biblatex.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-04-26 03:02:41 +0000
committerNorbert Preining <norbert@preining.info>2020-04-26 03:02:41 +0000
commit7d9d2e08fcab92adcc759e3f1e4bb0a15a63f220 (patch)
tree8b20347f7722711d9a3577782906d96684424c9a /macros/latex/contrib/biblatex-contrib/biblatex-software/software-biblatex.tex
parent7a7be7eaa67109eac37916ea48662c24ddc570d0 (diff)
CTAN sync 202004260302
Diffstat (limited to 'macros/latex/contrib/biblatex-contrib/biblatex-software/software-biblatex.tex')
-rw-r--r--macros/latex/contrib/biblatex-contrib/biblatex-software/software-biblatex.tex241
1 files changed, 241 insertions, 0 deletions
diff --git a/macros/latex/contrib/biblatex-contrib/biblatex-software/software-biblatex.tex b/macros/latex/contrib/biblatex-contrib/biblatex-software/software-biblatex.tex
new file mode 100644
index 0000000000..71aeac1350
--- /dev/null
+++ b/macros/latex/contrib/biblatex-contrib/biblatex-software/software-biblatex.tex
@@ -0,0 +1,241 @@
+\documentclass{ltxdockit}
+\usepackage{a4wide}
+\usepackage{hyperref}
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage{alltt}
+\usepackage{listings}
+\usepackage{shortvrb}
+\MakeShortVerb{\|}
+
+\titlepage{%
+ title={Bib\LaTeX\ style extension for Software},
+ subtitle={Citation and References macros for Bib\LaTeX},
+ url={http://mirror.ctan.org/macros/latex/exptl/biblatex-contrib/biblatex-software/},
+ author={Roberto Di Cosmo},
+ email={roberto@dicosmo.org},
+ revision={1.0},
+ date={\today}}
+
+\hypersetup{%
+ pdftitle={Bib\LaTeX\ style extension for Software},
+ pdfsubject={Style for Bib\LaTeX},
+ pdfauthor={Roberto Di Cosmo},
+ pdfkeywords={latex, biblatex, software, style}}
+
+\begin{document}
+
+\printtitlepage
+\tableofcontents
+
+\section{Introduction}\label{sec:intro}
+
+\subsection{About}
+
+Software plays a significant role in modern research, and it must be properly
+acknowledged and referenced in scholarly works. To this end, specific
+bibliographic entries for describing \emph{software}, \emph{software versions},
+\emph{software modules} and \emph{code fragments} have been designed by a
+dedicated task force at Inria in 2020 that brought together researchers from
+Computer Science and Applied Mathematics to discuss best practices for archiving
+and referencing software source code~\cite{2020GtCitation}.\\
+
+This package is a Bib\LaTeX\ \emph{style extension} that adds support for these
+four \emph{software entry types} to any other Bib\LaTeX\ style used in documents
+typeset in \latex. It is made up of the following key components: a references
+section style (\path{software.bbx}), a data model extension
+(\path{software.dbx}) and string localisation files
+(\path{<language>-software.lbx})\footnote{String localisations are provided for
+ some languages: localisations for other languages are welcome, feel free to
+ contribute them on the official repository, see Section \emph{Contributing} below.}.\\
+
+The distribution contains other material, for demonstration purposes, and for
+more advanced use.
+
+\subsection{License}
+
+Permission is granted to copy, distribute and/or modify this software under
+the terms of the \latex Project Public License, version
+1.3c\footnote{\url{http://www.latex-project.org/lppl.txt}}. The current
+maintainer is Roberto Di Cosmo (\textcopyright\ 2020).
+
+\subsection{History}
+
+When I decided to start the Software Heritage initiative in 2015, software in
+general and research software in particular was not yet a first class citizen in
+the scholarly world. The absence of support for properly citing software in a
+bibliography was just one of the many signs of this lack of recognition.
+
+In order to properly reference a software project, and ensure that these
+references are stable enough to pass the test of time, it was necessary to build
+a \emph{universal archive} for software source code, and to equip every software
+artifact with \emph{intrinsic} identifiers.
+
+Now that \href{https://www.softwareheritage.org}{Software Heritage} is providing
+the universal archive~\cite{swhcacm2018}, with Software Heritage \emph{intrinsic
+ identifiers} (SWH-IDs) widely available~\cite{cise-2020-doi}, it is finally
+possible to propose proper bibliographic entries for software, at various levels
+of granularity, down to the line of code.
+
+\subsection{Acknowledgments}
+
+Thanks to the Inria working group members for their precious feedback and
+contribution to the desing of the software bibliography entries: Pierre Alliez,
+Benjamin Guedj, Alain Girault, Morane Gruenpeter, Mohand-Said Hacid, Arnaud
+Legrand, Xavier Leroy, Nicolas Rougier and Manuel Serrano.
+
+\section{Software entries}
+\input{swentries}
+
+\section{Use}\label{ref:use}
+\label{use}
+
+This package can be used as a standalone on the fly extension, or to produce
+full bibliographic styles that extend pre-existing styles.
+
+\subsection{Use as an \emph{on the fly} extension}
+
+The simplest way to use this package is to follow the example given in the
+\path{sample-use-sty.tex} that shows how one can \emph{extend on the fly} any
+existing Bib\LaTeX\ style by just doing the following:
+
+\begin{itemize}
+\item pass the \texttt{datamodel=software} option to the \texttt{biblatex} package as in
+ \begin{ltxcode}
+ \usepackage[datamodel=software]{biblatex}
+ \end{ltxcode}
+ \item load the software biblatex style using
+ \begin{ltxcode}
+ \usepackage{software-biblatex}
+ \end{ltxcode}
+ \item set software specific bibliography options using the macro |\ExecuteBibliographyOptions|;
+ the options with their default values are as in
+ \begin{ltxcode}
+ \ExecuteBibliographyOptions{
+ halid=true,
+ swhid=true,
+ swlabels=true,
+ vcs=true,
+ license=true}
+ \end{ltxcode}
+\end{itemize}
+
+This is quite handy to add support for software entries in a single article, as
+it is enough to add \path{software.dbx}, \path{software.bbx},
+\path{<language>-software.lbx} and \path{software-biblatex.sty} to make it work.
+
+\subsection{Generate extended styles}
+
+When a more systematic use is foreseen, as for institution-wide reports, or
+conference and journal proceedings, it is more appropriate to generate a new
+biblatex style that includes support for the software entries right away.
+
+The following simple mechanism is provided for this use case:
+
+\begin{itemize}
+\item add to the \path{stublist} file the names of all the existing styles that must be extended
+\item run \texttt{make biblatex-styles} to produce new style files, with an added \texttt{+sw} suffix,
+ for each of the existing style
+\item install the newly generated files in the standard path where Bib\LaTeX\ files are found
+\end{itemize}
+
+The stock \path{stublist} file contains the names of all the standard Bib\LaTeX\
+styles. If this approach is followed, then one can load directly the extended
+file, and the software specific bibliography options become available when
+loading the Bib\LaTeX\ package directly. See the \path{sample.tex} file for a
+working example.
+
+\subsection{Installation}\label{sec:install}
+
+This package may become available in standard distributions like \TeX Live as
+|biblatex-software|. To install manually, you can download it from CTAN and
+then, put the relevant files in your texmf tree, usually:\\
+
+\noindent\path{<texmf>/tex/latex/biblatex-software/software-biblatex.sty}\\
+\path{<texmf>/tex/latex/biblatex-software/software.bbx}\\
+\path{<texmf>/tex/latex/biblatex-software/software.dbx}\\
+\path{<texmf>/tex/latex/biblatex-software/<language>-software.lbx}\\
+
+
+\subsection{Package options}\label{sec:options}
+
+The following options are available to control the typesetting of
+software related entries.
+
+\begin{ltxcode}
+ swlabels=true|false
+\end{ltxcode}
+
+\noindent Software is a special research output, distinct from
+publications, hence software entries in a bibliography are
+distinguished by a special label by default.
+This behaviour can be disabled by setting this option to |false|.
+
+\begin{ltxcode}
+ license=true|false
+\end{ltxcode}
+
+\noindent This option controls whether license information for
+the software entry is typeset. The default is |true|.
+
+\begin{ltxcode}
+ halid=true|false
+\end{ltxcode}
+
+\noindent This option controls the inclusion of the identifier on the HAL repository of the
+metadata record for the software described in the entry. The default is |true|.
+
+\begin{ltxcode}
+ swhid=true|false
+\end{ltxcode}
+
+\noindent This option controls the inclusion of the identifier on the Software Heritage archive
+of the source code of the software described in the entry. The default is |true|.
+
+\begin{ltxcode}
+ vcs=true|false
+\end{ltxcode}
+
+\noindent This option controls the inclusion of the url of the code hosting
+platform where the software described in the enttry is developed. The default is |true|.
+
+\section{Details}
+
+The detailed information for this style is contained in the example document and
+accompanying \path{.bib} files:
+\begin{description}
+\item[\path{software-biblatex.tex}] This document.
+\item[\path{biblio.bib}] An example bibliography showcasing all the software entries.
+\item[\path{sample-use-sty.tex}]\footnote{\path{sample-use-sty.pdf} is also
+ provided and is the typeset version of this \latex source file.} This document
+ exerces most useful feature of this style extension, using the
+ \path{biblio.bib} entries.
+\item[\path{sample.tex}] This document produces the same output as
+ \path{sample-use-sty.tex}, but instead of extending on the fly and existing
+ style, it assumes that an extended bibliographic style \texttt{numeric+sw} has
+ been created starting from the standard \texttt{numeric} style.
+\item[\path{software.bbx}] The |biblatex-software| references style.
+\item[\path{software.dbx}] The |biblatex-software| data model additions.
+\item[\path{*.lbx}] The |biblatex-software| localisation files.
+\item[\path{software-biblatex.sty}] The |software-biblatex| \LaTeX\ package for extending on the fly any preloaded Bib \LaTeX\ style.
+\end{description}
+
+\section{Contributing}
+
+This style extension is currently developed on a git-based repository at
+\url{https://gitlab.inria.fr/gt-sw-citation/bibtex-sw-entry/}.
+Contributions and bug reports are very welcome. In particular, translation
+of the localization strings for other languages are needed.
+
+\section{Revision history}\label{rev}
+
+\begin{changelog}
+
+\input{history}
+
+\end{changelog}
+
+\bibliography{manual}
+\bibliographystyle{abbrv}
+
+\end{document}