%%
%% 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'.
