% ==========================================================
% transition-metals-example.tex
% أمثلة احترافية لاستخدام حزمة transition-metals
% ==========================================================

\documentclass[12pt,a4paper]{article}
\usepackage[top=1.5cm,bottom=1.5cm,left=1.5cm,right=1.5cm]{geometry}
%\usepackage{transition-metals-fainl}
\usepackage{transition-metals}
% ==========================================================
% إعدادات اللغة العربية
% ==========================================================

\usepackage{polyglossia}

\setmainlanguage[numerals=maghrib]{arabic}
\setotherlanguage{english}

% تعريف الخطوط
 \newfontfamily\arabicfont[Script=Arabic]{Calibri}
\newfontfamily\arabicfontsf[Script=Arabic]{Amiri}
\newfontfamily\arabicfonttt[Script=Arabic]{Courier New}

\newfontfamily\englishfont{Times New Roman}

% ==========================================================
% الحزم الأساسية
% ==========================================================

\usepackage{geometry}
\geometry{top=2cm,bottom=2cm,left=2.5cm,right=2.5cm}
\usepackage{enumitem}
\usepackage{amsmath}
\usepackage{booktabs}
\usepackage{array}
\usepackage{caption}
\usepackage{graphicx}
\usepackage{xcolor}

% ==========================================================
% تنسيق الرأس
% ==========================================================
\usepackage{fancyhdr}
\setlength{\headheight}{15pt}
\pagestyle{fancy}
\fancyhead[L]{\textbf{\textarabic{حزمة \textenglish{transition-metals}}}}
\fancyhead[R]{ 18 مايو 2026 }
\fancyfoot[C]{\thepage}
\renewcommand{\headrulewidth}{0.4pt}

% ==========================================================
% تنسيق عام
% ==========================================================
\setlength{\parindent}{0pt}
\setlength{\parskip}{1em}

% ==========================================================
% أوامر لعرض الكود بشكل آمن (لا يتم تنفيذه)
% ==========================================================
\newcommand{\code}[1]{{%
    \begin{english}%
    \ttfamily
    \detokenize{#1}%  يحول الكود إلى نص عادي
    \end{english}%
}}

\newenvironment{codeblock}{%
    \begin{quote}
    \begin{english}
    \ttfamily
    \small
    \detokenize\expandafter{\bgroup\aftergroup\egroup}%  يجعل المحتوى نصاً عادياً
}{%
    \end{english}
    \end{quote}
}
% ==========================================================
% عنوان الوثيقة
% ==========================================================
\title{%
    \vspace{2cm}
    \Huge\textbf{\textarabic{دليل استخدام حزمة \textsf{transition-metals}}}\\
    \vspace{0.5cm}
    \Large\textbf{\textarabic{رسم الترتيبات الإلكترونية للعناصر الانتقالية ومعقداتها}}\\
    \vspace{1cm}
}
\author{%
    \textbf{\textarabic{دليل تعريفي للمستخدم}}
}
\date{18 مايو 2026}

% ==========================================================
% بداية الوثيقة
% ==========================================================
\begin{document}

\maketitle
\thispagestyle{empty}
\newpage

\tableofcontents
\newpage

% ==========================================================
% القسم 1: مقدمة
% ==========================================================
\section{\textarabic{مقدمة}}

\textarabic{تعد حزمة \texttt{transition-metals} أداة متخصصة لرسم الترتيبات الإلكترونية للعناصر الانتقالية ومعقداتها. 
توفر الحزمة واجهة سهلة الاستخدام لإنشاء رسوم توضيحية احترافية للتوزيع الإلكتروني، 
والتهجين، والمعقدات التناسقية مع تمييز تلقائي بين الليكاندات القوية والضعيفة.}

\subsection{\textarabic{المتطلبات}}
\begin{itemize}
    \item \LaTeXe \textarabic{مع تحديثات 2020 أو أحدث}
    \item \textarabic{الحزم التالية مثبتة:} \texttt{tikz}, \texttt{mhchem}, \texttt{xcolor}, \texttt{ifthen}
    \item \textarabic{لدعم اللغة العربية:} \texttt{polyglossia} \textarabic{مع الإعدادات المناسبة}
\end{itemize}

\subsection{\textarabic{التثبيت}}

\noindent\textbf{\textarabic{الطريقة الأولى: التثبيت المحلي}}
\begin{english}
\begin{verbatim}
mkdir -p ~/texmf/tex/latex/transition-metals
cp transition-metals.sty ~/texmf/tex/latex/transition-metals/
texhash ~/texmf
\end{verbatim}
\end{english}

\noindent\textbf{\textarabic{الطريقة الثانية: وضع الملف في مجلد المشروع}}
\begin{verbatim}
ضع ملف transition-metals.sty في نفس مجلد ملف .tex الخاص بك
\end{verbatim}

% ==========================================================
% القسم 2: الأوامر الأساسية
% ==========================================================
\section{\textarabic{الأوامر الأساسية}}

\subsection{\texttt{\textbackslash Series} \textarabic{رسم السلاسل الفارغة}}

\textarabic{الأمر يرسم الأوربيتالات الفارغة لسلسلة انتقالية محددة.}

\subsubsection*{\textarabic{الاستخدام}}
\begin{verbatim}
\Series{1}   % سلسلة الانتقال الأولى (3d, 4s, 4p)
\Series{2}   % سلسلة الانتقال الثانية (4d, 5s, 5p)
\Series{3}   % سلسلة الانتقال الثالثة (5d, 6s, 6p + 4f)
\end{verbatim}

\subsubsection*{\textarabic{التطبيق}}

\begin{center}
\Series{1}
\captionof{figure}{\textarabic{سلسلة الانتقال الأولى: 3d و 4s و 4p}}
\end{center}

\begin{center}
\Series{2}
\captionof{figure}{\textarabic{سلسلة الانتقال الثانية: 4d و 5s و 5p}}
\end{center}

\begin{center}
\Series{3}
\captionof{figure}{\textarabic{سلسلة الانتقال الثالثة: 5d و 6s و 6p مع 4f\textsuperscript{14}}}
\end{center}

% ==========================================================
% القسم 3: الذرات والأيونات
% ==========================================================
\section{\textarabic{الذرات والأيونات}}

\subsection{\texttt{\textbackslash neutralAtom} \textarabic{الذرة المتعادلة}}

\textarabic{الأمر يرسم الذرة المتعادلة مع توزيعها الإلكتروني.}

\subsubsection*{\textarabic{الاستخدام}}
\begin{verbatim}
\neutralAtom{26}{Fe}
\end{verbatim}

\subsubsection*{\textarabic{التنطبيق}}

\noindent\textbf{\textarabic{الحديد Fe (العدد الذري 26)}}:
\begin{center}
\neutralAtom{26}{Fe}
\captionof{figure}{\textarabic{الحديد المتعادل: \textenglish{[Ar] 3d⁶ 4s²}}}
\end{center}

\noindent\textbf{\textarabic{النحاس Cu (العدد الذري 29)}}:
\begin{center}
\neutralAtom{29}{Cu}
\captionof{figure}{\textarabic{النحاس المتعادل: \textenglish{[Ar] 3d¹⁰ 4s¹}}}
\end{center}

\noindent\textbf{\textarabic{الكروم Cr (العدد الذري 24)}}:
\begin{center}
\neutralAtom{24}{Cr}
\captionof{figure}{\textarabic{الكروم المتعادل: \textenglish{[Ar] 3d⁵ 4s¹} (حالة استثنائية)}}
\end{center}

\noindent\textbf{\textarabic{الفضة Ag (العدد الذري 47)}}:
\begin{center}
\neutralAtom{47}{Ag}
\captionof{figure}{\textarabic{الفضة المتعادل: \textenglish{[Kr] \, 4d\textsuperscript{10} \, 5s\textsuperscript{1}} (حالة استثنائية)}}
\end{center}

\noindent\textbf{\textarabic{البلاتين Pt (العدد الذري 78)}}:
\begin{center}
\neutralAtom{78}{Pt}
\captionof{figure}{\textarabic{البلاتين المتعادل:  \textenglish{[Xe] \, 4f\textsuperscript{14}\, 5d\textsuperscript{9}\, 6s\textsuperscript{1}} (حالة استثنائية)}}
\end{center}

\noindent\textbf{\textarabic{الذهب Au (العدد الذري 79)}}:
\begin{center}
\neutralAtom{79}{Au}
\captionof{figure}{\textarabic{الذهب المتعادل: \textenglish{[Xe] \, 4f\textsuperscript{14}\, 5d\textsuperscript{10} \, 6s\textsuperscript{1}} (حالة استثنائية)}}
\end{center}

% ------------------------ new page --------------------------- %
\newpage


\subsection{\texttt{\textbackslash ionAtom} \textarabic{الأيون}}

\textarabic{الأمر يرسم الأيون مع التوزيع الإلكتروني بعد فقد أو اكتساب الإلكترونات.}

\subsubsection*{\textarabic{الاستخدام}}
\begin{verbatim}
\ionAtom{26}{Fe}{2+}
\end{verbatim}

\subsubsection*{\textarabic{أمثلة}}

\noindent\textbf{\textarabic{أيون الحديد الثنائي Fe²⁺}}:
\begin{center}
\ionAtom{26}{Fe}{2+}
\captionof{figure}{\textarabic{\textenglish{[Ar] 3d⁶ 4s⁰}}}
\end{center}

\noindent\textbf{\textarabic{أيون الكوبالت الثنائي Co²⁺}}:
\begin{center}
\ionAtom{27}{Co}{2+}
\captionof{figure}{\textarabic{\textenglish{[Ar] 3d⁷ 4s⁰}}}
\end{center}

\noindent\textbf{\textarabic{أيون النحاس الثنائي Cu²⁺}}:
\begin{center}
\ionAtom{29}{Cu}{1+}
\captionof{figure}{\textarabic{\textenglish{[Ar] 3d\textsuperscript{10} 4s\textsuperscript{0}}}}

\ionAtom{29}{Cu}{2+}
\captionof{figure}{\textarabic{\textenglish{[Ar] 3d⁹ 4s⁰}}}
\end{center}

% ---------------------- page ---------------------- %
\newpage

\begin{center}
\ionAtom{47}{Ag}{1+}
\captionof{figure}{\textarabic{\textenglish{[Kr] 4d\textsuperscript{10} 5s\textsuperscript{0}}}}
\end{center}

\begin{center}
\ionAtom{78}{Pt}{2+}
\captionof{figure}{\textarabic{\textenglish{[Xe] 5d\textsuperscript{8} 6s⁰}}}
\end{center}

\begin{center}
\ionAtom{28}{Ni}{2+}
\captionof{figure}{\textarabic{\textenglish{[Ar] 3d\textsuperscript{8} 4s⁰}}}
\end{center}

\begin{center}
\ionAtom{24}{Cr}{3+}
\captionof{figure}{\textarabic{\textenglish{[Ar] 3d\textsuperscript{3} 4s⁰}}}
\end{center}

% ---------------------- page ---------------------- %
\newpage

% ==========================================================
% القسم 4: المعقدات التناسقية
% ==========================================================
\section{\textarabic{المعقدات التناسقية}}

\subsection{\texttt{\textbackslash ComplexWeak} \textarabic{معقد ليكاند ضعيف (\textenglish{High Spin})}}

\textarabic{عندما يكون الليكاند ضعيفاً (مثل Cl⁻, H₂O, F⁻)، يكون الانقسام صغيراً وتكون إلكترونات d عالية السبين.}

\noindent\textbf{\textarabic{مثال: [Fe(H₂O)₆]²⁺}}:
\begin{verbatim}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\ComplexWeak{26}{Fe}{2+}{(H2O)}{6}
\end{verbatim}

\begin{center}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\ComplexWeak{26}{Fe}{2+}{(H2O)}{6}
\captionof{figure}{\textarabic{توزيع \textenglish{high spin} وتهجين \textenglish{sp³d²}}}
\end{center}

\subsection{\texttt{\textbackslash ComplexStrong} \textarabic{معقد ليكاند قوي (\textenglish{Low Spin})}}

\textarabic{عندما يكون الليكاند قوياً 
مثل (\textenglish{CN⁻, CO, NH₃, en})، يكون الانقسام كبيراً وتكون إلكترونات d منخفضة الغزل.}

\noindent\textbf{\textarabic{مثال: [Fe(CN)₆]⁴⁻}}:
\begin{verbatim}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\ComplexStrong{26}{Fe}{2+}{(CN)}{6}
\end{verbatim}
\begin{center}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\ComplexStrong{26}{Fe}{2+}{(CN)}{6}
\captionof{figure}{\textarabic{توزيع \textenglish{low spin} وتهجين \textenglish{d²sp³}}}
\end{center}

\subsection{\texttt{\textbackslash Complex} \textarabic{الأمر التلقائي}}

\textarabic{الأمر يختار تلقائياً بين} \texttt{\textenglish{ComplexWeak}} \textarabic{و} \texttt{\textenglish{ComplexStrong}} \textarabic{بناءً على نوع الليكاند.}

\begin{center}
\begin{tabular}{l l}
\toprule
\textbf{\textarabic{الليكاند}} & \textbf{\textarabic{الصيغ المقبولة}} \\
\midrule
\textarabic{أمونيا} &  (\ce{NH3}), [\ce{NH3}] \\
\textarabic{سيانيد} &  (\ce{CN}), [\ce{CN}] \\
\textarabic{أول أكسيد الكربون} &  (\ce{CO}), [\ce{CO}] \\
\textarabic{إيثيلين ثنائي الأمين} &  (\ce{en}), [\ce{en}] \\
\bottomrule
\end{tabular}
\end{center}

\noindent\textbf{\textarabic{مثال: \ce{NH3} (ليكاند قوي)}}:
\begin{verbatim}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{27}{Co}{3+}{(NH3)}{6}
\end{verbatim}
\begin{center}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{27}{Co}{3+}{(NH3)}{6}
\captionof{figure}{\textarabic{يختار \textenglish{low spin} تلقائياً}}
\end{center}

\noindent\textbf{\textarabic{مثال: \ce{H2O} (ليكاند ضعيف)}}:
\begin{verbatim}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{27}{Co}{3+}{(H2O)}{6}
\end{verbatim}
\begin{center}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{27}{Co}{3+}{(H2O)}{6}
\captionof{figure}{\textarabic{يختار \textenglish{high spin} تلقائياً}}
\end{center}

% ==================== page ==================
\newpage

\subsection{\textarabic{معقدات السلسلة الثانية والثالثة}}

\noindent\textbf{\textarabic{مثال: \ce{H2O} (ليكاند ضعيف)}}:
\begin{verbatim}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{47}{Ag}{1+}{(H2O)}{2}
\end{verbatim}

\begin{center}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{47}{Ag}{1+}{(H2O)}{2}
\captionof{figure}{\textarabic{يختار \textenglish{high spin} تلقائياً}}
\end{center}

\noindent\textbf{\textarabic{مثال: \ce{NH3} (ليكاند قوي)}}:
\begin{verbatim}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{47}{Ag}{1+}{(NH3)}{2}
\end{verbatim}

\begin{center}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{47}{Ag}{1+}{(NH3)}{2}
\captionof{figure}{\textarabic{يختار \textenglish{high spin} تلقائياً}}
\end{center}

%\vspace{1cm}
% ==================== page ==================
\newpage

\noindent\textbf{\textarabic{مثال: \ce{H2O} (ليكاند ضعيف)}}:
\begin{verbatim}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{78}{Pt}{2+}{(H2O)}{4}
\end{verbatim}

\begin{center}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{78}{Pt}{2+}{(H2O)}{4}
\captionof{figure}{\textarabic{يختار \textenglish{high spin} تلقائياً}}
\end{center}

\noindent\textbf{\textarabic{مثال: \ce{NH3} (ليكاند قوي)}}:
\begin{verbatim}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{78}{Pt}{2+}{(NH3)}{4}
\end{verbatim}

\begin{center}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{78}{Pt}{2+}{(NH3)}{4}
\captionof{figure}{\textarabic{يختار \textenglish{high spin} تلقائياً}}
\end{center}

% ==================== page =================== %
\newpage

\noindent\textbf{\textarabic{مثال: \ce{I} (ليكاند قوي)}}:
\begin{verbatim}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{80}{Hg}{2+}{I}{3}
\end{verbatim}

\begin{center}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{80}{Hg}{2+}{I}{3}
\captionof{figure}{\textarabic{يختار \textenglish{high spin} تلقائياً}}
\end{center}

\noindent\textbf{\textarabic{مثال: \ce{I} (ليكاند ضعيف)}}:
\begin{verbatim}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{28}{Ni}{2+}{Cl}{4}
\end{verbatim}

\begin{center}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{28}{Ni}{2+}{Cl}{4}
\captionof{figure}{\textarabic{يختار \textenglish{high spin} تلقائياً}}
\end{center}

\noindent\textbf{\textarabic{مثال: \ce{I} (ليكاند قوي)}}:
\begin{verbatim}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{28}{Ni}{2+}{(CN)}{4}
\end{verbatim}

\begin{center}
\SetComplexInfo{1}% امر اظهار صندوق المعلومات 
\Complex{28}{Ni}{2+}{(CN)}{4}
\captionof{figure}{\textarabic{يختار \textenglish{high spin} تلقائياً}}
\end{center}




% ==========================================================
% القسم 5: الجداول المرجعية
% ==========================================================
\section{\textarabic{الجداول المرجعية}}

\begin{table}[h!]
\centering
\caption{\textarabic{الأعداد التناسقية وأنواع التهجين}}
\begin{tabular}{c c c c}
\toprule
\textbf{\textarabic{العدد}} & \textbf{\textarabic{الشكل}} & \textbf{\textarabic{تهجين (ضعيف)}} & \textbf{\textarabic{تهجين (قوي)}} \\
\midrule
2 & \textarabic{خطي} & \textenglish{sp} & \textenglish{sp} \\
3 & \textarabic{مثلث مستو} & \textenglish{sp²} & \textenglish{sp²} \\
4 & \textarabic{رباعي السطوح} & \textenglish{sp³} & \textenglish{dsp²} \\
5 & \textarabic{هرمي ثنائي} & \textenglish{sp³d }& \textenglish{sp³d} \\
6 & \textarabic{ثماني السطوح} & \textenglish{sp³d² }& \textenglish{d²sp³} \\
\bottomrule
\end{tabular}
\end{table}

% ==========================================================
% القسم 6: استكشاف الأخطاء
% ==========================================================
\section{\textarabic{استكشاف الأخطاء وإصلاحها}}

\subsection*{\textarabic{لا تظهر الأسهم }}
\textbf{\textarabic{الحل:}} \textarabic{تأكد من تحميل حزمة} \texttt{fontspec} \textarabic{وخط يدعم الرموز}.

\subsection*{\textarabic{الأرقام تظهر هندية (٠١٢٣)}}
\textbf{\textarabic{الحل:}} \textarabic{استخدم الخيار} \texttt{\textenglish{[numerals=maghrib]}} \textarabic{في} \texttt{\textenglish{\textbackslash setmainlanguage}}.

\subsection*{\textarabic{أخطاء في التجميع}}
\textbf{\textarabic{الحل:}} \textarabic{تأكد من تثبيت الحزم:} \texttt{tikz}, \texttt{mhchem}, \texttt{xcolor}, \texttt{polyglossia}, \texttt{fontspec}

% ==========================================================
% الخاتمة
% ==========================================================

\begin{center}
\Large\textbf{\textarabic{شكراً لاستخدامك حزمة \textsf{transition-metals}}}\\
\vspace{0.5cm}
 18 مايو 2026 
\end{center}

\end{document}