summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/base/inputenc.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/base/inputenc.dtx')
-rw-r--r--Master/texmf-dist/source/latex/base/inputenc.dtx182
1 files changed, 163 insertions, 19 deletions
diff --git a/Master/texmf-dist/source/latex/base/inputenc.dtx b/Master/texmf-dist/source/latex/base/inputenc.dtx
index 3fc18039b06..20dfce417cf 100644
--- a/Master/texmf-dist/source/latex/base/inputenc.dtx
+++ b/Master/texmf-dist/source/latex/base/inputenc.dtx
@@ -1,6 +1,6 @@
% \iffalse meta-comment
%
-% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006
+% Copyright 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009
% The LaTeX3 Project and any individual authors listed elsewhere
% in this file.
%
@@ -46,7 +46,7 @@
%</driver>
% \fi
%
-% \CheckSum{3463}
+% \CheckSum{3467}
%
%% \CharacterTable
%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -140,6 +140,7 @@
% \changes{v0.97}{1998/03/05}{Spanish ords changed to text chars, pr/2579}
% \changes{v1.1b}{2006/03/04}{Number of normalisations in the LICR
% representation (pr/3849)}
+% \changes{v1.1c}{2006/11/18}{Added missing \cs{ProvidesFile} line for cp1257 (pr/3892)}
%
%
% \section{Introduction}
@@ -163,7 +164,8 @@
%
% The encodings provided by this package are:
% \begin{itemize}
-% \item |ascii| ASCII encoding for the range 32--127.
+% \item |ascii| ASCII encoding for the range 32--127 (all others are made
+% invalid, i.e., this really defines a 7-bit encoding).
% \item |latin1| ISO Latin-1 encoding.
% \item |latin2| ISO Latin-2 encoding.
% \item |latin3| ISO Latin-3 encoding.
@@ -174,12 +176,12 @@
% \item |decmulti| DEC Multinational Character Set encoding.
% \item |cp850| IBM 850 code page.
% \item |cp852| IBM 852 code page.
-% \item |cp858| IBM 858 code page (this is 850 with euro symbol).
+% \item |cp858| IBM 858 code page (this is 850 with Euro symbol).
% \item |cp437| IBM 437 code page.
% \item |cp437de| IBM 437 code page (German version).
% \item |cp865| IBM 865 code page.
% \item |applemac| Macintosh encoding.
-% \item |macce| Macintosh Central European codepage.
+% \item |macce| Macintosh Central European code page.
% \item |next| Next encoding.
% \item |cp1250| Windows 1250 (central and eastern Europe) code page.
% \item |cp1252| Windows 1252 (Western Europe) code page.
@@ -188,9 +190,22 @@
% (synonym\footnote{It is now generated using the guards
% \texttt{cp1252,ansinew} the latter only used for the provides
% file line.} for |cp1252|).
+% \item |utf8| Unicode UTF-8 encoding support.
% \end{itemize}
-% See also the file \texttt{utf8ienc.dtx} that provides UTF8 support using the
-% \textsf{inputenc} package interface.
+%
+%
+%
+% \subsection{8-bit input encoding support}
+%
+% The \texttt{inputenc} package makes the upper 8-bit characters active and
+% assigns to all of them an error message. It then waits for the
+% input encoding definitions to change this set-up. Similarly, whenever
+% |\inputencoding| is encountered in a document, first the upper
+% 8-bit characters are set back to produce an error and then the
+% definitions for the new input encoding are loaded, changing some of the
+% previous settings.
+%
+%
%
% Each encoding has an associated |.def| file, for example
% |latin1.def| which defines the behaviour of each input character,
@@ -228,6 +243,132 @@
% See the documentation in |fntguide.tex| and |ltoutenc.dtx| for
% details of how to declare text commands.
%
+%
+% \subsection{UTF-8 encoding support}
+%
+%
+% The Unicode UTF-8 support works differently. It too uses a |.def| file
+% (i.e., |utf8.def|) but this file does not contain code point declarations
+% via |\DeclareInputText| or |\DeclareInputMath|. Instead it defines a number of
+% parsing commands that parse UTF-8 characters and then provides the
+% corresponding \LaTeX{} definitions (if possible).
+%
+% Unfortunately the number of Unicode characters that in theory could be
+% contained in a document is enormous. Thus even with today's amount of
+% computer memory it would be unrealistic to predefine all of them. Therefore the
+% approach taken by \LaTeX{} is as follows:
+% \begin{itemize}
+% \item
+% At the start of the document (|\begin{document}|) it examines all font
+% encodings that are being used within the current document.
+% \item
+% For each such font encoding it loads all known UTF-8 mappings that generate
+% characters from this font encoding.
+% \item
+% All other UTF-8 characters remain undefined and will produce an error
+% message if they appear in the document.
+% \end{itemize}
+%
+% The rationale behind this approach is that UTF-8 characters that do not
+% correspond to any glyph within the used font encodings cannot be represented
+% by \LaTeX{} anyway (without loading a font containing the glyph, which in
+% turn should ``hopefully'' set up the corresponding UTF-8 mapping).
+%
+% This works well enough for the main Western languages for which \LaTeX{}
+% has proper font encoding support, but currently already falls short on
+% languages like Greek (which has some semi-official font support, but for
+% which corresponding UTF-8 mappings still need to be defined).
+%
+% For some languages (such as Greek mentioned above) all that remains doing is
+% to provide the necessary mappings and stick them into |utf8ienc.dtx|, so
+% volunteers are welcome. For other languages that do not fit well into
+% \LaTeX{} font selection scheme, e.g., Asian languages the outlined inputenc
+% approach will not work. If that is the case one can try using Dominique
+% Unruh's option |utf8x| for inputenc which has a somewhat different approach
+% and encodes many more UTF-8 characters than the standard |utf8| option.
+% However, we recommend to do so only if you really need such alphabets as
+% there are problems with this extended approach which were precisely the
+% reason that we decided to limit the support to what is properly supported
+% within the boundaries of \LaTeX's font selection.
+%
+% If a UTF-8 mapping is missing and it is known to what \LaTeX{} definition it
+% should map to, one can manually define it using a |\DeclareUnicodeCharacter|
+% declaration. This declaration is available after inputenc has been loaded
+% with the |utf8| option.
+%
+% The |\DeclareUnicodeCharacter| takes UTF-8 code point as its first argument
+% (in form of a a hexadecimal number) and the definition that this maps to as
+% its second argument. For example, the code point |00E4| which is
+% ``LATIN SMALL LETTER A WITH DIAERESIS'' would be set up via:
+%\begin{verbatim}
+% \DeclareUnicodeCharacter{00E4}{\"a}
+%\end{verbatim}
+% Conceptually the second argument should only contain ``encoding-specific
+% commands'' as defined by \LaTeX{} font encoding concept, i.e., commands that
+% automatically change behavior if the font encoding changes (see chapter~7 of
+% the \LaTeX{} Companion for details).
+%
+% For details of the mappings per font encoding and some more technical
+% information see the file \texttt{utf8ienc.dtx} that provides UTF-8 support
+% using the \textsf{inputenc} package interface.
+%
+%
+%
+%
+% \subsection{Error messages}
+%
+% In certain situations the inputenc package generates one of the following
+% three error messages.
+%
+% \subsubsection{\normalfont\ttfamily Keyboard character used is undefined in
+% inputencoding `\meta{name}'}
+
+% The document contains an 8-bit character that is not defined by the
+% current input encoding in force. This means that either there is a
+% mismatch between the document encoding that the document claims it
+% is in (the option to inputenc) and the real encoding this document
+% is encoded in. These days more often you find that UTF-8 is used as
+% the encoding when saving a file in some text editor.
+%
+% Of course, it is also possible that the input encoding |.def| file is
+% defective and the offending code point is simply missing from that file.
+% Please check if the encoding file is one of the list above prior to
+% reporting an error---on the net there are many additional encoding files
+% supported by third parties.
+%
+%
+%
+% \subsubsection{\normalfont\ttfamily Cannot define Unicode char value < 00A0}
+%
+% This error message is shown if one tries to define a UTF-8 character
+% with a code point lower than |00A0|. Those cannot be defined in
+% \LaTeX{} through the |\DeclareUnicodeCharacter|.
+%
+%
+% \subsubsection{\normalfont\ttfamily Unicode char \meta{charcode} not set up
+% for use with LaTeX}
+%
+% This is the dreaded error message that one will receive if the
+% document contains an UTF-8 character that isn't known to \LaTeX{}.
+% It is quite possible that the character looks very unsuspicious and
+% is rendered perfectly in the editor.
+%
+% For example, when entering a Euro symbol from the keyboard one may receive
+% this error rather than a typeset symbol. But if this happens the reason is
+% simply that the document doesn't load a font containing the Euro symbol,
+% e.g., via the |textcomp| package. Thus \LaTeX{} does not know how to typeset
+% one and therefore responds with this error message.
+%
+% However, even if \LaTeX{} can type that character in question it may not
+% have been set up in which case you would need to do that yourself via
+% |\DeclareUnicodeCharacter|. If you provide these declarations for a full
+% font encoding then please contribute that work to this package so that
+% others can benefit too.
+%
+%
+%
+%
+
% \subsection{Programmers interface}
%
% To better support packages that manage their own character mappings and
@@ -282,9 +423,10 @@
%<ansinew> \ProvidesFile{ansinew.def}
%<cp1252&!ansinew> \ProvidesFile{cp1252.def}
%<cp1250> \ProvidesFile{cp1250.def}
- [2006/05/05 v1.1b Input encoding file]
+%<cp1257> \ProvidesFile{cp1257.def}
+ [2008/03/30 v1.1d Input encoding file]
%<cp850>%%
-%<cp850>%% If you need a euro symbol, try cp858 instead.
+%<cp850>%% If you need a Euro symbol, try cp858 instead.
%<cp850>%%
% \end{macrocode}
%
@@ -467,12 +609,14 @@
% \changes{v0.998}{2001/05/25}{Suppress all spaces for horizontal mode
% (pr/3273)}
% \changes{v1.0f}{2004/05/06}{Really do (pr/3273)}
+% \changes{v1.1d}{2007/08/06}{Set \cs{endlinechar} properly (pr/3926)}
% \begin{macrocode}
- \advance\endlinechar\@M
+ \xdef\saved@endlinechar@code{\the\endlinechar}%
+ \endlinechar\m@ne
\xdef\saved@space@catcode{\the\catcode`\ }%
\catcode`\ 9\relax
\input{#1.def}%
- \advance\endlinechar-\@M
+ \endlinechar\saved@endlinechar@code\relax
\catcode`\ \saved@space@catcode\relax
% \end{macrocode}
%
@@ -720,7 +864,7 @@
%
% The ASCII encoding only allows characters in the range 32--127, so
% we only need to provide a more or less empty |.def| file.
-% But we supress the warning that would normally appear if there are no
+% But we suppress the warning that would normally appear if there are no
% encoding definitions.
%
% \changes{v1.1b}{2006/03/03}{Suppress unnecessary warning (pr/3849)}
@@ -858,7 +1002,7 @@
%
% It can be used for general purpose applications in
% typical office environments in the following languages:
-% Afrikaans, Catalan, English, Esperanto, French, Gallician, German,
+% Afrikaans, Catalan, English, Esperanto, French, Galician, German,
% Italian, Maltese, and Turkish.
%
% \begin{macrocode}
@@ -976,7 +1120,7 @@
% (\texttt{hana.skoumalova@ff.cuni.cz}).
%
% It was created for Estonian, Latvian, Lithuanian, Finnish, Lappish,
-% Swedish, Norvegian, Danish, Icelandic and Greenlandic Inuit. Some
+% Swedish, Norwegian, Danish, Icelandic and Greenlandic Inuit. Some
% alphabets, however, are incomplete (Greenlandic, Icelandic and Lappish).
% Some glyphs are not available in the fonts. For example, the
% Greenlandic character `kra' is not available at all;
@@ -1769,7 +1913,7 @@
% Constantin Kahn (\texttt{kahn@\linebreak[0]math.toronto.edu}),
% with minor modifications by Alan Jeffrey.
%
-% \changes{v0.09c}{1995/05/30}{Made mac encoding `active german quote
+% \changes{v0.09c}{1995/05/30}{Made mac encoding `active German quote
% safe', and added the correct docstrip magic.}
%
% \begin{macrocode}
@@ -1914,8 +2058,8 @@
%</applemac>
% \end{macrocode}
%
-% This input encoding for the Apple Central European Codepage was
-% contributed by Radek Tryc and Marcin Wolinski
+% This input encoding for the Apple Central European code page was
+% contributed by Radek Tryc and Marcin Woli\'nski
% \verb=<wolinski@mimuw.edu.pl>=.
%
% \changes{v0.99b}{2002/06/16}{Added macce encoding (pr/3433)}
@@ -2184,7 +2328,7 @@
% Danish, Dutch, English, Finnish, French, German, Icelandic,
% Italian, Norwegian, Portuguese, Spanish, and Swedish.
%
-% Note: Windows ANSI --- like Macintosh standard roman encoding ---
+% Note: Windows ANSI --- like Macintosh standard Roman encoding ---
% has quotesingle at 39, and grave at 96 --- which is here
% ignored.
%
@@ -2200,7 +2344,7 @@
% been added and this could be the killer argument for many 8-bit
% texts to be written in Latin-9 in the future.
%
-% According to a Linux manpage, ISO~Latin-9 supports Albanian, Basque,
+% According to a Linux man page, ISO~Latin-9 supports Albanian, Basque,
% Breton, Catalan, Danish, Dutch,
% English, Estonian, Faroese, Finnish, French, Frisian, Galician, German,
% Greenlandic, Icelandic, Irish Gaelic, Italian, Latin, Luxemburgish,