1 files changed, 98 insertions, 9 deletions

diff --git a/samples/template-01.tex b/samples/template-01.tex
index fba7173..3d5f27d 100644
--- a/samples/template-01.tex
+++ b/samples/template-01.tex
@@ -1,20 +1,109 @@
-\documentclass[paper=letter, DIV=classic]{scrartcl}
-
-\usepackage{fontspec}
-\setmainfont{CMU Serif}
-\setsansfont{CMU Sans Serif}
-\setmonofont{CMU Typewriter Text}
+\documentclass[paper=letter, DIV=classic, headings=small]{scrartcl}
 
 \usepackage{ccicons}
+\usepackage{paralist}
 
-\usepackage[trans]{arabluatex}
+\usepackage{arabluatex}
+
+\usepackage{hyperref}
+\hypersetup{colorlinks, linkcolor=blue, breaklinks}
 
-\title{\textsf{arabluatex} sample file}
+\subject{\textsf{arabluatex} sample files}
+\title{The Basics}
 \author{Robert Alessi\thanks{\cczero\ This file is public domain.}}
 
 \begin{document}
 \maketitle
 
-Test: \arb{da_hala 'l-^gAmi`aTa mubtasimaN}
+\begin{abstract}
+  This file demonstrates the basic features of \texttt{arabluatex}.
+\end{abstract}
+
+\section{The less, the better}
+\label{sec:less-better}
+\textsf{arabluatex} is loaded by one single line in the preamble:
+\begin{verbatim}
+\usepackage{arabluatex}
+\end{verbatim}
+That said, there are two subsequent requirements:
+\begin{compactenum}
+\item An Arabic font: \textsf{arabluatex} tries to load the
+  \textsf{Amiri} Arabic font which is already part of
+  \textsf{texlive}.
+\item A Roman font that has all the characters that are needed for
+  the transliteration of the Arabic.
+\end{compactenum}
+
+Once these requirements are met, one may insert Arabic words in
+left-to-right paragraphs like so: \verb|\arb{da_hala mubtasimaN}|,
+\arb{da_hala mubtasimaN}. Or insert running paragraphs of Arabic text
+inside the \verb|arab| environment, like so:---
+\begin{verbatim}
+\begin{arab}
+  'at_A .sadIquN 'il_A ju.hA ya.tlubu min-hu .himAra-hu li-yarkaba-hu
+  fI safraTiN qa.sIraTiN fa-qAla la-hu: sawfa 'u`Idu-hu 'ilay-ka fI
+  'l-masA'-i wa-'adfa`u la-ka 'ujraTaN. fa-qAla ju.hA: 'anA 'AsifuN
+  jiddaN 'annI lA 'asta.tI`u 'an 'u.haqqiqa la-ka ra.gbata-ka
+  fa-'l-.himAr-u laysa hunA 'l-yawm-a.  wa-qabla 'an yutimma ju.hA
+  kalAma-hu bada'a 'l-.himAr-u yanhaqu fI 'i.s.tabli-hi. fa-qAla la-hu
+  .sadIqu-hu: 'innI 'asma`u .himAra-ka yA ju.hA yanhaqu. fa-qAla la-hu
+  ju.hA: .garIbuN 'amru-ka yA .sadIqI 'a-tu.saddiqu 'l-.himAr-a
+  wa-tuka_d_diba-nI?
+\end{arab}
+\end{verbatim}
+\begin{arab}
+  'at_A .sadIquN 'il_A ju.hA ya.tlubu min-hu .himAra-hu li-yarkaba-hu
+  fI safraTiN qa.sIraTiN fa-qAla la-hu: sawfa 'u`Idu-hu 'ilay-ka fI
+  'l-masA'-i wa-'adfa`u la-ka 'ujraTaN. fa-qAla ju.hA: 'anA 'AsifuN
+  jiddaN 'annI lA 'asta.tI`u 'an 'u.haqqiqa la-ka ra.gbata-ka
+  fa-'l-.himAr-u laysa hunA 'l-yawm-a.  wa-qabla 'an yutimma ju.hA
+  kalAma-hu bada'a 'l-.himAr-u yanhaqu fI 'i.s.tabli-hi. fa-qAla la-hu
+  .sadIqu-hu: 'innI 'asma`u .himAra-ka yA ju.hA yanhaqu. fa-qAla la-hu
+  ju.hA: .garIbuN 'amru-ka yA .sadIqI 'a-tu.saddiqu 'l-.himAr-a
+  wa-tuka_d_diba-nI?
+\end{arab}
+
+\section{Options}
+\label{sec:options}
+\textsf{arabluatex} may be loaded with four mutually exclusive options:---
+\begin{compactdesc}
+\item[voc] To have every short vowel written. This option is loaded by
+  default.
+\item[fullvoc] To have the \arb[trans]{sukUn} and the
+  \arb[trans]{wa.slaT} expressed in addition to what \verb|voc|
+  already does.
+\item[novoc] To have all the diacritics discarded.
+\item[trans] To have the Arabic transliterated into one of the
+  accepted standards.
+\end{compactdesc}
+\begin{verbatim}
+% <preamble>
+\usepackage{arabluatex} % this loads 'voc' by default
+\usepackage[voc]{arabluatex}
+\usepackage[fullvoc]{arabluatex}
+\usepackage[novoc]{arabluatex}
+\usepackage[trans]{arabluatex}
+\end{verbatim}
+
+At any point of the document, any mode can be set locally, like so:---
+\begin{verbatim}
+English paragraph: To have the \arb[trans]{sukUn} and the
+  \arb[trans]{wa.slaT} expressed...
+
+\begin{arab}[trans] % Arabic paragraph
+  'at_A .sadIquN 'il_A \cap{j}u.hA ya.tlubu min-hu .himAra-hu
+  li-yarkaba-hu fI safraTiN qa.sIraTiN fa-qAla la-hu: sawfa 'u`Idu-hu
+  'ilay-ka fI 'l-masA'-i wa-'adfa`u la-ka 'ujraTaN.
+\end{arab}
+\end{verbatim}
+
+English paragraph: To have the \arb[trans]{sukUn} and the
+  \arb[trans]{wa.slaT} expressed...
+
+\begin{arab}[trans] % Arabic paragraph
+  'at_A .sadIquN 'il_A \cap{j}u.hA ya.tlubu min-hu .himAra-hu
+  li-yarkaba-hu fI safraTiN qa.sIraTiN fa-qAla la-hu: sawfa 'u`Idu-hu
+  'ilay-ka fI 'l-masA'-i wa-'adfa`u la-ka 'ujraTaN.
+\end{arab}
 
 \end{document}