% ======================================================================
% common-dictum-en.tex
% Copyright (c) Markus Kohm, 2001-2023
%
% 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-dictum-en.tex}
                 [$Date: 2023-04-20 10:04:17 +0200 (Do, 20. Apr 2023) $
                  KOMA-Script guide (common paragraphs)]
\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi\and
	Karl Hagen}

\section{Dicta}
\seclabel{dictum}%
\BeginIndexGroup
\BeginIndex{}{saying}%
\BeginIndex{}{dictum}%
\BeginIndex{}{epigraph}%

\IfThisCommonFirstRun{}{%
  The information in \autoref{sec:\ThisCommonFirstLabelBase.dictum} applies
  equally to this chapter. %
  \IfThisCommonLabelBase{scrextend}{%
    However, \Package{scrextend} does not support the commands
    \DescRef{maincls.cmd.setchapterpreamble} and
    \DescRef{maincls.cmd.setpartpreamble}.
	\iftrue% Umbruchvariante
	  Whether the class you are using offers an equivalent instruction
	  can be found in the documentation for the respective class .%
    \fi%
  }{}%
  So if you have already read and understood
  \autoref{sec:\ThisCommonFirstLabelBase.dictum}, you can skip ahead to
  \autoref{sec:\ThisCommonLabelBase.dictum.next},
  \autopageref{sec:\ThisCommonLabelBase.dictum.next}.%
}{}%

\IfThisCommonLabelBase{scrextend}{% Umbruchkorrekturvarianten
  A common element in a document is an epigraph or quotation that is set above
  or below a chapter or section heading, typically right-justified.  The
  epigraph and its source are usually specially formatted.%
}{%
  A common element in a document is an epigraph or quotation that is set above
  or below a chapter or section heading, along with a reference to the source
  and its own formatting.%
} %
\KOMAScript{} refers to such an epigraph as a \emph{dictum}.

\begin{Declaration}
  \Macro{dictum}\OParameter{author}\Parameter{text}%
  \Macro{dictumwidth}%
  \Macro{dictumauthorformat}\Parameter{author}%
  \Macro{dictumrule}%
  \Macro{raggeddictum}%
  \Macro{raggeddictumtext}%
  \Macro{raggeddictumauthor}
\end{Declaration}%
You can set such a saying with the help of the \Macro{dictum} command. %
\IfThisCommonLabelBase{maincls}{%
  This\textnote{Hint!} macro can be included in the mandatory argument of
  either the \DescRef{maincls.cmd.setchapterpreamble} or the
  \DescRef{maincls.cmd.setpartpreamble} command. However, this is not
  obligatory.\par%
}{}%
The dictum, along with an optional \PName{author}, is inserted in a
\Macro{parbox}\IndexCmd{parbox} (see \cite{latex:usrguide}) of width
\Macro{dictumwidth}. However, \Macro{dictumwidth} is not a length which can be
set with \Macro{setlength}. It is a macro that can be redefined using
\Macro{renewcommand}. The default is \PValue{0.3333\Length{textwidth}}, which
is one third of the text width. The box itself is aligned with the command
\Macro{raggeddictum}. The default is \Macro{raggedleft}\IndexCmd{raggedleft},
that is, right justified. \Macro{raggeddictum} can be redefined
with \IfThisCommonLabelBase{scrextend}{% Umbruchoptimierung
}{the help of }\Macro{renewcommand}.

You can align the \PName{dictum} within the box using
\Macro{raggeddictumtext}\important{\Macro{raggeddictumtext}}.
The default is \Macro{raggedright}\IndexCmd{raggedright}, that is, left
justified. You can also redefine this macro with \Macro{renewcommand}.%
\BeginIndexGroup
\BeginIndex{FontElement}{dictum}\LabelFontElement{dictum}%
\LabelFontElement{dictumtext}%
The output uses the default font setting for the element
\FontElement{dictum}\important{\FontElement{dictum}}, which can be changed
with the commands \DescRef{\ThisCommonLabelBase.cmd.setkomafont} and
\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} (see
\autoref{sec:\ThisCommonLabelBase.textmarkup},
\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}). Default settings are
listed in \autoref{tab:maincls.dictumfont}%
\IfThisCommonFirstRun{.%
  \begin{table}
%  \centering%
    \KOMAoptions{captions=topbeside}%
    \setcapindent{0pt}%
%  \caption
    \begin{captionbeside}{Default settings for the elements of a dictum}
      [l]
      \begin{tabular}[t]{ll}
        \toprule
        Element & Default \\
        \midrule
        \IfThisCommonLabelBase{maincls}{%
          \ChangedAt{v3.39}{\Class{scrbook}\and \Class{scrreprt}\and
            \Class{scrartcl}}%
        }{%
          \IfThisCommonLabelBase{scrextend}{%
            \ChangedAt{v3.39}{\Package{screxend}}%
          }{%
            \IfThisCommonLabelBase{scrlttr2}{%
              \ChangedAt{v3.39}{\Class{scrlttr2}}%
            }{}%
          }%
        }%
        \DescRef{\LabelBase.fontelement.dictum}
                & \Macro{normalfont}\Macro{normalcolor}%
                  \DescRef{\LabelBase.cmd.maybesffamily}\IndexCmd{maybesffamily}%
                  \Macro{small}\\
        \DescRef{\LabelBase.fontelement.dictumauthor} &
          \Macro{itshape}\\
        \bottomrule
      \end{tabular}
    \end{captionbeside}
    \label{tab:\ThisCommonLabelBase.dictumfont}
  \end{table}
}{%
  , \autopageref{tab:\ThisCommonFirstLabelBase.dictumfont}.%
}
\EndIndexGroup

If an \PName{author} is defined, it is separated from the \PName{dictum} by
a horizontal rule spanning the full width of the \Macro{parbox}. This%
\IfThisCommonLabelBase{maincls}{%
  \ChangedAt{v3.10}{\Class{scrbook}\and \Class{scrreprt}\and
    \Class{scrartcl}}%
}{%
  \IfThisCommonLabelBase{scrextend}{%
    \ChangedAt{v3.10}{\Package{scrextend}}%
  }{\InternalCommonFileUsageError}%
} %
rule is defined in \Macro{dictumrule}\important{\Macro{dictumrule}} as a
vertical object with
\begin{lstcode}
  \newcommand*{\dictumrule}{\vskip-1ex\hrulefill\par}
\end{lstcode}

The \Macro{raggeddictumauthor}\important{\Macro{raggeddictumauthor}} command
defines the alignment for the rule and the \PName{author}. The default is
\Macro{raggedleft}. This command can also be redefined using
\Macro{renewcommand}. The format is defined with
\Macro{dictumauthorformat}\important{\Macro{dictumauthorformat}}. This macro
expects the \PName{author} text as its argument. By default
\Macro{dictumauthorformat} is defined as
\begin{lstcode}
  \newcommand*{\dictumauthorformat}[1]{(#1)}
\end{lstcode}
Thus the \PName{author} is set enclosed in rounded parentheses.
\BeginIndexGroup
\BeginIndex{FontElement}{dictumauthor}\LabelFontElement{dictumauthor}%
For the \FontElement{dictumauthor}\important{\FontElement{dictumauthor}}
element, you can define a different font than that used for the
\DescRef{\LabelBase.fontelement.dictum} element. The default settings are
listed in \autoref{tab:maincls.dictumfont}. Changes can be made using the
\DescRef{\ThisCommonLabelBase.cmd.setkomafont} and
\DescRef{\ThisCommonLabelBase.cmd.addtokomafont} commands (see
\autoref{sec:\ThisCommonLabelBase.textmarkup},
\DescPageRef{\ThisCommonLabelBase.cmd.setkomafont}).%
\EndIndexGroup

\IfThisCommonLabelBase{maincls}{%
  If you use \Macro{dictum} within the
  \DescRef{maincls.cmd.setchapterpreamble} or
  \DescRef{maincls.cmd.setpartpreamble} macro, \Length{textwidth} is not the
  width of the whole text body but the current text width. If
  \Macro{dictumwidth} is set to \PValue{.5\Length{textwidth}} and
  \DescRef{maincls.cmd.setchapterpreamble} has an optional width of
  \PValue{.5\Length{textwidth}} too, you will get a box with a width one
  quarter of the text width.  The horizontal positioning of the dictum inside
  the box is always done with \Macro{raggeddictum}. The optional argument for
  horizontal positioning which is implemented for these two commands has no
  effect to the \Macro{text}.  If you use \Macro{dictum} you should
  refrain from setting the optional width for
  \DescRef{maincls.cmd.setchapterpreamble} or
  \DescRef{maincls.cmd.setpartpreamble}.

  If\textnote{Hint!} you have more than one dictum, one under another, you
  should separate them by an additional vertical space, which is easily
  accomplished using the \Macro{bigskip}\IndexCmd{bigskip} command.%
  \iftrue%
}{\csname iffalse\endcsname}

 \begin{Example}
   You are writing a chapter about modern marriage, and you want to place a
   dictum in the preamble to the chapter heading. You write:
\begin{lstcode}
  \setchapterpreamble[u]{%
    \dictum[Schiller]{So pause ye who would link your fates~\dots}}
  \chapter{Modern Marriage}
\end{lstcode}
  The output would look as follows:
  \begin{ShowOutput}
    {\usekomafont{disposition}\usekomafont{chapter}%
      17\enskip Modern Marriage\par} \vspace{\baselineskip}
    \dictum[Schiller]{So pause ye who would link 
      your fates~\dots}
  \end{ShowOutput}
	
  If you want the dictum to span only a quarter of the text width
  rather than a third, you can redefine \Macro{dictumwidth} this way:
\begin{lstcode}
  \renewcommand*{\dictumwidth}{.25\textwidth}
\end{lstcode}
\end{Example}

\IfThisCommonLabelBase{maincls}{}{% Umbruchkorrekturtext
  At this point, note the \Package{ragged2e}\important{\Package{ragged2e}}%
  \IndexPackage{ragged2e} package, with which you can produce unjustified text
  that uses hyphenation (see \cite{package:ragged2e}).%
}%
\fi
%
\EndIndexGroup
%
\EndIndexGroup

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