Initial commit

kvafa · May 17, 2022 · 541735d · 541735d
1 parent a2fb461
commit 541735d
Show file tree

Hide file tree

Showing 18 changed files with 27,061 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,2 @@
+
+.DS_Store
diff --git a/README.md b/README.md
@@ -0,0 +1,34 @@
+# The bidi Package
+The `bidi` package provides a convenient interface for typesetting 
+bidirectional texts with plain TeX and LaTeX. 
+
+The package includes adaptations for use with many other commonly-used 
+packages.
+
+The official versions of the package is released on [CTAN](https://ctan.org/pkg/bidi).
+
+## Using the Package
+The following example illustrates how the package can be used.
+````tex
+\documentclass{article}
+\usepackage{bidi}
+\setRTL
+\begin{document}
+...
+\end{document}
+````
+
+## Reporting Issues
+If you think that you have found an issue in the package, please use 
+[the package issue tracker](https://github.com/kvafa/bidi/issues) 
+to report it.
+
+## Discussions
+You may also have conversations, ask questions and post answers
+without opening issues using the [Discussions space](https://github.com/kvafa/bidi/discussions).
+
+## Announcements
+The announcements for the new releases of the package will
+also appear in the Discussions space under the [Announcements
+category](https://github.com/kvafa/bidi/discussions/categories/announcements).
+
diff --git a/bidi-bibitem.pdf b/bidi-bibitem.pdf
diff --git a/bidi-doc-intro.ltx b/bidi-doc-intro.ltx
@@ -0,0 +1,38 @@
+\documentclass{ltxdoc}
+\input{bidi-doc-preamble.ltx}
+\begin{document}
+\section*{Introduction}
+\textsf{bidi} provides a convenient interface for typesetting bidirectional texts in plain \TeX\ and \LaTeX, using the \XeTeX{} engine.
+
+\subsection*{\textsf{bidi} Info On The Terminal and In The Log File}
+If you use \textsf{bidi} package to write any input \TeX\ document, and then run \texttt{xelatex} on your document, \textsf{bidi} writes some information about itself to the terminal and to the log file. The information is something like:
+\begin{verbatim}
+****************************************************
+* 
+* bidi package (Bidirectional typesetting in
+* plain TeX and LaTeX, using XeTeX engine)
+* 
+* Description: A convenient interface for
+* typesetting bidirectional texts in plain TeX
+* and LaTeX. The package includes adaptations
+* for use with many other commonly-used packages.
+* 
+* Copyright (c) 2007--2022 Vafa Khalighi
+* Copyright (c) 2018--2020 bidi-tex GitHub Organization
+* 
+* v36.7, 2022/02/18
+* 
+* License: LaTeX Project Public License, version
+* 1.3c or higher (your choice)
+* 
+* Location on CTAN: /macros/xetex/latex/bidi
+* 
+* Issue tracker: https://github.com/kvafa/bidi/issues
+* 
+* Discussions: https://github.com/kvafa/bidi/discussions
+* 
+* Primary author of bidi package: Vafa Khalighi.
+* 
+****************************************************
+\end{verbatim}
+\end{document}
diff --git a/bidi-doc-latex-basics.ltx b/bidi-doc-latex-basics.ltx
diff --git a/bidi-doc-latex-pkgs.ltx b/bidi-doc-latex-pkgs.ltx
@@ -0,0 +1,55 @@
+\documentclass{ltxdoc}
+\input{bidi-doc-preamble.ltx}
+\begin{document}
+\section{Extra \textsf{bidi} Packages and Classes}
+\subsection{\textsf{biditufte} bundle}
+A modified version of \textsf{tufte-latex}, \textsf{biditufte} bundle, mainly for RTL typesetting, is provided. If you never used \textsf{biditufte} bundle or \textsf{tufte-latex} package and you want to use \textsf{biditufte} bundle, then you need to look at \textsf{tufte-latex} package's manual and examples. In addition, for using \textsf{biditufte} bundle, you need to know the following notes:
+\begin{itemize}
+\item You need to use \textsf{biditufte-book} class instead \textsf{tufte-book} class and \textsf{biditufte-handout} class instead \textsf{tufte-handout} class. 
+\item \textsf{biditufte} bundle provides the following extra commands:
+\begin{BDef}
+\Lcs{LTRsidenote}\quad\Lcs{RTLsidenote}\quad\Lcs{LTRmarginnote}\quad\Lcs{RTLmarginnote}
+\end{BDef}
+\item \textsf{biditufte} bundle unlike \textsf{tufts-latex} package, only provides justified lines.
+\item Some features of \textsf{tufte-latex} that does not make any sense in RTL, do not exist in \textsf{biditufte} bundle (no need for \textsf{soul}, \textsf{letterspace} and \textsf{macrotype} packages).
+\item If you want to configure \textsf{biditufte-book} class for your own needs, then you can create a file with the name \texttt{biditufte-book.cfg} and put your \LaTeX{} macros in that file; similarly, if you want to configure \textsf{biditufte-handout} class for your own needs, then you can create a file with the name \texttt{biditufte-handout.cfg} and put your \LaTeX{} macros in that file.
+\end{itemize}
+\subsection{Typesetting \TeX{} and \LaTeX{} Codes}
+The \LaTeX{} codes in this manual are typeset  using the \textsf{bidicode} package.
+In standard \LaTeX\, you can not use footnotes inside \Lcs{chapter}, \Lcs{part}, \Lcs{section}, \Lcs{subsection}, \Lcs{subsection} and any other section-like commands, \Lcs{caption} and tabular environment.
+
+\textsf{bidi} package provides \textsf{bidiftnxtra} package that solves the issue of footnote in standard \LaTeX. \textsf{bidiftnxtra} package should be loaded after \textsf{bidi} package.
+\subsection{Typesetting Poems}
+The \textsf{bidi} package provides \textsf{bidipoem} package for typesetting Persian poems. It provides four environments, \texttt{traditionalpoem}, \texttt{modernpoem} and starred version of these. In the starred version of these environments you do not need to type {\ttfamily\symbol{92}\symbol{92}} and that is the only difference with the normal version of the environments. The \texttt{traditionalpoem} environment and its starred version are also useful for typesetting Classic Arabic poetry, in fact this package may also be useful for other RTL languages.
+
+When using \textsf{bidipoem} package, at least you need to run \texttt{xelatex} twice on your document. In fact, if you run \texttt{xelatex} just once on your document, you get a message saying ``Unjustified poem.  Rerun \texttt{XeLaTeX} to get poem right''.
+
+When you typeset your poems, you might get underfull \Lcs{hbox} messages. This is absolutely normal and if you want to get rid of these underfull \Lcs{hbox} messages, then you would need to use Kashida.
+
+If you need to change the default distance between two verses, you can do just that by:
+\begin{BDef}
+\Lcs{renewcommand}\Lcs{poemcolsepskip}\Largb{\Larga{length}}
+\end{BDef}
+\begin{BDef}
+\LBEG{traditionalpoem}\\
+\Larga{verse1}\texttt{\&}\Larga{verse2}{\ttfamily\symbol{92}\symbol{92}}\\
+\Larga{verse3}\texttt{\&}\Larga{verse4}{\ttfamily\symbol{92}\symbol{92}}\\
+\ldots\\
+\LEND{traditionalpoem}
+\end{BDef}
+\begin{BDef}
+\LBEG{traditionalpoem*}\\
+\Larga{verse1}\texttt{\&}\Larga{verse2}\\
+\Larga{verse3}\texttt{\&}\Larga{verse4}\\
+\ldots\\
+\LEND{traditionalpoem*}
+\end{BDef}
+\subsection{Typesetting Resum\'e}
+The \textsf{bidi} package provides \textsf{bidimoderncv}\footnote{This class is the modified version of \textsf{moderncv} class.} class for typesetting resum\'es. There are two examples, namely \texttt{test-casualcv.tex} and \texttt{test-classiccv.tex}, in the \textsf{doc} folder than you can look and learn how you can use it.
+\subsection{Print Two Pages On A Single Page}
+\textsf{bidi} package provides \textsf{bidi2in1} package  for printing two pages on a single (landscape) A4 page. Page numbers appear on the included pages, and not on the landscape 'container' page.
+
+\subsection{Producing Presentations}
+At the moment, there is only one class that you can prepare your presentations
+with.
+\end{document}
diff --git a/bidi-doc-latex-pkgsupport.ltx b/bidi-doc-latex-pkgsupport.ltx
@@ -0,0 +1,49 @@
+\documentclass{ltxdoc}
+\input{bidi-doc-preamble.ltx}
+\begin{document}
+\section{Support For Various Packages and Classes}
+The \textsf{bidi} package supports \textsf{amsmath}, \textsf{amstext}, \textsf{amsthm}, \textsf{array}, \textsf{arydshln}, \textsf{breqn}, \textsf{cals}, \textsf{caption}, \textsf{color}, \textsf{colortbl}, \textsf{crop}, \textsf{cuted}, \textsf{cutwin}, \textsf{dblfnote} \textsf{draftwatermark}, \textsf{empheq},   \textsf{fancyhdr}, \textsf{fancybox}, \textsf{fix2col}, \textsf{float}, \textsf{floatrow}, \textsf{flowfram}, \textsf{framed}, \textsf{ftnright}, \textsf{geometry}, \textsf{graphicx}, \textsf{hvfloat},  \textsf{hyperref}, \textsf{lettrine}, \textsf{listings}, \textsf{mdframed}, \textsf{midfloat}, \textsf{minitoc}, \textsf{multicol}, \textsf{multienum}, \textsf{newfloat}, \textsf{pdfpages}, \textsf{pstricks}, \textsf{quotchap}, \textsf{picinpar}, \textsf{ragged2e}, \textsf{rotating},  \textsf{sidecap}, \textsf{stabular}, \textsf{subfig}, \textsf{subfigure}, \textsf{supertabular}, \textsf{xtab}, \textsf{tabls}, \textsf{tabulary}, \textsf{PGF \&\ TIKZ}, \textsf{tocbibind}, \textsf{tocloft}, \textsf{tocstyle}, \textsf{wrapfig}, \textsf{xcolor}, \textsf{xltxtra} packages, \textsf{amsart}, \textsf{amsbook}, \textsf{artikel1}, \textsf{artikel2}, \textsf{artikel3}, \textsf{extarticle}, \textsf{flashcards}, \textsf{standrad article}, \textsf{boek}, \textsf{boek3}, \textsf{standard book}, \textsf{bookest}, \textsf{extbook}, \textsf{extletter}, \textsf{scrlettr},\textsf{standard letter}, \textsf{memoir}, \textsf{extreport}, \textsf{rapport1},  \textsf{rapport3}, \textsf{refrep}, \textsf{standard report}, \textsf{scrartcl}, \textsf{scrbook}, \textsf{scrreprt} classes and any other packages and classes that relies on these packages and classes. This means, you can use all these packages and classes in addition to other packages and classes that rely on these packages and classes and use their functionality fully for your bidirectional documents. 
+
+We now give some details that you should know about the supported packages or classes.
+\subsection{Color}
+You can use \textsf{color} and \textsf{xcolor} packages to typeset texts in colours and colour boxes produced by \Lcs{colorbox} and \Lcs{fcolorbox} commands. Please note that your Coloured text should not span more than a line, if your text  spans more than a line, you will be in trouble which means your whole document, page or paragraph may be coloured. If your texts spans more than a line, then you should use \textsf{xecolor} package.
+
+Also if you are going to use \Lcs{color} command to colour the text at the beginning of a paragraph, then you should have \Lcs{leavevmode} before \Lcs{color} command.
+
+For having coloured tabular, you can use \textsf{colortbl} package.
+\subsection{The \textsf{dblfnote} package}
+The \textsf{dblfnote} package makes footnotes double-columned. In addition \textsf{bidi} package adds bidirectional support for the \textsf{dblfnote} package by providing the following commands:
+\begin{BDef}
+\Lcs{RTLdfnmakecol}\qquad\Lcs{LTRdfnmakecol}
+\end{BDef}
+\begin{itemize}
+\item \Lcs{RTLdfnmakecol}  makes footnotes double-columned RTL.
+\item \Lcs{LTRdfnmakecol} makes footnotes double-columned LTR.
+\item If the main direction of the document is RTL, \Lcs{RTLdfnmakecol} is active and if the main direction of the document is LTR, \Lcs{LTRdfnmakecol} is active.
+\end{itemize}
+ Please note that when using \textsf{dblfnote} package, the footnote rule will be as wide as the footnote column and \Lcs{autofootnoterule}, \Lcs{rightfootnoterule}, \Lcs{leftfootnoterule}, and \Lcs{textwidthfootnoterule} commonds have no effects.
+\subsection{Hyperref}
+The \textsf{hyperref} package works fine with bidirectional documents if and only if, your link will not span more than a line. If your link spans more than a line, then your whole document, or page or paragraph may be linked.
+
+
+\subsection{The \textsf{listings} package}
+ Suppose that the main direction of the document is RTL, and you want to typeset a piece of C code in LTR mode but you also have the requirement that the caption of that particular code should be RTL. Since the direction of the code is LTR, then the direction of the caption also will be LTR and this is not something you want; sadly there is no easy way to do this. For this very reason, the \textsf{bidi} package adds a key to the \textsf{listings} package, namely \texttt{captiondirection}. This key can have the following values:
+\begin{itemize}
+\item \texttt{textdirection} follows the direction of the text (default).
+\item \texttt{RTL} sets the direction of the caption to RTL.
+\item \texttt{LTR} sets the direction of the caption to LTR.
+\end{itemize}
+ Giving any other values gives you an error.
+
+
+\subsection{\textsf{flowfram} Package}
+You can use \textsf{flowfram} package for your bidirectional documents. Please note that \textsf{flowfram} package provides support for bidirectional column typesetting, for details, see its manual.
+\subsection{Multicolumn Typesetting}
+In the previous versions of \textsf{bidi} package, it was recommended that you need to use \textsf{fmultico} package instead the original \textsf{multicol} package for RTL multicolumn typesetting. This is not the case any more and you should not use buggy \textsf{fmultico} package any more. Simply load the original \textsf{multicol} package before loading \textsf{bidi}. \textsf{bidi} now supports \textsf{multicol} package and you can typeset bidirectional multi columns. When using \textsf{multicol} package, the following two additional commands are proveded:
+\begin{BDef}
+\Lcs{RTLmulticolcolumns}\quad\Lcs{LTRmulticolcolumns}
+\end{BDef}
+If  the main direction of the document is RTL, then you get RTL multi columns and if the main direction of the document is LTR, then you get LTR multi columns. In addition, \Lcs{RTLmulticolcolumns} allows you to have RTL multi columns  and \Lcs{LTRmulticolcolumns} allows you to have LTR multi columns.
+
+In addition, you also can use \textsf{vwcol} package for variable width bidirectional column typesetting.
+\end{document}
diff --git a/bidi-doc-latex-programming.ltx b/bidi-doc-latex-programming.ltx
@@ -0,0 +1,72 @@
+\documentclass{ltxdoc}
+\input{bidi-doc-preamble.ltx}
+\begin{document}
+\section{Some Useful Internal Macros and Programming Tips}
+There are some useful internal macros and programming tips that might be helpful for you. This section, explains all these useful internals and programming tips.
+\subsection{Equating Conditionals}
+\begin{BDef}
+\Lcs{eqnewif}\Largb{\Larga{\Lcs{newconditional1}}}\Largb{\Larga{\Lcs{newconditional2}}}
+\end{BDef}
+In standard \LaTeX, \Lcs{newif} command is provided that you can define a new conditional with it. \Lcs{eqnewif} command is similar to \Lcs{newif} command but:
+\begin{itemize}
+\item With \Lcs{eqnewif} command, you can define two new conditionals instead one, so clearly it has two mandatory arguments.
+\item \Lcs{newconditional1} will be identical to \Lcs{newconditional2}, so that whenever \Lcs{newconditional1} is true, then \Lcs{newconditional2} is also true and whenever \Lcs{newconditional1} is false, then \Lcs{newconditional2} is also false and vice versa.
+\end{itemize}
+\subsection{RTL Conditional}
+\begin{BDef}
+\Lcs{if@RTL}
+\end{BDef}
+\Lcs{if@RTL} conditional is true inside RTL mode and it is false in LTR mode. 
+\subsection{Main RTL Conditional}
+\begin{BDef}
+\Lcs{if@RTLmain}
+\end{BDef}
+If the main direction of the document is RTL, \Lcs{if@RTLmain} is true and if the main direction of the document is LTR, \Lcs{if@RTLmain} is false.
+\subsection{Latin Conditional}
+\begin{BDef}
+\Lcs{if@nonlatin}
+\end{BDef}
+The packages should set the value of \Lcs{if@nonlatin} inside any environment that uses LTR script to false (\Lcs{@nonlatinfalse}) and inside any environment that uses RTL script to true (\Lcs{@nonlatintrue}).
+\subsection{Tags Internal Macro}
+\begin{BDef}
+\Lcs{@iftagsloaded}\Largb{\Larga{tags name}}\Largb{\Larga{do thing(s) if the tag is loaded}}\\
+\Largb{\Larga{do thing(s) if the tag is not loaded}}
+\end{BDef}
+As you can see, the syntax of \Lcs{@iftagsloaded} is exactly the same as the syntax of \Lcs{@ifpackageloaded} and \Lcs{@ifclassloaded}. By tags, we mean things like \texttt{leqno} or \texttt{reqno}. Please note that in the argument \Larga{tags name}, the extension \texttt{clo} should not be given.
+\subsection{Definition File Loaded Internal Macro}
+\begin{BDef}
+\Lcs{@ifdefinitionfileloaded}\Largb{\Larga{definition file name}}\\
+\Largb{\Larga{do thing(s) if the definition file is loaded}}\\
+\Largb{\Larga{do thing(s) if the definition file  is not loaded}}
+\end{BDef}
+As you can see, the syntax of \Lcs{@ifdefinitionfileloaded} is exactly the same as the syntax of \Lcs{@ifpackageloaded} and \Lcs{@ifclassloaded}. By definition file, we mean things like \texttt{hyperref-bidi.def} or \texttt{wrapfig-bidi.def}. Please note that in the argument \Larga{definition file name}, the extension \texttt{def} should not be given.
+\subsection{Tabular Conditional}
+\begin{BDef}
+\Lcs{if@RTLtab}
+\end{BDef}
+If the tabular is typeset RTL, \Lcs{if@RTLtab} is true and if the tabular is typeset LTR, \Lcs{if@RTLtab} is false.
+\subsection{Footnote Conditional}
+\begin{BDef}
+\Lcs{if@RTL@footnote}
+\end{BDef}
+When footnotes are typeset RTL, \Lcs{if@RTL@footnote} is true and when footnotes are typeset LTR, \Lcs{if@RTL@footnote} is false.
+\subsection{Direction Ensuring Macros}
+\begin{BDef}
+\Lcs{@ensure@RTL}\Largb{\Larga{text}}\quad\Lcs{@ensure@RL}\Largb{\Larga{text}}\quad\Lcs{@ensure@LTR}\Largb{\Larga{text}}\\
+\Lcs{@ensure@LR}\Largb{\Larga{text}}\quad
+\Lcs{@ensure@dir}\Largb{\Larga{text}}\quad\Lcs{@ensure@maindir}\Largb{\Larga{text}}
+\end{BDef}
+\begin{itemize}
+\item  \Lcs{@ensure@RTL} and \Lcs{@ensure@RL} internals make sure that \Larga{text} is always typeset RTL, independent on the current mode.
+\item  \Lcs{@ensure@LTR} and \Lcs{@ensure@LR} internals make sure that \Larga{text} is always typeset LTR, independent on the current mode.
+\item \Lcs{@ensure@dir} and \Lcs{@ensure@maindir} if used in RTL mode, they put \Larga{text} inside \Lcs{RLE} and if used in LTR mode, they put the text as it is.
+\end{itemize}
+\subsection{Reset Direction Macro}
+\begin{BDef}
+\Lcs{save@dir}\quad\Lcs{saved@@dir}\quad\Lcs{reset@dir}
+\end{BDef}
+\begin{itemize}
+\item \Lcs{save@dir}, if the direction of typesetting is RTL, defines \Lcs{saved@@dir} to be RTL and if the direction of typesetting is LTR, defines \Lcs{saved@@dir} to be LTR.
+\item \Lcs{reset@dir}, if \Lcs{saved@@dir} is defined as RTL, inserts \Lcs{setRTL} otherwise, if  \Lcs{saved@@dir} is defined as LTR, inserts \Lcs{setLTR}, otherwise does nothing.
+\end{itemize}
+\end{document}