-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathbabel.dtx
19288 lines (18741 loc) · 576 KB
/
babel.dtx
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% \iffalse
% This document requires lualatex
%%
%% Copyright (C) 2012-2018 Javier Bezos and Johannes L. Braams.
%% Copyright (C) 1989-2012 Johannes L. Braams and
%% any individual authors listed elsewhere in this file.
%% All rights reserved.
%%
%% This file is part of the Babel system.
%% --------------------------------------
%%
%% It may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
%% 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.3 or later is part of all distributions of LaTeX
%% version 2003/12/01 or later.
%%
%% This work has the LPPL maintenance status "maintained".
%%
%% The Current Maintainer of this work is Javier Bezos.
%%
%% The list of derived (unpacked) files belonging to the distribution
%% and covered by LPPL is defined by the unpacking scripts (with
%% extension |.ins|) which are part of the distribution.
%%
% \fi
%
% \CheckSum{5011}
%
% \iffalse
%<*filedriver>
\ProvidesFile{babel.dtx}[2018/11/13 v3.27 The Babel package]
\documentclass{ltxdoc}
\GetFileInfo{babel.dtx}
\usepackage{fontspec}
\setmainfont[Scale=.88]{Noto Serif}
\setsansfont[Scale=.88]{Noto Sans}
\setmonofont[Scale=.88,FakeStretch=.95]{Noto Mono}
\raggedright
\addtolength{\textwidth}{25pt}
\addtolength{\textheight}{3.5cm}
\addtolength{\topmargin}{-2cm}
\font\manual=logo10 % font used for the METAFONT logo, etc.
\newcommand*\MF{{\manual META}\-{\manual FONT}}
\newcommand*\babel{\textsf{babel}}
\newcommand*\Babel{\textsf{Babel}}
\newcommand*\xetex{\textsf{xetex}}
\newcommand*\pdftex{\textsf{pdftex}}
\newcommand*\luatex{\textsf{luatex}}
\newcommand*\nb[1]{}
\newcommand*\m[1]{\mbox{$\langle$\normalfont\itshape#1\/$\rangle$}}
\newcommand*\langlist{%
\meta{language}\texttt{,}\meta{language}\texttt{,}...}
\newcommand*\langvar{\m{lang}}
\newcommand*\Lopt[1]{\textsf{#1}}
\newcommand*\Lenv[1]{\texttt{#1}}
\newcommand*\menv[1]{\char`\{#1\char`\}}
\newcommand*\Eenv[1]{%
\quad\ldots\quad
\texttt{\color{thered}\string\end\menv{#1}}}
\newcommand*\file[1]{\texttt{#1}}
\newcommand*\cls[1]{\texttt{#1}}
\newcommand*\pkg[1]{\texttt{#1}}
\addtolength{\oddsidemargin}{1em}
\setlength{\leftmargini}{1.5em}
\usepackage{framed}
\usepackage{multicol}
\usepackage{color,colortbl}
\usepackage[linkbordercolor={.9 .7 .5}]{hyperref}
\newcommand\New[1]{%
\colorbox[rgb]{.92, .86, .73}{New #1}\enspace\ignorespaces}
\definecolor{thered} {rgb}{0.65,0.04,0.07}
\definecolor{thegrey} {gray}{0.8}
\definecolor{shadecolor}{rgb}{1,1,0.97}
\definecolor{messages}{rgb}{.66,.13,.27}
\makeatletter
\def\@begintheorem#1#2{%
\list{}{}%
\global\advance\@listdepth\m@ne
\item[{\sffamily\bfseries\color{messages}\hspace*{1.3em}%
\MakeUppercase{#1}}]}%
\makeatother
\newtheorem{warning}{Warning}
\newtheorem{note}{Note}
\newtheorem{example}{Example}
\newtheorem{troubleshooting}{Troubleshooting}
\let\bblxv\verbatim
\let\bblexv\endverbatim
\def\verbatim{\begin{shaded*}\bblxv\vskip-\baselineskip\vskip2.5\parsep}
\def\endverbatim{\bblexv\vskip-2\baselineskip\end{shaded*}}
\catcode`\_=\active
\def_{\bgroup\let_\egroup\color{thered}}
\def\MacroFont{\fontencoding \encodingdefault \fontfamily\ttdefault
\fontseries\mddefault \fontshape\updefault \small \catcode`\_=\active}
\definecolor{shadecolor}{rgb}{0.96,0.96,0.93}
\def\PrintDescribeMacro#1{%
\strut\MacroFont\color{thered}\normalsize\string#1}
\def\Describe#1{%
\par\penalty-500\vskip3ex\noindent
\DescribeMacro{#1}\args}
\def\DescribeOther{\vskip-4ex\Describe}
\makeatletter
\def\trouble#1{\addcontentsline{tsh}{trouble}{#1}}
\def\listoftroubles{\section*{Troubleshoooting}\@starttoc{tsh}}
\let\l@trouble\l@figure
\let\saved@check@percent\check@percent
\let\check@percent\relax
\def\args#1{%
\def\bbl@tempa{#1}%
\ifx\bbl@tempa\@empty\else#1\vskip1ex\fi\ignorespaces}
\begingroup % Changes to ltxdoc
\catcode`\<\active
\catcode`\>\active
\gdef\check@plus@etc{%
\let\bbl@next\pm@module
\ifx*\next
\let\bbl@next\star@module
\else\ifx/\next
\let\bbl@next\slash@module
\else\ifx<\next
\let\bbl@next\var@module
\fi\fi\fi
\bbl@next}
\gdef\var@module#1#2#3>>{%
$\langle$\pm@module#2#3>$\rangle$%
\ifx*#2\ $\equiv$\fi}
\endgroup
\renewcommand*\l@section[2]{%
\ifnum \c@tocdepth >\z@
\addpenalty\@secpenalty
\addvspace{1.0em \@plus\p@}%
\setlength\@tempdima{2em}%
\begingroup
\parindent \z@ \rightskip \@pnumwidth
\parfillskip -\@pnumwidth
\leavevmode \bfseries
\advance\leftskip\@tempdima
\hskip -\leftskip
#1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par
\endgroup
\fi}
\renewcommand*\l@subsection{\@dottedtocline{2}{2em}{3em}}
\renewcommand*\l@subsubsection{\@dottedtocline{3}{5em}{4em}}
\renewcommand*\l@paragraph{\@dottedtocline{4}{9em}{4.5em}}
\renewcommand\partname{Part}
\def\@pnumwidth{3em}
\makeatother
\begin{document}
\title{Babel, a multilingual package for use with \LaTeX's standard
document classes\thanks{During the development ideas from Nico
Poppelier, Piet van Oostrum and many others have been used.
Bernd Raichle has provided many helpful suggestions.}}
\author{Johannes Braams\\
Kersengaarde 33\\
2723 BP Zoetermeer\\
The Netherlands\\
\normalsize From version 3.9 on, Javier Bezos\\
\normalsize \texttt{www.texnia.com}}
\date{Typeset \today}
\begin{titlepage}
\begin{minipage}[t][0pt]{30cm}
\vspace{-3cm}\hspace{-7cm}
\sffamily
\begin{tabular}{p{8cm}p{15cm}}
\cellcolor[rgb]{.86,.73,.67}
&\cellcolor[rgb]{.95,.95,.95}
\vspace{3.6cm}%
\color[rgb]{.55,.4,.35}
\leftskip5mm
\sffamily\fontsize{72}{72}\selectfont Babel
\vspace{1.8cm}
\\
\cellcolor[rgb]{.95,.95,.95}
\vspace{2cm}\hspace{1.5cm}
\begin{minipage}{5cm}
\Large
Version \csname @gobble\expandafter\endcsname\fileversion\newline
\filedate
\vspace{1cm}
\textit{Original author}\newline
Johannes L. Braams
\vspace{.3cm}
\textit{Current maintainer}\newline
Javier Bezos
\end{minipage}
&\cellcolor[rgb]{.92, .86, .73}
\vspace{2cm}
\leftskip5mm
\begin{minipage}{10cm}
\large\setlength\parskip{3mm}\raggedright
The standard distribution of \LaTeX\ contains a number of document
classes that are meant to be used, but also serve as examples for
other users to create their own document classes. These document
classes have become very popular among \LaTeX\ users. But it should
be kept in mind that they were designed for American tastes and
typography. At one time they even contained a number of hard-wired
texts.
This manual describes \babel{}, a package that makes use of the
capabilities of \TeX\ version 3 and, to some extent, \xetex{} and
\luatex, to provide an environment in which documents can be typeset
in a language other than US English, or in more than one language or
script.
Current development is focused on Unicode engines (Xe\TeX{} and
Lua\TeX) and the so-called \textit{complex scripts}. New features
related to font selection, bidi writing and the like will be added
incrementally.
\Babel{} provides support (total or partial) for about 200
languages, either as a “classical” package option or as an
|ini| file. Furthermore, new languages can be created from scratch
easily.
\vspace{20cm}
\end{minipage}
\end{tabular}
\end{minipage}
\end{titlepage}
\tableofcontents
\listoftroubles
\clearpage
\part{User guide}
\begin{itemize}
\item This user guide focuses on \LaTeX. There are also some notes on
its use with Plain \TeX.
\item Changes and new features with relation to version 3.8 are
highlighted with \New{X.XX}\hspace{-.5em}. The most recent features
could be still unstable. Please, report any issues you find on
\texttt{https://github.com/latex3/latex2e/issues}, which is better
than just complaining on an e-mail list or a web forum.
\item If you are interested in the \TeX{} multilingual support, please
join the \textsf{kadingira} list on
\texttt{http://tug.org/mailman/listinfo/kadingira}. You can follow
the development of \babel{} on
\texttt{https://github.com/latex3/latex2e/tree/master/required/babel}
(which provides some sample files, too).
\item See section \ref{contribute} for contributing a language.
\item The first sections describe the traditional way of loading a
language (with |ldf| files). The alternative way based on |ini|
files, which complements the previous one (it will \textit{not}
replace it), is described below.
\end{itemize}
\section{The user interface}\label{U-I}
\subsection{Monolingual documents}
In most cases, a single language is required, and then all you need in
\LaTeX{} is to load the package using its standand mechanism for this
purpose, namely, passing that language as an optional argument. In
addition, you may want to set the font and input encodings.
\begin{example}
Here is a simple full example for “traditional” \TeX{} engines
(see below for \xetex{} and \luatex{}). The packages |fontenc| and
|inputenc| do not belong to \babel, but they are included in the
example because typically you will need them (however, the package
\textsf{inputenc} may be omitted with \LaTeX{} $\ge$ 2018-04-01 if
the encoding is UTF-8):
\begin{verbatim}
\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
_\usepackage[french]{babel}_
\begin{document}
Plus ça change, plus c'est la même chose!
\end{document}
\end{verbatim}
\end{example}
\begin{troubleshooting}
\trouble{Paragraph ended before \textbackslash UTFviii@three@octets
was complete}
A common source of trouble is a wrong setting of the input encoding.
Very often you will get the following somewhat cryptic error:
\begin{verbatim}
! Paragraph ended before \UTFviii@three@octets was complete.
\end{verbatim}
Make sure you set the encoding actually used by your editor.
\end{troubleshooting}
Another approach is making the language (\Lopt{french} in the example)
a global option in order to let other packages detect and use it:
\begin{verbatim}
_\documentclass[french]{article}_
\usepackage{babel}
\usepackage{varioref}
\end{verbatim}
In this last example, the package \texttt{varioref} will also see
the option and will be able to use it.
\begin{note}
Because of the way \babel{} has evolved, ``language'' can refer to
(1) a set of hyphenation patterns as preloaded into the format, (2)
a package option, (3) an |ldf| file, and (4) a name used in the
document to select a language or dialect. So, a package option
refers to a language in a generic way -- sometimes it is the actual
language name used to select it, sometimes it is a file name loading
a language with a different name, sometimes it is a file name
loading several languages. Please, read the documentation for
specific languages for further info.
\end{note}
\begin{troubleshooting}
The following warning is about hyphenation patterns, which are
not under the direct control of \babel:
\trouble{No hyphenation patterns were preloaded for (babel) the
language `LANG' into the format}
\begin{verbatim}
Package babel Warning: No hyphenation patterns were preloaded for
(babel) the language `LANG' into the format.
(babel) Please, configure your TeX system to add them and
(babel) rebuild the format. Now I will use the patterns
(babel) preloaded for \language=0 instead on input line 57.
\end{verbatim}
The document will be typeset, but very likely the text will not be
correctly hyphenated. Some languages may be raising this warning
wrongly (because they are not hyphenated); it is a bug to be fixed
-- just ignore it. See the manual of your distribution (Mac\TeX,
Mik\TeX, \TeX Live, etc.) for further info about how to configure
it.
\end{troubleshooting}
\subsection{Multilingual documents}
In multilingual documents, just use several options. The last one is
considered the main language, activated by default. Sometimes, the
main language changes the document layout (eg, |spanish| and |french|).
\begin{example}
In \LaTeX, the preamble of the document:
\begin{verbatim}
\documentclass{article}
\usepackage[dutch,english]{babel}
\end{verbatim}
would tell \LaTeX\ that the document would be written in two
languages, Dutch and English, and that English would be the first
language in use, and the main one.
\end{example}
You can also set the main language explicitly:
\begin{verbatim}
\documentclass{article}
\usepackage[_main=english_,dutch]{babel}
\end{verbatim}
\begin{warning}
Languages may be set as global and as package option at the same
time, but in such a case you should set explicitly the main language
with the package option |main|:
\begin{verbatim}
\documentclass[_italian_]{book}
\usepackage[ngerman,_main=italian_]{babel}
\end{verbatim}
\end{warning}
\begin{warning}
In the preamble the main language has \textit{not} been selected,
except hyphenation patterns and the name assigned to |\languagename|
(in particular, shorthands, captions and date are not activated). If
you need to define boxes and the like in the preamble, you might
want to use some of the language selectors described below.
\end{warning}
To switch the language there are two basic macros, decribed below in
detail: |\selectlanguage| is used for blocks of text, while
|\foreignlanguage| is for chunks of text inside paragraphs.
\begin{example}
A full bilingual document follows. The main language is |french|, which
is activated when the document begins. The package \textsf{inputenc}
may be omitted with \LaTeX{} $\ge$ 2018-04-01 if the encoding is UTF-8.
\begin{verbatim}
\documentclass{article}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
_\usepackage[english,french]{babel}_
\begin{document}
Plus ça change, plus c'est la même chose!
_\selectlanguage{english}_
And an English paragraph, with a short text in
_\foreignlanguage{french}{français}_.
\end{document}
\end{verbatim}
\end{example}
\subsection{Modifiers}
\New{3.9c} The basic behavior of some languages can be modified when
loading \babel{} by means of \textit{modifiers}. They are set after
the language name, and are prefixed with a dot (only when the language
is set as package option -- neither global options nor the |main| key
accept them). An example is (spaces are not significant and they can
be added or removed):\footnote{No predefined ``axis'' for modifiers
are provided because languages and their scripts have quite different
needs.}
\begin{verbatim}
\usepackage[latin_.medieval_, spanish_.notilde.lcroman_, danish]{babel}
\end{verbatim}
Attributes (described below) are considered modifiers, ie, you can
set an attribute by including it in the list of modifiers. However,
modifiers is a more general mechanism.
\subsection{\textsf{xelatex} and \textsf{lualatex}}
Many languages are compatible with \textsf{xetex} and \textsf{luatex}.
With them you can use \babel{} to localize the documents.
The Latin script is covered by default in current \LaTeX{} (provided
the document encoding is UTF-8), because the font loader is preloaded
and the font is switched to |lmroman|. Other scripts require loading
\textsf{fontspec}. You may want to set the font attributes with
\textsf{fontspec}, too.
\begin{example}
The following bilingual, single script document in UTF-8 encoding
just prints a couple of ‘captions’ and |\today| in Danish and
Vietnamese. No additional packages are required.
\begin{verbatim}
\documentclass{article}
_\usepackage[vietnamese,danish]{babel}_
\begin{document}
\prefacename{} -- \alsoname{} -- \today
\selectlanguage{vietnamese}
\prefacename{} -- \alsoname{} -- \today
\end{document}
\end{verbatim}
\end{example}
\begin{example}
Here is a simple monolingual document in Russian (text from the
Wikipedia). Note neither \textsf{fontenc} nor \textsf{inputenc} are
necessary, but the document should be encoded in UTF-8 and a
so-called Unicode font must be loaded (in this example |\babelfont| is
used, described below).
\begin{verbatim}
\documentclass{article}
_\usepackage[russian]{babel}_
\babelfont{rm}{DejaVu Serif}
\begin{document}
Россия, находящаяся на пересечении множества культур, а также
с учётом многонационального характера её населения, — отличается
высокой степенью этнокультурного многообразия и способностью к
межкультурному диалогу.
\end{document}
\end{verbatim}
\end{example}
\subsection{Troubleshooting}
\begin{itemize}
\item Loading directly |sty| files in \LaTeX{} (ie,
|\usepackage|\marg{language}) is deprecated and you will get the
error:\footnote{In old versions the error read ``You have used an
old interface to call babel'', not very helpful.}
\trouble{You are loading directly a language style}
\begin{verbatim}
! Package babel Error: You are loading directly a language style.
(babel) This syntax is deprecated and you must use
(babel) \usepackage[language]{babel}.
\end{verbatim}
\item Another typical error when using \babel{} is the
following:\footnote{In old versions the error read ``You haven't
loaded the language LANG yet''.}
\trouble{Unknown language `LANG'}
\begin{verbatim}
! Package babel Error: Unknown language `#1'. Either you have
(babel) misspelled its name, it has not been installed,
(babel) or you requested it in a previous run. Fix its name,
(babel) install it or just rerun the file, respectively. In
(babel) some cases, you may need to remove the aux file
\end{verbatim}
The most frequent reason is, by far, the latest (for example, you
included |spanish|, but you realized this language is not used after
all, and therefore you removed it from the option list). In most
cases, the error vanishes when the document is typeset again, but in
more severe ones you will need to remove the |aux| file.
\end{itemize}
\subsection{Plain}
In Plain, load languages styles with |\input| and then use
|\begindocument| (the latter is defined by \babel):
\begin{verbatim}
\input estonian.sty
\begindocument
\end{verbatim}
\begin{warning}
Not all languages provide a |sty| file and some of them are not
compatible with Plain.\footnote{Even in the \babel{} kernel there
were some macros not compatible with plain. Hopefully these issues
have been fixed.}
\end{warning}
\subsection{Basic language selectors}
This section describes the commands to be used in the document to
switch the language in multilingual documents. In most cases, only the
two basic macros |\selectlanguage| and |\foreignlanguage| are
necessary. The environments |otherlanguage|, |otherlanguage*| and
|hyphenrules| are auxiliary, and described in the next section.
The main language is selected automatically when the |document|
environment begins.
\Describe{\selectlanguage}{\marg{language}}
When a user wants to switch from one language to another he can
do so using the macro |\selectlanguage|. This macro takes the
language, defined previously by a language definition file, as
its argument. It calls several macros that should be defined in
the language definition files to activate the special definitions
for the language chosen:
\begin{verbatim}
\selectlanguage{german}
\end{verbatim}
This command can be used as environment, too.
\begin{note}
For ``historical reasons'', a macro name is converted to a language
name without the leading |\|; in other words,
|\selectlanguage{\german}| is equivalent to |\selectlanguage{german}|.
Using a macro instead of a ``real'' name is deprecated.
\end{note}
\begin{warning}
If used inside braces there might be some non-local changes, as this
would be roughly equivalent to:
\begin{verbatim}
{\selectlanguage{<inner-language>} ...}\selectlanguage{<outer-language>}
\end{verbatim}
If you want a change which is really local, you must enclose this
code with an additional grouping level.
\end{warning}
\Describe{\foreignlanguage}{\marg{language}\marg{text}}
The command |\foreignlanguage| takes two arguments; the second
argument is a phrase to be typeset according to the rules of the
language named in its first one. This command (1) only switches the
extra definitions and the hyphenation rules for the language,
\emph{not} the names and dates, (2) does not send information about
the language to auxiliary files (i.e., the surrounding language is
still in force), and (3) it works even if the language has not been
set as package option (but in such a case it only sets the hyphenation
patterns and a warning is shown). With the |bidi| option, it also
enters in horizontal mode (this is not done always for backwards
compatibility).
\subsection{Auxiliary language selectors}
\Describe{\begin\menv{otherlanguage}}{\marg{language}\Eenv{otherlanguage}}
The environment \Lenv{otherlanguage} does basically the same as
|\selectlanguage|, except the language change is (mostly) local to
the environment.
Actually, there might be some non-local changes, as this environment
is roughly equivalent to:
\begin{verbatim}
\begingroup
\selectlanguage{<inner-language>}
...
\endgroup
\selectlanguage{<outer-language>}
\end{verbatim}
If you want a change which is really local, you must enclose this
environment with an additional grouping, like braces |{}|.
Spaces after the environment are ignored.
\Describe{\begin\menv{otherlanguage*}}%
{\marg{language}\Eenv{otherlanguage*}}
Same as |\foreignlanguage| but as environment. Spaces after the
environment are \textit{not} ignored.
This environment was originally intended for intermixing left-to-right
typesetting with right-to-left typesetting in engines not supporting a
change in the writing direction inside a line. However, by default it
never complied with the documented behavior and it is just a version as
environment of |\foreignlanguage|, except when the option |bidi| is
set -- in this case, |\foreignlanguage| emits a |\leavevmode|, while
|otherlanguage*| does not.
\Describe{\begin\menv{hyphenrules}}{\marg{language}\Eenv{hyphenrules}}
The environment \Lenv{hyphenrules} can be used to select \emph{only} the
hyphenation rules to be used (it can be used as command, too). This can
for instance be used to select `nohyphenation', provided that in
\file{language.dat} the `language' \textsf{nohyphenation} is defined by
loading \file{zerohyph.tex}. It deactivates language shorthands, too
(but not user shorthands).
Except for these simple uses, |hyphenrules| is discouraged and
|otherlanguage*| (the starred version) is preferred, as the former does
not take into account possible changes in encodings of characters like,
say, |'| done by some languages (eg, \textsf{italian}, \textsf{french},
\textsf{ukraineb}). To set hyphenation exceptions, use
|\babelhyphenation| (see below).
\subsection{More on selection}
\Describe{\babeltags}{\char`\{\m{tag1} \texttt{=} \m{language1}, \m{tag2}
\texttt{=} \m{language2}, \dots\char`\}}
\New{3.9i} In multilingual documents with many language switches the
commands above can be cumbersome. With this tool shorter names can be
defined. It adds nothing really new -- it is just syntactical sugar.
It defines |\text|\m{tag1}\marg{text} to be
|\foreignlanguage|\marg{language1}\marg{text}, and |\begin|\marg{tag1}
to be |\begin{otherlanguage*}|\marg{language1}, and so on. Note
|\|\m{tag1} is also allowed, but remember to set it locally inside a
group.
\begin{example}
With
\begin{verbatim}
\babeltags{de = german}
\end{verbatim}
you can write
\begin{verbatim}
text \textde{German text} text
\end{verbatim}
and
\begin{verbatim}
text
\begin{de}
German text
\end{de}
text
\end{verbatim}
\end{example}
\begin{note}
Something like \verb|\babeltags{finnish = finnish}| is legitimate --
it defines |\textfinnish| and |\finnish| (and, of course,
|\begin{finnish}|).
\end{note}
\begin{note}
Actually, there may be another advantage in the ‘short’ syntax
|\text|\m{tag}, namely, it is not affected by |\MakeUppercase| (while
|\foreignlanguage| is).
\end{note}
\Describe{\babelensure}{|[include=|\m{commands}|,exclude=|\m{commands}%
|,fontenc=|\m{encoding}|]|\marg{language}}
\New{3.9i} Except in a few languages, like \textsf{russian},
captions and dates are just strings, and do not switch the
language. That means you should set it explicitly if you want to use
them, or hyphenation (and in some cases the text itself) will be
wrong. For example:
\begin{verbatim}
\foreignlanguage{russian}{text \foreignlanguage{polish}{\seename} text}
\end{verbatim}
Of course, \TeX{} can do it for you. To avoid switching the language
all the while, |\babelensure| redefines the captions for a given
language to wrap them with a selector:
\begin{verbatim}
\babelensure{polish}
\end{verbatim}
By default only the basic captions and |\today| are redefined, but you
can add further macros with the key |include| in the optional argument
(without commas). Macros not to be modified are listed in
|exclude|. You can also enforce a font encoding with
|fontenc|.\footnote{With it encoded string may not work as expected.}
A couple of examples:
\begin{verbatim}
\babelensure[include=\Today]{spanish}
\babelensure[fontenc=T5]{vietnamese}
\end{verbatim}
They are activated when the language is selected (at the |afterextras|
event), and it makes some assumptions which could not be fulfilled in
some languages. Note also you should include only macros defined by
the language, not global macros (eg, |\TeX| of |\dag|).
With |ini| files (see below), captions are ensured by default.
\subsection{Shorthands}
A \textit{shorthand} is a sequence of one or two characters that
expands to arbitrary \TeX{} code.
Shorthands can be used for different kinds of things, as for example:
(1) in some languages shorthands such as |"a| are defined to be able
to hyphenate the word if the encoding is |OT1|; (2) in some languages
shorthands such as |!| are used to insert the right amount of white
space; (3) several kinds of discretionaries and breaks can be inserted
easily with |"-|, |"=|, etc.
The package \textsf{inputenc} as well as \xetex{} an \luatex{} have
alleviated entering non-ASCII characters, but minority languages and
some kinds of text can still require characters not directly available
on the keyboards (and sometimes not even as separated or precomposed
Unicode characters). As to the point 2, now \textsf{pdfTeX} provides
|\knbccode|, and \luatex{} can manipulate the glyph list. Tools for
point 3 can be still very useful in general.
There are three levels of shorthands: \textit{user},
\textit{language}, and \textit{system} (by order of
precedence). Version 3.9 introduces the \textit{language user} level
on top of the user level, as described below. In most cases, you will
use only shorthands provided by languages.
\begin{note} Note the following:
\begin{enumerate}
\item Activated chars used for two-char shorthands cannot be followed
by a closing brace |}| and the spaces following are gobbled. With
one-char shorthands (eg,~|:|), they are preserved.
\item If on a certain level (system, language, user) there is a
one-char shorthand, two-char ones starting with that
char and on the same level are ignored.
\item Since they are active, a shorthand cannot contain the same
character in its definition (except if it is deactivated with, eg,
|string|).
\end{enumerate}
\end{note}
A typical error when using shorthands is the following:
\trouble{Argument of \textbackslash language@active@arg"
has an extra \textbraceright}
\begin{verbatim}
! Argument of \language@active@arg" has an extra }.
\end{verbatim}
It means there is a closing brace just after a shorthand, which is not
allowed (eg,~|"}|). Just add |{}| after (eg,~|"{}}|).
\Describe{\shorthandon}{\marg{shorthands-list}}
\DescribeOther{\shorthandoff}{%
\colorbox{thegrey}{\ttfamily\hskip-.2em*\hskip-.2em}%
\marg{shorthands-list}}
It is sometimes necessary to switch a shorthand
character off temporarily, because it must be used in an
entirely different way. For this purpose, the user commands
|\shorthandoff| and |\shorthandon| are provided. They each take a
list of characters as their arguments.
The command |\shorthandoff| sets the |\catcode| for each of the
characters in its argument to other (12); the command |\shorthandon|
sets the |\catcode| to active (13). Both commands only work on `known'
shorthand characters.
% TODO - Is the following true ????
% If a character is not known to be a shorthand character its category
% code will be left unchanged.
\New{3.9a} However, |\shorthandoff| does not behave as
you would expect with characters like |~| or |^|, because they
usually are not ``other''. For them |\shorthandoff*| is provided,
so that with
\begin{verbatim}
\shorthandoff*{~^}
\end{verbatim}
|~| is still active, very likely with the meaning of a non-breaking
space, and |^| is the superscript character. The catcodes used are
those when the shorthands are defined, usually when language files are
loaded.
\Describe{\useshorthands}{%
\colorbox{thegrey}{\ttfamily\hskip-.2em*\hskip-.2em}%
\marg{char}}
The command |\useshorthands| initiates the definition of user-defined
shorthand sequences. It has one argument, the character that starts
these personal shorthands.
\New{3.9a} User shorthands are not always alive, as they may
be deactivated by languages (for example, if you use |"| for your user
shorthands and switch from \textsf{german} to \textsf{french}, they
stop working). Therefore, a starred version
|\useshorthands*|\marg{char} is provided, which makes sure shorthands
are always activated.
Currently, if the package option |shorthands| is used, you must include any
character to be activated with |\useshorthands|. This restriction will
be lifted in a future release. % <- TODO
\Describe\defineshorthand{\texttt{[}\langlist\texttt{]}%
\marg{shorthand}\marg{code}}
The command |\defineshorthand| takes two arguments: the first is
a one- or two-character shorthand sequence, and the second is the
code the shorthand should expand to.
\New{3.9a} An optional argument allows to (re)define language and
system shorthands (some languages do not activate shorthands, so you
may want to add |\languageshorthands|\marg{lang} to the corresponding
|\extras|\m{lang}, as explained below). By default, user shorthands
are (re)defined.
User shorthands override language ones, which in turn override
system shorthands. Language-dependent user shorthands (new in
3.9) take precedence over ``normal'' user shorthands.
\begin{example}
Let's assume you want a unified set of shorthand for discretionaries
(languages do not define shorthands consistently, and |"-|, |\-|,
|"=| have different meanings). You could start with, say:
\begin{verbatim}
\useshorthands*{"}
\defineshorthand{"*}{\babelhyphen{soft}}
\defineshorthand{"-}{\babelhyphen{hard}}
\end{verbatim}
However, behavior of hyphens is language dependent. For example, in
languages like Polish and Portuguese, a hard hyphen inside compound
words are repeated at the beginning of the next line. You could then
set:
\begin{verbatim}
\defineshorthand[*polish,*portugese]{"-}{\babelhyphen{repeat}}
\end{verbatim}
Here, options with |*| set a language-dependent user shorthand,
which means the generic one above only applies for the rest of
languages; without |*| they would (re)define the language shorthands
instead, which are overriden by user ones.
Now, you have a single unified shorthand (|"-|), with a
content-based meaning (`compound word hyphen') whose visual behavior
is that expected in each context.
\end{example}
\Describe{\aliasshorthand}{\marg{original}\marg{alias}}
The command |\aliasshorthand| can be used to let another
character perform the same functions as the default shorthand
character. If one prefers for example to use the character |/|
over |"| in typing Polish texts, this can be achieved by entering
|\aliasshorthand{"}{/}|.
\begin{note}
The substitute character must \textit{not} have been declared before
as shorthand (in such a case, |\aliashorthands| is ignored).
\end{note}
\begin{example}
The following example shows how to replace a shorthand by another
\begin{verbatim}
\aliasshorthand{~}{^}
\AtBeginDocument{\shorthandoff*{~}}
\end{verbatim}
\end{example}
\begin{warning}
Shorthands remember somehow the original character, and the fallback
value is that of the latter. So, in this example, if no shorthand if
found, |^| expands to a non-breaking space, because this is the
value of |~| (internally, |^| still calls |\active@char~| or
|\normal@char~|). Furthermore, if you change the |system| value of
|^| with |\defineshorthand| nothing happens.
\end{warning}
\Describe{\languageshorthands}{\marg{language}} The command
|\languageshorthands| can be used to switch the shorthands on the
language level. It takes one argument, the name of a language or
|none| (the latter does what its name suggests).\footnote{Actually,
any name not corresponding to a language group does the same as
\texttt{none}. However, follow this convention because it might be
enforced in future releases of \babel{} to catch possible errors.}
Note that for this to work the language should have been specified as
an option when loading the \babel\ package. For example, you can use
in \textsf{english} the shorthands defined by \textsf{ngerman} with
\begin{verbatim}
\addto\extrasenglish{\languageshorthands{ngerman}}
\end{verbatim}
(You may also need to activate them with, for example,
|\useshorthands|.)
Very often, this is a more convenient way to deactivate shorthands
than |\shorthandoff|, as for example if you want to define a macro
to easy typing phonetic characters with \textsf{tipa}:
\begin{verbatim}
\newcommand{\myipa}[1]{{\languageshorthands{none}\tipaencoding#1}}
\end{verbatim}
\Describe{\babelshorthand}{\marg{shorthand}}
With this command you can use a shorthand even if (1) not activated in
\texttt{shorthands} (in this case only shorthands for the current
language are taken into account, ie, not user shorthands), (2) turned
off with |\shorthandoff| or (3) deactivated with the internal
|\bbl@deactivate|; for example, \verb|\babelshorthand{"u}| or
\verb|\babelshorthand{:}|. (You can conveniently define your own
macros, or even you own user shorthands provided they do not ovelap.)
For your records, here is a list of shorthands, but you must double
check them, as they may change:\footnote{Thanks to Enrico Gregorio}
\begin{description}
\itemsep=-\parskip
\item[Languages with no shorthands] Croatian, English (any variety),
Indonesian, Hebrew, Interlingua, Irish, Lower Sorbian, Malaysian,
North Sami, Romanian, Scottish, Welsh
\item[Languages with only \texttt{"} as defined shorthand character]
Albanian, Bulgarian, Danish, Dutch, Finnish, German (old and new
orthography, also Austrian), Icelandic, Italian, Norwegian, Polish,
Portuguese (also Brazilian), Russian, Serbian (with Latin script),
Slovene, Swedish, Ukrainian, Upper Sorbian
\item[Basque] |" ' ~|
\item[Breton] |: ; ? !|
\item[Catalan] |" ' `|
\item[Czech] |" -|
\item[Esperanto] |^|
\item[Estonian] |" ~|
\item[French] (all varieties) |: ; ? !|
\item[Galician] |" . ' ~ < >|
\item[Greek] |~|
\item[Hungarian] |`|
\item[Kurmanji] |^|
\item[Latin] |" ^ =|
\item[Slovak] |" ^ ' -|
\item[Spanish] |" . < > '|
\item[Turkish] |: ! =|
\end{description}
In addition, the \babel{} core declares |~| as a one-char shorthand
which is let, like the standard |~|, to a non breaking
space.\footnote{This declaration serves to nothing, but it is
preserved for backward compatibility.}
\Describe\ifbabelshorthand{\marg{character}\marg{true}\marg{false}}
\New{3.23} Tests if a character has been made a shorthand.
\subsection{Package options}
\New{3.9a}
These package options are processed before language options, so
that they are taken into account irrespective of its order. The first
three options have been available in previous versions.
\Describe{KeepShorthandsActive}{}
Tells babel not to deactivate shorthands after loading a language
file, so that they are also availabe in the preamble.
\Describe{activeacute}{} For some languages \babel\ supports this
options to set |'| as a shorthand in case it is not done by default.
\Describe{activegrave}{}
Same for |`|.
\Describe{shorthands=}{\meta{char}\meta{char}...
$\string|$ \texttt{off}}
The only language shorthands activated
are those given, like, eg:
\begin{verbatim}
\usepackage[esperanto,french,shorthands=:;!?]{babel}
\end{verbatim}
If \verb|'| is included, \texttt{activeacute} is set; if \verb|`| is
included, \texttt{activegrave} is set. Active characters (like
\verb|~|) should be preceded by \verb|\string| (otherwise they will be
expanded by \LaTeX{} before they are passed to the package and
therefore they will not be recognized); however, |t| is provided for
the common case of |~| (as well as |c| for not so common case of the
comma).
With |shorthands=off| no language shorthands are defined,
As some languages use this mechanism for tools not available
otherwise, a macro \verb|\babelshorthand| is defined, which allows
using them; see above.
\Describe{safe=}{\texttt{none} $\string|$ \texttt{ref} $\string|$