% Sample for persian-calendar: every line shows the call (in monospace) followed by what it prints.
% Build: make test   (XeLaTeX; xepersian and the font Parisa are needed only to print the Persian text)
\documentclass[12pt]{article}

\usepackage[a4paper,margin=2cm]{geometry}
\usepackage{persian-calendar}
\usepackage{pgffor}
\usepackage{tikz}
\usetikzlibrary{calendar}
\usepackage{xepersian}

\settextfont{Parisa}
\setlatintextfont{Latin Modern Roman}

\newcount\jd \newcount\wday

% \note{English text}: explanatory paragraph
\newcommand\note[1]{\par\medskip\noindent\lr{#1}\par\smallskip}
% \code{...}: the call, shown literally
\newcommand\code[1]{\lr{\texttt{\detokenize{#1}}}}
% \demo{call as text}{result}{comment}: one line = call, result, comment
\newcommand\demo[3]{\par\noindent\code{#1}\quad$\Rightarrow$\quad#2\ifx\relax#3\relax\else\quad\lr{(#3)}\fi}

% The date macros take a literal Y-M-D (a macro such as \d would not be expanded),
% so the dates are spelled out through these helpers rather than a \foreach list.
\newcommand\GtoJ[2]{\demo{\pdate{#1}}{\pdate{#1}}{}\demo{\pisodate{#1}}{\lr{\pisodate{#1}}}{#2}\par\smallskip}
\newcommand\JtoG[2]{\demo{\gdate{#1}}{\gdate{#1}}{}\demo{\gisodate{#1}}{\lr{\gisodate{#1}}}{#2}\par\smallskip}
\newcommand\YEAR[1]{\demo{\gisodate{#1-01-01}}{\lr{\gisodate{#1-01-01}}}{start of Jalali year #1}}
% one table cell: year and its animal, empty after 1420; \YROW gives a row of years 8 apart
\newcommand\yc[1]{\edef\yy{\number\numexpr#1\relax}\ifnum\yy>1420 \else\lr{\yy}\quad\pcalyearname{\yy}\fi}
\newcommand\YROW[1]{\yc{#1}&\yc{#1+8}&\yc{#1+16}&\yc{#1+24}&\yc{#1+32}}
\newcommand\WEEKDAY[2]{%
  \pcalweekday{#1}{\wday}%
  \par\noindent\code{#1}\quad$\Rightarrow$\quad\pcaldateweekdayname{#1}\quad\lr{(\number\wday, #2)}}

% the main font is Persian, so the title and the section numbers are set in the Latin font
\title{\lr{persian-calendar: sample and manual test}}\author{}\date{}
\renewcommand\thesection{\lr{\arabic{section}}}
\begin{document}
\setLTR % the explanations are English; only the results are Persian

\maketitle

\note{persian-calendar converts dates between the Persian (Jalali) and Gregorian calendars and provides
Persian month, weekday and year names. Each line below shows the call, an arrow, and the typeset result.
Only printing the Persian text needs a Unicode engine and a Persian font; this sample uses XeLaTeX with
\texttt{xepersian}. The conversions themselves work with any engine.}

\section{\lr{Today}}
\note{\texttt{\textbackslash year}, \texttt{\textbackslash month} and \texttt{\textbackslash day} are
LaTeX's current date (Gregorian), so these lines change every day.}
\demo{\pdate{\year-\month-\day}}{\pdate{\year-\month-\day}}{today as day, month name, year}
\demo{\pisodate{\year-\month-\day}}{\lr{\pisodate{\year-\month-\day}}}{today as DD/MM/YYYY}

\section{\lr{Gregorian to Jalali}}
\note{\texttt{\textbackslash pdate\{Y-M-D\}} takes a Gregorian date and prints the Jalali date with the month name.
\texttt{\textbackslash pisodate\{Y-M-D\}} prints it as DD/MM/YYYY, zero padded.}
\GtoJ{2015-03-21}{Nowruz 1394, the first day of the Jalali year}
\GtoJ{2021-03-20}{last day of a leap year, Esfand 30, 1399}
\GtoJ{2024-03-20}{Nowruz 1403}
\GtoJ{2024-12-31}{a day in Dey, which crosses the Gregorian new year}
\GtoJ{2025-03-20}{Esfand 30, 1403, the next leap-year end}

\section{\lr{Jalali to Gregorian}}
\note{\texttt{\textbackslash gdate\{Y-M-D\}} and \texttt{\textbackslash gisodate\{Y-M-D\}} are the reverse:
the argument is a Jalali date, the result is Gregorian.}
\JtoG{1394-01-01}{Nowruz 1394}
\JtoG{1399-12-30}{last day of leap year 1399}
\JtoG{1403-01-01}{Nowruz 1403}
\JtoG{1403-10-11}{a day in Dey 1403}
\JtoG{1403-12-30}{last day of leap year 1403}

\section{\lr{Start of each Jalali year}}
\note{The Gregorian date on which every fifth Jalali year starts. It is March 20, 21 or 22.}
\YEAR{1380}
\YEAR{1385}
\YEAR{1390}
\YEAR{1395}
\YEAR{1400}
\YEAR{1405}

\section{\lr{Name macros}}
\note{These take a number and print the name. Months are 1 to 12; weekdays are 0 to 6,
where 0 is Saturday, the first day of the Persian week.}
\demo{\pcalmonthname{1}}{\pcalmonthname{1}}{Jalali month 1}
\demo{\pcalmonthname{12}}{\pcalmonthname{12}}{Jalali month 12}
\demo{\pcalgregorianmonthname{3}}{\pcalgregorianmonthname{3}}{Gregorian month 3, in Persian}
\demo{\pcalweekdayname{0}}{\pcalweekdayname{0}}{weekday 0}
\demo{\pcalweekdayname{6}}{\pcalweekdayname{6}}{weekday 6}
\demo{\pcalweekdayshortname{0}}{\pcalweekdayshortname{0}}{short weekday 0}
\par\medskip\noindent\lr{All Jalali months:}\quad
\foreach \m in {1,...,12}{\pcalmonthname{\m}\space}

\section{\lr{Julian day numbers and date arithmetic}}
\note{\texttt{\textbackslash pcaldatetojulian\{Y-M-D\}\{\textbackslash count\}} stores the Julian day
number of a Jalali date in a count register. A \texttt{+N} suffix adds N days.
\texttt{\textbackslash pcaljuliantodate\{\textbackslash count\}\{\textbackslash y\}\{\textbackslash m\}\{\textbackslash d\}}
converts a day number back and sets \texttt{\textbackslash y}, \texttt{\textbackslash m}, \texttt{\textbackslash d}.}
\pcaldatetojulian{1394-01-01}\jd%
\demo{\pcaldatetojulian{1394-01-01}\jd}{\number\jd}{day number of 1394-01-01}
\pcaldatetojulian{1394-01-01+10}\jd%
\demo{\pcaldatetojulian{1394-01-01+10}\jd}{\number\jd}{ten days later}
\pcaljuliantodate\jd\y\m\d%
\demo{\pcaljuliantodate\jd\y\m\d}{\lr{\number\y-\number\m-\number\d}}{back to a Jalali date}
\pcaldatetojulian{1403-12-29+1}\jd%
\pcaljuliantodate\jd\y\m\d%
\demo{\pcaldatetojulian{1403-12-29+1}\jd}{\lr{\number\y-\number\m-\number\d}}{1403 is a leap year, so Esfand has 30 days}
\pcaldatetojulian{1403-12-29+2}\jd%
\pcaljuliantodate\jd\y\m\d%
\demo{\pcaldatetojulian{1403-12-29+2}\jd}{\lr{\number\y-\number\m-\number\d}}{rolls over into the new year}

\section{\lr{Weekday of a Jalali date}}
\note{\texttt{\textbackslash pcalweekday\{Y-M-D\}\{\textbackslash count\}} stores the weekday,
Saturday = 0 as in \texttt{\textbackslash pcalweekdayname}; \texttt{\textbackslash pcaldateweekdayname\{Y-M-D\}}
prints its name.}
\WEEKDAY{1394-01-01}{Saturday, March 21, 2015}
\WEEKDAY{1403-01-01}{Wednesday, March 20, 2024}
\WEEKDAY{1404-01-01}{Friday, March 21, 2025}

\section{\lr{Animal year names}}
\note{\texttt{\textbackslash pcalyearname\{year\}} gives the animal of the 12-year cycle of the
Turkish-Mongol calendar for a Jalali year. It is defined for 0 to 2099 only.}
\medskip
\begin{tabular}{lllll}
\YROW{1380}\\
\YROW{1381}\\
\YROW{1382}\\
\YROW{1383}\\
\YROW{1384}\\
\YROW{1385}\\
\YROW{1386}\\
\YROW{1387}\\
\end{tabular}

\section{\lr{A Jalali month grid with TikZ}}
\note{With \texttt{tikz} and its \texttt{calendar} library loaded, \texttt{jalali dates} and
\texttt{jalali week list} lay out Jalali months, Saturday to Friday. The negative \texttt{day xshift}
puts Saturday on the right. The month is Dey 1404, which has 30 days; Fridays are red.}
\begin{center}
\tikz\calendar[jalali dates=1404-10-01 to 1404-10-last, jalali week list, day xshift=-2em, day yshift=2.4ex,
  jalali month label above centered] if (Friday) [red];
\end{center}

\clearpage
\section{\lr{A year by season}}
\note{One \texttt{\textbackslash calendar} per month in a \texttt{\textbackslash foreach}, placed with
\texttt{at}: each season is a row of three months, read right to left. The labels show the month name only (\texttt{month text}), since all months are in 1405.
1405 is not a leap year, so Esfand ends on the 29th.}
\begin{center}
\begin{tikzpicture}
\foreach \m in {1,...,12} {
  \pgfmathtruncatemacro\col{mod(\m-1,3)}% month within the season
  \pgfmathtruncatemacro\row{div(\m-1,3)}% season
  \calendar at (-\col*6.2cm, -\row*5cm)
    [jalali dates=1405-\m-01 to 1405-\m-last, jalali week list,
     day xshift=-0.8cm, day yshift=0.55cm, jalali month label above centered,
     month text={\pcalmonthname{\pcalcurrentmonth}}]
    if (Friday) [red];
}
\end{tikzpicture}
\end{center}

\clearpage
\section{\lr{A boxed grid with weekday initials}}
\note{\texttt{jalali day boxes} draws each day as a box one step wide and high, so the boxes join into a
grid, and empty boxes complete the first and last weeks; \texttt{jalali weekday initials} adds the initials above each month. Fridays are filled through their
\texttt{every day} style.}
\begin{center}
\tikz\calendar[jalali dates=1405-01-01 to 1405-02-last, jalali week list,
  jalali day boxes, jalali weekday initials,
  day xshift=-0.9cm, day yshift=0.7cm, jalali month label above centered]
  if (Friday) [red, every day/.append style={fill=red!10}];
\end{center}

\section{\lr{Limits}}
\note{The date arguments must be literal \texttt{Y-M-D} text. A macro holding a date, such as
\texttt{\textbackslash pdate\{\textbackslash mydate\}}, is not expanded and fails. The Jalali leap rule is the
33-year arithmetic approximation, which can differ from the official calendar in some years.}

\end{document}