summaryrefslogtreecommitdiff
path: root/macros/xetex/latex/xepersian-hm/xepersian-hm-doc.ltx
blob: 1a2d88f8aa5b84d3140b0d55cc50c0f7271478d4 (plain)
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
%%
%% 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{longtable}
\usepackage{hypdoc}

\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-01 \quad v0.5c}

\begin{document}

\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{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{Kashida=off,RTLdocument=on}{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.

      \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'}}
\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}
\end{document}
%% 
%%
%% End of file `xepersian-hm-doc.ltx'.