\documentclass[12pt]{article}
\usepackage{xsipa}

\title{The \texttt{xsipa} Package}
\author{Author: \texttt{Akpoué Kouamé Josué}\\ email: \texttt{djosuebetsaleelakpoue@gmail.com}}
\date{\today}

\begin{document}
	\maketitle
	
	\section*{Summary}
	
	The \texttt{xsipa} package offers a compact and customizable way to transcribe IPA using a modified XSAMPA system. It defines user-friendly commands that shorten the verbose \texttt{tipa} syntax, while remaining compatible with both \LaTeX{} and XeLaTeX{} workflows.
	
	\section{Loading the Package}
	
	To use \texttt{xsipa}, add the following line in your preamble:
	
	\begin{verbatim}
		\usepackage{xsipa}
	\end{verbatim}
	
	If using XeLaTeX{} or LuaLaTeX{}, the package supports Unicode output via \texttt{xunicode} when enabled internally (future versions may expose this as an option).
	
	\section{Basic Usage}
	
	\subsection{Single Symbols}
	
	Commands are based on XSAMPA codes, prefixed with \verb|\xs|. Examples:
	
	\begin{verbatim}
		----------------------------------
		xsipa	    %  tipa	        % XSAMPA
		----------------------------------
		\xsE      %  \textepsilon % E
		\xsO      %  \textopeno   % O
		\xs;H{a}  %  \'a          % a_H
		----------------------------------
	\end{verbatim}
	
	\subsection{Starred Environment: \texttt{\textbackslash xs*...\textasteriskcentered}}
	
	The command \verb|\xs*...*| expands a custom XSAMPA-like string into a sequence of IPA symbols:
	
	\begin{verbatim}
		\xs*EO*       % equivalent to \xsE\xsO
		\xs*; {e}*    % nasalized "e", equivalent to \xs;~{e}
	\end{verbatim}
	
	Another example: 
	\begin{itemize}
		\item Input 1: \verb|m\xs;H\xsO d\xsZ\xs;Hukr\xs;Lu| (single symbols mode)  
		\item Item 2: \verb|\xs*m;H{O}dZ;Hukr;Lu*| (starred environment mode)
		\item Output: \textipa{m\'OdZ\'ukr\`u}
	\end{itemize}
	
	\textbf{Note:} Diacritics and modifiers must be placed \emph{before} the segments they modify, and always used with braces: \verb|\xs;{e}|.
	
	\section{Modifications from XSAMPA}
	
	Due to LaTeX constraints, the following changes have been made:
	
	\begin{itemize}
		\item \verb|{| → \verb|[|, \verb|}| → \verb|]|
		\item \verb|@| → \verb|\@| (in single symbols commands only)
		\item \verb|%| → \verb|,|
		\item \verb|_| → \verb|;|
		\item \verb|\| → \verb|/|
		\item Alternative forms: \verb|<| and \verb|>| can be replaced with \verb|(| and \verb|)| (if you don't have access to \verb|<| and \verb|>| on your keyboard)
		\item So e.g. XSAMPA \verb|;>| may alternatively be typeset as \verb|;)| 
	\end{itemize}
	
	\section{Known Issues and Warnings}
	
	\begin{itemize}
		\item Commands like \verb|\xsd|, \verb|\xsp|, \verb|\xst| require an argument: use \verb|{}| to avoid errors.
		\item Avoid starting a \verb|\xs*...*| string with \verb|;|, \verb|:|, \verb|?| or \verb+|+; use \verb|{}| to protect them.
		\item Spaces inside \verb|\xs*...*| are interpreted as nasalization: avoid using them.
	\end{itemize}
	
	\section{Limitations}
	
	Available symbols in single symbols commands include consonnants, vowels, nasalization diacritic and some tone accents only. 
	Tone accents not included are : 
	\begin{itemize}
		\item Low rising
		\item High rising
		\item Rising falling
		\item Downstep
		\item Upstep
		\item Global rise
		\item Global fall
	\end{itemize}
	
	For nasalisation, \verb|;~| is not available. Instead, use \verb|\xs~|, \verb|\xs*...; {<symbol code>}...| or \verb|\xs*... {<symbol code>}...| only (i.e. the space is mandatory). 
\end{document}