1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
|
%%
%% This is file `xepersian-hm-doc.tex'
%%
%% Copyright (c) Hossein Movahhedian 2020
%%
%% It may be distributed and/or modified under the LaTeX Project Public License,
%% version 1.3c or higher (your choice). The latest version of
%% this license is at: http://www.latex-project.org/lppl.txt
%%
\documentclass{ltxdoc}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{hypdoc}
\usepackage{xepersian-hm}
\settextfont[Scale=1]{HM XKayhan}
\title{
The \textsf{xepersian-hm} package\\Fixing kashida in xepersian\\User Documentation
}
\author{
Hossein Movahhedian\thanks
{
E-mail:
\href{mailto:dma8hm1334@gmail.com}
{\textsf{dma8hm1334@gmail.com}}
}
}
\date{Released \quad 2020-05-20 \quad v0.5f}
\let\tmpthepage\thepage
\renewcommand{\thepage}{\lr{\Large\textbf\tmpthepage}}
\begin{document}
\begin{latin}
\maketitle
Kashida feature in \textsf{xepersian} has problems with some fonts such as \mbox{\textsf{HM Series}}
available at
\href{https://dma8hm1334.bitbucket.io}{\texttt{https://dma8hm1334.bitbucket.io}}
and \mbox{\textsf{X Series 2}} available at
\href{http://wiki.irmug.com/index.php/X_Series_2}{\texttt{http://wiki.irmug.com/index.php/X\_Series\_2}}.
The \textsf{xepersian-hm} package fixes these problems.
The files \texttt{kashida-glyph-example.tex} and \texttt{kashida-hrule-example.tex}
in the directory \texttt{texmf-dist/doc/xelatex/xepersian-hm/} can be used as simple
examples of the usage of the package.
Please use the Bitbucket issue tracker:
\href{https://bitbucket.org/dma8hm1334/xepersian-hm/issues}{\textsf{https://bitbucket.org/dma8hm1334/\linebreak[4]xepersian-hm/issues}}
to report a bug, request a feature or if you have a comment.
I will do my best to fix all the bugs you report, but, unfortunately,
time is a big hurdle to overcome; so, my apologies in advance for those
which I cannot make time to fix.
\section{Brief outline of the issues}
Kashida is one of the most important features that must be included in any
Persian typesetter. In xepersian this feature is implemented but with some
problems. These problems along withe fixes in xepersian-hm are briefly:
\newcounter{bean}
\begin{list}{P-\Roman{bean}}{\usecounter{bean}\setlength{\rightmargin}{\leftmargin}}
\item In \textsf{xepersian} overlapping of glyphs occurs in letter
combinations such as "\rl{ب + ی}", "\rl{ت + ی}", and
"\rl{پ + ی}" because the character
\textsf{U+FEF0 (ARABIC LETTER FARSI YEH FINAL FORM)} is replaced with
another character. This is fixed by modifying the fixed part of the
glue inserted between the consecutive characters. Furthermore, both,
the fixed and the stretchable parts of the glue can be changed by the
user.
\item In letter combinations such as "\rl{ه + ی}", in \textsf{xepersian},
the character \textsf{U+FEEB (ARABIC LETTER HEH INITIAL FORM)} is
replaced with \textsf{U+06BE (ARABIC LETTER HEH DOACHASHEMEE)}. This
is fixed by inserting the character \textsf{U+200E} before the
combination "\textsf{U+200D + hrule + U+200D}" which is used as
stretching item.
\item In \textsf{xepersian} when outline or shadow fonts are used, the gaps
filled by horizontal rule appears as a solid box. This is fixed by
using the \textsf{kashida} glyph instead of the horizontal rule in
\textsf{xepersian-hm}.
\item Activating kashida in \textsf{xepersian} disturbs ligatures. This is
fixed in \textsf{xepersian-hm} by escaping the components of the
ligature which form the glyph, i.e. by inserting an escape character
before Persian letters joined to form the ligature without any empty
characters, blank characters, invisible characters and whitespace
characters which form the glyph. See
\mbox{Figures \ref{fig:ligatures-xep} and \ref{fig:ligatures-xephm}}.
Currently only 3 ligature glyphs are available in
\textsf{xepersian-hm}, but you can add as many as you want or let
me know the ligature glyphs that you need, so that I can add them in
the next release of the package. Of course, this is not the best
solution, but it works.
\item If italic or oblique style of some fonts such as \textsf{X Series 2}
is used in \textsf{xepersian}, an extra gap is left between the
stretched characters. This is fixed in \textsf{HM Series} fonts.
\end{list}
For comparing the outputs of \textsf{xepersian} and \textsf{xepersian-hm} with
a variety of options available to these packages, please see the
\mbox{Figures \ref{fig:xepersian-XB}, \ref{fig:xepersian-hm-hrule}}, and \ref{fig:xepersian-hm-glyph}.
\begin{figure}
\centerline{\fbox{\includegraphics[scale=1]{doc-ligature-xep.pdf}}}
\caption{Package: \textsf{xeprsian}, Font: \textsf{Noto Sans Arabic}, \textsf{Scale=1.1}, \textsf{Kashida=On}}
\label{fig:ligatures-xep}
\end{figure}
\begin{figure}
\centerline{\fbox{\includegraphics[scale=1]{doc-ligature-xephm.pdf}}}
\caption{Package: \textsf{xeprsian-hm}, Font: \textsf{Noto Sans Arabic}, \textsf{Scale=1.1}, \textsf{Kashida=glyph}}
\label{fig:ligatures-xephm}
\end{figure}
\begin{figure}
\centerline{\fbox{\includegraphics[scale=1]{doc-samples-xep.pdf}}}
\caption{Package: \textsf{xeprsian}, Font: \textsf{XB Kayhan}, \textsf{Scale=4.5}, \textsf{Kashida=0n}}
\label{fig:xepersian-XB}
\end{figure}
\begin{figure}
\centerline{\fbox{\includegraphics[scale=1]{doc-samples-hrule.pdf}}}
\caption{Package: \textsf{xeprsian-hm}, Font: \textsf{HM XKayhan}, \textsf{Scale=4.5}, \textsf{Kashida=hrule}}
\label{fig:xepersian-hm-hrule}
\end{figure}
\begin{figure}
\centerline{\fbox{\includegraphics[scale=1]{doc-samples-glyph.pdf}}}
\caption{Package: \textsf{xeprsian-hm}, Font: \textsf{HM XKayhan}, \textsf{Scale=4.5}, \textsf{Kashida=glyph}}
\label{fig:xepersian-hm-glyph}
\end{figure}
\section{Package loading and options}
Please note that \textsf{xepersian-hm} loads \textsf{xepersian} automatically,
so you may only pass options to the package using the command
\verb|\PassOptionsToPackage| before \verb|\documentclass|. For example:
\begin{verbatim}
\PassOptionsToPackage{debugfootnotedirection=off,localise=off}{xepersian}
\documentclass{report}
\usepackage{xcolor}
\usepackage[Kashida,kashidastretch=0.14 em plus 0.5 em]{xepersian-hm}
\end{verbatim}
The options available in \textsf{xepersian-hm} are:
\begin{itemize}
\item \texttt{Kashida}: \\
which implements kashida feature with two possible values:
\begin{itemize}
\item \texttt{glyph}: \\
which uses the \texttt{Kashida} character to stretch the text.
With this option you should run \texttt{xelatex} thrice. For example: \\
\texttt{rm -f kashida-example.aux \\
xelatex kashida-example.tex \\
xelatex kashida-example.tex \\
xelatex kashida-example.tex}
Please note that this feature is still experimental and is not regarded as stable.
If you are going to use this option be ready for unpredictable results. Also, note
that the value of \texttt{Kashida} is mandatory.
\item \texttt{hrule}: \\
which uses a horizontal rule (\verb|\hrule|) to stretch the text.
\end{itemize}
For example \texttt{Kashida=glyph} inserts a stretched \texttt{Kashida} glyph where ever it is needed.
\item \texttt{linebreakpenalty}: \\
which specifies the amount of penalty for preventing bad line-breaking.
You may strictly specify the value of this option. For example \texttt{'linebreakpenalty=8'} or you
may use the default values. The available default values of penalties which are put into the
horizontal list output are the negative of the followings:
\begin{longtable}{ll}
\texttt{min}: & \texttt{0} \\
\texttt{low}: & \texttt{8} \\
\texttt{medium}: & \texttt{15} \\
\texttt{high}: & \texttt{25} \\
\texttt{max}: & \texttt{10000}
\end{longtable}
\item \texttt{kashidastretch}: \\
which specifies the amount of extra stretching
for some combinations of characters. You may strictly specify the value of
this option. For example \texttt{'kashidastretch=0.14 em plus 0.5 em'} or you
may use the default values. The available default values are:
\begin{longtable}{lll}
\texttt{kayhan} & \texttt{0.14 em plus 0.5 em} \\
\texttt{khorramshahr} & \texttt{0.131 em plus 0.5 em} \\
\texttt{kayhannavaar} & \texttt{0.129 em plus 0.5 em} \\
\texttt{kayhanpook} & \texttt{0.133 em plus 0.5 em} \\
\texttt{kayhansayeh} & \texttt{0.135 em plus 0.5 em} \\
\texttt{khoramshahr} & \texttt{0.128 em plus 0.5 em} \\
\texttt{khorramshahr} & \texttt{0.13 em plus 0.5 em} \\
\texttt{niloofar} & \texttt{0.132 em plus 0.5 em} \\
\texttt{paatch} & \texttt{0.127 em plus 0.5 em} \\
\texttt{riyaz} & \texttt{0.125 em plus 0.5 em} \\
\texttt{roya} & \texttt{0.142 em plus 0.5 em} \\
\texttt{shafigh} & \texttt{0.143 em plus 0.5 em} \\
\texttt{shafighKurd} & \texttt{0.126 em plus 0.5 em} \\
\texttt{shafighUzbek} & \texttt{0.123 em plus 0.5 em} \\
\texttt{shiraz} & \texttt{0.122 em plus 0.5 em} \\
\texttt{sols} & \texttt{0.124 em plus 0.5 em} \\
\texttt{tabriz} & \texttt{0.119 em plus 0.5 em} \\
\texttt{titr} & \texttt{0.12 em plus 0.5 em} \\
\texttt{titre} & \texttt{0.121 em plus 0.5 em} \\
\texttt{traffic} & \texttt{0.124 em plus 0.5 em} \\
\texttt{vahid} & \texttt{0.134 em plus 0.5 em} \\
\texttt{vosta} & \texttt{0.136 em plus 0.5 em} \\
\texttt{yaghut} & \texttt{0.138 em plus 0.5 em} \\
\texttt{yagut} & \texttt{0.137 em plus 0.5 em} \\
\texttt{yas} & \texttt{0.126 em plus 0.5 em} \\
\texttt{yekan} & \texttt{0.141 em plus 0.5 em} \\
\texttt{yermook} & \texttt{0.139 em plus 0.5 em} \\
\texttt{zar} & \texttt{0.116 em plus 0.5 em} \\
\texttt{ziba} & \texttt{0.119 em plus 0.5 em} \\
\texttt{default} & \texttt{0.14 em plus 0.5 em} \\
\texttt{noskip} & \texttt{0 em plus 0.5 em}
\end{longtable}
For example: \mbox{\texttt{'kashidastretch=titr'}} is equivalent to\linebreak
\mbox{\texttt{'kashidastretch=0.12 em plus 0.5 em'}}
\item \texttt{ligature}: \\
which fixes the disturbance of ligatures caused by activation of kashida in
\textsf{xepersian}. You may strictly specify the value of this option.
For example \texttt{'ligature=dlig'} or you may use the default value.
The available values are:
\begin{longtable}{ll}
\texttt{aalt}: & Access All Alternatives \\
\texttt{ccmp}: & Glyph Composition/Decomposition \\
\texttt{dlig}: & Discretionary Ligatures \\
\texttt{fina}: & Final (Terminal) Forms \\
\texttt{init}: & Initial Forms \\
\texttt{locl}: & Localized Forms \\
\texttt{medi}: & Medial Forms \\
\texttt{rlig}: & Required Ligatures \\
\texttt{default}: & All the above features
\end{longtable}
Please note that this feature is still experimental and is not regarded as stable.
\end{itemize}
\section{Commands}
\begin{description}
\item \verb|\discouragebadlinebreaks[linebreakpenalty][kashidastretch]{|{\it text}\verb|}|:
{\it text} may not contain paragraph breaks.
This command puts a penalty after each Persian word.
The optional arguments \texttt{linebreakpenalty} and \texttt{kashidastretch} locally specify the value of the penalty and the amount
of extra stretching for some combinations of characters respectively as discussed previously. For example:
\texttt{\bslash discouragebadlinebreaks[9][0.12 em plus 0.5 em]\{\dots\}}
\end{description}
\section{Important notes}
\begin{description}
\item Kashida and ligatures:
The method used to implement kashida feature breaks a ligature if it is applied to the letters which are joined to form
the ligature. This is fixed in \textsf{xepersian-hm}, but it is still immature.
\end{description}
\end{latin}
\end{document}
%%
%%
%% End of file `xepersian-hm-doc.ltx'.
|
