% \iffalse meta-comment
%
% Copyright (C) 2011,2012,2013 Zvi Gilboa (zgilboa@virginia.edu)
% 
% This file is part of the `hebpatch' package.
% --------------------------------------------
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2008/05/04 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Zvi Gilboa.
%
% This work consists of the files hebpatch.dtx and hebpatch.ins
% and the derived filebase hebpatch.sty.
% 
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{hebpatch.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<driver>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\def\PackageName{hebpatch}
%<driver>\def\PackageName{hebpatch}
%<package>\def\fileversion{v0.1}
%<driver>\def\fileversion{v0.1}
%<package>\def\filedate{2012/06/01}
%<driver>\def\filedate{2012/06/01}
%<package>\def\fileinfo{A Compatibility Patch for \babel's Original Implementation of Hebrew Language Support}
%<driver>\def\fileinfo{A Compatibility Patch for \babel's Original Implementation of Hebrew Language Support}
%<package>\ProvidesPackage{hebpatch}[2012/06/01]
%
%<*driver>
\documentclass{ltxdoc}
% default fonts
\IfFileExists{tgbonum.sty}%
{\usepackage{tgbonum}}{}
% hacking
\usepackage{defhack}
%LaTeX options
\usepackage{ifpdf}
% encoding options: MUST COME BEFORE BABEL
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenx}
\usepackage[strict=true,autostyle=true,english=american]{csquotes}
% multilingual support
\usepackage[hebrew,english]{babel}
% graphic packages
\usepackage[usenames,dvipsnames]{xcolor}
\usepackage{graphicx}
\usepackage{wrapfig}
% references, hyperlinks, and citation
\usepackage[unicode=true,
            bookmarks=true,
            bookmarksdepth=5,
            breaklinks=false,
            pdfusetitle,
            colorlinks=true,
            urlcolor=Blue,
            linkcolor=Sepia,
            citecolor=MidnightBlue]
        {hyperref}
% a poor man's color-coded documentation
\def\PrintMacroName#1{\strut \MacroFont\bfseries\textcolor{Sepia}{\string #1}\ }
\def\PrintDescribeMacro#1{\strut \MacroFont\bfseries\textcolor{Sepia}{\string #1}\ }
\def\PrintEnvName#1{\strut \MacroFont\bfseries\textcolor{Blue}{#1}\ }
\def\PrintDescribeEnv#1{\strut \MacroFont\bfseries\textcolor{Blue}{#1}\ }
% some extra formatting
\providecommand\babel{\textsf{babel}}
\providecommand\dst{\textsc{docstrip}}
\providecommand\file[1]{\texttt{#1}}
\providecommand\pkg[1]{\texttt{#1}}
% referece to TeX--XeT
\providecommand\XeT{X\kern-.125em\lower.5ex\hbox{E}\kern-.1667emT\@}
% references to XeTeX and XeLaTeX
\def\XeTeX{\leavevmode%
           \setbox0=\hbox{X\lower.5ex\hbox{\kern-.15em\reflectbox{E}}\kern-.1667em 
                          \TeX}%
           \dp0=0pt\ht0=0pt\box0}
\def\XeLaTeX{\leavevmode%
           \setbox0=\hbox{X\lower.5ex\hbox{\kern-.15em\reflectbox{E}}\kern-.1667em 
                          \LaTeX}%
           \dp0=0pt\ht0=0pt\box0}
% references to LuaTeX and LuaLaTeX
\def\LuaTeX{Lua\TeX}
\def\LuaLaTeX{Lua\LaTeX}
% reference to MikTeX
\def\MiKTeX{MiK\TeX}
% the current package
\usepackage{hebpatch}[2012/06/01]
% documentation options
\EnableCrossrefs         
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{hebpatch.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
%
% \fi
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{0.1}{2012/06/01}{Initial Version}
%
% \DoNotIndex{\newcommand,\newenvironment}
%
% \providecommand*{\url}{\texttt}
% \title{The \pkg{\PackageName} Package \\ \smallskip
%        \Large \fileinfo}
% \author{Zvi Gilboa \\ \url{zgilboa@virginia.edu}}
% \date{\fileversion~from \filedate}
%
% \maketitle
%
% \begin{abstract}
%   The current package aims to render \babel's Hebrew 
%   implementation (last updated in March 2005) compatible
%   with a variety of contemporary macro packages,
%   including, but not limited to \pkg{biblatex},
%   \pkg{tabu}, \pkg{pst-text}, and \pkg{Arabi}.
%   As Hebrew's incompatibility with such packages 
%   is primarily the result of kernel macros being
%   redefined in \file{rlbabel.def} (in itself a  
%   necessity since neither \LaTeX\ nor \babel\ provide
%   native bi-directional support), the task undertaken by
%   \pkg{hebpatch} is to patch the relevant macros in a way
%   that would retain all existing features on the one
%   hand, yet be compatible with the rest of \LaTeX\ on
%   the other.
% \end{abstract}
%
% \small
% \makeatletter 
% \begin{center}
%           {\bfseries Acknowledgments \vspace {-.5em}\vspace {\z@ }}
% \end {center}
% \makeatother
% \quotation
%   I am deeply indebted to Maxim Iorsh, Youssef Jabri,
%   Philipp Lehman, James Clawson, and Vafa Khalighi, 
%   whose feedback and ideas gave direction to, as well
%   as helped me set the goals of a larger project that
%   strives to provide extended Hebrew support in \LaTeXe,
%   and of which \pkg{hebpatch} makes the first part.
%   The current package was created with sincere gratitude
%   to the many developers of \LaTeX\ Hebrew support 
%   throughout the years, and out of deep appreciation
%   to lasting contributions by Michail Rozman, 
%   Boris Lavva, and the late Rama Porrat.
%
% \section{Introduction}
%
% \def\hebrewxDtxTmp{Background}
% \subsection*{\hebrewxDtxTmp}
% \addcontentsline{toc}{subsection}{\hebrewxDtxTmp}
%
% With the advent of \XeTeX\ as well as
% continuing development of \LuaTeX,
% many users have met the decision to switch -- at least
% when composing new documents -- to the above \TeX\ engines,
% not the least since they both include, among many other
% exciting and innovative features, the native support
% of OpenType fonts.
%
% In view of the growing number of high-quality 
% OpenType fonts that contain the glyphs needed by
% semitic alphabets and are available in the public domain, 
% using the \pkg{bidi} package by Vafa Khalighi 
% in conjunction with either the \pkg{Polyglossia} package 
% by Fran{\c{c}}ois Charette (if using \XeTeX) or
% \babel\ (if using \LuaTeX) has thus become
% many \TeX\ users' preferred method for typesetting
% (Biblical) Hebrew or (Classical) Arabic.
%
% There are, however, various instances where one cannot (yet) 
% use \XeTeX\ or \LuaTeX, at least not in an intuitive manner.
% For anyone interested in typesetting \textit{text along path}, 
% for instance, the \cs{pstextpath} macro from the \pkg{pst-text}
% package is truly indispensable.  Then again, if one wishes to
% revise or expand an old document that includes Hebrew or Arabic, 
% switching to \XeTeX\ or \LuaTeX\ will not only require a 
% considerable amount of debugging effort (consider for 
% a minute all those \cs{sethebrew}, \cs{unsethebrew}, 
% \cs{L} and \cs{R} occurrences), but will also 
% inevitably result in a document that, for better
% or for worse, looks somehow different.\footnote{When
%   switching a document to \LuaTeX\ or \XeTeX\, we
%   would either replace all (or some) fonts with their OpenType
%   counterparts, or stick to the document's original fonts.
%   If changing fonts, differences in appearance (minor as they
%   might be) are most likely unavoidable.  Holding on to the 
%   document's original (Type1) fonts, on the other hand, will result 
%   in a typesetting mishmash that counts on the novel bi-directional
%   and multilingual support mechanisms, as currently implemented in
%   \XeTeX\ or \LuaTeX, to handle right-to-left paragraph building 
%   in general, and Hebrew or Arabic language features in particular, 
%   just as \TeX{-}{-}\XeT\ and \babel\ would.  There are
%   many factors that render the latter impossible, most notably
%   the fact that neither \XeTeX\ nor \LuaTeX\ provide perfect 
%   equivalences to \cs{beginR}, \cs{beginL}, \cs{endR}, and \cs{endL}.}
% In light of the above, then, it is my belief that
% in order for true choice between \LaTeX, \LuaLaTeX, and \XeLaTeX\ 
% to exist -- at least as far as Hebrew goes -- we must guarantee 
% that the functionality of a language's
% special features, and likewise compatibility of its support files
% with the major macro packages used in one's system, be retained 
% with respect to as many typesetting engines as possible.
%
%
% \def\hebrewxDtxTmp{\enquote{Off-Shore} Hebrew}
% \subsection*{\hebrewxDtxTmp}
% \addcontentsline{toc}{subsection}{\hebrewxDtxTmp}
%
% \def\hebrewxDtxTmp{A Brief Historical Account}
% \subsubsection*{\hebrewxDtxTmp}
% \addcontentsline{toc}{subsubsection}{\hebrewxDtxTmp}
%
% As of June 2012, the source files that comprise \babel's 
% Hebrew support\footnote{These files are \file{hebinp.dtx}, 
%   \file{hebrew.dtx}, and {hebrew.fdd}.  To perform the installation
%   manually (note, however, that both \TeX\-Live and \MiKTeX\ install
%   the entire \babel\ package by default), one would also 
%   need the driver file \file{hebrew.ins}.  If you are curious 
%   enough to visit the CTAN directory which contains the source files
%   of \babel\, you'd notice the presence of another Hebrew-related 
%   file, specifically \file{heb209.dtx}.  As its name suggests, 
%   that file contains code that has long been considered obsolete.}
% date back to March 2005.  To be sure, development of Hebrew (font) 
% support for \LaTeXe\ did not cease at that time.  On the contrary, 
% development of the \textsf{Culmus} Hebrew 
% fonts\footnote{\url{culmus.sourceforge.net}},
% most notably by Maxim Iorsh and Yoram Gnat, has continued --
% and still continues -- to take place, and there emerged also several 
% loosely related \LaTeX\ packages that made \textsf{Culmus} 
% fonts accessible to \TeX, specifically by providing the required
% font-metrics (tfm), virtual-font (vf), encoding (enc), 
% and finally font-mapping (map) files.
%
% As a single roof under which all \enquote{post-\babel} 
% code could be found has not yet been created,
% it seems useful to provide here a brief, not to say crude
% historical account of the developemnt that took
% place since 2004, that is, since the point in time when Hebrew
% support in \babel\ was about to become stable.\footnote{The 
%   details provided here are based on personal email communication,
%   study of the relevant developer websites, study of the Ivri\TeX 
%   mailing list archives, and a comparison of the source files
%   included in each of the packages -- all necessary steps
%   for \pkg{hebpatch} to provide users with maximum backward
%   compatibility.  Any and all comments regarding the accuracy
%   and/or completeness of this rather rough historical account 
%   are more than welcome, and will be reflected in the next 
%   version of this package's documentation.}
%
% The initial location at which independent development 
% took place was Itai Levi's \textsf{Nikud} 
% Project\footnote{\url{nikud.berlios.de}}.  
% Implementing Sivan Toledo's technique 
% for vowel-placement by means of Type-3 fonts\cite{toledo}, 
% the \textsf{Nikud} project provided a set of files that
% consisted of the raw \textsf{Culmus} fonts, the custom 
% Type-3 fonts, and the corresponding virtual fonts, 
% thus making it possible to use these fonts in bi-directional
% \LaTeX\ documents.
%
% \def\tmpURL
%   {\url{http://sourceforge.net/projects/ivritex/}}
% Using both the \textsf{Nikud} Project and \pkg{Ivritex} 
% as its starting point, the \textsf{culmus-latex} 
% project\footnote{\tmpURL} 
% -- geared towards Linux users and led by Baruch Cohen, 
% Guy Rutenberg, Tzafrir Cohen, and Yotam Medini -- 
% provided enhanced font-definition as well font-encoding 
% files for use with \textsf{Culmus}, and also included a 
% modified version of \file{hebrew.ldf}, setting cp1255 as
% the default Hebrew input encoding and HE8 as the default 
% Hebrew font encoding, respectively.
%
% \def\tmpURL
%   {\url{http://www.ma.huji.ac.il/~sameti/tex/culmusmiktex.html}}
% Aiming to provide \MiKTeX\ users with similar support,
% Iddo Samet created a variant of 
% \textsf{culmus-latex}\footnote{\tmpURL}
% in which font definition files exort greater flexibility
% with respect to font scaling.
%
% Last but not least, Amit Aronovitch had identified a
% discrepancy between \file{rlbabel.def}'s handling of 
% the \texttt{book} class and the way the class is treated
% elsewhere in \LaTeX, for which he also posted a working patch.
%
% For one or the other reason, none of the above packages
% had made it to CTAN.  What's more, as the \textsf{Culmus} support
% packages for Linux and \MiKTeX contain many overlapping files,
% and since both also include an alternate \file{hebrew.ldf},
% incorporating any of these packages in its current form into any 
% of the main \TeX\ distributions will most likely generate unpredictable, 
% or otherwise inconsist behavior of the system.  As a result, 
% Hebrew support in \LaTeX\ does not fully work 
% \enquote{out of the box,} and instead requires that
% the Culmus fonts, along with all files needed in order 
% to use them, must be downloaded and installed seperately.
%
% \def\hebrewxDtxTmp{\pkg{\PackageName} in Relation to Other 
%                    Hebrew Support Packages}
% \subsubsection*{\hebrewxDtxTmp}
% \addcontentsline{toc}{subsubsection}{\hebrewxDtxTmp}
%
% In light of the above, the current package aims to rememdy, by way 
% of a hot patch, the most accute problems encountered when using the above
% legacy support files for Hebrew, while yet keeping these files intact.
% Accordingly, users should consider one of the three following approahces:
% 1) use the current package along with the legacy packages and font files;
% 2) use the current package in conjunction with the \pkg{culmusx} package, 
%    thereby gaining access to enhanced support of the \textsf{culmus} fonts; or
% 3) use the \pkg{hebrewx} package (rather than the current package) along 
%    with the \pkg{culmusx} package.
% As neither \pkg{hebrewx} nor \pkg{culmusx} uses any of the legacy
% Hebrew support files, this last approach should be preferred
% for all new documents.
%
% \section{Usage}
%
% Put text here.
%
% \StopEventually{}
%
% \section{Implementation}
%
% \iffalse
%<*package>
% \fi
%
% \def\hebrewxDtxTmp{Compatability with \babel\ and Friends}
% \subsection*{\hebrewxDtxTmp}
% \addcontentsline{toc}{subsection}{\hebrewxDtxTmp}
%
% Our first task is to restore \babel's original language 
% selection mechanism.  The rationale here is that
% instead of redefining \babel's sequence of macro 
% calls, we only make a small addition to the 
% portion of the kernel responsible for content tables, while
% otherwise leaving \babel's logic and flow algorithm intact.
% Then again, several language-related packages 
% (most notably Philipp Lehman's \pkg{biblatex}) 
% depend on \babel's original language-selection 
% macros, and accordingly break (or have some features
% break) as soon as the legacy \file{rlbabel.def} has been loaded by \babel.
%
%
%   \begin{macro}{\selectlanguage}
%
% We begin by restoring the definitions of
% \cs{selectlanguage} and all of its 
% variants.\footnote{%
%   For a detailed description of these macros,
%   see the \babel\ package documentation.}
%
%
%    \begin{macrocode}
\edef\selectlanguage{%
  \noexpand\protect
  \expandafter\noexpand\csname selectlanguage \endcsname
  }
%    \end{macrocode}
%   \end{macro}
%
%
%
%   \begin{macro}{*}
%
% Now follows \cs{languagename }, also known as the variant
% with the trailing space in its name.
%
%    \begin{macrocode}
\expandafter\def\csname selectlanguage \endcsname#1{%
  \bbl@push@language
  \aftergroup\bbl@pop@language
  \bbl@set@language{#1}}
%    \end{macrocode}
%   \end{macro}
%
%
%   \begin{macro}{\bbl@set@language}
%
% Having restored the definitions of the two
% \cs{selectlanguage} macros, we now need to
% gurantee that support of bi-directional content tables
% retains its behaviour as currently defined in 
% \file{rlbabel.def} and \file{hebrew.ldf}.
% To achieve this we amend the definition of 
% \cs{bbl@set@language}---the kernel macro which
% (beginning with \babel\ version 3.7f) handles
% language track-keeping in auxiliary files---so that it
% also treats the three right-to-teft content tables
% as appropriate.
%
% As should be noted, \cs{bbl@set@language} calls
% \cs{select@language} prior to adding the 
% relevant lines to the various auxiliary files.
% We may thus replace the reference to \#1 
% (as used in \file{rlbabel.def}'s \cs{@@selectlanguage}), 
% with a more meaningful reference to \cs{languagename}.
%
%    \begin{macrocode}
\def\bbl@set@language#1{%
  \edef\languagename{%
    \ifnum\escapechar=\expandafter`\string#1\@empty
    \else \string#1\@empty\fi}%
  \select@language{\languagename}%
  \if@filesw
    \protected@write\@auxout{}{\string\select@language{\languagename}}%
     \if@rl%
       \addtocontents{cot}{\xstring\select@language{\languagename}}%
       \addtocontents{fol}{\xstring\select@language{\languagename}}%
       \addtocontents{tol}{\xstring\select@language{\languagename}}%
     \else%
       \addtocontents{toc}{\xstring\select@language{\languagename}}%
       \addtocontents{lof}{\xstring\select@language{\languagename}}%
       \addtocontents{lot}{\xstring\select@language{\languagename}}%
     \fi%
  \fi}
%    \end{macrocode}
%   \end{macro}
%
% \def\hebrewxDtxTmp{The Right-to-Left Implementation}
% \subsection*{\hebrewxDtxTmp}
% \addcontentsline{toc}{subsection}{\hebrewxDtxTmp}
%
% \def\hebrewxDtxTmp{In a Nutshell: \TeX, \LaTeX, and Right-to-Left Languages}
% \subsubsection*{\hebrewxDtxTmp}
% \addcontentsline{toc}{subsubsection}{\hebrewxDtxTmp}
% 
% To typeset Right-to-Left documents in \TeX\ or \LaTeX\
% 
% need our typesetting engine to support bi
%
%
%
%
%
%
%
%
%
% \Finale
\endinput
