| 1 |
\documentclass{ltxdoc} % Process with xelatex -shell-esc |
| 2 |
\usepackage{unisugar} |
| 3 |
\usepackage[colorlinks=true]{hyperref} |
| 4 |
\usepackage{bashful} |
| 5 |
\usepackage{varioref} |
| 6 |
|
| 7 |
⌘let⌘use␣package=⌘usepackage |
| 8 |
⌘use␣package{xspace} |
| 9 |
⌘let⌘new␣command=⌘newcommand |
| 10 |
⌘new␣command⌘unisugar{⌘texttt{unisugar}⌘xspace} |
| 11 |
|
| 12 |
⌘use␣package{graphicx} |
| 13 |
⌘use␣package{metalogo} |
| 14 |
⌘use␣package{hyperref} |
| 15 |
⌘use␣package{polyglossia} |
| 16 |
⌘setmainlanguage{english} |
| 17 |
⌘setotherlanguage{hebrew} |
| 18 |
⌘newfontfamily⌘hebrewfont[Script=Hebrew]{David CLM} |
| 19 |
⌘newfontfamily⌘codefont{DejaVu Sans Mono} |
| 20 |
|
| 21 |
⌘let⌘new␣environment=⌘newenvironment |
| 22 |
|
| 23 |
⌘new␣command⌘command␣key{{⌘codefont⌘⌘}} |
| 24 |
⌘new␣command⌘return␣key{{⌘codefont⌘⏎}⌘xspace} |
| 25 |
|
| 26 |
⌘new␣command⌘Unicode{⌘textsc{Unicode}⌘xspace} |
| 27 |
⌘new␣environment{code}{% |
| 28 |
⌘begingroup |
| 29 |
⌘quote |
| 30 |
⌘small |
| 31 |
⌘codefont |
| 32 |
⌘tt |
| 33 |
}{% |
| 34 |
⌘endquote |
| 35 |
⌘endgroup |
| 36 |
} |
| 37 |
⌘new␣command⌘me{unisugar} |
| 38 |
⌘title{The ⌘textsf{⌘me} Package\thanks{ |
| 39 |
Copyright ⌘copyright{} 2011 by Yossi Gil |
| 40 |
⌘url{mailto:[email protected]}. |
| 41 |
This work may be distributed and/or modified under the conditions of the |
| 42 |
⌘emph{⌘LaTeX{} Project Public License} (LPPL), either version 1.3 of this |
| 43 |
license or (at your option) any later version. |
| 44 |
The latest version of this license is in |
| 45 |
⌘url{http://www.latex-project.org/lppl.txt} and version 1.3 or later |
| 46 |
is part of all distributions of ⌘LaTeX{} version 2005/12/01 or later. |
| 47 |
This work has the LPPL maintenance status `maintained'. |
| 48 |
The Current Maintainer of this work is Yossi Gil. |
| 49 |
This work consists of the files ⌘texttt{⌘me.tex} and ⌘texttt{⌘me.sty} |
| 50 |
and the derived file |
| 51 |
⌘texttt{⌘me.pdf} |
| 52 |
}} |
| 53 |
|
| 54 |
⌘author{Yossi Gil⌘thanks{⌘url{mailto:[email protected]}}⏎ |
| 55 |
⌘normalsize Department of Computer Science⏎ |
| 56 |
⌘normalsize The Technion---Israel Institute of Technology⏎ |
| 57 |
⌘normalsize Technion City, Haifa 32000, Israel |
| 58 |
} |
| 59 |
|
| 60 |
⌘date{{⌘makeatletter |
| 61 |
⌘date@unisugar\thanks{ |
| 62 |
This document describes ⌘unisugar ⌘version@unisugar.}}} |
| 63 |
|
| 64 |
|
| 65 |
|
| 66 |
⌘begin{document} |
| 67 |
⌘bash[stdoutFile=README] |
| 68 |
cat << EOF |
| 69 |
The unisugar package 0.92 |
| 70 |
========================= |
| 71 |
|
| 72 |
This package requires a TeX-alike system that uses native Unicode input system; |
| 73 |
current examples are XeTeX and LuaTeX. The package provides syntactic sugar for |
| 74 |
selected LaTeX commands, allowing these to be replaced with their Unicode- |
| 75 |
character counterpart, e.g., a Unicode bullet can be used instead of a \item, |
| 76 |
and a pilcrow can be used instead of \paragraph. |
| 77 |
|
| 78 |
The intent is to minimize the use of English left-to-right characters in |
| 79 |
documents whose main language is written right-to-left, since mixing characters |
| 80 |
of different directionality confuses both text editors and human beings. |
| 81 |
|
| 82 |
Using this package, you may find yourself typing a bit less, provided you can |
| 83 |
configure your text editor or keyboard driver to generate the handful of Unicode |
| 84 |
characters defined by this package. More importantly, the package is useful in |
| 85 |
defining macros whose name is composed of right-to-left characters and in |
| 86 |
minimizing mixed directionality text in right-to-left documents. |
| 87 |
|
| 88 |
This package may be distributed and/or modified under the LaTeX Project Public |
| 89 |
License (LPPL), version 1.3 or higher (your choice). The latest version of this |
| 90 |
license can be found at: http://www.latex-project.org/lppl.txt |
| 91 |
|
| 92 |
This work is author-maintained(as per LPPL maintenance status) by Yossi Gil |
| 93 |
<[email protected]> |
| 94 |
EOF |
| 95 |
\END |
| 96 |
|
| 97 |
⌘maketitle |
| 98 |
⌘begin{abstract} |
| 99 |
This package provides syntactic sugar |
| 100 |
for ⌘LaTeX{} commands, using selected |
| 101 |
⌘href{http://www.unicode.org/standard/standard.html}⌘Unicode |
| 102 |
characters: |
| 103 |
Selected ⌘Unicode characters can be used as shorthand for certain |
| 104 |
⌘LaTeX{} commands. |
| 105 |
The package also makes it possible to use the familiar |
| 106 |
command key symbol,~⌘command␣key{} as a prefix of ⌘TeX{}'s |
| 107 |
macros (the backlash character,~⌘textbackslash, can |
| 108 |
still be used). |
| 109 |
And it allows the use of visual space,~⌘␣, |
| 110 |
within the names of macros, thus making it easier to |
| 111 |
write macros whose names are composed of more than one word. |
| 112 |
|
| 113 |
In this document I describe these syntactical extensions, |
| 114 |
and explain why they make it easier to compose |
| 115 |
right-to-left documents. |
| 116 |
⌘end{abstract} |
| 117 |
|
| 118 |
{⌘small⌘tableofcontents} |
| 119 |
|
| 120 |
⌘parindent 1.5ex |
| 121 |
⌘parskip 0.5em |
| 122 |
|
| 123 |
§ Introduction |
| 124 |
You do not really ⌘emph{need} this package. |
| 125 |
As its name implies, all it offers is what people call |
| 126 |
``syntactic sugar''---the ability to use a selected |
| 127 |
number of ⌘textsc{⌘Unicode} characters instead of and within |
| 128 |
the most common ⌘LaTeX{} commands. |
| 129 |
|
| 130 |
Some may appreciate the fact that using this package, |
| 131 |
the text you type---the input to ⌘LaTeX{}---will look |
| 132 |
a bit more neat |
| 133 |
and infinitesimally closer to the output. |
| 134 |
Others will argue against it, mentioning that the input document |
| 135 |
will be less portable, |
| 136 |
and less ``⌘LaTeX-like'' (whatever this term means). |
| 137 |
|
| 138 |
Still, using this package, |
| 139 |
you will find yourself typing a bit less, |
| 140 |
provided you can configure your text editor or |
| 141 |
keyboard driver to generate |
| 142 |
the handful of ⌘Unicode characters defined by this package. |
| 143 |
|
| 144 |
More importantly, if your input files include right-to-left text, |
| 145 |
you are likely to find this package indispensable. |
| 146 |
If your document is indeed going to include right-to-left text, please |
| 147 |
pay special attention to Section~☝{Section:rtl:divisions}, |
| 148 |
which describes how ⌘unisugar should help you with |
| 149 |
your document divisioning directives, and |
| 150 |
to Section~☝{Section:rtl:commands}, |
| 151 |
which explains how ⌘unisugar makes it easier |
| 152 |
to intermix ⌘LaTeX{} commands with your text. |
| 153 |
If however you are not likely to include right-to-left text in |
| 154 |
your documents, |
| 155 |
you do not need to read these sections. |
| 156 |
|
| 157 |
|
| 158 |
§ User Guide |
| 159 |
Simply apply a ⌘verb+\usepackage+ directive to use |
| 160 |
this package. |
| 161 |
⌘begin{code} |
| 162 |
⌘verb+\usepackage{unisugar}+ |
| 163 |
⌘end{code} |
| 164 |
|
| 165 |
There are no package options at this time. |
| 166 |
|
| 167 |
You would then have to use a ⌘Unicode based version of ⌘LaTeX{}, |
| 168 |
that is ⌘XeLaTeX{} or ⌘LuaLaTeX{} |
| 169 |
to process your input file, e.g., for processing the document |
| 170 |
you are now reading, |
| 171 |
I typed at my shell command prompt |
| 172 |
⌘begin{code} |
| 173 |
xelatex unisugar.tex |
| 174 |
⌘end{code} |
| 175 |
|
| 176 |
§§ Document Divisioning Commands |
| 177 |
|
| 178 |
Two of ⌘Unicode's typographical characters,~⌘texttt{⌘¶} |
| 179 |
(code point B6, the pilcrow sign) and~⌘texttt{⌘§} |
| 180 |
(code point A7, the section sign) are employed |
| 181 |
in ⌘unisugar to make shorthands |
| 182 |
for ⌘LaTeX{} traditional document divisionining commands: |
| 183 |
⌘verb+\section+, |
| 184 |
⌘verb+\subsection+, ⌘verb+\subsubsection+, and the lesser units, |
| 185 |
⌘verb+\paragraph+, |
| 186 |
and ⌘verb+\subparagraph+ commands. |
| 187 |
|
| 188 |
Thus, instead of writing |
| 189 |
⌘begin{code} |
| 190 |
⌘textbackslash section⌘{User Guide⌘} |
| 191 |
⌘end{code} |
| 192 |
at the beginning of this section, I typed just |
| 193 |
⌘begin{code} |
| 194 |
⌘§ User Guide |
| 195 |
⌘end{code} |
| 196 |
Similarly, instead of |
| 197 |
⌘begin{code} |
| 198 |
⌘textbackslash subsection⌘{Document Divisioning Commands⌘} |
| 199 |
⌘end{code} |
| 200 |
I typed |
| 201 |
⌘begin{code} |
| 202 |
⌘§⌘§ Document Divisioning Commands |
| 203 |
⌘end{code} |
| 204 |
to generate the header of this subsection. |
| 205 |
|
| 206 |
Observe that I did not need to type nor an opening curly |
| 207 |
bracket,~⌘verb+{+, neither a closing curly bracket,~⌘verb+}+. |
| 208 |
The division's title extends from the~⌘texttt{⌘§} |
| 209 |
character (in case of a section), or the~⌘texttt{⌘§⌘§} |
| 210 |
characters pair (in case of a subsection) |
| 211 |
until the end of the line. |
| 212 |
|
| 213 |
|
| 214 |
Table ☝{Table:divisions} summarizes the shorthands for the document |
| 215 |
divisioning commands. |
| 216 |
The original versions are always there, in case you need |
| 217 |
to use the starred version of the divisioning command, |
| 218 |
or pass an optional argument to it. |
| 219 |
|
| 220 |
⌘begin{table}[!Hht] |
| 221 |
⌘small |
| 222 |
⌘begin{center} |
| 223 |
⌘begin{tabular}{lll} |
| 224 |
Division & ⌘LaTeX{} & ⌘unisugar ⏎ |
| 225 |
\hline |
| 226 |
\hline |
| 227 |
part & ⌘verb+\part+ & --- ⏎ |
| 228 |
chapter & ⌘verb+\chapter+ & --- ⏎ |
| 229 |
section & ⌘verb+\section+ & ⌘texttt{\§} ⏎ |
| 230 |
sub-section & ⌘verb+\section+ & ⌘texttt{\§\§} ⏎ |
| 231 |
sub-sub-section & ⌘verb+\subsection+ & ⌘texttt{\§\§\§} ⏎ |
| 232 |
paragraph & ⌘verb+\paragraph+ & ⌘texttt{\¶} ⏎ |
| 233 |
sub-paragraph & ⌘verb+\subparagraph+ & ⌘texttt{\¶\¶} ⏎ |
| 234 |
\hline |
| 235 |
⌘end{tabular} |
| 236 |
\caption{Shorthands for divisioning commands} |
| 237 |
⌖{Table:divisions} |
| 238 |
⌘end{center} |
| 239 |
⌘end{table} |
| 240 |
|
| 241 |
§§ Right-to-left Text Editing |
| 242 |
⌖{Section:rtl:divisions} |
| 243 |
There is a great advantage of using these sugared replacements |
| 244 |
in composing left-to-right documents. |
| 245 |
Think of a a Hebrew document including a section |
| 246 |
named ⌘texthebrew{מבוא} (Which means ``Introduction'' in Hebrew). |
| 247 |
Then, with plain ⌘XeLaTeX{}, the document would start with |
| 248 |
a directive |
| 249 |
⌘begin{code} |
| 250 |
⌘textbackslash{}section⌘{⌘fontspec{Courier New} |
| 251 |
מבוא% |
| 252 |
⌘rm⌘tt⌘} |
| 253 |
⌘end{code} |
| 254 |
Even if your text editor can manage well mixed directionality text, |
| 255 |
you will find editing the above line a bit confusing. |
| 256 |
The reason is that the character following the opening |
| 257 |
curly brackets is |
| 258 |
not~⌘texthebrew{א} but rather ⌘texthebrew{מ}. |
| 259 |
|
| 260 |
As the cursor moves forward beginning at the first character in |
| 261 |
the line, it hits the opening curly brackets, and then you may |
| 262 |
expect it to proceed to the adjacent |
| 263 |
letter ⌘texthebrew{א}. |
| 264 |
This so called ⌘emph{visual} flow is |
| 265 |
in incorrect. |
| 266 |
The more correct ⌘emph{logical} flow prescribes |
| 267 |
that the cursor should instead ``jump'' to the |
| 268 |
to the letter ⌘texthebrew{מ}, which is the first letter of |
| 269 |
the word ⌘texthebrew{מבוא}. |
| 270 |
|
| 271 |
Some editors adhere to the visual flow, others, more modern |
| 272 |
editors, to the logical flow. |
| 273 |
But experience shows that both are quite confusing. |
| 274 |
|
| 275 |
Our sugared version of the divisioning directives |
| 276 |
offer a more sane alternative. |
| 277 |
You can write instead |
| 278 |
⌘begin{hebrew} |
| 279 |
⌘begin{code} |
| 280 |
\§ ⌘fontspec{Courier New} מבוא |
| 281 |
⌘end{code} |
| 282 |
⌘end{hebrew} |
| 283 |
|
| 284 |
To understand why the latter is so much better than the former, |
| 285 |
you need to know a bit about the manner in which ⌘Unicode deals with |
| 286 |
text directionality. |
| 287 |
Broadly speaking, characters come |
| 288 |
in three major varieties: |
| 289 |
⌘begin{enumerate} |
| 290 |
• Left-to-right directed characters, including e.g., Latin characters. |
| 291 |
• Right-to-left directed characters, including e.g., |
| 292 |
characters of the Hebrew |
| 293 |
alphabet. |
| 294 |
• Undirected characters, including the digits 0-9, punctuation characters, |
| 295 |
and characters such as ⌘§, ⌘¶, ⌘␣, and ⌘command␣key{} |
| 296 |
which are not part of specific writing script. |
| 297 |
⌘end{enumerate} |
| 298 |
⌘Unicode assigns a direction to each line |
| 299 |
according to the first strongly directed character of that line, and then |
| 300 |
proceeds to assigning directionality to subsequences of characters |
| 301 |
occurring in that line.⌘footnote{% |
| 302 |
The full algorithm is fairly complicated, taking into account |
| 303 |
``weak'' directionality of some of the undirected characters, |
| 304 |
explicit directionality markers and nested directionality levels; |
| 305 |
details can be found here ⌘url{http://unicode.org/reports/tr9}.} |
| 306 |
|
| 307 |
Most text editors follow ⌘Unicode's algorithm. |
| 308 |
The line |
| 309 |
⌘begin{code} |
| 310 |
⌘textbackslash{}section\{\fontspec{Courier New} מבוא% |
| 311 |
⌘rm⌘tt⌘} |
| 312 |
⌘end{code} |
| 313 |
will thus be classified as left-to-right, with |
| 314 |
the ⌘texthebrew{מבוא} portion classified right-to-left, leading |
| 315 |
to the visual vs.\ logical confusion and to irritating |
| 316 |
cursor jumps. |
| 317 |
|
| 318 |
Further, the fact that the entire line is left-to-right will |
| 319 |
lead text editors such as ⌘texttt{gedit} to place |
| 320 |
the first character of that line at the left most position |
| 321 |
in the window. |
| 322 |
This might be confusing even further since the section body will, |
| 323 |
most likely, |
| 324 |
be classified as right-to-left, and hence will be laid out |
| 325 |
on the screen with the first character at the right-most |
| 326 |
position. |
| 327 |
|
| 328 |
|
| 329 |
⌘begin{figure}[!htbp] |
| 330 |
⌘begin{center} |
| 331 |
⌘includegraphics[scale=0.3]{traditional.png} |
| 332 |
⌘end{center} |
| 333 |
⌘caption{Using traditional sectioning directive with right-to-left text} |
| 334 |
⌖{Figure:traditional} |
| 335 |
⌘end{figure} |
| 336 |
|
| 337 |
Figure~☝{Figure:traditional} depicting the use of ⌘texttt{gedit} |
| 338 |
to compose a Hebrew ⌘LaTeX{} document |
| 339 |
may help in visualizing the difficulty. |
| 340 |
Line~18 containing the section title is laid out left-to-right, |
| 341 |
despite the fact that the title is written Hebrew, in |
| 342 |
visual discrepancy with lines~19 and on, containing the section body, |
| 343 |
which are laid out right-to-left. |
| 344 |
|
| 345 |
In contrast, the sugared version of our document divisioning command |
| 346 |
⌘begin{hebrew} |
| 347 |
⌘begin{code} |
| 348 |
\fontspec{Courier New} |
| 349 |
\§ ⌘fontspec{Courier New} מבוא |
| 350 |
⌘end{code} |
| 351 |
⌘end{hebrew} |
| 352 |
has no left-to-right characters, and hence will be classified |
| 353 |
as being entirely right-to-left: |
| 354 |
The cursor will not jump as it moves |
| 355 |
across that line. |
| 356 |
|
| 357 |
|
| 358 |
Compare Figure~☝{Figure:traditional} with Figure~☝{Figure:sugar} |
| 359 |
in which the sugared version of the ⌘verb+\section+ directive is used. |
| 360 |
We see that in Figure~☝{Figure:sugar} ⌘emph{all} lines |
| 361 |
are laid out right-to-left. |
| 362 |
|
| 363 |
|
| 364 |
⌘begin{figure}[!hbtp] |
| 365 |
⌘begin{center} |
| 366 |
⌘includegraphics[scale=0.3]{sugar.png} |
| 367 |
⌘end{center} |
| 368 |
⌘caption{Using sugared sectioning directive with right-to-left text} |
| 369 |
⌖{Figure:sugar} |
| 370 |
⌘end{figure} |
| 371 |
|
| 372 |
§§ Other Useful ⌘Unicode Characters |
| 373 |
The above sugar replacement for divisioning commands |
| 374 |
does not scale well. |
| 375 |
With the exception of mathematical symbols, it is difficult |
| 376 |
to find reasonable substitutes for ⌘Unicode replacements |
| 377 |
for the majority of ⌘LaTeX{} commands. |
| 378 |
|
| 379 |
Still, four more ⌘Unicode characters are used by ⌘unisugar |
| 380 |
as aliases for common ⌘LaTeX{} commands: |
| 381 |
⌘begin{enumerate} |
| 382 |
• Code point 2022, the bullet, rendered as ⌘•, is |
| 383 |
yet another name for the ⌘verb+\item+ command. |
| 384 |
To obtain this item, I typed |
| 385 |
⌘begin{code} |
| 386 |
\• Code point 2022, the bullet, rendered as ⌘textbackslash\•,⏎ |
| 387 |
is yet another name for the ⌘verb-\verb+\item+- command.⏎ |
| 388 |
To obtain this item, I typed:⏎ |
| 389 |
⌘end{code} |
| 390 |
• Code point 23CE, the return symbol, rendered |
| 391 |
as~⌘return␣key is an alias for ⌘verb+\\+. |
| 392 |
The ⌘verb+\author+ directive of this manuscript was |
| 393 |
typed out as |
| 394 |
⌘begin{code} |
| 395 |
⌘verb+\author{+\\ |
| 396 |
⌘verb+ Yossi Gil+\\ |
| 397 |
⌘verb+ ⌘thanks{\url{mailto:[email protected]}}+⌘return␣key⏎ |
| 398 |
⌘verb+ ⌘normalsize Department of Computer Science+⌘return␣key⏎ |
| 399 |
⌘verb+ ⌘normalsize The Technion---Israel Institute+\\ |
| 400 |
⌘verb+ of Technology+⌘return␣key⏎ |
| 401 |
⌘verb+ ⌘normalsize Technion City, Haifa 32000, Israel+\\ |
| 402 |
⌘verb+}+ |
| 403 |
⌘end{code} |
| 404 |
• Code point 2316 (position indicator), rendered as |
| 405 |
{\fontspec{DejaVu Sans Mono}\⌖} |
| 406 |
is an alias for ⌘LaTeX's ⌘verb+\label+ command. |
| 407 |
To generate a label for Table ☝{Table:divisions}, |
| 408 |
I wrote: |
| 409 |
⌘begin{code} |
| 410 |
{\fontspec{Courier New}\⌖}⌘verb+{Table:divisions}+ |
| 411 |
⌘end{code} |
| 412 |
• Code point 261D (white up pointing index) rendered as |
| 413 |
{\fontspec{DejaVu Sans Mono}\☝} |
| 414 |
is an alias ⌘LaTeX{}'s ⌘verb+\ref+ command. |
| 415 |
To reference Table ☝{Table:divisions}, I wrote |
| 416 |
⌘begin{code} |
| 417 |
To reference Table {\fontspec{DejaVu Sans Mono}\☝}\{Table:divisions\}, |
| 418 |
I wrote |
| 419 |
⌘end{code} |
| 420 |
|
| 421 |
• Code point 2026 (horizontal ellipsis), rendered as \verb+…+, serves as a sugar nickname for |
| 422 |
\verb+\ldots+, the lower ellipsis command. |
| 423 |
|
| 424 |
⌘end{enumerate} |
| 425 |
|
| 426 |
|
| 427 |
§§ Extended Syntax for Commands |
| 428 |
It is futile to try to introduce an pictorial, easy to remember, |
| 429 |
symbol for each of the |
| 430 |
⌘LaTeX{} commands in ordinary use, or even for a substantial |
| 431 |
portion of these. |
| 432 |
As large as it is, the ⌘Unicode character repertoire |
| 433 |
simply does not include icons that associated visually with notions |
| 434 |
such as ⌘verb-\verb+-, ⌘verb+\begin{description}+, etc. |
| 435 |
And even if it was, such a large set would be difficult to |
| 436 |
memorize. |
| 437 |
Worse, methods for producing so many characters would be cumbersome. |
| 438 |
|
| 439 |
Thus, you would have to type ⌘LaTeX{} commands every so often. |
| 440 |
This package offers a slightly better syntax for writing these. |
| 441 |
|
| 442 |
|
| 443 |
First, ⌘Unicode's code point 2318, rendered as ⌘command␣key, |
| 444 |
is used in many computing systems |
| 445 |
to denote the command key. |
| 446 |
With ⌘unisugar,the~⌘command␣key{} |
| 447 |
character can be used as a control sequence |
| 448 |
prefix, |
| 449 |
So, instead of writing at the beginning of this document |
| 450 |
⌘begin{code} |
| 451 |
⌘verb+\begin{document}+⏎ |
| 452 |
⌘verb+\maketitle+⏎ |
| 453 |
⌘verb+\begin{abstract}+⏎ |
| 454 |
⌘verb+This package provides syntactic sugar+⌘ldots |
| 455 |
⌘end{code} |
| 456 |
I wrote |
| 457 |
⌘begin{code} |
| 458 |
⌘command␣key⌘verb+begin{document}+⏎ |
| 459 |
⌘command␣key⌘verb+maketitle+⏎ |
| 460 |
⌘command␣key⌘verb+begin{abstract}+⏎ |
| 461 |
⌘verb+This package provides syntactic sugar+⌘ldots |
| 462 |
⌘end{code} |
| 463 |
|
| 464 |
Second, ⌘unisugar, extends to the usual set of~52 letters (a--z and A--Z) |
| 465 |
⌘Unicode character 2423, |
| 466 |
the open box, which looks like like visible space in its |
| 467 |
rendering~⌘␣. |
| 468 |
This character can thus participate in control sequences. |
| 469 |
The intention is that it will serve for separating words |
| 470 |
in the case that your control sequence is composed of |
| 471 |
several words. |
| 472 |
|
| 473 |
|
| 474 |
The names of a large number of ⌘LaTeX{} commands are made |
| 475 |
from two words. |
| 476 |
There are even a dozen or so control sequences whose |
| 477 |
name consists of three words, e.g., ⌘verb+\enlargethispage+ |
| 478 |
and ⌘verb+\addcontentsline+. |
| 479 |
Although ⌘unisugar does not provide aliases for any of |
| 480 |
these multi-word commands, you can do so yourself. |
| 481 |
For example, at the preamble of this document, right after |
| 482 |
⌘verb+\usepackage{unisugar}+, |
| 483 |
I wrote |
| 484 |
⌘begin{code} |
| 485 |
⌘command␣key{}let⌘command␣key{}use␣package=⌘command␣key{}usepackage⏎ |
| 486 |
⌘command␣key{}use␣package⌘{xspace⌘}⏎ |
| 487 |
⌘command␣key{}let⌘command␣key{}new␣command=⌘command␣key{}newcommand⏎ |
| 488 |
⌘command␣key{}new␣command⌘command␣key{}% |
| 489 |
unisugar⌘{⌘command␣key{}texttt⌘{unisugar⌘}⌘command␣key{}xspace⌘}⏎ |
| 490 |
⌘end{code} |
| 491 |
|
| 492 |
§§ Intermixing Commands with Right-to-Left Text |
| 493 |
⌖{Section:rtl:commands} |
| 494 |
You may not appreciate so much the advantage of |
| 495 |
typing ⌘Unicode's~⌘command␣key{} |
| 496 |
instead of plain ASCII's~⌘texttt{⌘textbackslash}. |
| 497 |
Granted, on most keyboards, typing~⌘texttt{⌘textbackslash} |
| 498 |
would be easier. |
| 499 |
|
| 500 |
However, the nice property of ⌘command␣key{} is that it directionally |
| 501 |
neutral. |
| 502 |
You would have to think about a sentence |
| 503 |
involving at least one ⌘LaTeX⌘ control sequence |
| 504 |
and/or a slash character to understand what I mean. |
| 505 |
You would not have to think so hard, |
| 506 |
since, this last sentence, namely, |
| 507 |
⌘begin{quote} |
| 508 |
``⌘emph{You would have to think about a sentence |
| 509 |
involving at least one ⌘LaTeX{} control sequence |
| 510 |
and/or a slash character to understand what I mean.}'' |
| 511 |
⌘end{quote} |
| 512 |
is a perfect example, since |
| 513 |
it is a sentence which involves a ⌘LaTeX{} control sequence, |
| 514 |
since the ⌘LaTeX⌘ logo is printed out using |
| 515 |
the ``⌘verb+\LaTeX\+" control sequence. |
| 516 |
Further, this sentence includes the slash character. |
| 517 |
|
| 518 |
Typing this sentence in English is fairly straightforward. |
| 519 |
⌘begin{code} |
| 520 |
You would have to think about a sentence |
| 521 |
involving at least one ⌘verb+\LaTeX\ +control sequence |
| 522 |
and/or a slash character to understand what I mean. |
| 523 |
⌘end{code} |
| 524 |
|
| 525 |
Let me translate this sentence into Hebrew for you. |
| 526 |
|
| 527 |
⌘begin{hebrew} |
| 528 |
יהיה עליך לחשוב על משפט המכיל לפחות פקודת בקרה אחת |
| 529 |
של ⌘LaTeX⌘ ו/או לוכסן בכדי להבין למה אני מתכוון. |
| 530 |
⌘end{hebrew} |
| 531 |
|
| 532 |
|
| 533 |
What input does ⌘LaTeX{} require in order to produce the above? |
| 534 |
Using backslashes and traditional ⌘LaTeX{} notation I would have written |
| 535 |
⌘begin{hebrew} |
| 536 |
⌘begin{code}⌘fontspec{Courier New} |
| 537 |
יהיה עליך לחשוב על משפט המכיל לפחות פקודת בקרה |
| 538 |
אחת ⏎ |
| 539 |
של |
| 540 |
⌘verb+\LaTeX\+ |
| 541 |
ו/או לוכסן בכדי להבין למה אני מתכוון. |
| 542 |
⌘end{code} |
| 543 |
⌘end{hebrew} |
| 544 |
|
| 545 |
Figure~☝{Figure:gedit-mixed-traditional} shows what this might look on |
| 546 |
an actual text editor. |
| 547 |
This may not seem too complicated, but a closer look |
| 548 |
would reveal that the production and inspection of this ⌘LaTeX{} |
| 549 |
is hindered by two or three annoying hidden issues. |
| 550 |
|
| 551 |
|
| 552 |
⌘begin{figure}[!htbp] |
| 553 |
⌘begin{center} |
| 554 |
%Produced from: |
| 555 |
% |
| 556 |
% |
| 557 |
%Let me translate this sentence into Hebrew for you. |
| 558 |
% |
| 559 |
%⌘begin{hebrew} |
| 560 |
%יהיה עליך לחשוב על משפט המכיל לפחות פקודת בקרה אחת |
| 561 |
%של ⌘LaTeX\ ו/או לוכסן בכדי להבין למה אני מתכוון. |
| 562 |
%⌘end{hebrew} |
| 563 |
% |
| 564 |
% |
| 565 |
% |
| 566 |
% |
| 567 |
⌘includegraphics[scale=0.3]{gedit-mixed-traditional.png} |
| 568 |
⌘end{center} |
| 569 |
⌘caption{A Hebrew sentence containing a control sequence (without ⌘unisugar).} |
| 570 |
⌖{Figure:gedit-mixed-traditional} |
| 571 |
⌘end{figure} |
| 572 |
|
| 573 |
|
| 574 |
First, the two backslash characters in the figure are not really |
| 575 |
⌘emph{back}slashes. |
| 576 |
The reason is that Hebrew is written right-to-left, and the ⌘textbackslash{} |
| 577 |
character leans in the text direction, and should therefore be considered |
| 578 |
a ⌘emph{forward} slash in this context. |
| 579 |
|
| 580 |
The second annoyance is the distinction between the |
| 581 |
two occurrences of this character: |
| 582 |
the first is at the beginning of the control sequence ⌘verb+\LaTeX+, |
| 583 |
denoting that the control sequence starts at that point. |
| 584 |
The second occurrence is at the end of the same control sequence, |
| 585 |
with the purpose of |
| 586 |
escaping the space that follows. |
| 587 |
This escape is required to prevent the control sequence from consuming |
| 588 |
the spaces that follow. |
| 589 |
|
| 590 |
The distinction between the first and which is the last ``backslash'' |
| 591 |
is clear in the case that the enclosing sentence is |
| 592 |
written left-to-right. |
| 593 |
But, both humans and text processing devices may be confused |
| 594 |
when the enclosing sentence is right-to-left. |
| 595 |
|
| 596 |
{⌘small⌘textsl |
| 597 |
(There is yet a third difficulty in the above sentence which I will |
| 598 |
not address here. |
| 599 |
The English forward slash character is used in Hebrew for separating the day, |
| 600 |
month and |
| 601 |
year components of a date. |
| 602 |
This is natural, since dates involve digits, and these are written, |
| 603 |
even in Hebrew, left to right. |
| 604 |
Most Hebrew authors extrapolate this convention to the separation of |
| 605 |
Hebrew words by a ``forward'' (left-leaning) slash as in the phrase |
| 606 |
⌘texthebrew{⌘fontspec{Courier New}% |
| 607 |
ו/או |
| 608 |
}% |
| 609 |
in the above. |
| 610 |
Other authors would right this phrase with the slash leaning in |
| 611 |
the text direction, i.e., |
| 612 |
⌘texthebrew{⌘fontspec{Courier New}% |
| 613 |
ו⌘textbackslash{}או |
| 614 |
}% |
| 615 |
)} |
| 616 |
|
| 617 |
The fact that the ⌘command␣key{} character does not |
| 618 |
lean neither left nor right, |
| 619 |
takes care of the first annoyance. |
| 620 |
|
| 621 |
The remedy for the second is simpler---use a pair of curly brackets |
| 622 |
to mark the end of the control sequence. |
| 623 |
|
| 624 |
Thus, with ⌘unisugar, I would write: |
| 625 |
⌘begin{hebrew} |
| 626 |
⌘begin{code} |
| 627 |
⌘fontspec{Courier New} |
| 628 |
יהיה עליך לחשוב על משפט המכיל לפחות פקודת בקרה |
| 629 |
אחת ⏎ של |
| 630 |
⌘setLTR⌘verb+{}+LaTeX⌘command␣key{}⌘setRTL |
| 631 |
ו/או לוכסן בכדי להבין למה אני מתכוון. |
| 632 |
⌘end{code} |
| 633 |
⌘end{hebrew} |
| 634 |
|
| 635 |
Figure~☝{Figure:gedit-mixed-traditional} shows this sugared input as it |
| 636 |
appears in the gedit editor. |
| 637 |
We can see that the entire control sequence phrase |
| 638 |
is written left-to-right, with the escape character |
| 639 |
first, and the pair of curly brackets last. |
| 640 |
|
| 641 |
|
| 642 |
⌘begin{figure}[!htbp] |
| 643 |
⌘begin{center} |
| 644 |
% |
| 645 |
%Produced from: |
| 646 |
% |
| 647 |
%Let me translate this sentence into Hebrew for you. |
| 648 |
% |
| 649 |
%⌘begin{hebrew} |
| 650 |
%יהיה עליך לחשוב על משפט המכיל לפחות פקודת בקרה אחת |
| 651 |
%של {}LaTeX⌘ ו/או לוכסן בכדי להבין למה אני מתכוון. |
| 652 |
%⌘end{hebrew} |
| 653 |
% |
| 654 |
% |
| 655 |
% |
| 656 |
% |
| 657 |
% |
| 658 |
% |
| 659 |
⌘includegraphics[scale=0.3]{gedit-mixed-sugar.png} |
| 660 |
⌘end{center} |
| 661 |
⌘caption{A Hebrew sentence containing a control sequence (with ⌘unisugar).} |
| 662 |
⌖{Figure:gedit-mixed-sugar} |
| 663 |
⌘end{figure} |
| 664 |
|
| 665 |
Evidently, mixed directionality text is slightly easier and clearer. |
| 666 |
But we can do even better, if we allow Hebrew characters |
| 667 |
in control sequences. |
| 668 |
This is carried out by (a yet to be published) another package, |
| 669 |
named ⌘texttt{sukkar}, which, relying on ⌘unisugar does precisely this |
| 670 |
and more. |
| 671 |
Package ⌘texttt{sukkar} also translates many common ⌘LaTeX{} |
| 672 |
commands to Hebrew, and since juxtaposition of words looks |
| 673 |
weird in Hebrew, it uses the~⌘␣{} Unicode character |
| 674 |
to separate words. |
| 675 |
With ⌘texttt{sukkar} |
| 676 |
one can write, e.g., |
| 677 |
⌘begin{hebrew}⌘codefont⌘command␣key⌘fontspec{Courier New} |
| 678 |
עשה⌘␣{}כותרת |
| 679 |
⌘end{hebrew} |
| 680 |
instead of ⌘verb+\make_title+. |
| 681 |
|
| 682 |
|
| 683 |
§ History |
| 684 |
⌘begin{description} |
| 685 |
•[Version 0.9] Initial release. |
| 686 |
•[Version 0.91] Placed under LPPL. |
| 687 |
•[Version 0.92] Added U+2026 HORIZONTAL ELLIPSIS, as nickname for ⌘verb+\ldots+. |
| 688 |
⌘end{description} |
| 689 |
|
| 690 |
|
| 691 |
§ Acknowledgements |
| 692 |
Will Robertson advised gave the advise of |
| 693 |
using ⌘XeLaTeX{} and ⌘texttt{polyglossia} |
| 694 |
to circumvent a bug of ⌘texttt{utf8x}. |
| 695 |
I pay tribute to Bruno Le Floch and Martin Scharrer who together |
| 696 |
devised the mechanism that made it possible to |
| 697 |
define a command which takes the rest of the line as argument. |
| 698 |
Martin Scharrer and Will Robertson encouraged me to work on this package. |
| 699 |
Vafa Khalighi |
| 700 |
devotion to bidirectional text processing with ⌘LaTeX{} |
| 701 |
was truly inspirational. |
| 702 |
|
| 703 |
|
| 704 |
|
| 705 |
|
| 706 |
|
| 707 |
⌘end{document} |