% =====================================================================
% biblatex-cse-doc.tex
% =====================================================================
% User Manual for the biblatex-cse package
%
% Implements the Council of Science Editors (CSE) Name–Year system
% =====================================================================
%
% Copyright (C) 2024–26 by João Lourenço <joao.lourenco@fct.unl.pt>
%
% This file may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, either version 1.3c of this license
% or (at your option) any later version. The latest version of this
% license is in:
%
%    http://www.latex-project.org/lppl.txt
%
% and version 1.3c or later is part of all distributions of LaTeX
% version 2006/05/20 or later.

\documentclass[11pt]{article}

\usepackage{tabularx}
\usepackage{booktabs}

% =====================================================================
% Load  biblatex-cse
\usepackage[style=biblatex-cse]{biblatex}
% in the preamble, after \usepackage{biblatex}
% Keep only master's theses, regardless of encoding
\defbibfilter{onlymasters}{%
  type=thesis and keyword=mastersthesis
}
\defbibfilter{onlyphd}{%
  type=thesis and keyword=phdthesis
}

% =====================================================================
% Load document packages
\usepackage[a4paper,margin=2.5cm]{geometry}
\usepackage{xcolor}
\usepackage{csquotes}
\usepackage{titling}
\usepackage{enumitem}
\usepackage{minted}

% =====================================================================
% Enable hyperlinking/hypertext and PDF metadata
\usepackage{hyperref}
\definecolor{cseblue}{RGB}{0,55,102}
\hypersetup{
  colorlinks=true,
  linkcolor=cseblue,
  urlcolor=cseblue,
  citecolor=cseblue
}


% =====================================================================
% Add bibliography database
\addbibresource{bibliography.bib}


% =====================================================================
% Uder defined commands
\newcommand{\nauthors}[1]{#1 authors: }
\AtBeginBibliography{\small\color{cseblue}}
\setcounter{tocdepth}{1}


% =====================================================================
% Document header
\title{The Council of Science Editors Name--Year Bib\LaTeX\ style (\textsf{\filename})}
\author{João M. Lourenço\\\url{https://github.com/joaomlourenco/biblatex-cse}}
\date{Version \bltxcsefileversion\ (\bltxcsefiledate)}



% =====================================================================
\begin{document}
\maketitle

\begin{abstract}
The \texttt{biblatex-cse} package provides a set of Bib\LaTeX{} bibliography and citation styles that implement the \textbf{Council of Science Editors (CSE) Name--Year} reference system. It formats references following the conventions of the \emph{CSE Manual for Authors, Editors, and Publishers} (9th edition). This manual describes installation, usage, and customization of the style.\footnote{This style is only a partial implementation of the CSE specification.  Please report any problems you may find in the project's GitHub page.}
\end{abstract}

\tableofcontents

% =====================================================================
\section{Introduction}

The \texttt{biblatex-cse} package is a style extension for Bib\LaTeX{}.  
It defines the bibliography style (\texttt{biblatex-cse.bbx}) and the citation style (\texttt{biblatex-cse.cbx}), implementing the CSE Name--Year system.

The Name--Year system is used widely across the sciences, requiring in-text citations in the form \texttt{(Author Year)} and a reference list ordered alphabetically by author and chronologically by year.

This style is designed for authors, students, and editors working in the biological, medical, or natural sciences who must conform to CSE standards.

% =====================================================================
\section{Installation}

\subsection{Package contents}
The distribution provides the following files:
\begin{itemize}
  \item \texttt{biblatex-cse.bbx} --- bibliography style definitions;
  \item \texttt{biblatex-cse.cbx} --- citation style definitions;
  \item \texttt{biblatex-cse-doc.tex} --- this documentation file;
  \item \texttt{bibliography.bib} --- example database.
\end{itemize}

\subsection{Installation steps}
As the \texttt{biblatex-cse} package is distributed with \texttt{biblatex}, most probably you may skip this step.  Come back if you get the following error
\begin{center}
\texttt{Package biblatex Error: Style 'biblatex-cse' not found.}
\end{center}
\noindent and follow the instructions below.

Copy the \texttt{.bbx} and \texttt{.cbx} files to one of:
\begin{itemize}[nosep]
  \item the current project directory, or
  \item a personal or system-wide \texttt{TEXMF} tree under \texttt{tex/latex/biblatex-cse/} and run \texttt{texhash}.
\end{itemize}

The package requires:
\begin{itemize}
  \item \texttt{biblatex} 3.20 or newer;
  \item \texttt{biber} 2.17 or newer;
  \item \texttt{csquotes} (optional, recommended).
\end{itemize}

% =====================================================================
\section{Loading the style}

In your preamble:
\begin{minted}{latex}
\usepackage[backend=biber,style=biblatex-cse]{biblatex}
\addbibresource{myrefs.bib}
\end{minted}

% Recommended global options:
\begin{minted}{latex}
\ExecuteBibliographyOptions{
  sorting=nyt,        % Name–Year–Title order (required for CSE)
  giveninits=true,    % use initials for given names
  maxcitenames=2,     % truncate to et al. after two names in citations
  maxbibnames=5,      % list up to five authors in the bibliography
  urldate=iso         % ISO access-date format (e.g., 2022-01-25)
}
\end{minted}

Run \texttt{pdflatex → biber → pdflatex → pdflatex} to compile.  Or, even better, run \texttt{latexmk -pdf yourdocument.tex}.

% =====================================================================
\section{Citation style (Name–Year)}

CSE uses the Name--Year system for in-text citations:
\begin{itemize}
  \item One author: \texttt{(Fauci 2020)}
  \item Two authors: \texttt{(Fauci and Lane 2020)}
  \item Three or more authors: \texttt{(Lee et al.\ 2020)}
  \item Multiple works: \texttt{(Lee et al.\ 2020a, 2020b)}
  \item Page or section: \texttt{(Lee et al.\ 2020, 45–47)}
\end{itemize}

Common commands:
\begin{minted}{latex}
\parencite{Fauci2020}            % → (Fauci 2020)
\textcite{Lee2020a}              % → Lee et al. (2020)
\parencite[45--47]{Lee2020b}     % → (Lee et al. 2020, 45–47)
\parencite{Lee2020a,Fauci2020}   % → (Lee et al. 2020; Fauci 2020)
\end{minted}

This style automatically suppresses the “p.” prefix and formats page ranges and multiple citations according to CSE punctuation.

% =====================================================================
\section{Bibliography formatting}

The general pattern is:

\begin{quote}
\textbf{Authors. Year. Title. Journal title. Volume(issue):pages. DOI/URL}
\end{quote}

Each element is separated by a period, and the page range is introduced by a colon.  
Journal titles are usually abbreviated according to the \emph{List of Title Word Abbreviations} (ISSN Centre).

\subsection*{Examples}

\paragraph{Journal article}
\begin{verbatim}
@Article{Fauci2020,
  author  = {Anthony S. Fauci and H. Clifford Lane},
  title   = {Four decades of HIV/AIDS—much accomplished, much to do},
  journal = {N Engl J Med},
  volume  = {383},
  number  = {1},
  pages   = {1–4},
  year    = {2020},
  doi     = {10.1056/NEJMp1916753},
}
\end{verbatim}

Output:
\begin{quote}
Fauci AS, Lane HC. 2020. Four decades of HIV/AIDS—much accomplished, much to do. N Engl J Med. 383(1):1–4. https://doi.org/10.1056/NEJMp1916753
\end{quote}

\paragraph{Book}
\begin{verbatim}
@Book{Reiss2023,
  author    = {Reiss, Michael J. and Ruse, Michael},
  title     = {The new biology: a battle between mechanism and organicism},
  publisher = {Harvard University Press},
  year      = {2023},
}
\end{verbatim}

Output:
\begin{quote}
Reiss MJ, Ruse M. 2023. The new biology: a battle between mechanism and organicism. Harvard University Press.
\end{quote}

\paragraph{Thesis}
\begin{verbatim}
@MastersThesis{Carvalho2002,
  author      = {Madeira de Carvalho, Luís Manuel},
  title       = {Epidemiologia e controlo da estrongilidose...},
  institution = {Faculdade de Medicina Veterinária},
  location    = {Lisbon},
  year        = {2002},
}
\end{verbatim}

Output:
\begin{quote}
Madeira de Carvalho LM. 2002. Epidemiologia e controlo da estrongilidose em diferentes sistemas de produção equina em Portugal. [master's thesis]. Faculdade de Medicina Veterinária.
\end{quote}

\paragraph{Website}
\begin{verbatim}
@Online{CDC2022,
  author   = {{Centers for Disease Control and Prevention}},
  title    = {Health equity considerations and racial and ethnic minority groups},
  year     = {2020},
  eventdate= {2022-01-25},
  urldate  = {2022-01-03},
  url      = {https://www.cdc.gov/coronavirus/...},
}
\end{verbatim}

Output:
\begin{quote}
Centers for Disease Control and Prevention. 2020. Health equity considerations and racial and ethnic minority groups. [updated 2022 Jan 25; accessed 2022 Jan 3]. https://www.cdc.gov/coronavirus/...
\end{quote}

% =====================================================================
\section{Supported entry types}

\subsection{@article}
Authors. Year. Article title. Journal title. Volume(issue):pages. DOI/URL

\subsection{@book}
Authors or editors. Year. Title. Edition. Publisher. DOI/URL

\subsection{@incollection}
Authors. Year. Chapter title. In: Editor(s), editor(s). Book title. Edition. Publisher. p pages. DOI/URL

\subsection{@thesis / @mastersthesis / @phdthesis}
Author. Year. Title [dissertation] \emph{or} [master's thesis]. Institution. DOI/URL

\subsection{@online}
Author. Date. Title. Publisher; [updated date]; [accessed date]. URL

If neither \texttt{year} nor \texttt{date} is set, the style prints \texttt{[date unknown]} in place of the date.

\subsection{@misc}
Author. Year. Title. Publisher. URL

\subsection{@newspaper}
Author. Date. Title. Newspaper title. [updated date]. URL

\subsection{@patent}
Inventor(s), inventors; Assignee, assignee. Year Mon DD. Title. Country patent number. DOI/URL

\subsection{@report / @techreport}
Author(s). Year. Title. Institution. Report No.:~number. DOI/URL

\subsection{@inproceedings}
Author(s). Year. Paper title. In: Editor(s), editors. Proceedings title (Conference name; YYYY Mon DD; Venue). Publisher. p~pages. DOI/URL\\[4pt]
Relevant fields: \texttt{author}, \texttt{year}, \texttt{title}, \texttt{editor}, \texttt{booktitle},
\texttt{eventtitle} (conference name), \texttt{eventyear}/\texttt{eventmonth}/\texttt{eventday} (conference date),
\texttt{venue} (conference location), \texttt{publisher}, \texttt{pages}, \texttt{doi}/\texttt{url}.\\[4pt]
When none of \texttt{eventtitle}, \texttt{eventyear}, or \texttt{venue} are present the
parenthetical conference block is omitted.

\subsection{@manual}
There is no dedicated \texttt{@manual} driver; these entries fall through to the \texttt{@misc} driver and are formatted as:\\
Author. Year. Title. Publisher. URL

% =====================================================================
\section{Separating thesis entries by degree}

Because Bib\LaTeX{}/Biber maps both \texttt{@mastersthesis} and \texttt{@phdthesis} to the
internal type \texttt{@thesis}, the style detects the degree automatically from the
\texttt{type} field and prints either \texttt{[master's thesis]} or \texttt{[dissertation]}.

To \emph{filter} bibliography lists by degree (e.g.\ a separate ``Master's Theses''
section), add a \texttt{keywords} field to each \texttt{.bib} entry:

\begin{minted}{bib}
@MastersThesis{Smith2020,
  ...
  keywords = {mastersthesis},
}
@PhdThesis{Jones2019,
  ...
  keywords = {phdthesis},
}
\end{minted}

Then define filters in the preamble and use them with \verb|\printbibliography|:

\begin{minted}{latex}
\defbibfilter{onlymasters}{type=thesis and keyword=mastersthesis}
\defbibfilter{onlyphd}{type=thesis and keyword=phdthesis}

\printbibliography[filter=onlymasters, title={Master's Theses}]
\printbibliography[filter=onlyphd,     title={Doctoral Dissertations}]
\end{minted}

% =====================================================================
\section{Options and customization}

The \texttt{biblatex-cse} style inherits all standard Bib\LaTeX{} options.  
Frequently used options:

\begin{center}
\begin{tabular}{@{}lll@{}}
\textbf{Option} & \textbf{Default} & \textbf{Description} \\
\hline
\texttt{giveninits} & true & Use initials for given names. \\
\texttt{maxcitenames} & 2 & Show up to two names in citations. \\
\texttt{maxbibnames} & 5 & Show up to five names in the bibliography. \\
\texttt{urldate} & iso & ISO date format for access dates. \\
\end{tabular}
\end{center}

Change these with:
\begin{minted}{latex}
\ExecuteBibliographyOptions{maxbibnames=10,urldate=long}
\end{minted}

You can also redefine bibliography headings, for example to print the list at subsection level:
\begin{minted}{latex}
\defbibheading{bibliography}{\subsection*{#1}}
\end{minted}  
or use
\begin{minted}{latex}
\printbibliography[heading=subbibliography]
\end{minted}

% =====================================================================
\section{Differences from standard BibLaTeX styles}

Compared with the built-in \texttt{authoryear} style, \texttt{biblatex-cse}:

\begin{itemize}
  \item separates reference elements with \textbf{periods}, not commas;
  \item uses a \textbf{colon before page numbers};
  \item removes parentheses around the year;
  \item prints \textbf{author initials without periods};
  \item abbreviates journal titles (manual input);
  \item prints DOIs as full URLs (\texttt{https://doi.org/...});
  \item omits “p.” in in-text page references.
\end{itemize}

% =====================================================================
\section{Known limitations}

\begin{itemize}
  \item The style does not automatically abbreviate journal titles; provide them abbreviated in your \texttt{.bib}.
  \item Unpublished materials and personal communications should be handled manually.
  \item Some advanced CSE categories (preprints, forthcoming, supplements) may need minor custom drivers.
\end{itemize}

% =====================================================================
\section{Acknowledgments}

The style is based on Bib\LaTeX{} by Philipp Lehman and Audrey Boruvka.  
Formatting conventions follow the \emph{CSE Manual for Authors, Editors, and Publishers, 9th edition} (Council of Science Editors, 2024).
Thanks to the Bib\LaTeX{} community for style-design examples.

% =====================================================================
\section{Change history}

\noindent
\begin{tabularx}{\textwidth}{>{\bfseries}llX}
  \toprule
  v2.0.1 & (2026-05-16) & Improve manual completeness.\\
         &              & Fix discrepancies from CSE standard.\\
         &              & Fix event date formatting to correctly display year, month, and day.\\
  v2.0.0 & (2025-11-06) & Rework of the style files to better comply to the CSE Name--Year specification.\\
  v1.1.0 & (2025-01-01) & Initial public release.\\
  \bottomrule
\end{tabularx}

% =====================================================================
\appendix
\section{Example document}

\begin{minted}{latex}
\documentclass{article}
\usepackage[backend=biber,style=biblatex-cse]{biblatex}
\addbibresource{bibliography.bib}

\begin{document}
\section*{Example}
Research on long-duration spaceflight has revealed
important physiological changes \parencite{Lee2020a,Lee2020b}.

\printbibliography[title={References}]
\end{document}
\end{minted}

Compiling this file with Biber produces CSE-compliant citations and references.

% =====================================================================
\section{Examples of citations and bibliography}

\noindent\textbf{Note:} The \texttt{\textbackslash nauthors\{n\}} command used below is a local helper defined in this document's preamble as \verb|\newcommand{\nauthors}[1]{#1 authors: }|.
It is \emph{not} part of the \texttt{biblatex-cse} style; it is only used here to annotate how many authors each entry has.

\subsection{Article Citations}
\indent
\par\nauthors{1}\cite[150]{Duddington1955} % reference to page 150
\par\nauthors{2}\cite{Asa2011}
\par\nauthors{3}\cite{Migaki1982}
\par\nauthors{4}\cite{Lysek1982}
\par\nauthors{5}\cite{Carvalho2007}
\par\nauthors{8}\cite{Riadigos2014}

\printbibliography[heading=subbibliography, type=article, title=Article References]

\subsection{Book Citations}
\indent
\par\nauthors{1}\cite{AnkelSimons2007}
\par\nauthors{2}\cite{Bogitsh2013}
\par\nauthors{3}\cite{Taylor2016}
\par\nauthors{4}\cite{Modry2015}
\par\nauthors{5}\cite{Modry2017}

\printbibliography[heading=subbibliography, type=book, title=Book References]


\subsection{Manual Citations}
\indent
\par\nauthors{1}\cite{Zoos2022}

\printbibliography[heading=subbibliography, type=manual, title=Manual References]


\subsection{Online Citations}
\indent
\par\nauthors{1}\cite{ZooBarcelona:Timeline}

\printbibliography[heading=subbibliography, type=online, title=Online References]


\subsection{Newspaper Citations}
\indent
\par\nauthors{2}\cite{NYT2023}

\printbibliography[heading=subbibliography, type=newspaper, title=Newspaper References]


\subsection{Master Thesis Citations}
\indent
\par\nauthors{1}\cite{Carvalho2002}

\printbibliography[heading=subbibliography, filter=onlymasters, title=Masterthesis References]


\subsection{PhD Thesis Citations}
\indent
\par\nauthors{1}\cite{Balan2017}

\printbibliography[heading=subbibliography, filter=onlyphd, title=Phdthesis References]


\subsection{Technical Report Citations}
\indent
\par\nauthors{1}\cite{Fiby2020}
\par\nauthors{2}\cite{Miller2011}
\par\nauthors{5}\cite{Abello2017}
\par\nauthors{5}\cite{Duque2018}

\printbibliography[heading=subbibliography, type=report, title=Techreport References]


\end{document}