% ======================================================================
% common-compatibility-en.tex
% Copyright (c) Markus Kohm, 2001-2022
%
% This file is part of the LaTeX2e KOMA-Script bundle.
%
% This work may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, version 1.3c of the license.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX 
% version 2005/12/01 or later and of this work.
%
% This work has the LPPL maintenance status "author-maintained".
%
% The Current Maintainer and author of this work is Markus Kohm.
%
% This work consists of all files listed in MANIFEST.md.
% ======================================================================
%
% Paragraphs that are common for several chapters of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ======================================================================

\KOMAProvidesFile{common-compatibility-en.tex}
                 [$Date: 2022-06-05 12:40:11 +0200 (So, 05. Jun 2022) $
                  KOMA-Script guide (common paragraphs)]
\translator{Markus Kohm\and Krickette Murabayashi\and Karl Hagen}

\section{Compatibility with Earlier Versions of \KOMAScript}
\seclabel{compatibilityOptions}
\BeginIndexGroup
\BeginIndex{}{Compatibility}

\IfThisCommonFirstRun{}{%
  The information in
  \autoref{sec:\ThisCommonFirstLabelBase.compatibilityOptions} applies equally
  to this chapter.
  \IfThisCommonLabelBase{scrlttr2}{However, this feature has existed in
    \Class{scrlttr2} since version~2.9t, whereas \Package{scrletter} does not
    offer it. }{}%
  So if you have already read and understood
  \autoref{sec:\ThisCommonFirstLabelBase.compatibilityOptions} you can skip
  ahead to \autopageref{sec:\ThisCommonLabelBase.compatibilityOptions.next},
  \autopageref{sec:\ThisCommonLabelBase.compatibilityOptions.next}.%
}

\IfThisCommonLabelBaseOneOf{typearea,maincls,scrlttr2}{%
  Those who produce their documents from source code typically attach the
  utmost importance to the fact that future \LaTeX{} runs will yield exactly
  the same result. In some cases, however, improvements and bug fixes to the
  \IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{class}{package} will
  result in changes of behaviour, especially to the layout. This, however,
  may be undesirable.%
}{%
  \IfThisCommonLabelBase{scrextend}{%
  % In some cases, improvements and bug fixes to the package will result
  % in changes of behaviour, especially to the layout. This, however,
  % may be undesirable. Those who produce their documents from source code
  % typically attach the utmost importance to the fact that future 
  % \LaTeX{} runs will yield exactly the same result.%
  }{%
  \ThisCommonLabelBaseFailure
  % \IfThisCommonLabelBase{scrlttr2}{%
  % In some cases, improvements and bug fixes to the package will result
  % in changes of behaviour, especially to the layout. This, however,
  % may be undesirable.
  % }{}%
  }%
}%


\begin{Declaration}
  \OptionVName{version}{value}%
  \OptionValue{version}{first}%
  \OptionValue{version}{last}
\end{Declaration}
%\ChangedAt{v2.96a}{\Class{scrbook}\and \Class{scrreprt}\and \Class{scrartcl}}%
%\ChangedAt{v2.9t}{\Class{scrlttr2}}%
%\ChangedAt{v3.01b}{\Package{typearea}}%
\IfThisCommonLabelBase{scrextend}{With \Package{scrextend}, you can}{Since
  \IfThisCommonLabelBase{typearea}{%
    Version~3.01b, \Package{typearea}\ChangedAt{v3.01b}{\Package{typearea}}}{%
    \IfThisCommonLabelBase{maincls}{%
      Version~2.96a, \KOMAScript{}\ChangedAt{v2.96a}{\Class{scrbook}\and
        \Class{scrreprt}\and \Class{scrartcl}}}{%
      \IfThisCommonLabelBase{scrlttr2}{%
        Version~2.9t, \Class{scrlttr2}\OnlyAt{\Class{scrlttr2}}%
        \ChangedAt{v2.9t}{\Class{scrlttr2}}}{%
        \InteralCommonFileUsageError}%
    }%
  }%
\ has been able to} %
choose whether the source file should, as much as possible, 
continue to produce exactly the same result within a \LaTeX{} run or should
be formatted according to the modifications of the latest version%
\IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{ of the class}{}. You
can specify the version with which you want your file to be compatible by
using the \Option{version} option. Compatibility with the oldest supported
\KOMAScript{} version can be achieved with
\OptionValue{version}{first}\important{\OptionValue{version}{first}} or
\OptionValue{version}{2.9} or \OptionValue{version}{2.9t}. Setting
\PName{value} to an unknown release number will result in a warning message
and selects \OptionValue{version}{first} for safety.

With \OptionValue{version}{last}\important{\OptionValue{version}{last}}%
\textnote{default}, you can select the latest version. In this case, you give
up backwards compatibility. If the option is used without a value,
\PValue{last} is assumed. This\ChangedAt{v3.01a}{\Class{scrbook}\and
  \Class{scrreprt}\and \Class{scrartcl}\and \Class{scrlttr2}\and
  \Package{scrextend}} also corresponds to the default setting, as long as you
do not use any deprecated options.

\IfThisCommonLabelBase{scrextend}{% scrextend doesn't recognize obsolete options
}{%
  If\textnote{Attention!} you use a deprecated option of \KOMAScript~2,
  \KOMAScript~3 will switch to \OptionValue{version}{first} automatically.
  This will also result in a warning message that explains how to prevent
  this switch. Alternatively, you can choose a different setting for
  \Option{version} with the desired compatibility after the deprecated
  option.%
}

Compatibility is primarily a question of line and page breaks (wrapping). If
you choose compatibility with an older version, new options that do not affect
wrapping are still available. The \Option{version} option does not affect any
wrapping changes that are the result of fixing unambiguous errors.
If\textnote{Hint!} you need unconditional wrapping compatibility even in the
case of bugs, you should physically save the old \KOMAScript{} version you
need together with your document.

\IfThisCommonLabelBase{scrlttr2}{%
  \begin{Example}
    The example letters in this chapter should use all the features of the
	latest version of \KOMAScript{}. For this, the we set the compatibility
	correspondingly when loading the class:%
    \lstinputcode[xleftmargin=1em,lastline=1]{letter-example-00-en.tex}%
    In this case the symbolic value \PValue{last} has been used to select the
    latest version.%
    \iftrue% Umbruchkorrektur
    Here, the latest version was simply chosen with the symbolic value
    \PValue{last}.%
    \else%
    In order not to have to specify a new version number for each new version,
    the symbolic value \PValue{last} was chosen here.%
    \fi
  \end{Example}}{}

Note\textnote{Attention!} that you cannot change the \Option{version} option
after loading the %
\IfThisCommonLabelBaseOneOf{maincls,scrlttr2}{class}{%
  \IfThisCommonLabelBase{typearea}{\Package{typearea}}{%
	\IfThisCommonLabelBase{scrextend}{\Package{scrextend}}{%
      \InternalCommonFileUsageError }%
  }%
\ package}. Setting this option with
\DescRef{\ThisCommonLabelBase.cmd.KOMAoptions} or
\DescRef{\ThisCommonLabelBase.cmd.KOMAoption} will
therefore cause an error.%
\EndIndexGroup
%
\EndIndexGroup

\phantomsection
\label{sec:\ThisCommonLabelBase.compatibilityOptions.end}
\endinput

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "scrguide-en.tex"
%%% coding: utf-8
%%% ispell-local-dictionary: "en_GB"
%%% eval: (flyspell-mode 1)
%%% End: