% Persian manual of the persian-calendar package. Build: make doc   (XeLaTeX, font XB Niloofar)
\documentclass[11pt]{article}

\usepackage[a4paper,margin=2.5cm]{geometry}
\usepackage{persian-calendar}
\usepackage{pgffor}
\usepackage{tikz}
\usetikzlibrary{calendar}
\usepackage[colorlinks,linkcolor=blue!50!black,urlcolor=blue!50!black]{hyperref}
\usepackage{xepersian}

\settextfont{XB Niloofar}
\setdigitfont{Parisa}
\setlatintextfont[Extension=.otf,BoldFont=lmroman10-bold,ItalicFont=lmroman10-italic,BoldItalicFont=lmroman10-bolditalic]{lmroman10-regular}

% --- helpers --------------------------------------------------------------
\newcommand\tx[1]{\mbox{\lr{\texttt{#1}}}}                  % code inside Persian text
\newcommand\cs[1]{\mbox{\lr{\texttt{\textbackslash #1}}}}   % a control sequence
\newcommand\pkg[1]{\mbox{\lr{\textsf{#1}}}}
\newcommand\iso[1]{\mbox{\lr{#1}}}                          % numeric dates must stay left to right
\newcommand\gap{\par\smallskip}
% \macro|syntax|: heading line for a macro description
\NewDocumentCommand\macro{v}{\par\bigskip\noindent\lr{\texttt{\bfseries #1}}\par\nopagebreak\smallskip}
% \ex|code|{result}: a call, an arrow and its typeset result (the call is typed twice on purpose)
\NewDocumentCommand\ex{v m}{\par\noindent\hspace*{1em}\lr{\texttt{#1}}\quad$\leftarrow$\quad#2}
\emergencystretch=3em
\newcount\jd \newcount\wday
\makeatletter\renewcommand*\l@section{\@dottedtocline{1}{0em}{2.3em}}\makeatother
% table cells for the name lists: \mc{n} month n, \yc{y} year y, each a number cell and a name cell,
% so both line up in right-to-left tables; \MROW/\YROW{first} fill a row of four/six pairs
\newcommand\mc[1]{\tx{\number\numexpr#1\relax}&\pcalmonthname{\number\numexpr#1\relax}}
\newcommand\yc[1]{\tx{\number\numexpr#1\relax}&\pcalyearname{\number\numexpr#1\relax}}
\newcommand\MROW[1]{\mc{#1}&\mc{#1+3}&\mc{#1+6}&\mc{#1+9}}
\newcommand\YROW[1]{\yc{#1}&\yc{#1+3}&\yc{#1+6}&\yc{#1+9}&\yc{#1+12}&\yc{#1+15}}

\title{بستهٔ \pkg{persian-calendar}}
\author{جواد رضویان\thanks{کد منبع و گزارش اشکال:\\
  \lr{\url{https://github.com/javadr/persian-calendar}}}}
\date{نسخهٔ \lr{\pcalendarversion}\quad(\lr{\pcalendardate})}

\begin{document}

\maketitle

\begin{abstract}\noindent
\pkg{persian-calendar} بسته‌ای برای کار با تقویم هجری شمسی در \lr{\LaTeX} است. با آن می‌توانید تاریخ شمسی را به
میلادی و تاریخ میلادی را به شمسی تبدیل کنید، تاریخ را با نام فارسی ماه‌ها چاپ کنید و به تاریخ‌ها روز
اضافه کنید یا از آن‌ها روز کم کنید. نام ماه‌ها، روزهای هفته و سال‌های دوازده‌حیوانی هم در همین بسته آماده
است. \pkg{persian-calendar} بر پایهٔ \pkg{pgfcalendar} نوشته شده است. تبدیل تاریخ با هر موتور \TeX{} کار می‌کند؛
فقط برای چاپ نام‌های فارسی به موتوری با پشتیبانی یونیکد و یک قلم فارسی نیاز دارید، مثلاً \lr{XeLaTeX}
همراه با \pkg{xepersian}.
\end{abstract}

\tableofcontents

% ---------------------------------------------------------------------------
\section{معرفی}\label{sec:what}

با \pkg{persian-calendar} می‌توانید:
\begin{itemize}
  \item تاریخ میلادی را به شمسی و تاریخ شمسی را به میلادی تبدیل کنید، چه به‌صورت متن (مثل «۱ فروردین ۱۳۹۴») و چه به‌صورت عدد (مثل ۰۱/۰۱/۱۳۹۴)؛
  \item شمارهٔ روز ژولین یک تاریخ شمسی را بگیرید، چند روز به آن اضافه یا از آن کم کنید و دوباره به تاریخ
    برگردانید؛
  \item نام ماه‌های شمسی و میلادی و نام روزهای هفته را چاپ کنید؛
  \item بفهمید هر سال به کدام حیوان از دورهٔ دوازده‌ساله تعلق دارد؛
  \item با کتابخانهٔ \tx{calendar} در \pkg{TikZ} جدول ماه‌ها و تقویم سال‌های شمسی را رسم کنید (بخش~\ref{sec:tikz})؛
  \item پلنر سالانهٔ دوصفحه‌ای به شیوهٔ \pkg{yplan} چاپ کنید (بخش~\ref{sec:yplan}).
\end{itemize}
اما این بسته مناسبت‌ها و تعطیلات رسمی را نمی‌شناسد.

\paragraph{پیش‌نیازها.} تبدیل تاریخ فقط به بستهٔ \pkg{pgf} (که \pkg{pgfcalendar} بخشی از آن است) نیاز دارد و با \lr{pdfLaTeX}، \lr{XeLaTeX} و \lr{LuaLaTeX} کار می‌کند. نام‌های فارسی (و در نتیجه \cs{pdate}، \cs{gdate} و فرمان‌های نام) به‌صورت متن \lr{UTF-8} در خود فایل بسته نوشته شده‌اند؛ پس چاپ آن‌ها به موتور و بسته‌هایی نیاز دارد که حروف فارسی \lr{UTF-8} را پشتیبانی کنند و به قلمی که این حروف را داشته باشد. این راهنما از \pkg{xepersian} همراه با \lr{XeLaTeX} استفاده می‌کند، اما هر روش دیگری که فارسی را حروف‌چینی کند کافی است. اگر چنین چیزی ندارید، از فرمان‌های عددی \cs{pisodate} و \cs{gisodate} استفاده کنید که فقط رقم چاپ می‌کنند.

% ---------------------------------------------------------------------------
\section{بارگذاری بسته}\label{sec:install}

\lr{TeX Live} و \lr{MiKTeX} این بسته را از \lr{CTAN} نصب می‌کنند، پس نیازی به نصب دستی نیست.

بسته را در مقدمهٔ سند بارگذاری کنید. در این راهنما برای متن فارسی از \pkg{xepersian} استفاده شده و \pkg{persian-calendar} پیش از آن بارگذاری می‌شود:
\begin{latin}\begin{verbatim}
\usepackage{persian-calendar}
\usepackage{xepersian}
\settextfont{XB Niloofar}
\end{verbatim}\end{latin}
\paragraph{گزینهٔ \tx{tikz}.} تقویم‌های شمسی بخش~\ref{sec:tikz} به \pkg{TikZ} و کتابخانهٔ \tx{calendar} آن نیاز دارند. گزینهٔ \tx{tikz} هر دو را بارگذاری می‌کند:
\begin{latin}\begin{verbatim}
\usepackage[tikz]{persian-calendar}
\end{verbatim}\end{latin}
بدون این گزینه بسته فقط \pkg{pgf} و \pkg{pgfcalendar} را بارگذاری می‌کند، پس سندی که فقط تاریخ تبدیل می‌کند سریع‌تر بارگذاری می‌شود. اگر \pkg{tikz} یا این کتابخانه را خودتان هم بارگذاری کنید اشکالی ندارد.

% ---------------------------------------------------------------------------
\section{شروع سریع}\label{sec:quick}

\begin{latin}\begin{verbatim}
\pdate{2015-03-21}          % Gregorian in, Jalali text out
\gdate{1394-01-01}          % Jalali in, Gregorian text out
\pisodate{2015-03-21}       % Gregorian in, Jalali as DD/MM/YYYY
\gisodate{1394-01-01}       % Jalali in, Gregorian as DD/MM/YYYY
\end{verbatim}\end{latin}
این چهار فرمان چنین چاپ می‌شوند:
\ex|\pdate{2015-03-21}|{\pdate{2015-03-21}}
\ex|\gdate{1394-01-01}|{\gdate{1394-01-01}}
\ex|\pisodate{2015-03-21}|{\iso{\pisodate{2015-03-21}}}
\ex|\gisodate{1394-01-01}|{\iso{\gisodate{1394-01-01}}}
\gap
تاریخ امروز را هم می‌توانید به تقویم شمسی چاپ کنید. نوشتن \cs{pdate}\tx{\{\textbackslash year-\textbackslash month-\textbackslash day\}} امروز را این‌طور چاپ می‌کند: \pdate{\year-\month-\day}.

% ---------------------------------------------------------------------------
\section{تبدیل تاریخ}\label{sec:date}

هر چهار فرمان یک ورودی می‌گیرند: تاریخی به شکل \tx{Y-M-D}، یعنی سال و شمارهٔ ماه و روز که با خط تیره از هم جدا شده‌اند. صفر ابتدای ماه و روز را می‌توانید ننویسید: \tx{2015-3-21} با \tx{2015-03-21} فرقی ندارد.

\macro|\pdate{Y-M-D}|
تاریخ میلادی می‌گیرد و تاریخ شمسی را به شکل «روز، نام ماه، سال» چاپ می‌کند؛ مثلاً \pdate{2024-03-20}.

\macro|\gdate{Y-M-D}|
تاریخ شمسی می‌گیرد و تاریخ میلادی را به همان شکل چاپ می‌کند. نام ماه میلادی هم فارسی نوشته می‌شود؛ مثلاً \gdate{1403-01-01}.

\macro|\pisodate{Y-M-D}|
مثل \cs{pdate} تاریخ میلادی می‌گیرد و تاریخ شمسی چاپ می‌کند، اما به‌صورت عددی: روز و ماه دورقمی‌اند و با اسلش از هم جدا می‌شوند؛ مثلاً \iso{\pisodate{2024-03-20}}. ترتیب خروجی روز/ماه/سال است، نه سال-ماه-روز مثل استاندارد \lr{ISO}.

\macro|\gisodate{Y-M-D}|
مثل \cs{gdate} تاریخ شمسی می‌گیرد و تاریخ میلادی چاپ می‌کند، اما عددی و با همان ترتیب روز/ماه/سال؛ مثلاً
\iso{\gisodate{1403-01-01}}.

\paragraph{سال کبیسه.} اسفند در سال کبیسه ۳۰ روز دارد:
\ex|\pdate{2025-03-20}|{\pdate{2025-03-20}}
\ex|\gdate{1403-12-30}|{\gdate{1403-12-30}}
\ex|\gdate{1404-12-30}|{\gdate{1404-12-30}}
\gap
تاریخ آخر غلط است، چون ۱۴۰۴ کبیسه نیست؛ اما بسته درست‌بودن ورودی را بررسی نمی‌کند
(بخش~\ref{sec:limits}).

\paragraph{نکتهٔ حروف‌چینی.} در متن فارسی ممکن است جای عددها عوض شود، چون \TeX{} متن دوسویه را طبق قاعدهٔ خاصی می‌چیند. اگر می‌خواهید خروجی \cs{pisodate} و \cs{gisodate} همیشه به ترتیب روز/ماه/سال بماند، آن را درون \cs{lr} بگذارید؛ در همین راهنما هم همین کار شده است.

% ---------------------------------------------------------------------------
\section{شمارهٔ روز و محاسبه روی تاریخ}\label{sec:julian}

فرمان‌های بالا فقط تبدیل می‌کنند و با آن‌ها نمی‌شود به تاریخ روز اضافه کرد. برای این کار بسته از شمارهٔ روز ژولین کمک می‌گیرد، همان شماره‌ای که \pkg{pgfcalendar} تعریف کرده است. روزها از یک مبدأ ثابت شمرده می‌شوند، پس تفاضل دو شماره دقیقاً برابر با تعداد روزهای بین دو تاریخ است.

\macro|\pcaldatetojulian{Y-M-D}{\count}|
شمارهٔ روز تاریخ \emph{شمسی} \tx{Y-M-D} را در شمارندهٔ \cs{count} می‌گذارد. اگر \tx{+N} را به آخر تاریخ بچسبانید، \tx{N} روز هم به آن اضافه می‌شود؛ مثلاً \tx{1394-01-01+10} یعنی ده روز بعد از اول فروردین ۱۳۹۴.

\macro|\pcaljuliantodate{\count}{\y}{\m}{\d}|
شمارهٔ روزِ داخل \cs{count} را دوباره به تاریخ \emph{شمسی} تبدیل می‌کند و سال و ماه و روز را در فرمان‌های \cs{y} و \cs{m} و \cs{d} می‌گذارد (به‌جای این سه می‌توانید نام دیگری هم بدهید).

\begin{latin}\begin{verbatim}
\newcount\jd
\pcaldatetojulian{1394-01-01+10}\jd
\pcaljuliantodate\jd\y\m\d
\number\y-\number\m-\number\d
\end{verbatim}\end{latin}
\pcaldatetojulian{1394-01-01+10}\jd%
\pcaljuliantodate\jd\y\m\d%
خروجی این کد \iso{\number\y-\number\m-\number\d} است.

\paragraph{\cs{y} و \cs{m} و \cs{d} را همان لحظه بخوانید.} بعد از \cs{pcaljuliantodate}، این سه فرمان رونوشتی از مقدار نیستند و فقط نام دیگری برای شمارنده‌های نتیجهٔ بسته‌اند. به همین دلیل هر تبدیل بعدی (\cs{pdate}، \cs{gisodate} و مانند آن‌ها) مقدارشان را عوض می‌کند. اگر بعداً به آن‌ها نیاز دارید، همان لحظه در شمارنده‌های خودتان نگه‌شان دارید:
\tx{\textbackslash newcount\textbackslash myyear\ \textbackslash myyear=\textbackslash y}.

\macro|\pcaldaysbetween{Y-M-D}{Y-M-D}{\count}|
تعداد روزها از تاریخ شمسی اول تا تاریخ شمسی دوم را در \cs{count} می‌گذارد؛ اگر تاریخ دوم زودتر باشد، نتیجه منفی است. هر دو تاریخ، مانند \cs{pcaldatetojulian}، می‌توانند با جابه‌جایی چند روزه تمام شوند.
\begin{latin}\begin{verbatim}
\newcount\n
\pcaldaysbetween{1403-01-01}{1404-01-01}{\n}
\number\n
\end{verbatim}\end{latin}
\pcaldaysbetween{1403-01-01}{1404-01-01}{\jd}%
نتیجه \number\jd{} روز است (۱۴۰۳ کبیسه است).

\paragraph{عبور از پایان سال.} محاسبهٔ روز، سال کبیسه را هم درنظر می‌گیرد:
\pcaldatetojulian{1403-12-29+1}\jd\pcaljuliantodate\jd\y\m\d%
یک روز بعد از ۱۴۰۳-۱۲-۲۹ می‌شود \iso{\number\y-\number\m-\number\d}، چون ۱۴۰۳ کبیسه است؛
\pcaldatetojulian{1403-12-29+2}\jd\pcaljuliantodate\jd\y\m\d%
و دو روز بعد از آن می‌شود \iso{\number\y-\number\m-\number\d}.

\paragraph{شمارنده‌های موقت.} \cs{pcaldatetojulian} هنگام کار از \cs{count1}، \cs{count2}، \cs{count3} و \cs{count8} استفاده می‌کند؛ پس مقداری در این شمارنده‌ها نگه ندارید.

% ---------------------------------------------------------------------------
\section{نام‌ها}\label{sec:names}

\macro|\pcalmonthname{n}|
نام ماه شمسی را چاپ می‌کند. \tx{n} عددی از ۱ تا ۱۲ است؛ برای عددهای دیگر چیزی چاپ نمی‌شود.
\ex|\pcalmonthname{1}|{\pcalmonthname{1}}
\gap
نام هر دوازده ماه به ترتیب:\gap
\begin{tabular}{*{4}{rr@{\hspace{1.5em}}}}
\MROW{1}\\
\MROW{2}\\
\MROW{3}
\end{tabular}

\macro|\pcalgregorianmonthname{n}|
نام ماه میلادی را به فارسی چاپ می‌کند (مثلاً «مارس»). \tx{n} این‌جا هم از ۱ تا ۱۲ است.
\ex|\pcalgregorianmonthname{3}|{\pcalgregorianmonthname{3}}

\macro|\pcalweekdayname{n}|
نام روز هفته را چاپ می‌کند. \tx{n} از ۰ تا ۶ است: ۰ شنبه، یعنی اولین روز هفته در ایران، و ۶ جمعه است.
\gap\leavevmode
\foreach \w in {0,...,6}{\hbox{\tx{\w}~\pcalweekdayname{\w}}\quad}

\macro|\pcalweekdayshortname{n}|
مخفف تک‌حرفی روز هفته را چاپ می‌کند؛ شماره‌گذاری مثل فرمان قبلی است.
\gap\leavevmode
\foreach \w in {0,...,6}{\hbox{\tx{\w}~\pcalweekdayshortname{\w}}\quad}

\macro|\pcalyearname{year}|
حیوان یک سال شمسی را در دورهٔ دوازده‌ساله چاپ می‌کند. \tx{year} باید بین ۰ تا ۲۰۹۹ باشد؛ برای مقدارهای دیگر چیزی چاپ نمی‌شود.
\ex|\pcalyearname{1403}|{\pcalyearname{1403}}
\gap
حیوان‌های سال به ترتیب، از سال ۱۳۸۰:\gap
{\setlength\tabcolsep{4pt}% six columns fit the text width
\begin{tabular}{*{6}{rr@{\hspace{1em}}}}
\YROW{1380}\\
\YROW{1381}\\
\YROW{1382}
\end{tabular}}

\macro|\pcalweekday{Y-M-D}{\count}|
روز هفتهٔ یک تاریخ شمسی را در شمارندهٔ \tx{\textbackslash count} می‌گذارد، با همان شماره‌گذاری \cs{pcalweekdayname}: ۰ شنبه و ۶ جمعه است. مانند \cs{pcaldatetojulian}، تاریخ می‌تواند با جابه‌جایی چند روزه تمام شود و ماکروهای درون آن باز می‌شوند.
\begin{latin}\begin{verbatim}
\newcount\wday
\pcalweekday{1403-01-01}{\wday}      % \wday = 4, Wednesday
\pcalweekday{1403-01-01+10}{\wday}   % ten days later: 0, Saturday
\end{verbatim}\end{latin}

\macro|\pcaldateweekdayname{Y-M-D}|
نام روز هفتهٔ یک تاریخ شمسی را چاپ می‌کند: \cs{pcalweekdayname} از نتیجهٔ \cs{pcalweekday}.
\ex|\pcaldateweekdayname{1403-01-01}|{\pcaldateweekdayname{1403-01-01}}

% ---------------------------------------------------------------------------
\section{تقویم با \lr{TikZ}}\label{sec:tikz}

کتابخانهٔ \tx{calendar} در \pkg{TikZ} با فرمان \cs{calendar} تقویم رسم می‌کند، اما فقط ماه‌های میلادی را می‌شناسد. این بسته چند کلید به آن اضافه می‌کند تا ماه‌های شمسی را بچیند. این کلیدها به \pkg{tikz} و این کتابخانه نیاز دارند که گزینهٔ \tx{tikz} آن‌ها را بارگذاری می‌کند (بخش~\ref{sec:install}):
\begin{latin}\begin{verbatim}
\usepackage[tikz]{persian-calendar}
...
\tikz\calendar[jalali dates=1405-01-01 to 1405-03-last,
               jalali week list, day xshift=-2.2em, day yshift=2.5ex,
               jalali month label above centered]
  if (Friday) [red] if (jalali equals=1-13) [blue];
\end{verbatim}\end{latin}
\begin{center}
\tikz\calendar[jalali dates=1405-01-01 to 1405-03-last,
               jalali week list, day xshift=-2.2em, day yshift=2.5ex,
               jalali month label above centered]
  if (Friday) [red] if (jalali equals=1-13) [blue];
\end{center}

\macro|jalali dates=Y-M-D to Y-M-D|
بازهٔ تاریخ‌هایی که رسم می‌شوند، به تاریخ شمسی. به‌جای روز می‌توانید \tx{last} بنویسید که یعنی روز آخر همان ماه (برای اسفند، بسته به کبیسه بودن سال، ۲۹ یا ۳۰). این کلید همان کلید \tx{dates} کتابخانه را تنظیم می‌کند، پس این دو را با هم به کار نبرید.

\macro|jalali|
تقویم را شمسی می‌کند. شمارهٔ روز، روز شمسی را نشان می‌دهد و عنوان ماه، نام فارسی ماه را همراه با سال (با \tx{day text} و \tx{month text} می‌توانید آن‌ها را عوض کنید). درون تقویم، شرط \tx{day of month=n} به روز شمسی اشاره می‌کند؛ به همین دلیل سبک‌های \tx{month label ...} خود کتابخانه در روز اول هر ماه شمسی اجرا می‌شوند. برای هر روز، \cs{pcalcurrentyear}، \cs{pcalcurrentmonth} و \cs{pcalcurrentday} تاریخ شمسی را نگه می‌دارند و \cs{pcalcurrentweekday} روز هفته را، با شمارش از شنبه برابر ۰ (مثل \cs{pcalweekdayname})؛ پس می‌توانید از آن‌ها در \tx{day code} استفاده کنید.

\macro|jalali week list|
مثل \tx{week list} کتابخانه، اما برای ماه‌های شمسی: \tx{jalali} را هم شامل می‌شود، هر هفته از شنبه تا جمعه است و هر ماه از سطر تازه‌ای شروع می‌شود. با \tx{day xshift} مثبت (پیش‌فرض) شنبه در سمت چپ است؛ با مقدار منفی، مثل نمونهٔ بالا، شنبه به سمت راست می‌رود.

\macro|jalali month label above centered|
مثل \tx{month label above centered} کتابخانه، که عنوان را با فاصلهٔ ثابت \tx{1.5ex} جا می‌دهد و برای همین کمی از وسط کنار می‌رود. این سبک پهنای یک روز دورقمی (\tx{30}) را با قلم جاری اندازه می‌گیرد و فاصلهٔ داخلی (\tx{inner sep}) گره‌های روز را هم به آن اضافه می‌کند؛ پس عنوان با هر اندازهٔ قلم درست بالای وسط هفته می‌نشیند. این سبک فرض می‌کند لنگر \tx{every day} همان پیش‌فرض کتابخانه (\tx{base east}) است.

\macro|jalali week columns|
چیدمان برعکس، مثل \pkg{calxxxx-yyyy}: هر روز هفته یک سطر (شنبه بالا) و بعد از هر جمعه یک ستون تازه؛ پس هر ماه چهار تا شش ستون پهنا دارد. با \tx{day xshift} منفی، هفتهٔ اول سمت راست قرار می‌گیرد. \tx{jalali day boxes} ستون‌های اول و آخر را کامل می‌کند، \tx{jalali weekday initials} حرف‌های روزهای هفته را در ستونی کنار ماه می‌گذارد و \tx{jalali month label above centered} عنوان را بالای وسط ستون‌های همان ماه می‌نشاند. نمونهٔ \tx{persian-calendar-years.tex} با همین کلید تقویم چند سال را، نُه سال در هر صفحهٔ \lr{A4}، چاپ می‌کند؛ کافی است \cs{FirstYear} و \cs{LastYear} را در ابتدای آن تنظیم کنید.

\macro|jalali day boxes|
هر روز را در خانه‌ای به پهنای یک گام روز (\tx{day xshift}) و به ارتفاع \tx{day yshift} رسم می‌کند تا خانه‌ها به هم بچسبند و جدول بسازند. همراه با \tx{jalali week list}، خانه‌های خالی جای روزهای پیش از روز اول و پس از روز آخر هر ماه (یا بازه) را پر می‌کنند تا هر ماه یک مستطیل کامل از هفته‌های کامل باشد. ارتفاع و عمق متن با واحد \tx{ex} ثابت شده است، پس سطرها با هر اندازهٔ قلم هم‌تراز می‌مانند. در این حالت \tx{jalali month label above centered} عنوان را بالای وسط خانه‌ها می‌گذارد. برای رنگ کردن زمینهٔ برخی روزها، مثل نمونهٔ زیر به سبک \tx{every day} آن‌ها چیزی اضافه کنید؛ \tx{fill=} ساده در \tx{if (...)} به خانه نمی‌رسد.

\macro|jalali weekday initials|
بالای هر ماه یک سطر حرف اول روزهای هفته (\pcalweekdayshortname{0}، \pcalweekdayshortname{1}، ...، \pcalweekdayshortname{6}، از \cs{pcalweekdayshortname}) می‌گذارد؛ اگر \tx{jalali day boxes} روشن باشد، این حرف‌ها هم در خانه می‌نشینند. این کلید با \tx{jalali week list} کار می‌کند و عنوان ماه بالای این سطر می‌رود. ظاهر حرف‌ها را با \tx{every jalali weekday} تنظیم کنید، مثلاً \tx{every jalali weekday/.style=\{font=\textbackslash bfseries\}}.

با هر کدام از این دو کلید، هر ماه دست‌کم سه سطر (با حرف‌های هفته چهار سطر) پایین‌تر از ماه قبل شروع می‌شود، هرچقدر هم \tx{month yshift} کوچک باشد؛ پس هفتهٔ ناتمام آخر ماه هیچ‌وقت روی عنوان ماه بعد نمی‌افتد.
\begin{latin}\begin{verbatim}
\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{verbatim}\end{latin}
\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}

\macro|jalali equals=M-D|
شرطی که در هر سال با یک ماه و روز شمسی جور درمی‌آید؛ مثلاً \tx{jalali equals=1-1} برای نوروز. این شرط و \tx{jalali day of month=n} را می‌توان در \tx{if (...)} و با \cs{pgfcalendarifdate} به کار برد، حتی بیرون از تقویم‌های \tx{jalali}.

\paragraph{چیدمان‌های دیگر.} \tx{day list downward}، \tx{day list upward}، \tx{day list right} و \tx{day list left} همراه با \tx{jalali} درست کار می‌کنند، چون فقط شرط \tx{day of month=1} را می‌سنجند. اما \tx{week list} و \tx{month list} کتابخانه از روز و روز هفتهٔ میلادی استفاده می‌کنند؛ به‌جای آن‌ها \tx{jalali week list} را به کار ببرید.

\paragraph{یک سال، فصل به فصل.} با \cs{foreach} برای هر ماه یک تقویم رسم کنید و جای آن را با \tx{at} تعیین کنید: شمارهٔ ماه در فصل ستون را مشخص می‌کند و شمارهٔ فصل سطر را. علامت منفی در \tx{-\textbackslash col} ماه‌های بعدی را به چپ می‌برد تا صفحه از راست به چپ خوانده شود؛ برای چپ به راست، این علامت و علامت منفی \tx{day xshift} را بردارید. فاصلهٔ افقی باید از پهنای هفت روز و فاصلهٔ عمودی از ارتفاع شش هفته و عنوان ماه بیشتر باشد. \tx{1405-\textbackslash m-01} کار می‌کند چون خط‌های تیره نوشته شده‌اند و \cs{m} فقط به‌عنوان عدد خوانده می‌شود؛ اما ماکرویی که کل تاریخ را نگه دارد کار نمی‌کند. چون همهٔ ماه‌ها در یک سال‌اند، \tx{month text} عنوان پیش‌فرض (ماه و سال) را با نام ماه به‌تنهایی عوض می‌کند؛ آن را بعد از \tx{jalali week list} بنویسید، چون آن سبک عنوان خودش را تنظیم می‌کند.
\begin{latin}\begin{verbatim}
\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*5.4cm, -\row*4.6cm)
    [jalali dates=1405-\m-01 to 1405-\m-last, jalali week list,
     day xshift=-0.7cm, day yshift=0.5cm,
     jalali month label above centered,
     month text={\pcalmonthname{\pcalcurrentmonth}}]
    if (Friday) [red];
}
\end{tikzpicture}
\end{verbatim}\end{latin}
\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*5.4cm, -\row*4.6cm)
    [jalali dates=1405-\m-01 to 1405-\m-last, jalali week list,
     day xshift=-0.7cm, day yshift=0.5cm,
     jalali month label above centered,
     month text={\pcalmonthname{\pcalcurrentmonth}}]
    if (Friday) [red];
}
\end{tikzpicture}
\end{center}

\paragraph{تقویم چند سال.} سند \pkg{calxxxx-yyyy} در \lr{CTAN} تقویم میلادی چند سال را چاپ می‌کند: نُه سال در هر صفحه، هر سال در چهار سطر سه‌ماهه، و هر ماه با یک ستون برای هر هفته و یک سطر برای هر روز هفته. \cs{pcalyear} و \cs{pcalyears} همین چیدمان را با \tx{jalali week columns} برای سال‌های شمسی رسم می‌کنند. این دو فرمان هم مانند کلیدهای بالا به \pkg{TikZ} و کتابخانهٔ \tx{calendar} آن (گزینهٔ \tx{tikz}) نیاز دارند و بدون آن‌ها با پیام خطایی که همین را می‌گوید متوقف می‌شوند.

\macro|\pcalyear{year}|
یک سال شمسی را به‌صورت یک \tx{tikzpicture} رسم می‌کند: سال در بالا، سپس چهار سطر برای فصل‌ها، هر کدام سه ماه از راست به چپ، با جمعه‌های قرمز. اندازهٔ آن برای نُه سال در یک صفحهٔ \lr{A4} تنظیم شده است، \lr{0.3\,cm} برای هر روز.

\macro|\pcalyears{first}{last}|
سال‌های \tx{first} تا \tx{last} را، سه سال در هر سطر، در هر چند صفحه که لازم باشد رسم می‌کند. نمونهٔ \tx{persian-calendar-years.tex}، که همراه بسته است، معادل شمسی \pkg{calxxxx-yyyy} است: \cs{pcalyears} را با \cs{FirstYear} و \cs{LastYear} صدا می‌زند که در ابتدای آن \tx{1405} و \tx{1413} تنظیم شده‌اند.

\paragraph{سبک‌ها.} چهار سبک \pkg{TikZ} ظاهر تقویم را تغییر می‌دهند؛ آن‌ها را با \cs{tikzset} تنظیم کنید:
\begin{itemize}
  \item \tx{every pcal year}: تصویر هر سال، که با \tx{font=\textbackslash tiny} شروع می‌شود؛
  \item \tx{every pcal year title}: سال در بالای تصویر، که با \tx{font=\textbackslash footnotesize\textbackslash bfseries} شروع می‌شود؛
  \item \tx{every pcal month}: به گزینه‌های \cs{calendar} هر ماه، پس از گزینه‌های خود بسته، افزوده می‌شود؛
  \item \tx{pcal friday}: جمعه‌ها، که به‌طور پیش‌فرض \tx{red} است.
\end{itemize}
سه سبک اول خالی‌اند. برای نمونه \tx{\textbackslash tikzset\{pcal friday/.style=\{blue\}\}} جمعه‌ها را آبی رسم می‌کند. این خروجی \tx{\textbackslash pcalyear\{1405\}} است:
\begin{center}
\pcalyear{1405}
\end{center}

% ---------------------------------------------------------------------------
\section{پلنر سالانه}\label{sec:yplan}

بستهٔ \pkg{yplan} در \lr{CTAN} یک پلنر سالانهٔ عمودی چاپ می‌کند: همهٔ روزهای سال در دو صفحهٔ \lr{A4}، شش ماه در هر صفحه، با یک ستون برای هر ماه و یک سطر برای هر روز. \cs{pcalplanner} همین کار را برای سال شمسی انجام می‌دهد. این پلنر یک \tx{tabular} معمولی است، پس به \pkg{TikZ} یا بستهٔ دیگری جز آن‌چه برای چاپ فارسی لازم است نیازی ندارد.

\macro|\pcalplanner{year}|  \quad\lr{\texttt{\bfseries\textbackslash pcalplanner*\{year\}}}
سال شمسی \tx{year} را در دو صفحه چاپ می‌کند: فروردین تا شهریور، و سپس مهر تا اسفند. هر صفحه با \cs{clearpage} شروع می‌شود و سبک صفحهٔ \tx{empty} دارد. بالای جدول سال و در سال کبیسه پس از آن \cs{pcalplannerleapyear} («\pcalplannerleapyear») می‌آید. در کنار جدول نام روزهای هفته است و سطرها بر اساس روز هفته چیده شده‌اند، پس هر سطر در همهٔ ماه‌ها یک روز هفته است. هفته از شنبه تا جمعه است و پس از هر جمعه خط دوتایی می‌آید. مانند \pkg{yplan} فقط دور خانه‌هایی که روز دارند خط کشیده می‌شود، و هر صفحه به اندازهٔ نیاز ماه‌هایش سطر دارد (حداکثر ۳۷). شش ستون ماه پهنایی را که ستون روزهای هفته و خط‌ها باقی می‌گذارند به تساوی تقسیم می‌کنند، پس حاشیه‌های صفحه پهنای آن‌ها را تعیین می‌کند. با \pkg{xepersian} جدول راست‌به‌چپ است: ستون روزهای هفته در سمت راست و پس از آن فروردین. سال می‌تواند یک ماکرو باشد.
\begin{latin}\begin{verbatim}
\documentclass{article}
\usepackage[a4paper,margin=1.2cm]{geometry}
\usepackage{persian-calendar}
\usepackage{xepersian}
\settextfont{Parisa}
\begin{document}
\pcalplanner{1405}
\end{document}
\end{verbatim}\end{latin}
نمونهٔ \tx{persian-calendar-planner.tex}، که همراه بسته است، چنین پلنرهایی را با جمعه‌های سایه‌دار و چند یادداشت چاپ می‌کند.

\paragraph{شمارهٔ هفته.} \cs{pcalplanner} شمارهٔ هفته را در هر خانهٔ شنبه، در سوی دیگر خانه نسبت به شمارهٔ روز (با \pkg{xepersian} سمت چپ)، و اگر ۱ فروردین شنبه نباشد در خانهٔ ۱ فروردین هم چاپ می‌کند؛ \cs{pcalplanner*} شمارهٔ هفته‌ها را چاپ نمی‌کند. قاعدهٔ رسمی‌ای برای شماره‌گذاری هفته‌های سال شمسی وجود ندارد، پس بسته استاندارد \lr{ISO 8601} را به هفتهٔ ایرانی منتقل می‌کند. \lr{ISO} هفتهٔ ۱ را هفته‌ای می‌گیرد که نخستین پنجشنبهٔ سال در آن است؛ پنجشنبه روز میانی هفتهٔ دوشنبه تا یکشنبه است. روز میانی هفتهٔ شنبه تا جمعه سه‌شنبه است، پس اینجا هفتهٔ ۱ هفته‌ای است که نخستین سه‌شنبهٔ سال، یعنی ۴ فروردین، در آن است. مانند \lr{ISO} همهٔ هفته‌ها از شنبه تا جمعه‌اند و سال ۵۲ هفته دارد، یا ۵۳ هفته اگر ۱ فروردین سه‌شنبه باشد، یا در سال کبیسه دوشنبه. اگر ۱ فروردین چهارشنبه، پنجشنبه یا جمعه باشد، ۱ تا ۳ فروردین جزو آخرین هفتهٔ سال قبل‌اند: ۱ فروردین ۱۴۰۳، که چهارشنبه بود، در هفتهٔ ۵۳ سال ۱۴۰۲ است. اگر ۱ فروردین سال بعد یکشنبه، دوشنبه یا سه‌شنبه باشد، آخرین روزهای اسفند جزو هفتهٔ ۱ سال بعدند. شماره را \cs{pcalplannerweeknumber} چاپ می‌کند که آن را به‌عنوان آرگومان می‌گیرد و با \cs{scriptsize} می‌نویسد؛ برای تغییر ظاهر آن را از نو تعریف کنید.

\paragraph{تنظیم چیدمان.} مانند \pkg{yplan}، این‌ها را می‌توانید با \cs{renewcommand} از نو تعریف کنید:
\begin{itemize}
  \item \cs{pcalplannerdaystrut}: ارتفاع سطرهای روز؛ به‌طور پیش‌فرض \tx{\textbackslash rule\{0pt\}\{12pt\}}. برای پر کردن صفحه آن را بلندتر یا کوتاه‌تر کنید.
  \item \cs{pcalplannermonthstrut}: همین برای سطر نام ماه‌ها.
  \item \cs{pcalplannerleapyear}: برچسب سال کبیسه.
\end{itemize}

\macro|\pcalplannernote{M-D}{text}|  \quad\lr{\texttt{\bfseries\textbackslash pcalplannernote\{Y-M-D\}\{text\}}}
مانند تقویم دیواری به یک روز یادداشت می‌افزاید: \cs{pcalplanner} پس از شمارهٔ آن روز در خانه‌اش \cs{pcalplannermark} (یک ستاره) می‌گذارد و یادداشت‌های هر صفحه را زیر جدول آن، به ترتیب تاریخ و دسته‌بندی‌شده بر اساس ماه، فهرست می‌کند: نام هر ماه یک بار و پس از آن روزها و یادداشت‌هایشان، مانند «فروردین: ۱) \ldots{} ۱۳) \ldots\quad خرداد: ۱۴) \ldots». تاریخ بدون سال (\tx{M-D}) برای همهٔ سال‌هاست و برای تعطیلات مناسب است؛ تاریخ با سال (\tx{Y-M-D}) فقط برای همان سال. یک روز می‌تواند چند یادداشت داشته باشد؛ آن روز یک بار می‌آید و متن‌هایش با ویرگول از هم جدا می‌شوند، و یادداشت‌های همهٔ سال‌ها اول می‌آیند. یادداشت‌ها را پیش از \cs{pcalplanner}، مثلاً در پیش‌درآمد سند، بنویسید. یادداشت ۳۰ اسفند فقط در سال کبیسه دیده می‌شود.
\begin{latin}\begin{verbatim}
\pcalplannernote{1-1}{Nowruz}
\pcalplannernote{1-13}{Nature Day}
\pcalplannernote{1405-7-1}{First day of autumn 1405}
\end{verbatim}\end{latin}
این فرمان‌ها ظاهر فهرست را تعیین می‌کنند؛ برای تغییر آن، آن‌ها و \cs{pcalplannermark} را از نو تعریف کنید:
\begin{itemize}
  \item \cs{pcalplannernotesfont}: قلم فهرست، \cs{footnotesize}؛
  \item \cs{pcalplannernotemonth}\tx{\{year\}\{month\}}: عنوان هر ماه، نام آن به‌صورت پررنگ با دونقطه؛
  \item \cs{pcalplannernoteday}\tx{\{year\}\{month\}\{day\}}: برچسب هر روز، \tx{day)}؛
  \item \cs{pcalplannernotemonthsep}، \cs{pcalplannernotesep} و \cs{pcalplannernotetextsep}: فاصلهٔ میان ماه‌ها (\cs{qquad})، میان روزها (\cs{quad}) و میان متن‌های یک روز (ویرگول فارسی).
\end{itemize}
یادداشت‌ها زیر جدول جا می‌گیرند: اگر زیاد باشند، \cs{pcalplannerdaystrut} را کوتاه‌تر کنید تا هر صفحه همچنان جا شود.

\macro|\pcalplannercell{year}{month}{day}{weekday}|
یک خانهٔ روز را چاپ می‌کند. \cs{pcalplanner} آن را برای هر روز با سال، ماه و روز شمسی و روز هفته صدا می‌زند؛ روز هفته مانند \cs{pcalweekdayname} شماره‌گذاری شده است (۰ شنبه و ۶ جمعه). به‌طور پیش‌فرض فقط شمارهٔ روز را چاپ می‌کند. برای رنگ کردن، علامت زدن یا نوشتن یادداشت در روزها آن را از نو تعریف کنید؛ خانه‌های خالی آن را صدا نمی‌زنند. تعریف زیر جمعه‌ها را سایه می‌زند و ۱ فروردین را قرمز چاپ می‌کند:
\begin{latin}\begin{verbatim}
\usepackage[table]{xcolor}
\providecommand\UseMathForPositioningText{}
...
\renewcommand\pcalplannercell[4]{%
  \ifnum#4=6 \cellcolor{gray!20}\fi
  \ifnum\numexpr#2*100+#3=101 \textcolor{red}{#3}\else#3\fi}
\end{verbatim}\end{latin}
\cs{cellcolor} از بستهٔ \pkg{colortbl} است که گزینهٔ \tx{table} در \pkg{xcolor} آن را بار می‌کند. سطر \cs{providecommand} اشکالی در \pkg{bidi} را دور می‌زند (بخش~\ref{sec:limits}). در خانه‌ها از \cs{textcolor} استفاده کنید نه \cs{color}: \cs{color} در ابتدای خانه شماره را یک سطر پایین می‌برد. هر خانه ستونی از نوع پاراگراف است، پس متن بلندتر، مثل نام یک مناسبت، درون آن می‌شکند.

% ---------------------------------------------------------------------------
\section{نمونه‌های کاربردی}\label{sec:recipes}

\paragraph{چاپ چند روز پیاپی.} برای چاپ پنج روز پشت‌سرهم از اول فروردین ۱۴۰۳ می‌توانید از حلقه استفاده کنید. هر تاریخ را باید همان‌جا تبدیل و چاپ کنید، چون با تبدیل بعدی نتیجه عوض می‌شود:
\begin{latin}\begin{verbatim}
\newcount\jd
\foreach \x in {0,...,4}{%
  \pcaldatetojulian{1403-01-01+\x}\jd
  \pcaljuliantodate\jd\y\m\d
  \number\y-\number\m-\number\d\par
}
\end{verbatim}\end{latin}
\foreach \x in {0,...,4}{%
  \pcaldatetojulian{1403-01-01+\x}\jd
  \pcaljuliantodate\jd\y\m\d
  \par\noindent\hspace*{1em}\iso{\number\y-\number\m-\number\d}%
}
\par\medskip
استفاده از \tx{\textbackslash x} درون \cs{pcaldatetojulian} اشکالی ندارد، چون این فرمان ورودی‌اش را باز می‌کند.

\paragraph{شمارنده‌ها را بیرون از حلقه تعریف کنید.} \cs{newcount} را درون حلقه ننویسید: در هر دور یک شمارندهٔ تازه برمی‌دارد و سرانجام کار با خطای «\lr{No room for a new \textbackslash count}» متوقف می‌شود.

% ---------------------------------------------------------------------------
\section{سازوکار داخلی}\label{sec:how}

تبدیل‌ها فقط با حساب روی شمارنده‌های \TeX{} انجام می‌شوند؛ نه برنامهٔ بیرونی لازم است و نه \lr{Lua}. کار اصلی با دو فرمان داخلی است: هر فرمان عمومی یکی از این دو را صدا می‌زند و بعد نتیجه را چاپ یا کپی می‌کند.

\begin{description}
  \item[\tx{\textbackslash pcal@gregoriantojalali\{Y-M-D\}}] تبدیل میلادی به شمسی. ابتدا کبیسه‌بودن سال
    میلادی را تعیین و جدول طول ماه‌های هر دو تقویم را آماده می‌کند. سپس تعداد روزهای گذشته از ابتدای سال
    میلادی تا تاریخ ورودی را می‌شمارد و آن‌قدر در ماه‌های شمسی جلو می‌رود که این روزها تمام شوند. سال‌های
    کبیسهٔ شمسی با قاعدهٔ رایج \emph{دورهٔ ۳۳ ساله} مشخص می‌شوند: در هر ۳۳ سال، هشت سال کبیسه است.
  \item[\tx{\textbackslash pcal@jalalitogregorian\{Y-M-D\}}] تبدیل شمسی به میلادی. ابتدا از روی سال، تعداد
    روزهای گذشته از یک مبدأ ثابت را حساب می‌کند (۳۶۵ روز برای هر سال، به‌اضافهٔ ۸ روز کبیسه در هر ۳۳ سال و
    روزهای کبیسهٔ دورهٔ ناقص). بعد روزهای ماه‌های قبلی را به آن اضافه می‌کند و مجموع را به بلوک‌های ۴۰۰ ساله،
    ۱۰۰ ساله، ۴ ساله و ۱ ساله میلادی تقسیم می‌کند.
\end{description}

\paragraph{شمارنده‌های نتیجه.} نتایج شمسی در \cs{pcal@y}، \cs{pcal@m} و \cs{pcal@d} و نتایج میلادی در
\cs{pcal@gy}، \cs{pcal@gm} و \cs{pcal@gd} ذخیره می‌شوند. پرچم‌های کبیسه \cs{ifpcal@leap} (میلادی) و
\cs{ifpcal@kabiseh} (شمسی) هستند. طول ماه‌ها در شمارنده‌هایی نگهداری می‌شود که نامشان به عدد رومی ختم
می‌شود (\cs{pcal@latini} تا \cs{pcal@latinxii} و \cs{pcal@persiani} تا \cs{pcal@persianxiii}). دی دو بار
می‌آید: خانهٔ اول بخشی از دی است که در سال میلادی باقی مانده و خانهٔ آخر کل ماه را نشان می‌دهد؛ برای همین
سیزده خانه لازم است.

\paragraph{پل شمارهٔ روز ژولین.} \cs{pcaldatetojulian} ابتدا تاریخ شمسی را با فرمان شمسی-به-میلادیِ
بالا به تاریخ میلادی برمی‌گرداند و آن را به \cs{pgfcalendardatetojulian} می‌دهد. \cs{pcaljuliantodate}
عکس این مسیر را می‌رود: \cs{pgfcalendarjuliantodate} تاریخ میلادی می‌سازد و فرمان میلادی-به-شمسی آن را
به تاریخ شمسی تبدیل می‌کند.

\paragraph{نام سال.} حیوان‌های سال هر ۱۲ سال تکرار می‌شوند. علاوه بر این، در هر سده یک جابه‌جایی سه‌حالتی
اعمال می‌شود تا سال ۰ دوره با حیوانی غیر از حیوان سال ۱۰۰ شروع شود. به همین دلیل این فرمان فقط تا ۲۰۹۹ کار
می‌کند.

\paragraph{بدون نشتی شمارنده.} همهٔ شمارنده‌ها هنگام بارگذاری بسته فقط یک بار تعریف می‌شوند؛ پس در یک سند
می‌توانید هر تعداد تبدیل انجام دهید. آزمونی در مخزن (\tx{leaks.lvt}) همین را بررسی می‌کند.

\paragraph{تقویم‌های \lr{TikZ}.} کلیدهای بخش~\ref{sec:tikz} هنگام بارگذاری بسته با \cs{pgfkeys} تعریف می‌شوند، پس تا وقتی به کار نروند به \pkg{TikZ} نیازی ندارند. \tx{jalali dates} هر دو سر بازه را به میلادی تبدیل می‌کند و به کلید \tx{dates} کتابخانه می‌دهد؛ \tx{last} به روز اول ماه شمسی بعد با جابه‌جایی \tx{+-1} تبدیل می‌شود. \tx{jalali} پیش از هر روز، و پیش از کدهای خود کتابخانه، فرمانی اجرا می‌کند که \cs{pcalcurrentyear} و بقیه را تنظیم می‌کند، و شرط \tx{day of month} را فقط برای همان تقویم از نو تعریف می‌کند. تبدیل‌ها درون یک گروه اجرا می‌شوند، چون \pkg{pgfcalendar} روزها را با \cs{loop} می‌پیماید و تبدیل‌ها هم از \cs{loop} استفاده می‌کنند.

\paragraph{پلنر سالانه.} \cs{pcalplanner} برای هر صفحه فقط روز اول هر یک از شش ماه آن (و ماه بعد) را با همان سازوکار \cs{pcaldatetojulian} به شمارهٔ روز تبدیل می‌کند؛ تفاضل آن‌ها طول ماه‌هاست و روز هفتهٔ روز اول هر ماه سطر شروع آن را می‌دهد. سپس سطرها در یک ثبات توکن نوشته می‌شوند، یک خانه برای هر ماه که در خانه‌های دارای روز \cs{pcalplannercell} را صدا می‌زند، همراه با \cs{cline}های زیر آن‌ها، و این ثبات درون \tx{tabular} قرار می‌گیرد. سطرها به همان دلیل بالا با بازگشت ساخته می‌شوند، نه با \cs{loop}.

% ---------------------------------------------------------------------------
\section{محدودیت‌ها و مشکلات شناخته‌شده}\label{sec:limits}

\begin{itemize}\sloppy % long code names cannot be hyphenated
  \item \textbf{ورودی بررسی نمی‌شود.} اگر ماه ۱۳، روز ۴۰ یا رشتهٔ نادرستی بدهید، یا خروجی غلط می‌شود یا \TeX{} خطا می‌دهد (نه خود بسته).
  \item \textbf{ورودی باید خودِ تاریخ باشد.} \cs{pdate}، \cs{gdate}، \cs{pisodate} و \cs{gisodate} ورودی را همان‌طور که نوشته شده در خط‌های تیره می‌شکنند و فرمانی را که تاریخ در آن ذخیره شده باز نمی‌کنند. پس این‌طور بنویسید: \cs{pdate}\tx{\{2015-03-21\}}، نه \cs{pdate}\cs{mydate}. (\cs{pcaldatetojulian} ورودی‌اش را
    باز می‌کند و این مشکل را ندارد.)
  \item \textbf{قاعدهٔ کبیسهٔ تقریبی.} قاعدهٔ ۳۳ ساله فقط تقریبی حسابی از تقویم رسمی است، چون تقویم رسمی بر پایهٔ رصد نجومی تعیین می‌شود. این دو در سال‌های رایج یکی‌اند، اما در همهٔ سال‌ها یکی نیستند. برای سال‌های دور، نتیجه را با یک جدول معتبر مقایسه کنید.
  \item \textbf{یک اشکال شناخته‌شده.} \cs{pcal@jalalitogregorian}\tx{\{1279-10-11\}} با پیام
    «\lr{Missing number, treated as zero}» متوقف می‌شود، در حالی که تاریخ‌های اطرافش درست‌اند. دلیلش را هنوز
    پیدا نکرده‌ام.
  \item \textbf{حلقه‌های تودرتو.} تبدیل‌ها در داخل خود از \cs{loop} هستهٔ \lr{\LaTeX} استفاده می‌کنند. اگر \cs{loop}\ldots\cs{repeat} شما این فرمان‌ها را صدا می‌زند، بدنهٔ آن را درون یک گروه (\cs{begingroup}\ldots\cs{endgroup}) بگذارید؛ وگرنه حلقه بعد از یک دور متوقف می‌شود. \cs{foreach} این
    مشکل را ندارد.
  \item \textbf{شمارنده‌های مشترک.} هر تبدیل شمارنده‌های نتیجه را از نو می‌نویسد، همان‌طور که در
    بخش~\ref{sec:julian} گفته شد.
  \item \textbf{نام سال} فقط برای ۰ تا ۲۰۹۹ کار می‌کند.
  \item \textbf{چیدمان‌های \lr{TikZ}.} فقط \tx{jalali week list}، \tx{jalali week columns} و سبک‌های \tx{day list} از ماه‌های شمسی پیروی می‌کنند؛ \tx{week list} و \tx{month list} کتابخانه میلادی می‌مانند.
  \item \textbf{\tx{jalali dates} و \tx{dates}} هر دو یک بازه را تنظیم می‌کنند، پس هر کدام که بعدتر بیاید اعمال می‌شود. تاریخ‌های \tx{jalali dates} هم مثل ورودی \cs{pdate} باید خودِ تاریخ باشند.
  \item \textbf{خانه‌ها و عنوان روزهای راست‌چین را فرض می‌کنند.} \tx{jalali day boxes} و \tx{jalali month label above centered} لنگر پیش‌فرض \tx{every day} کتابخانه (\tx{base east}) را فرض می‌کنند. حرف‌های روزهای هفته همه یک سبک دارند، پس نمی‌شود فقط حرف جمعه را رنگی کرد.
  \item \textbf{وابستگی به جزئیات داخلی \lr{TikZ}.} \tx{jalali} کد خود را به ماکروی داخلی \cs{tikz@before@day} کتابخانه اضافه می‌کند. اگر نسخهٔ آیندهٔ \pkg{TikZ} نام آن را عوض کند، تقویم‌های شمسی از کار می‌افتند؛ آزمون \tx{tikz.lvt} این را نشان می‌دهد.
  \item \textbf{سایه زدن خانه‌های پلنر با \pkg{xepersian}.} بار کردن \pkg{colortbl} (مثلاً با \tx{\textbackslash usepackage[table]\{xcolor\}}) همراه با \pkg{xepersian} در اولین جدول با خطای «\lr{\texttt{Undefined control sequence}}» برای \cs{UseMathForPositioningText} متوقف می‌شود. نسخهٔ \pkg{bidi} از \pkg{array} این ماکرو را به کار می‌برد که نسخه‌های فعلی \pkg{array} دیگر تعریفش نمی‌کنند. تا وقتی \pkg{bidi} اصلاح شود، این ماکرو را با \cs{providecommand} در پیش‌درآمد سند خالی تعریف کنید (سطر دوم مثال بخش~\ref{sec:yplan}).
  \item \textbf{پلنر اندازهٔ صفحه را تغییر نمی‌دهد.} \cs{pcalplanner} اندازهٔ صفحه و حاشیه‌ها را عوض نمی‌کند؛ آن‌ها را با \pkg{geometry} و ارتفاع سطرها را با \cs{pcalplannerdaystrut} تنظیم کنید.
  \item \textbf{\cs{wd} را از نو تعریف نکنید.} \cs{newcount}\cs{wd} یا مانند آن یک فرمان پایهٔ \TeX{} را که \pkg{TikZ} لازم دارد از بین می‌برد و متن ناخواسته‌ای مثل «\tx{==0pt}» در تصویرها ظاهر می‌شود.
\end{itemize}

% ---------------------------------------------------------------------------
\section{تاریخچهٔ نسخه‌ها}\label{sec:history}

\begin{description}\sloppy % long code names cannot be hyphenated
  \item[\lr{0.78 (2026-11-06)}] \cs{pcalplannernote}: یادداشت در پلنر سالانه، با ستاره در خانه‌ها و فهرستی ماه‌به‌ماه زیر هر صفحه، مانند تقویم دیواری.
  \item[\lr{0.77 (2026-11-06)}] شمارهٔ هفته در \cs{pcalplanner}، با قاعدهٔ \lr{ISO 8601} برای هفتهٔ شنبه تا جمعه؛ \cs{pcalplanner*} آن را چاپ نمی‌کند.
  \item[\lr{0.76 (2026-11-06)}] راهنماها: بخش «نصب» اکنون «بارگذاری بسته» است.
  \item[\lr{0.75 (2026-11-06)}] \cs{pcaldaysbetween}: تعداد روزهای میان دو تاریخ شمسی.
  \item[\lr{0.74 (2026-11-06)}] \cs{pcalweekday} و \cs{pcaldateweekdayname}: روز هفتهٔ یک تاریخ شمسی.
  \item[\lr{0.73 (2026-11-06)}] گزینهٔ \tx{tikz} که \pkg{TikZ} و کتابخانهٔ \tx{calendar} آن را بارگذاری می‌کند.
  \item[\lr{0.72 (2026-11-05)}] \cs{pcalyear} و \cs{pcalyears}: تقویم سال‌ها به شیوهٔ \pkg{calxxxx-yyyy}، با سبک‌هایی برای سال، عنوان آن، ماه‌ها و جمعه‌ها.
  \item[\lr{0.71 (2026-11-05)}] نام‌های کوتاه‌تر: \cs{pcal\ldots} به جای \cs{pcalendar\ldots}؛ نام‌های قدیمی هنوز کار می‌کنند.
  \item[\lr{0.7 (2026-11-05)}] پلنر سالانه به شیوهٔ \pkg{yplan}: فرمان \cs{pcalplanner} و فرمان \cs{pcalplannercell} برای رنگ کردن یا یادداشت‌گذاری روزها. نمونهٔ \tx{persian-calendar-planner.tex}.
  \item[\lr{0.62 (2026-11-04)}] \tx{jalali week columns} و نمونهٔ \tx{persian-calendar-years.tex}.
  \item[\lr{0.61 (2026-11-03)}] \tx{jalali day boxes} (جدول خانه‌دار) و \tx{jalali weekday initials} (حرف اول روزهای هفته).
  \item[\lr{0.6 (2026-11-03)}] تغییر نام از \pkg{pcalendar} به \pkg{persian-calendar} به درخواست \lr{CTAN} (فقط نام فایل‌ها و بسته؛ نام فرمان‌ها تغییری نکرده است). رسم جدول ماه‌های شمسی با کتابخانهٔ \tx{calendar} در \pkg{TikZ} (بخش~\ref{sec:tikz}). ذکر مجوز به‌صورت \lr{LPPL 1.3c} در همه‌جا.
  \item[\lr{0.51 (2026-11-01)}] فقط مستندات: راهنماها حالا توضیح می‌دهند که تنها چاپ نام‌های فارسی به موتور یونیکد
    و قلم فارسی نیاز دارد؛ راهنمای فارسی هم بازنویسی شد.
  \item[\lr{0.5 (2026-11-01)}] رفع نشتی شمارنده (چند \cs{newcount} در هر فراخوانی) و شمارندهٔ تعریف‌نشدهٔ طول
    ماه؛ افزودن این راهنما و \cs{pcalendardate}/\cs{pcalendarversion}.
  \item[\lr{0.4 (2023-11-07)}] آمادهٔ انتشار در \lr{CTAN}.
  \item[\lr{0.3 (2015-08-14)}] نام حیوان سال شمسی، از ۰ تا ۲۰۹۹.
  \item[\lr{0.2 (2015-08-09)}] تبدیل شمسی به میلادی.
  \item[\lr{0.1 (2015-07-25)}] نخستین نسخه.
\end{description}

\end{document}