%% ---------------------------------------------------------------
%% biblatex-phys --- A biblatex implementation of the AIP and APS 
%%   bibliography style
%% Maintained by Joseph Wright
%% E-mail: joseph.wright@morningstar2.co.uk
%% Released under the LaTeX Project Public License v1.3c or later
%% See http://www.latex-project.org/lppl.txt
%% ---------------------------------------------------------------
%%  

\documentclass[a4paper]{ltxdoc}
\usepackage{lmodern}
\usepackage[final]{microtype}
\usepackage[T1]{fontenc}
\usepackage[backend=biber,style=phys]{biblatex}
\usepackage{csquotes}
\usepackage{hyperref}

\hypersetup{hidelinks}

\addbibresource{biblatex-phys.bib}

\author{Joseph Wright\thanks{E-mail: 
  \href{mailto:joseph.wright@morningstar2.co.uk}
  {\texttt{joseph.wright@morningstar2.co.uk}}}}
\title{\pkg{biblatex-phys} -- A \pkg{biblatex} implementation of the
  \textsc{aip} and \textsc{aps} bibliography style%
  \footnote{This file describes v1.1b, last revised 2019/12/03.}}
\date{Released 2019/12/03}

\providecommand*{\opt}[1]{\texttt{#1}}
\providecommand*{\pkg}[1]{\textsf{#1}}

\let\DescribeOption\DescribeEnv

\RecordChanges

\begin{document}

\maketitle

This package provides a style for \pkg{biblatex} which follows the
guidelines of the \textsc{aip} and \textsc{aps}. The citation style is numeric
and unsorted. The bibliography style follows the pattern of the official
REV\TeX{} class (\url{http://ctan.org/pkg/revtex}). The style should be loaded
in the usual way
\begin{verbatim}
  \usepackage[style=phys]{biblatex}
\end{verbatim}
Load-time options are provided to deal with the small number of variations
between the \textsc{aip} and \textsc{aps} styles.
The References section of this document demonstrates the format 
generated by the package using the \texttt{biblatex-phys.bib} database
of example citations.

The styles use the standard \pkg{biblatex} database requirements. This means
that a database designed for traditional \pkg{biblatex} use may need some
editing for optimal output. The accompanying example database
\texttt{biblatex-phys.bib} shows examples of all of the supported entry types
with common fields filled in.

\section{Style options}

All of the styles here add a small number of package options to the standard
set provided by \pkg{biblatex}. This allows the styles to cover the variations
seen between the \textsc{aip} and \textsc{aps} styles.

\DescribeOption{doi}
\DescribeOption{eprint}
\DescribeOption{isbn}
\DescribeOption{url}
The standard style options \opt{doi}, \opt{eprint} \opt{isbn} and
\opt{eprint}, as described in the \pkg{biblatex} manual. However, these
options are turned off as standard by the \pkg{phys} style. This reflects the
fact that these entries may be present in reference databases but are not
generally included in published bibliographies. Note that \textsc{doi} values
are printed for journal articles with no pages given, even if the \opt{doi}
option is \opt{false}.

\DescribeOption{subentry}
In common with the standard \pkg{biblatex} numeric styles, all of the styles
in the bundle support the boolean \texttt{subentry} option. With this set
\opt{true}, entries of type \texttt{set} are given individual labels within
the bibliography.

\DescribeOption{articletitle}
The use of article titles varies between the \textsc{aip} and \textsc{aps}
styles. The boolean option \opt{articletitle} is available is control this
behaviour. The standard settings is \opt{true}, which follows the guidelines of
the \textsc{aip}: it should be set to \opt{false} to follow the \textsc{aps}
style. (This option also applies to the titles of proceedings entries and
patents, which are treated in the same way.)

\DescribeOption{biblabel}
The format of the numbers used in the bibliography (the \enquote{bibliography
label}) varies. he \opt{biblabel} option allows the user to easily set the
format used. This option takes a values \opt{superscript} (the standard
setting) and \opt{brackets}.

\DescribeOption{chaptertitle}
Printing chapter titles for \texttt{incollection} entries is part of the
\textsc{aip} style but is not part of the \textsc{aps} style. The
\opt{chaptertitle} option can be used to control this.

\DescribeOption{pageranges}
The inclusion of the full page range of journal articles varies between the
\textsc{aip} and \textsc{aps} styles. The boolean option \opt{pageranges} is
available is control this behaviour. The standard settings is \opt{true},
which follows the guidelines of the \textsc{aip} and prints the full range:
it should be set to \opt{false} to follow the \textsc{aps} style, which will
result in only the first page being printed.

\subsection{\texttt{collaboration} field}

To support large-scale collaborations, the style recognises the
\texttt{collaboration} field. This is a simple text field which gives the
name of the collaboration, and which is printed in parenthesis after the
authors.

\subsection{\textsc{aip} and \textsc{aps} styles}

As detailed above, the standard settings follow the \textsc{aip} style.
To obtain the \textsc{aps} style, use
\begin{verbatim}
  \usepackage[%
      style=phys,%
      articletitle=false,biblabel=brackets,%
      chaptertitle=false,pageranges=false%
    ]
    {biblatex}
\end{verbatim}

\section{Title formatting}

The style convert article titles to sentence case format. This can be
suppressed using
\begin{verbatim}
\DeclareFieldFormat{titlecase}{#1}
\end{verbatim}

\section{\textsc{url} formatting}

The style uses the \pkg{url} package to format hyperlinks. As such, the
format of these is left to the document author to alter. The \cs{urlstyle}
command may be used to alter this, either for the whole document or only
for the bibliography, for example by using
\begin{verbatim}
\AtBeginBibliography{%
  \urlstyle{rm}%
}
\end{verbatim}

\section{Interaction with \pkg{babel}}

In common with other \pkg{biblatex} styles, \pkg{biblatex-phys} uses the
\pkg{csquotes} package mechanism to place article titles in quotation marks.
This means that the formatting of these will depend on the \pkg{babel}
language in use. Full details are covered in the manuals for \pkg{biblatex}
and \pkg{csquotes}.

\section{Errors and omissions}

Suggestions for improvement and bug reports can be logged in the package issue
database, found at
\url{https://github.com/josephwright/biblatex-phys/issues}, or can
be sent by e-mail to 
\href{mailto:joseph.wright@morningstar2.co.uk}
  {\texttt{joseph.wright@morningstar2.co.uk}}.
  
\nocite{*}

\printbibliography

\changes{v0.9a}{2012/07/13}{Detect and remove repeated information in
  entry sets at any position in the set}
\changes{v0.9b}{2013/01/04}{Enable use of \texttt{firstinits} option}
\changes{v0.9b}{2013/01/04}{Fix handling of \texttt{doi} field for
  \texttt{article} entries}
\changes{v0.9b}{2013/01/04}{Print \texttt{doi} or \texttt{url} after year
  for \texttt{article} entries, consistent with \texttt{online} behaviour}
\changes{v0.9c}{2013/01/22}{Link article publication details using \textsc{doi},
  \textsc{url} or arXiv \texttt{eprint}}
\changes{v0.9c}{2013/01/22}{Titles in sentence case}
\changes{v0.9d}{2013/01/23}{Update journal title printing so case is unchanged
  by processing of article titles (introduced in v0.9c)}
\changes{v0.9d}{2013/01/27}{Improve arXiv formatting}
\changes{v0.9d}{2013/01/27}{Minor fix for book formatting}
\changes{v0.9d}{2013/01/27}{Link book titles using \textsc{doi} or
  \textsc{url}}
\changes{v0.9d}{2013/01/27}{Correctly include \enquote{related} material
  (Biber-only)}
\changes{v0.9e}{2013/01/29}{Link \enquote{related} articles using \textsc{doi}
  or \textsc{url}}
\changes{v0.9f}{2014/05/14}{Allow for variation in \texttt{journaltitle}
  formatting}
\changes{v1.0}{2016/03/10}{First stable release}
\changes{v1.0a}{2016/03/13}{Ensure style works with both backends}
\changes{v1.0b}{2016/08/23}{Fix author list formatting issue}
\changes{v1.0c}{2018/10/19}{Update DOI link structure}
\changes{v1.0c}{2018/10/19}{Update internals to follow standard \pkg{biblatex}
  style changes}
\changes{v1.1}{2018/10/19}{Support for \texttt{collaboration} field}
\changes{v1.1a}{2019-09-20}{Biber support for \texttt{collaboration} field}
\changes{v1.1b}{2019-12-03}{Fix printing of DOI when pages are missing}

\PrintChanges

\end{document}

%% 
%% Copyright (C) 2012-2014,2016,2018,2019 by
%%   Joseph Wright <joseph.wright@morningstar2.co.uk>
%% 
%% It may be distributed and/or modified under the conditions of
%% the LaTeX Project Public License (LPPL), either version 1.3c of
%% this license or (at your option) any later version.  The latest
%% version of this license is in the file:
%% 
%%    http://www.latex-project.org/lppl.txt
%% 
%% This work is "maintained" (as per LPPL maintenance status) by
%%   Joseph Wright.
%% 
%% This work consists of the files biblatex-phys.bib,
%%                                 biblatex-phys.tex,
%%                                 biblatex-phys.tex,
%%                                 phys.bbx,
%%                                 phys.cbx and
%%                                 phys.dbx,
%%           and the derived file  biblatex-phys.pdf.
%%
%% End of file `biblatex-phys.tex'.
