% ======================================================================
% common-dictum.tex
% Copyright (c) Markus Kohm, 2001-2017
%
% 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.txt.
% ----------------------------------------------------------------------
% common-dictum.tex
% Copyright (c) Markus Kohm, 2001-2017
%
% Dieses Werk darf nach den Bedingungen der LaTeX Project Public Lizenz,
% Version 1.3c, verteilt und/oder veraendert werden.
% Die neuste Version dieser Lizenz ist
%   http://www.latex-project.org/lppl.txt
% und Version 1.3c ist Teil aller Verteilungen von LaTeX
% Version 2005/12/01 oder spaeter und dieses Werks.
%
% Dieses Werk hat den LPPL-Verwaltungs-Status "author-maintained"
% (allein durch den Autor verwaltet).
%
% Der Aktuelle Verwalter und Autor dieses Werkes ist Markus Kohm.
% 
% Dieses Werk besteht aus den in manifest.txt aufgefuehrten Dateien.
% ======================================================================
%
% Paragraphs that are common for several chapters of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ----------------------------------------------------------------------
%
% Absaetze, die mehreren Kapiteln der KOMA-Script-Anleitung gemeinsam sind
% Verwaltet von Markus Kohm
%
% ======================================================================

\KOMAProvidesFile{common-dictum.tex}
                 [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $
                  KOMA-Script guide (common paragraphs)]
\translator{Gernot Hassenpflug\and Markus Kohm\and Krickette Murabayashi}

% Date of the translated German file: 2017-01-02

\section{Dicta}
\seclabel{dictum}%
\BeginIndexGroup
\BeginIndex{}{smart slogan}%
\BeginIndex{}{dictum}%
\BeginIndex{}{excerpt}%

\IfThisCommonFirstRun{}{%
  What is written in \autoref{sec:\ThisCommonFirstLabelBase.dictum} applies,
  mutatis mutandis. %
  \IfThisCommonLabelBase{scrextend}{%
    However, \Package{scrextend} does not support the commands
    \DescRef{maincls.cmd.setchapterpreamble} and
    \DescRef{maincls.cmd.setpartpreamble}. You should read the manual of the
    used class, if you want to know, if that class does support similar
    commands. %
  }{}%
  So if you have alread read and understood
  \autoref{sec:\ThisCommonFirstLabelBase.dictum} you can jump to
  \autoref{sec:\ThisCommonLabelBase.dictum.next} on
  \autopageref{sec:\ThisCommonLabelBase.dictum.next}.%
}

Sometimes you may find a dictum, a kind of smart slogan or excerpt, often
ragged left above or below the heading of a chapter or section. The text and
the source of the slogan often use special styles.


\begin{Declaration}
  \Macro{dictum}\OParameter{author}\Parameter{dictum}%
  \Macro{dictumwidth}%
  \Macro{dictumauthorformat}\Parameter{author}%
  \Macro{dictumrule}%
  \Macro{raggeddictum}%
  \Macro{raggeddictumtext}%
  \Macro{raggeddictumauthor}
\end{Declaration}%
The command \Macro{dictum} inserts such a dictum. %
\IfThisCommonLabelBase{maincls}{%
  This\textnote{Hint!} macro can be used as obligatory argument of either the
  command \DescRef{maincls.cmd.setchapterpreamble} or
  \DescRef{maincls.cmd.setpartpreamble}. However, this is not obligatory.\par%
}{}%
The dictum together with an optional \PName{author} is inserted in a
\Macro{parbox}\IndexCmd{parbox} (see \cite{latex:usrguide}) of width
\Macro{dictumwidth}. Yet \Macro{dictumwidth} is not a length which can be set
with \Macro{setlength}. It is a macro that can be redefined using
\Macro{renewcommand}. Default setting is \PValue{0.3333\Length{textwidth}},
which is a third of the textwidth. The box itself is positioned with the
command \Macro{raggeddictum}. Default here is
\Macro{raggedleft}\IndexCmd{raggedleft}, that is, right justified.  The
command \Macro{raggeddictum} can be redefined using \Macro{renewcommand}.

\BeginIndexGroup
\BeginIndex{FontElement}{dictum}\LabelFontElement{dictum}%
Within the box the \PName{dictum} is set using \Macro{raggeddictumtext}.
Default setting is \Macro{raggedright}\IndexCmd{raggedright}, that is, left
justified. Similarly to \Macro{raggeddictum} this can be redefined with
\Macro{renewcommand}.  The output uses the default font setting for the
element \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
        \DescRef{\LabelBase.fontelement.dictum} &
          \Macro{normalfont}\Macro{normalcolor}\Macro{sffamily}\Macro{small}\\
        \DescRef{\LabelBase.fontelement.dictumauthor} &
          \Macro{itshape}\\
        \bottomrule
      \end{tabular}
    \end{captionbeside}
    \label{tab:\ThisCommonLabelBase.dictumfont}
  \end{table}
}{%
  , \autopageref{tab:\ThisCommonFirstLabelBase.dictumfont}.%
}

If there is an \PName{author} name, it is separated from the \PName{dictum} by
a rule to 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 as vertical object to command \Macro{dictumrule}:
\begin{lstcode}
  \newcommand*{\dictumrule}{\vskip-1ex\hrulefill\par}
\end{lstcode}

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

\IfThisCommonLabelBase{maincls}{%
  If \Macro{dictum} is used within the macro
  \DescRef{maincls.cmd.setchapterpreamble} or
  \DescRef{maincls.cmd.setpartpreamble} you have to take care of the
  following: the horizontal positioning is always done with
  \Macro{raggeddictum}.  Therefore, the optional argument for horizontal
  positioning which is implemented for these two commands has no
  effect. \Length{textwidth} is not the width of the whole text corpus but the
  actually used 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.  Therefore, if you use
  \Macro{dictum} it is recommended to 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, easily accomplished
  using the command \Macro{bigskip}\IndexCmd{bigskip}.%
  \iftrue%
}{\csname iffalse\endcsname}

  \begin{Example}
    You are writing a chapter on an aspect of weather forecasting. You
    have come across an aphorism which you would like to place at the
    beginning of the chapter beneath the heading. You could write:
\begin{lstcode}
  \setchapterpreamble[u]{%
    \dictum[Anonymous]{Forecasting is the art of saying
            what is going to happen and then to explain
            why it didn't.}}
  \chapter{Weather forecasting}
\end{lstcode}
    The output would look as follows:
    \begin{ShowOutput}
      {\usekomafont{disposition}\usekomafont{chapter}%
        17\enskip Weather forecasting\par} \vspace{\baselineskip}
      \dictum[Anonymous]{Forecasting is the art of saying what is going to
        happen and then to explain why it didn't.}
    \end{ShowOutput}

    If you would rather the dictum span only a quarter of the text width
    rather than one third you can redefine \Macro{dictumwidth}:
\begin{lstcode}
  \renewcommand*{\dictumwidth}{.25\textwidth}
\end{lstcode}
  \end{Example}

  For a somewhat more sophisticated formatting of left- or right-aligned
  paragraphs including hyphenation you can use the
  package~\Package{ragged2e}~\cite{package:ragged2e}.%
\fi
%
\EndIndexGroup
%
\EndIndexGroup

%%% Local Variables:
%%% mode: latex
%%% coding: us-ascii
%%% TeX-master: "../guide"
%%% End:
