% !TEX program = xelatex
% hadith-doc.tex — Documentation for the hadith package v1.1.0
\documentclass[11pt,a4paper]{ltxdoc}

\usepackage[a4paper,margin=2.5cm,headheight=15pt]{geometry}
\usepackage{array,booktabs,tabularx,longtable}
\usepackage{enumitem}
\usepackage{titlesec}
\usepackage{fancyhdr}
\usepackage{setspace}
\usepackage[table]{xcolor}

\usepackage{bidi}
\usepackage[no-math]{fontspec}
\usepackage[quiet]{polyglossia}

\setmainfont[Scale=0.95]{Amiri-Regular.ttf}
\newfontfamily\arabicfont[Script=Arabic,Scale=0.9]{Amiri-Regular.ttf}
\newfontfamily\englishfont[Scale=0.9]{TeX Gyre Termes}
\newfontfamily\codefont[Scale=0.85]{Consolas}

\setdefaultlanguage[calendar=gregorian]{arabic}
\setotherlanguage[variant=british]{english}

\usepackage[bukhari,ornbraces,showgrade,showtrans]{hadith}

\usepackage[breaklinks,colorlinks,linkcolor=blue,urlcolor=blue]{hyperref}
\hypersetup{pdftitle={hadith package documentation},pdfauthor={Nibras Abo Alzahab}}

\EnableCrossrefs
\CodelineIndex

\titleformat{\section}{\large\bfseries}{\thesection}{0.7em}{}
\pagestyle{fancy}
\fancyhf{}
\fancyhead[R]{\small\itshape \textenglish{hadith package v1.1.0}}
\fancyfoot[C]{\small\thepage}
\renewcommand{\headrulewidth}{0.3pt}

\setstretch{1.4}

\newcommand{\cmd}[1]{\textcolor{blue}{\texttt{\char`\\#1}}}

\begin{document}

\title{The \texttt{hadith} Package\\[0.3em]
\large An easy way to typeset Hadith in \LaTeX{}}
\author{Nibras Abo Alzahab\\\texttt{nibras.abo.alzahab@gmail.com}}
\date{\textenglish{Version 1.1.0 \quad 2025-01-15}}

\maketitle

\begin{abstract}
\noindent
The \texttt{hadith} package provides macros for typesetting Hadith text (with Arabic diacritics) from the Seven Canonical Books of Islamic tradition. It is modeled after the \texttt{quran} package and works with Xe\LaTeX{} or Lua\LaTeX{}. \textenglish{Version 1.1.0} adds on-demand chapter loading, all seven collections (36,390 hadiths), English translations, hadith grades, and case-insensitive collection names.
\end{abstract}

\tableofcontents

\section{Introduction}

The \texttt{hadith} package offers an easy way to typeset Hadith---the sayings, actions, and approvals of Prophet Muhammad~\raisebox{0.5ex}{\scalebox{0.8}{ﷺ}}---from the canonical collections. It is inspired by and modeled after the \texttt{quran} package.

\section{Requirements}

The package requires:
\begin{itemize}[itemsep=0.3em]
  \item Xe\LaTeX{} or Lua\LaTeX{} (not pdf\LaTeX{})
  \item \texttt{bidi} package for right-to-left text
  \item \texttt{polyglossia} for Arabic language support
  \item Arabic Unicode font (Amiri, Scheherazade, etc.)
  \item \texttt{xkeyval}, \texttt{xparse}, \texttt{xstring}
\end{itemize}

\section{Loading the Package}

Load the package after \texttt{polyglossia} and before \texttt{hyperref}:

\begin{quote}
\texttt{\char`\\usepackage[sixbooks,showgrade,showtrans]\{hadith\}}
\end{quote}

\section{Package Options}

\begin{longtable}{ll}
\toprule
\textbf{Option} & \textbf{Description} \\
\midrule
\texttt{bukhari} & Load Sahih al-Bukhari \\
\texttt{muslim} & Load Sahih Muslim \\
\texttt{abudawud} & Load Sunan Abi Dawud \\
\texttt{tirmidhi} & Load Jami at-Tirmidhi \\
\texttt{nasai} & Load Sunan an-Nasa'i \\
\texttt{ibnmajah} & Load Sunan Ibn Majah \\
\texttt{malik} & Load Muwatta Malik \\
\texttt{ahmad} & Load Musnad Ahmad \\
\texttt{darimi} & Load Sunan al-Darimi \\
\texttt{sixbooks} & Load the Six Canonical Books (default) \\
\texttt{all} & Load all 9 collections \\
\texttt{nonumber} & Hide hadith numbers \\
\texttt{ornbraces} & Use ornamental brackets for numbers \\
\texttt{compact} & Compact formatting \\
\texttt{showgrade} & Show hadith grades (default: on) \\
\texttt{showtrans} & Show English translations (default: off) \\
\bottomrule
\end{longtable}

\section{Commands}

\subsection{Main command}

\begin{quote}
\cmd{hadith}[collection][number]
\end{quote}

Typeset the specified hadith. Collection names are case-insensitive (\texttt{bukhari}, \texttt{Bukhari}, \texttt{BUKHARI} all work). The starred version \cmd{hadith*} adds a paragraph break after.

\subsection{Range command}

\begin{quote}
\cmd{hadithrange}[collection][start-end]
\end{quote}

Typeset a range of hadiths (e.g., \texttt{[bukhari][1-10]}).

\subsection{Shortcut commands}

\begin{longtable}{ll}
\toprule
\textbf{Command} & \textbf{Equivalent} \\
\midrule
\cmd{hadithbukhari}\{n\} & \cmd{hadith}[bukhari][n] \\
\cmd{hadithmuslim}\{n\} & \cmd{hadith}[muslim][n] \\
\cmd{hadithabudawud}\{n\} & \cmd{hadith}[abudawud][n] \\
\cmd{hadithtirmidhi}\{n\} & \cmd{hadith}[tirmidhi][n] \\
\cmd{hadithnasai}\{n\} & \cmd{hadith}[nasai][n] \\
\cmd{hadithibnmajah}\{n\} & \cmd{hadith}[ibnmajah][n] \\
\bottomrule
\end{longtable}

\subsection{Citation command}

\begin{quote}
\cmd{hadithcite}[collection][number]
\end{quote}

Produces an inline citation like ``[Sahih al Bukhari, \#1]''.

\subsection{Metadata commands}

\begin{quote}
\cmd{hadithname}\{collection\} --- Returns the display name of a collection.\\[0.3em]
\cmd{hadithsection}\{collection\}\{number\} --- Returns the section/chapter name.
\end{quote}

\section{On-Demand Loading}

The package uses on-demand loading to avoid TeX memory limits. Only metadata (index) files are loaded at package initialization. Chapter text files are loaded automatically when a hadith from that chapter is first requested. This keeps memory usage low even with 34,532 hadiths across 6 collections.

\section{Available Collections}

\begin{longtable}{lrr}
\toprule
\textbf{Collection} & \textbf{Hadiths} & \textbf{Chapters} \\
\midrule
Sahih al-Bukhari & 7,589 & 98 \\
Sahih Muslim & 7,563 & 57 \\
Sunan Abi Dawud & 5,274 & 43 \\
Jami at-Tirmidhi & 3,998 & 49 \\
Sunan an-Nasa'i & 5,765 & 52 \\
Sunan Ibn Majah & 4,343 & 38 \\
\midrule
\textbf{Total} & \textbf{34,532} & \textbf{337} \\
\bottomrule
\end{longtable}

\section{Data Source}

Hadith text is sourced from \url{https://github.com/fawazahmed0/hadith-api} (public domain, The Unlicense). The text includes full Arabic diacritics (tashkeel) and English translations.

\section{License}

\begin{itemize}[itemsep=0.3em]
\item Package code (\texttt{.sty}, documentation): \textbf{LPPL 1.3c}
\item Hadith text data (\texttt{.def} files): \textbf{Public domain}
\item Hadith text itself: Classical works, public domain
\end{itemize}

\end{document}