Debian Codegraph @

texmf-dist/doc/xelatex/unisugar/unisugar.tex

raw
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}