\documentclass[11pt,a4paper]{ltxdoc}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{microtype}
\usepackage{xcolor}
\usepackage{booktabs}
\usepackage{array}
\usepackage{listings}
\usepackage{fancyvrb}
\usepackage{url}

% Define custom blue color
\definecolor{customblue}{HTML}{4169E1}

% Configure hyperref with custom colors
\usepackage[
  colorlinks=true,
  linkcolor=customblue,
  urlcolor=customblue,
  citecolor=customblue,
  filecolor=customblue,
  bookmarksnumbered=true,
  bookmarksopen=true
]{hyperref}

% Manual documentation only (no live bibliography resource required).
% Examples live alongside this file: biblatex-asa-with-package.*,
% biblatex-asa-without-package.*, and the shared biblatex-asa-example.bib.
%\usepackage[backend=biber]{biblatex}

\lstset{
  basicstyle=\ttfamily\small,
  commentstyle=\color{gray},
  keywordstyle=\color{blue},
  stringstyle=\color{red},
  showstringspaces=false,
  breaklines=true,
  frame=single,
  backgroundcolor=\color{gray!10}
}

\title{The \textsf{biblatex-asa} Package\\
       \Large American Sociological Association Style for \textsf{biblatex}}
\author{%
  \begin{tabular}{@{}c@{\hspace{3cm}}c@{}}
    Yuqi Liang & Version 1.0.0 \\
    \texttt{yuqi.liang.1900@gmail.com} & August 6, 2026
  \end{tabular}%
}
\date{}

\begin{document}

\maketitle

\begin{abstract}
The \textsf{biblatex-asa} package provides an ASA citation and bibliography style for \textsf{biblatex}.
It follows common American Sociological Association / \emph{American Sociological Review} conventions for names, journals, chapters, and in-text citations, with DOI and URL presentation aligned to the ASA Style Guide, 7th edition (2022).
\end{abstract}

\tableofcontents

\section{Introduction}

The \textsf{biblatex-asa} package provides citation and bibliography formatting according to the American Sociological Association (ASA) style guide. This package is particularly useful for students writing sociology papers or theses, researchers submitting to sociology journals, and anyone requiring ASA-style citations and references.

\subsection{Requirements}

You will need:

\begin{itemize}
  \item \textbf{LaTeX distribution:} TeX Live 2020 or later, MiKTeX 2020 or later
  \item \textbf{biblatex:} Version 3.14 or later
  \item \textbf{biber:} Version 2.14 or later (recommended backend)
  \item \textbf{etoolbox:} Version 2.5 or later (automatically loaded by biblatex)
\end{itemize}

The package is built on top of biblatex's \texttt{standard} and \texttt{authoryear} styles.

\subsection{Acknowledgments}

This is my first LaTeX package. I would like to express my sincere gratitude to Vincent Goulet from the CTAN team for helping me lay a solid foundation. I have learned from his rigor, comprehensiveness, professionalism, and enthusiasm. I also thank Jan Meyerhoff-Liang and Ridhi Kashyap for their support.

\section{Installation}

\subsection{Automatic Installation}

Install through your TeX distribution's package manager:

\begin{itemize}
  \item \textbf{TeX Live}: \texttt{tlmgr install biblatex-asa}
  \item \textbf{MiKTeX}: Available through MiKTeX Package Manager
  \item \textbf{Overleaf}: Pre-installed and ready to use
\end{itemize}

\subsection{Manual Installation}

For local use, first generate the style files from the provided sources:
\begin{itemize}
  \item Run \texttt{latex biblatex-asa.ins} in the package directory.
  \item This will create \texttt{biblatex-asa.sty}, \texttt{biblatex-asa.bbx}, and \texttt{biblatex-asa.cbx}.
  \item Copy these files to your project directory (or leave them in place if working in the same folder).
\end{itemize}

For system-wide installation, place files in your local \texttt{texmf} tree under \texttt{texmf/tex/latex/biblatex-asa/} and run \texttt{texhash} (TeX Live) or \texttt{initexmf --update-fndb} (MiKTeX).

\section{Usage}

\subsection{Basic Usage}

Load the package in your document preamble:

\begin{lstlisting}[language=TeX]
\documentclass{article}
\usepackage{biblatex-asa}
\addbibresource{references.bib}

\begin{document}
This is a citation \parencite{key2023}.
\textcite{author2022} argues that...
\printbibliography
\end{document}
\end{lstlisting}

\subsection{Direct Style Usage}

Alternatively, use the ASA style directly:

\begin{lstlisting}[language=TeX]
\usepackage[backend=biber,style=biblatex-asa]{biblatex}
\addbibresource{references.bib}
\end{lstlisting}

\subsection{Package Options}

\begin{description}
  \item[\texttt{giveninits}] Use initials for given names
  \item[\texttt{nogiveninits}] Use full given names (default)
  \item[\texttt{backend=biber}] Use biber backend (recommended)
  \item[\texttt{backend=bibtex}] Use bibtex backend
\end{description}

Example:
\begin{lstlisting}[language=TeX]
\usepackage[giveninits,backend=biber]{biblatex-asa}
\end{lstlisting}

\section{Citation Commands}

The package supports standard \textsf{biblatex} citation commands:

\begin{description}
  \item[\cs{parencite\{key\}}] Parenthetical citation: (Author Year)
  \item[\cs{textcite\{key\}}] In-text citation: Author (Year)
  \item[\cs{cite\{key\}}] Bare citation: Author Year
\end{description}

Examples:
\begin{itemize}
  \item \texttt{\cs{parencite\{smith2020\}}} → (Smith 2020)
  \item \texttt{\cs{textcite\{jones2019\}} argues...} → Jones (2019) argues...
  \item \texttt{\cs{parencite[p.~42]\{doe2018\}}} → (Doe 2018, p. 42)
\end{itemize}

\section{Compilation}

Compile documents using this sequence:

\begin{enumerate}
  \item \texttt{pdflatex document.tex}
  \item \texttt{biber document}
  \item \texttt{pdflatex document.tex}
  \item \texttt{pdflatex document.tex}
\end{enumerate}

For Overleaf users, the compilation sequence is handled automatically.

\section{ASA Format Implementation}

\subsection{Citation Format}

\begin{itemize}
  \item Single author: (Smith 2020)
  \item Two authors: (Smith and Jones 2020)
  \item Three or more authors: (Smith et al. 2020)
  \item Multiple citations: (Smith 2020; Jones 2021)
\end{itemize}

\subsection{Bibliography Format}

\begin{itemize}
  \item Authors: First author inverted (Last, First), subsequent authors normal order
  \item All authors listed (no "et al." truncation in bibliography)
  \item Articles: Journal name italicized, volume(issue):pages format
  \item Books: Publisher and location information
  \item Book chapters: "Pp. X–Y in..." formatting
  \item Proper handling of publication dates, DOIs, and URLs
\end{itemize}

\section{Package Details}

The distributed package includes the following files:

\begin{description}
  \item[\texttt{biblatex-asa.dtx}, \texttt{biblatex-asa.ins}] The documented source and installation script. To use the package locally, first run \texttt{latex biblatex-asa.ins} to generate \texttt{biblatex-asa.sty}, \texttt{biblatex-asa.bbx}, and \texttt{biblatex-asa.cbx}.
  \item[\texttt{docs/biblatex-asa-example.bib}] Shared example bibliography database.
  \item[\texttt{docs/biblatex-asa-with-package.tex}] Example using the package wrapper (\texttt{\textbackslash usepackage\{biblatex-asa\}}).
  \item[\texttt{docs/biblatex-asa-without-package.tex}] Example using the style directly (\texttt{style=biblatex-asa}).
  \item[\texttt{docs/biblatex-asa-manual.pdf}] This user manual.
\end{description}

The style files (\texttt{biblatex-asa.sty}, \texttt{biblatex-asa.bbx}, \texttt{biblatex-asa.cbx}) are not included directly in the package archive. They must be generated from the provided sources as described above, unless you install the package through your TeX distribution.

Users new to the package should start with \texttt{biblatex-asa-with-package.tex}.

\section{Supported Entry Types}

The package supports all standard \textsf{biblatex} entry types with ASA formatting:

\begin{itemize}
  \item \texttt{@article} - Journal articles
  \item \texttt{@book} - Books
  \item \texttt{@incollection} - Book chapters
  \item \texttt{@inproceedings} - Conference proceedings
  \item \texttt{@misc} - Miscellaneous sources
  \item \texttt{@online} - Online sources
  \item \texttt{@report} - Reports
  \item \texttt{@thesis} - Theses and dissertations
\end{itemize}

\section{Troubleshooting}

\begin{description}
  \item[References not showing] Ensure you run \texttt{biber} (not \texttt{bibtex}).
  \item[File not found errors] Check package installation or ensure files are in project directory.
  \item[Encoding problems] Save all files as UTF-8.
\end{description}

\section{License and Contact}

This work is distributed under the LaTeX Project Public License (LPPL), version 1.3c or later.

\begin{description}
  \item[Author:] Yuqi Liang, University of Oxford
  \item[Email:] \texttt{yuqi.liang.1900@gmail.com}
  \item[GitHub:] \url{https://github.com/yuqi-liang-qiqi/biblatex-asa}
\end{description}

\end{document}