From a7f36e4ae3b52f21ae3a176edd7283924c16040c Mon Sep 17 00:00:00 2001
From: Robert Alessi <alessi@robertalessi.net>
Date: Thu, 16 Jun 2022 11:09:04 +0200
Subject: documentation: added an environment for remarks

---
 arabluatex.dtx | 175 +++++++++++++++++++++++++++++----------------------------
 1 file changed, 88 insertions(+), 87 deletions(-)

(limited to 'arabluatex.dtx')

diff --git a/arabluatex.dtx b/arabluatex.dtx
index 9de351f..9c2edbb 100644
--- a/arabluatex.dtx
+++ b/arabluatex.dtx
@@ -601,14 +601,14 @@
 % issue a warning message and attempt to load the Amiri
 % font\footnote{\textcite{pkg:amiri}.} like so:---\\
 % \tcboxverb{\newfontfamily\arabicfont{Amiri}[Script=Arabic]}
-% \begin{quoting}
-%   \textsc{Rem.~1} By default Amiri places the \arb[trans]{kasraT} in
-%   combination with the \arb[trans]{ta^sdId} below the consonant,
-%   like so: \arb{BBi}\,. That is correct, as at least in the oldest
+% \begin{remarks}
+% \item By default Amiri places the \arb[trans]{kasraT} in combination
+%   with the \arb[trans]{ta^sdId} below the consonant, like so:
+%   \arb{BBi}\,. That is correct, as at least in the oldest
 %   manuscripts {\renewfontfamily\arabicfont{Amiri}[Script=Arabic,
-%   RawFeature={+ss05}]\arb{BBi}} may stand for \arb{BBa} as
-%   well as \arb{BBi}\,. See \textcite[i. 14 C--D]{Wright}. The placement
-%   of the \arb[trans]{kasraT} above the consonant may be obtained by
+%   RawFeature={+ss05}]\arb{BBi}} may stand for \arb{BBa} as well as
+%   \arb{BBi}\,. See \textcite[i. 14 C--D]{Wright}. The placement of
+%   the \arb[trans]{kasraT} above the consonant may be obtained by
 %   selecting the |ss05| feature of the Amiri font, like
 %   so:---\footnote{See the documentation of \package{amiri},
 %   \textcite[6]{pkg:amiri}.}\\
@@ -616,10 +616,10 @@
 %
 %   Other Arabic fonts may behave differently.
 %
-%   \noindent\textsc{Rem.~2} \cs{newfontfamily} can be used to have
+%   \item \cs{newfontfamily} can be used to have
 %   either Indian of Arabic numbers printed. See
 %   \vpageref{ref:arabic-numbers} for more information.
-% \end{quoting}
+% \end{remarks}
 %
 % \subsection{Options}
 % \label{sec:options}
@@ -1018,11 +1018,11 @@
 % \arb[novoc]{^n}\footnote{See \vref{fn:not-in-dmg}.} & \dmg{^n} &
 % \loc{^n} & \brill{^n} & \verb|^n| \\
 % \end{longtable}
-% \begin{quoting}
-%   \textsc{Rem.} The alveolar consonants \arb[novoc]{^c} and
+% \begin{remarks}
+% \item[\textsc{Rem.}] The alveolar consonants \arb[novoc]{^c} and
 %   \arb[novoc]{^z} are processed as solar letters by
 %   \package{arabluatex}.
-% \end{quoting}
+% \end{remarks}
 % 
 % \subsection{Vowels}
 % \subsubsection{Long vowels}
@@ -1057,10 +1057,10 @@
 % \arb[novoc]{B_i} & \dmg{B_i} & \loc{B_i} & \brill{B_i} & \verb|_i| \\
 % \end{longtable}
 %
-% \begin{quoting}
-%   \textsc{Rem.}~\emph{a.} The long vowels \arb[trans]{A, U, I},
-%   otherwise called \arb[trans]{.hurUf-u 'l-madd-i}, \emph{the
-%   letters of prolongation}, involve the placing of the short vowels
+% \begin{remarks}
+% \item The long vowels \arb[trans]{A, U, I}, otherwise called
+%   \arb[trans]{.hurUf-u 'l-madd-i}, \emph{the letters of
+%   prolongation}, involve the placing of the short vowels
 %   \arb[trans]{Ba, Bu, Bi} before the letters \arb[novoc]{A},
 %   \arb[novoc]{U}, \arb[novoc]{I} respectively. \package{arabluatex}
 %   does that automatically in case any from |voc|, |fullvoc| or
@@ -1068,23 +1068,23 @@
 %   \arb[voc]{qIla} \arb[trans]{qIla}, \arb[voc]{yaqUlu}
 %   \arb[trans]{yaqUlu}.
 %
-%   \textsc{Rem.}~\emph{b.} Defective writings, such as
-%   \arb[novoc]{B_a}, \arb[trans]{al-'alif-u 'l-ma.h_dUfaT-u}, or
-%   defective writings of \arb[trans]{B_u} and \arb[trans]{B_i} are
-%   encoded |_a| |_u| and |_i| respectively, e.g. |_d_alika|
-%   \arb[voc]{_d_alika}, |al-mal_a'ikaT-u| |'l-ra.hm_an-u|
-%   \arb[voc]{al-mal_a'ikaT-u 'l-ra.hm_an-u}, |.hu_dayfaT-u| |bn-u|
-%   |'l-yamAn_i| \arb[fullvoc]{.hu_dayfaT-u bn-u 'l-yamAn_i} for
+% \item Defective writings, such as \arb[novoc]{B_a},
+%   \arb[trans]{al-'alif-u 'l-ma.h_dUfaT-u}, or defective writings of
+%   \arb[trans]{B_u} and \arb[trans]{B_i} are encoded |_a| |_u| and
+%   |_i| respectively, e.g. |_d_alika| \arb[voc]{_d_alika},
+%   |al-mal_a'ikaT-u| |'l-ra.hm_an-u| \arb[voc]{al-mal_a'ikaT-u
+%   'l-ra.hm_an-u}, |.hu_dayfaT-u| |bn-u| |'l-yamAn_i|
+%   \arb[fullvoc]{.hu_dayfaT-u bn-u 'l-yamAn_i} for
 %   \arb[trans]{\uc{.hu_dayfaT-u} bn-u 'l-\uc{yamAn_i}}, etc.
 %
-%   \textsc{Rem.}~\emph{c.} The letter \arb[novoc]{y} with two points
-%   below, \arb{al-yA'u 'l-mu_tannATu min ta.hti-hA}, may also be
-%   written without diacritical points as \arb[novoc]{Y}. When it is
-%   used as a long vowel, it is encoded |iY|, where |i| recalls the
+% \item The letter \arb[novoc]{y} with two points below, \arb{al-yA'u
+%   'l-mu_tannATu min ta.hti-hA}, may also be written without
+%   diacritical points as \arb[novoc]{Y}. When it is used as a long
+%   vowel, it is encoded |iY|, where |i| recalls the
 %   \arb[trans]{kasraT} placed below the preceding letter in vocalized
 %   Arabic, like so: |liY| \arb{liY} \arb[trans]{liY}, |yam^siY|
 %   \arb{yam^siY} \arb[trans]{yam^siY}.
-% \end{quoting}
+% \end{remarks}
 % 
 % \subsubsection{Short vowels}
 % \Vref{tab:arabtex-short-vowels} gives the Arab\TeX\ equivalents for
@@ -2141,19 +2141,19 @@
 %   kitAbu-hu fI 'l-`AdAt-i} \arb[trans]{\abjad{45} kitAbu-hu fI
 %   'l-`AdAt-i}.
 % \end{quote}
-% \begin{quoting}
-%   \textsc{Rem.}~\emph{a.} As can be seen in the above given example,
+% \begin{remarks}
+% \item As can be seen in the above given example,
 %   \package{arabluatex} expresses the \arb[trans]{'abjad} numbers in
 %   Roman numerals if it finds the \cs{abjad} command in any of the
 %   transliteration modes.
 %
-%   \textsc{Rem.}~\emph{b.} \cs{abjad} may also be found outside
-%   Arabic environments. In that case, \package{arabluatex} does not
-%   print the stroke as a distinctive mark over the number for it is
-%   not surrounded by other Arabic words. In case one nonetheless
-%   wishes to print the stroke, he can either use the \cs{aoline*}
-%   command that is described below in \vref{sec:underlining} or
-%   insert the \arb[trans]{'ab^gad} number in |\arb[novoc]{}|:---
+% \item \cs{abjad} may also be found outside Arabic environments. In
+%   that case, \package{arabluatex} does not print the stroke as a
+%   distinctive mark over the number for it is not surrounded by other
+%   Arabic words. In case one nonetheless wishes to print the stroke,
+%   he can either use the \cs{aoline*} command that is described below
+%   in \vref{sec:underlining} or insert the \arb[trans]{'ab^gad}
+%   number in |\arb[novoc]{}|:---
 %   \begin{quote}
 %     |The| |\arb[trans]{'abjad}| |number| |for| |1874| |is|
 %     |\abjad{1874}| The \arb[trans]{'abjad} number for 1874 is
@@ -2167,7 +2167,7 @@
 %     |\arb[novoc]{\abjad{1874}}| The \arb[trans]{'abjad} number for
 %     1874 is \arb[novoc]{\abjad{1874}}.
 %   \end{quote}
-% \end{quoting}
+% \end{remarks}
 %
 % \newfeature[v1.12]\cs{abjad} may also be used to convert values of
 % counters into \arb[trans]{'ab^gad} numbers, like so:--- %
@@ -2256,18 +2256,18 @@
 %   \arb[trans]{\abjad{45}: kitAbu-hu \aemph{fI 'l-\uc{`AdAt-i}}}.
 % \end{quote}
 % 
-% \begin{quoting}
-%   \textsc{Rem.}~\emph{a.} As the above example shows,
-%   \package{arabluatex} places the horizontal stroke \emph{under} the
-%   emphasized words in any of the transliteration modes.
-%
-%   \textsc{Rem.}~\emph{b.} \newfeature[v1.9.2]\DescribeMacro{\aemph*}
-%   \cs{aemph*} is also provided should one wish to always have the
-%   horizontal stroke printed over the emphasized words, like so:
-%   |\abjad{45}:| |kitAbu-hu| |\aemph*{fI| |'l-`AdAt-i}|
-%   \arb[voc]{\abjad{45}: kitAbu-hu \aemph*{fI 'l-`AdAt-i}}
-%   \arb[trans]{\abjad{45}: kitAbu-hu \aemph*{fI 'l-\uc{`AdAt-i}}}.
-% \end{quoting}
+% \begin{remarks}
+% \item As the above example shows, \package{arabluatex} places the
+%   horizontal stroke \emph{under} the emphasized words in any of the
+%   transliteration modes.
+%
+% \item \newfeature[v1.9.2]\DescribeMacro{\aemph*} \cs{aemph*} is also
+%   provided should one wish to always have the horizontal stroke
+%   printed over the emphasized words, like so: |\abjad{45}:|
+%   |kitAbu-hu| |\aemph*{fI| |'l-`AdAt-i}| \arb[voc]{\abjad{45}:
+%   kitAbu-hu \aemph*{fI 'l-`AdAt-i}} \arb[trans]{\abjad{45}:
+%   kitAbu-hu \aemph*{fI 'l-\uc{`AdAt-i}}}.
+% \end{remarks}
 %
 % \subsubsection{Underlining words or numbers}
 % \label{sec:underlining}
@@ -3102,8 +3102,8 @@
 %   \arb{^gAmi`aT|\arbcolor[red]{\arbnull{T}aN}}
 %   \arb[trans]{^gAmi`aT|\arbcolor[red]{\arbnull{T}aN}}.
 % \end{quote}
-% \begin{quoting}
-%   \textsc{Rem.} Note that in the last example
+% \begin{remarks}
+% \item[\textsc{Rem.}] Note that in the last example
 %   (\arb[trans]{^gAmi`aT|\arbcolor[red]{\arbnull{T}aN}}), the
 %   \enquote*{pipe} character has been inserted before
 %   \cs{arbcolor}. Otherwise, the |dmg| mode of the transliteration
@@ -3112,7 +3112,7 @@
 %   \txtrans{t}).\footnote{See also \vpageref{ref:ta-marbutah-pipe}
 %   \enquote{Discarding the \arb[trans]{'i`rAb}} for more
 %   information.}
-% \end{quoting}
+% \end{remarks}
 %
 % The \arb[trans]{tanwIn} preceding a \arb[novoc]{_A} conveys even
 % more intricate business to the rendering with the utmost accuracy in
@@ -3169,10 +3169,10 @@
 %</example>
 % \fi%
 % 
-% \begin{quoting}
-%   \textsc{Rem.} In the preceding example, any consonant could have
-%   been passed as argument to the \cs{arbnull} command.
-% \end{quoting}
+% \begin{remarks}
+% \item[\textsc{Rem.}] In the preceding example, any consonant could
+%   have been passed as argument to the \cs{arbnull} command.
+% \end{remarks}
 % 
 % \paragraph{\texorpdfstring{\arb[trans]{^sad\-daT}}{šaddah}}
 % In the following example, it is assumed that the
@@ -3431,14 +3431,15 @@
 %</example>
 % \fi
 % 
-% \begin{quoting}\label{ref:prname-star}
-%   \textsc{Rem.} \DescribeMacro{\prname*} \package{arabluatex} also
-%   provides \cs{prname*} which only renders in upright roman style
-%   already transliterated proper names without applying any further
+% \begin{remarks}
+% \item[\textsc{Rem.}] \label{ref:prname-star}
+%   \DescribeMacro{\prname*} \package{arabluatex} also provides
+%   \cs{prname*} which only renders in upright roman style already
+%   transliterated proper names without applying any further
 %   processing. It is mostly used internally and applied to proper
 %   names exported in Unicode to an external selected
 %   file.\footnote{See below \vref{sec:arabtex2utf} for more details.}
-% \end{quoting}
+% \end{remarks}
 % 
 % \subsection{Additional note on \texttt{dmg} convention}
 % \label{sec:additional-note-dmg}
@@ -3509,29 +3510,29 @@
 %   \arb[voc]{al-.zulm-Atu} \arb[trans]{al-.zulm-Atu}.
 % \end{quote}
 %
-% \begin{quoting}
-%   \textsc{Rem.}~\emph{a.} As the \arb[trans]{tanwIn} is passed over
-%   in pronunciation when it is followed by the letters
-%   \arb[novoc]{r}, \arb[novoc]{l}, \arb[novoc]{m}, \arb[novoc]{w},
-%   \arb[novoc]{y} (see \vref{ref:assimilation}), it may be desirable
-%   to further distinguish it by putting it above the line, but not to
-%   do the same for \arb[trans]{.gayr mun.sarif} terminations. This
-%   can be achieved by simply omitting the hyphen before any
+% \begin{remarks}
+% \item As the \arb[trans]{tanwIn} is passed over in pronunciation
+%   when it is followed by the letters \arb[novoc]{r}, \arb[novoc]{l},
+%   \arb[novoc]{m}, \arb[novoc]{w}, \arb[novoc]{y} (see
+%   \vref{ref:assimilation}), it may be desirable to further
+%   distinguish it by putting it above the line, but not to do the
+%   same for \arb[trans]{.gayr mun.sarif} terminations. This can be
+%   achieved by simply omitting the hyphen before any
 %   \arb[trans]{.gayr mun.sarif} termination:---\\
 %   |kAna| |.ganiyyaN| |l_akinna-hu| |labisa| |^gubbaTaN| |mumazzaqaN|
 %   |'aydu-hA| \arb[voc]{kAna .ganiyyaN l_akinna-hu labisa ^gubbaTaN
 %   mumazzaqaN 'aydu-hA} \arb[trans]{kAna .ganiyyaN l_akinna-hu labisa
 %   ^gubbaTaN mumazzaqaN 'aydu-hA}.
 %
-%   \textsc{Rem.}~\emph{b.} Although the hyphen before the
-%   \arb[trans]{tanwIn} is optional as \package{arabluatex} always
-%   parses nouns with such termination, it may also be used to mark
+% \item Although the hyphen before the \arb[trans]{tanwIn} is optional
+%   as \package{arabluatex} always parses nouns with such termination,
+%   it may also be used to mark
 %   better the inflectional endings:---\\
 %   |mana`a| |'l-nAs-a| |kAffaT-aN| |min| |mu_hA.tabati-hi|
 %   |'a.had-uN| |bi-sayyidi-nA| \arb[voc]{mana`a 'l-nAs-a kAffaT-aN
 %   min mu_hA.tabati-hi 'a.had-uN bi-sayyidi-nA} \arb[trans]{mana`a
 %   'l-nAs-a kAffaT-aN min mu_hA.tabati-hi 'a.had-uN bi-sayyidi-nA}.
-% \end{quoting}
+% \end{remarks}
 % 
 % \paragraph{\texorpdfstring{Discar\-ding the
 % \arb[trans]{'i`rAb}}{Discarding the ʾiʿrāb}}
@@ -3549,17 +3550,17 @@
 %   state): |.hikmaT| |al-l_ah| \arb[trans]{.hikmaT| \uc{al-l_ah}},
 %   |fi.d.daT| |al-darAhim| \arb[trans]{fi.d.daT al-darAhim}.
 % \end{enumerate}
-% \begin{quoting}
-%   \textsc{Rem.} It may so happen, as in the absence of the article
-%   before the annexed word, that \package{arabluatex} be unable to
-%   determine which of the above two cases the word ending with
-%   \arb[trans]{tA' marbU.taT} falls into. The \enquote*{pipe}
+% \begin{remarks}
+% \item[\textsc{Rem.}] It may so happen, as in the absence of the
+%   article before the annexed word, that \package{arabluatex} be
+%   unable to determine which of the above two cases the word ending
+%   with \arb[trans]{tA' marbU.taT} falls into. The \enquote*{pipe}
 %   character (see \vref{sec:pipe}) may be appended to that word to
 %   indicate that what follows is in the construct state:
 %   |\uc{r}isAlaT| |fI| |tartIb| \verb+qirA'aT|+ |kutub|
-%   |\uc{^g}AlInUs| \arb[trans]{\uc{r}isAlaT fI tartIb qirA'aT|
-%   kutub \uc{^g}AlInUs}.
-% \end{quoting}
+%   |\uc{^g}AlInUs| \arb[trans]{\uc{r}isAlaT fI tartIb qirA'aT| kutub
+%   \uc{^g}AlInUs}.
+% \end{remarks}
 % 
 %
 % \paragraph{Uncertain short vowels}
@@ -4236,11 +4237,11 @@
 % \iffalse
 %</example>
 % \fi
-% \begin{quoting}
-%   \textsc{Rem.} Do not forget to set back the quoting style to its
-%   initial state once the Arabic environment is closed. See the last
-%   line in the code above.
-% \end{quoting}
+% \begin{remarks}
+% \item[\textsc{Rem.}] Do not forget to set back the quoting style to
+%   its initial state once the Arabic environment is closed. See the
+%   last line in the code above.
+% \end{remarks}
 %
 % \subsection{Two-argument special commands}
 % \label{sec:two-arg-cmds}
-- 
cgit v1.2.3

