% ======================================================================
% scrjura.tex
% Copyright (c) Markus Kohm, 2011-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.
% ----------------------------------------------------------------------
% scrjura.tex
% Copyright (c) Markus Kohm, 2011-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.
% ======================================================================
%
% Chapter about scrjura of the KOMA-Script guide
% Maintained by Markus Kohm
%
% ----------------------------------------------------------------------
%
% Kapitel ueber scrjura in der KOMA-Script-Anleitung
% Verwaltet von Markus Kohm
%
% ======================================================================

\KOMAProvidesFile{scrjura.tex}%
                 [$Date: 2017-01-02 13:30:07 +0100 (Mon, 02 Jan 2017) $
                  KOMA-Script guide (chapter: scrjura)]

\translator{Alexander Willand\and Markus Kohm}

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

\chapter{Support for the Law Office by \Package{scrjura}}
\labelbase{scrjura}
\BeginIndexGroup
\BeginIndex{Package}{scrjura}

In case you'd like to write a contract\Index{contract}, the bylaws of a
company or of the club, an act of law or a whole commentary, the package
\Package{scrjura} will provide typographical support. Despite the fact that
\Package{scrjura} is intended as a broad help for juridical documents, the
contract is the central element of the package. Particular attention is being
paid to the clause with numbered title and numbered paragraphs\,---\,if
a clause consists of more than one paragraph\,---, even numbered sentences,
entries in the table of contents and cross references according to German
standards.

The package has been developed in cooperation with Dr Alexander Willand, 
lawyer in Karlsruhe.

Note\textnote{Attention!} that the package cooperates with
\Package{hyperref}\IndexPackage{hyperref}. Nevertheless, \Package{hyperref}
has to be loaded after \Package{scrjura} as usual.

\LoadCommonFile{options}% \section{Early or late Selection of Options}

\LoadCommonFile{textmarkup}% \section{Text Markup}

\section{Table of Contents}
\label{sec:scrjura.toc}

The package \Package{scrjura} provides entries into the table of contents.

\begin{Declaration}
  \OptionVName{juratotoc}{simple switch}%
  \OptionVName{juratotoc}{level number}
\end{Declaration}
A clause\Index{clause} is being shown in the table of contents only, if its
\PName{level number} is smaller or equal to the counter
\DescRef{maincls.counter.tocdepth}%
\important{\DescRef{maincls.counter.tocdepth}}\IndexCounter{tocdepth} (see
\autoref{sec:maincls.toc}, \DescPageRef{maincls.counter.tocdepth}). Default
for the \PName{level number} is 10000, which as well will be used, if the
option is switched off by the \PName{simple
  switch}\important{\OptionValue{juratotoc}{false}} (see
\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}). Because the
counter \DescRef{maincls.counter.tocdepth} usually has a one digit value,
clause entries are not shown in the table of contents.

If you switch on the option using the \PName{simple
  switch}\important{\OptionValue{juratotoc}{true}}, as a default \PName{level
  number} 2 is used, so that clauses are shown in the table of contents on the
same level as subsections. If the counter \DescRef{maincls.counter.tocdepth}
has default values as well, clauses are shown with all \KOMAScript{} classes.%
\EndIndexGroup


\begin{Declaration}
  \OptionVName{juratocindent}{indent}%
  \OptionVName{juratocnumberwidth}{number width}
\end{Declaration}
These two options can be used to determine the indentation in the table of 
contents as well as the reserved space for the numbers there. Defaults are the 
values for the subsection entries in \Class{scrartcl}.%
\EndIndexGroup


\section{Environment for Contracts}
\label{sec:scrjura.contract}

\BeginIndexGroup
\BeginIndex{}{contract}
The main mechanism of \Package{scrjura} only work inside of the contract
environment.

\begin{Declaration}
  \begin{Environment}{contract}\end{Environment}
\end{Declaration}
Till this date, this is the one and only environment for legal practitioner
provided by \Package{scrjura}. Using it will activate the automatic numbering
of paragraphs and the commands \DescRef{\LabelBase.cmd.Clause} and
\DescRef{\LabelBase.cmd.SubClause} will become a form, which will be
documented below.

The\textnote{Attention!} environment \DescRef{\LabelBase.env.contract} must
not be nested in itself. Within the document the environment may be used
several times. In this case the clauses within the environment are treated as
if they were within the same environment. Ending the environment means just a
break and with beginning a new environment in the same document the former
environment is continued. A break inside a clause is not possible.%
\EndIndexGroup


\begin{Declaration}
  \Option{contract}
\end{Declaration}
The whole document becomes a contract if you use this option while loading the
package with \DescRef{\LabelBase.cmd.usepackage}%
\important{\DescRef{\LabelBase.cmd.usepackage}} or as a global option with
\DescRef{\LabelBase.cmd.documentclass}%
\important{\DescRef{\LabelBase.cmd.documentclass}}.  The document behaves as
if you started the contract environment right after the beginning of the
document.

Neither\textnote{Attention!} you can use this option with
\DescRef{\LabelBase.cmd.KOMAoption} nor with
\DescRef{\LabelBase.cmd.KOMAoptions}, so that it is not possible to switch the
option off in this way. Please use the \DescRef{\LabelBase.env.contract}
environment directly.%
\EndIndexGroup


\subsection{Clauses}
\label{sec:scrjura.clause}
\index{section|seealso{clause}}

With \Package{scrjura} clauses\footnote{%
  In English, the word ``section'' also is used in an act of law or in an
  agreement. To distinguish \DescRef{maincls.cmd.section} of most document
  classes from the section in \Package{scrjura}, we decided to call the
  section in the latter simply ``clause''.} in a legal sense only exist inside
of contracts, meaning inside of the environment
\DescRef{\LabelBase.env.contract}.

\begin{Declaration}
  \Macro{Clause}\OParameter{options}%
  \Macro{SubClause}\OParameter{options}
\end{Declaration}
These are the most important commands inside of a contract. Without using
further \PName{options} the command \Macro{Clause} creates the heading of a
clause, which consists only of the sign »\S«, followed by its number. In
contrast to this the command \Macro{SubClause} creates the heading of a clause
with the last number used by \Macro{Clause} and adds a lowercase
letter. \Macro{SubClause} mainly is intended for cases where an act or a
contract is amended and not only clauses are changed or deleted, but between
existing clauses new ones are inserted without changing the numbering.

Both commands except as \PName{options} a list separated by commas of
properties. An overview over possible properties is provided by
\autoref{tab:scrjura.Clause.options}. For the most important of them we will
go into the details.

\begin{table}
  \caption{Possible properties for the optional argument of \Macro{Clause} and
    \Macro{SubClause}}
  \label{tab:scrjura.Clause.options}
  \begin{desctabular}
    \entry{\Option{dummy}}{%
      The heading will not be printed but counted in the automatic numbering.%
    }%
    \entry{\OptionVName{head}{running head}}{%
      If running heads are available, \PName{running head} is used instead of
      the clause \PName{title}.%
    }%
    \entry{\Option{nohead}}{%
      The running head stays unchanged.%
    }%
    \entry{\Option{notocentry}}{%
      Does not make an entry into the table of contents.%
    }%
    \entry{\OptionVName{number}{number}}{%
      Uses \PName{number} for the output of the clause number.%
    }%
    \entry{\OptionVName{preskip}{skip}}{%
      Changes the vertical \PName{skip} before the clause heading.%
    }%
    \entry{\OptionVName{postskip}{skip}}{%
      Changes the vertical \PName{skip} after the clause heading.%
    }%
    \entry{\OptionVName{title}{title}}{%
      Additional to the clause number a clause \PName{title} will be printed.
      This is also used as default for the \PName{running head} and the
      \PName{entry} in the table of contents.%
    }%
    \entry{\OptionVName{tocentry}{entry}}{%
      Independent from the clause \PName{title}, an \PName{entry} into the
      table of contents will be made, if such entries are activated.%
    }%
  \end{desctabular} 
\end{table}

A skip of two lines is inserted before the heading and afterwards a skip of
one line as a default. Via the options
\Option{preskip}\important[i]{\Option{preskip}, \Option{postskip}} and
\Option{postskip} these skips can be changed. The new values are not only
valid for the current clause but beginning with the actual clause until the
end of the current contract environment. It is possible as well to set these
keys in advance by writing
\begin{flushleft}\quad\small
  \textbf{\Macro{setkeys}}\PParameter{contract}%
  \PParameter{preskip=\PName{skip},\\
    \normalsize\quad\small
    \hspace{11.5em}postskip=\PName{skip}}
\end{flushleft}
independently from a clause and outside of a contract environment as well.
Also it is possible to set the keys inside of the preamble after loading
\Package{scrjura}. But it is not possible to set these options while loading
the package or by using \DescRef{\LabelBase.cmd.KOMAoptions} or
\DescRef{\LabelBase.cmd.KOMAoption}.

\BeginIndex{FontElement}{contract.Clause}\LabelFontElement{contract.Clause}%
\BeginIndex{FontElement}{Clause}\LabelFontElement{Clause}%
The headings use as a default the fonts
\Macro{sffamily}\Macro{bfseries}\Macro{large}. The fonts can be changed using
the element
\FontElement{contract.Clause}\important{\FontElement{contract.Clause}} with
the help of \DescRef{\LabelBase.cmd.setkomafont}%
\important[i]{\DescRef{\LabelBase.cmd.setkomafont},
  \DescRef{\LabelBase.cmd.addtokomafont}} and
\DescRef{\LabelBase.cmd.addtokomafont} (see \autoref{sec:maincls.textmarkup},
\DescPageRef{\LabelBase.cmd.setkomafont}). Inside the
\DescRef{\LabelBase.env.contract} environment instead of
\FontElement{contract.Clause} simply
\FontElement{Clause}\important{\FontElement{Clause}} may be used.%
\EndIndex{FontElement}{Clause}%
\EndIndex{FontElement}{contract.Clause}

With the options \Option{title}\important[i]{\Option{title}, \Option{head},
  \Option{tocentry}}, \Option{head}, and \Option{tocentry} a clause may get in
addition to the number a title. It\textnote{Attention!} is recommended to put
the value of these options inside brackets. Failing this, e.g., commas may
lead to confusion between different options. Empty values for \Option{head}
and \Option{tocentry} cause an empty entry. If one would like to avoid an
entry, the options \Option{nohead}\important[i]{\Option{nohead},
  \Option{notocentry}} and \Option{notocentry} have to be used.

Instead of the running numbers the option
\Option{number}\important{\Option{number}} manually sets the number of a
clause. This will have no impact on the numbers of the subsequent clauses.
Empty numbers are not possible. Fragile commands inside \PName{number} have to
be protected with \Macro{protect}. It\textnote{Attention!} is recommended only
to use numbers and letters as assignment to \Option{number}.

With the option \Option{dummy}\important{\Option{dummy}} the output of the
whole heading of a clause can be suppressed. The automatic numbering will
count this clause nonetheless. Thus you can skip a clause in the automatic
numbering with\textnote{Example} 
\begin{lstcode}
  \Clause{dummy}
\end{lstcode}
in case the clause has been deleted in a later version of a contract.

Note\textnote{Attention!}, only the values \PValue{true} and \PValue{false}
may be used in combination with \Option{dummy}. All other values will be
ignored, but may throw up an error.%
\EndIndexGroup


\begin{Declaration}
  \Macro{Clauseformat}\Parameter{number}
\end{Declaration}
As already mentioned the clauses and subclauses usually are being numbered.
The format of the number is done with the help of the command
\Macro{Clauseformat}, which expects as one and only argument the number. The
default is defined as
\begin{lstcode}
  \newcommand*{\Clauseformat}[1]{\S~#1}
\end{lstcode}
and, as you see, it is only the \Macro{S}\IndexCmd{S} followed by a
non-breaking space and the number. In case of redefinition take care to keep
it expandable.%
\EndIndexGroup


\begin{Declaration}
  \OptionVName{juratitlepagebreak}{simple switch}
\end{Declaration}%
Usually a page break inside a heading is prohibited. Some jurists may need 
page breaks inside of clause headings. Such a break may be allowed using 
\Option{juratitlepagebreak}\important{\Option{juratitlepagebreak}}. The
possible values for \PName{simple switch} are printed in
\autoref{tab:truefalseswitch}, \autopageref{tab:truefalseswitch}.%
\EndIndexGroup
  
\begin{Declaration}
  \OptionVName{clausemark}{value}
\end{Declaration}%
Clauses are a kind of inferior structure with an independent numbering
they will not have running headlines as a default. Running headlines
are possible and may be created with alternative properties. The
possible \PName{values} and their meaning are listed in 
\autoref{tab:scrjura.clausemark}.%
%
\begin{table}
  \caption{Possible values for option \Option{clausemark} for activation of
    running heads}%
  \label{tab:scrjura.clausemark}%
  \begin{desctabular}
    \entry{\PValue{both}}{%
      Clauses generate left and right marks for running heads, if the document
      provides automatic running heads.%
      \IndexOption{clausemark~=\PValue{both}}%
    }%
    \entry{\PValue{false}, \PValue{off}, \PValue{no}}{%
      Clauses do not generate marks for running heads and therefore do not
      change running heads.%
      \IndexOption{clausemark~=\PValue{false}}%
    }%
    \entry{\PValue{forceboth}}{%
      Clauses use \DescRef{maincls.cmd.markboth} to generate left and right
      marks for running heads even if the document does not provide automatic
      running heads for the current page style.%
      \IndexOption{clausemark~=\PValue{forceboth}}%
    }%
    \entry{\PValue{forceright}}{%
      Clauses use \DescRef{maincls.cmd.markright} to generate right marks for
      running heads even if the document does not provide automatic running
      heads for the current page style.%
      \IndexOption{clausemark~=\PValue{forceright}}%
    }%
    \entry{\PValue{right}}{%
      Clauses generate right marks for running heads, if the document provides
      automatic running heads.%
      \IndexOption{clausemark~=\PValue{right}}%
    }%
  \end{desctabular}
\end{table}
%
\EndIndexGroup


\subsection{Paragraphs}
\label{sec:scrjura.par}

\BeginIndexGroup
\BeginIndex{}{paragraph>number}%
Within clauses the paragraphs are being numbered automatically. With this, the
paragraphs are a strongly structuring element, similar to
\DescRef{maincls.cmd.paragraph} or \DescRef{maincls.cmd.subparagraph} known,
e.\,g., from article classes. Contracts usually use a vertical skip between
paragraphs. The package \Package{scrjura} does not provide its own mechanism
for this. Instead, it uses the option \DescRef{maincls.option.parskip}%
\IndexOption{parskip}\important{\DescRef{maincls.option.parskip}} of the
\KOMAScript{} classes (see \autoref{sec:maincls.parmarkup},
\DescPageRef{maincls.option.parskip}).


\begin{Declaration}
  \OptionVName{parnumber}{value}
\end{Declaration}
The default numbering of paragraphs is \OptionValue{parnumber}{auto} and
\OptionValue{parnumber}{true}. Once in a while it might be necessary to switch
off the automatic numbering. This is done with \OptionValue{parnumber}{false}%
\important{\OptionValue{parnumber}{false}}%
\IndexOption{parnumber~=\PValue{false}}. In this case the numbering of
sentences will be reseted.

To realise this way of numbering paragraphs it has been necessary to gear into
the paragraph building mechanism of \LaTeX. In rare cases there is a negative
impact, which can be avoided by switching to \OptionValue{parnumber}{manual}%
\important{\OptionValue{parnumber}{manual}}%
\IndexOption{parnumber~=\PValue{manual}}. On the other hand \LaTeX itself
sometimes undoes the change. In those cases one has to activate it again with
\OptionValue{parnumber}{auto}%
\important{\OptionValue{parnumber}{auto}}%
\IndexOption{parnumber~=\PValue{auto}}.

In a clause which consist of only one paragraph, the paragraph usually
has no number. This does only work if there are not two clauses with an
identical number in a document. Note that the number of paragraphs in a clause
is not available before the end of the clause. Therefore you need a least two
\LaTeX{} runs to get the correct, automatic paragraph numbering.%
\EndIndexGroup


\begin{Declaration}
  \Counter{par}%
  \Macro{thepar}%
  \Macro{parformat}%
  \Macro{parformatseparation}
\end{Declaration}%
For numbering the paragraphs inside a clause we use the counter
\Counter{par}. The output of \Macro{thepar} will display an arabic number,
because the default is \Macro{arabic}\PParameter{par}. \Macro{parformat}
provides the format, which is \Macro{thepar} in rounded brackets. For
numbering a paragraph manually, use \Macro{parformat} as well. It makes sense
to call \Macro{parformat} with a following \Macro{nobreakspace} or a tilde.

The\ChangedAt{v0.7}{\Package{scrjura}} output of \Macro{parformat} is followed
by one or more delimiter(s). These are provided by
\Macro{parformatseparation}, which currently consists of
\Macro{nonbreakspace}, the non-breakable inter word distance.

Package\textnote{Attention!} \Package{scrjura} assumes internally, that
\Macro{thepar} is an arabic number. Don't redefine!%
\EndIndexGroup


\begin{Declaration}
  \Macro{ellipsispar}\OParameter{number}%
  \Macro{parellipsis}
\end{Declaration}
Sometimes\ChangedAt{v0.7}{\Package{scrjura}}\,---\,particularly in
comparisons\,---\,it is desirable to omit paragraphs, but to mark the
omission. Those omitted paragraphs\Index{paragraph>omission} shall be included
in the counter of the paragraphs. The package \Package{scrjura} provides the
command \Macro{ellipsispar} to do this.

By default \Macro{ellipsispar} omits precisely one paragraph. Using the
optional argument multiple paragraphs may be omitted. In any case the output
shows just one not numbered paragraph, which only consists of the ellipsis
defined by \Macro{parellipsis}. The automatic numbering of paragraphs takes
the \PName{number} of omitted paragraphs into account.
\begin{Example}
  Supposed you are writing a »comment« of the German\footnote{We have decided
    to translate it into English. But please remember, it is only an example
    not of existing law but of a technical realisation with
    \Package{scrjura}.} penal code, but only paragraph 3 of §~2. Nevertheless
  you'd like to hint at the omission. This can be done this way:
\begin{lstcode}
  \documentclass[parskip=half]{scrartcl}
  \usepackage{scrjura}
  \begin{document}
  \begin{contract}
    \Clause{title={Temporal application},number=2}
    \ellipsispar[2]

    If, subsequent to the commission of a criminal
    offence, the law provides for a lighter penalty,
    that penalty shall be applicable.

    \ellipsispar[3]
  \end{contract}
  \end{document}
\end{lstcode}
  To see the result, just give it a try.
\end{Example}

The ellipsis is by default \Macro{textellipsis}\IndexCmd{textellipsis}, if
such a command is defined. If not, \Macro{dots} will be
used. \Macro{parellipsis} may be redefined with \Macro{renewcommand}.%
\EndIndexGroup
%
\EndIndexGroup


\subsection{Sentences}
\label{sec:scrjura.sentence}

\BeginIndexGroup
\BeginIndex{}{sentence>number}%
In a contract the paragraphs consist of one or more sentences. In German acts
of law it is common to number the sentences as well. Regarding
\Package{scrjura}, an automatic numbering is cumbersome and error-prone and
has not been implemented yet.

\begin{Declaration}
  \Counter{sentence}%
  \Macro{thesentence}%
  \Macro{Sentence}
\end{Declaration}
Manual numbering of sentences is done with the command \Macro{Sentence}. It
adds one to the counter \Counter{sentence}. As a default, \Macro{thesentence}
is printed as an arabic number.

Using\textnote{Hint!} \Package{babel}\IndexPackage{babel} offers an easy way
to define a short hand for \Macro{Sentence}:%
\phantomsection\label{sec:scrjura.shorthandexample}%
\begin{lstcode}[moretexcs={useshorthands,defineshorthand}]
  \useshorthands{'}
  \defineshorthand{'S}{\Sentence\ignorespaces}
\end{lstcode}
With this definition any space after \lstinline|'S| will be ignored. It is
even possible to use the dot as abbrevation for dot and new number of the
following sentence:
\begin{lstcode}[moretexcs={useshorthands,defineshorthand}]
  \defineshorthand{'.}{. \Sentence\ignorespaces}
\end{lstcode}
These abbrevations have been tried and tested. For details regarding
\Macro{useshorthands} and \Macro{defineshorthands} please consult the manual
of the package \Package{babel} (see \cite{package:babel}).%
\EndIndexGroup
%
\EndIndexGroup
%
\EndIndexGroup


\section{Cross References}
\label{sec:scrjura.ref}

The conventional mechanism to set cross references using
\Macro{label}\IndexCmd{label}\important{\Macro{label}}, \Macro{ref}, and
\Macro{pageref} does not suffice. \Package{scrjura} provides more commands.

\begin{Declaration}
  \Macro{ref}\Parameter{label}%
  \Macro{refL}\Parameter{label}%
  \Macro{refS}\Parameter{label}%
  \Macro{refN}\Parameter{label}
\end{Declaration}
The commands \Macro{refL}, \Macro{refS}, and \Macro{refN} give a full
reference to clause, paragraph and sentence. \Macro{refL} is a long text,
\Macro{refS} a short text and \Macro{refN} an abbreviated, numeric
form. \Macro{ref} defaults to \Macro{refL}.%
\EndIndexGroup


\begin{Declaration}
  \Macro{refClause}\Parameter{label}%
  \Macro{refClauseN}\Parameter{label}
\end{Declaration}
For a cross reference to to a clause without displaying paragraph and
sentences as well. \Macro{refClause} puts a section symbol (\S) in front of
the reference, while \Macro{refClauseN} does not.%
\EndIndexGroup


\begin{Declaration}
  \Macro{refPar}\Parameter{label}%
  \Macro{refParL}\Parameter{label}%
  \Macro{refParS}\Parameter{label}%
  \Macro{refParN}\OParameter{number format}\Parameter{label}
\end{Declaration}
You can make a cross reference to a paragraph using \Macro{refParL},
\Macro{refParS} and \Macro{refParN}. The differences between the forms
correspond to the differences between \DescRef{\LabelBase.cmd.refL},
\DescRef{\LabelBase.cmd.refN} and \DescRef{\LabelBase.cmd.refS}. A special
feature is the optional argument of \Macro{refParN}. Usually the numeric
reference to a paragraph uses a roman number. The optional argument allows to
set a different \PName{number format}, it may make sense to use arabic
numbers. \Macro{refPar} defaults to \Macro{refParL}.%
\EndIndexGroup


\begin{Declaration}
  \Macro{refSentence}\Parameter{label}%
  \Macro{refSentenceL}\Parameter{label}%
  \Macro{refSentenceS}\Parameter{label}%
  \Macro{refSentenceN}\Parameter{label}
\end{Declaration}
You can make a cross reference to a sentence with \Macro{refSentenceL},
\Macro{refSentenceS}, or \Macro{refSentenceN}. Again we have a long text form,
a short text form and a numerical form. \Macro{refSentence} defaults to
\Macro{refSentenceL}.%
\EndIndexGroup


\begin{Declaration}
  \OptionVName{ref}{value}
\end{Declaration}
The results of \DescRef{\LabelBase.cmd.ref}, \DescRef{\LabelBase.cmd.refPar},
and \DescRef{\LabelBase.cmd.refSentence} depend on the \PName{value} of option
\Option{ref}. Defaults are \DescRef{\LabelBase.cmd.refL},
\DescRef{\LabelBase.cmd.refParL} and
\DescRef{\LabelBase.cmd.refSentenceL}. For possible values and their meaning
see \autoref{tab:scrjura.ref}.%
%
\begin{table}
%\begin{desclist}
%  \desccaption
  \caption[{%
    Possible values for option \Option{ref} to configure the cross reference
    format%
  }]{%
    Possible values for option \Option{ref} to configure the cross reference
    format of \DescRef{\LabelBase.cmd.ref}, \DescRef{\LabelBase.cmd.refPar},
    and \DescRef{\LabelBase.cmd.refSentence}%
    \label{tab:scrjura.ref}%
  }%
  \begin{desctabular}
    \entry{\PValue{long}}{%
      Combination of \PValue{parlong} and \PValue{sentencelong}.%
      \IndexOption{ref~=\PValue{long}}%
    }%
    \entry{\PValue{numeric}}{%
      Combination of \PValue{parnumeric} and \PValue{sentencenumeric}.%
      \IndexOption{ref~=\PValue{numeric}}%
    }%
    \entry{\PValue{clauseonly}, \PValue{onlyclause}, \PValue{ClauseOnly},
      \PValue{OnlyClause}}{%
      Combination of \PValue{paroff} and \PValue{sentenceoff}; note that
      \DescRef{\LabelBase.cmd.refPar} and \DescRef{\LabelBase.cmd.refSentence}
      have empty results!%
      \IndexOption{ref~=\PValue{long}}%
    }%
    \entry{\PValue{parlong}, \PValue{longpar}, \PValue{ParL}}{%
      Paragraphs are referenced in long textual form.%
      \IndexOption{ref~=\PValue{parlong}}%
    }%
    \entry{\PValue{parnumeric}, \PValue{numericpar}, \PValue{ParN}}{%
      Paragraphs are referenced in simple numerical form.%
      \IndexOption{ref~=\PValue{parnumeric}}%
    }%
    \entry{\PValue{paroff}, \PValue{nopar}}{%
      Paragraphs have not reference. Note that \DescRef{\LabelBase.cmd.refPar}
      has an empty result!%
      \IndexOption{ref~=\PValue{paroff}}%
    }%
    \entry{\PValue{parshort}, \PValue{shortpar}, \PValue{ParS}}{%
      Paragraphs are referenced in short textual form.%
      \IndexOption{ref~=\PValue{parshort}}%
    }%
    \entry{\PValue{sentencelong}, \PValue{longsentence}, \PValue{SentenceL}}{%
      Sentences are referenced in long textual form.%
      \IndexOption{ref~=\PValue{parlong}}%
    }%
    \entry{\PValue{sentencenumeric}, \PValue{numericsentence},
      \PValue{SentenceN}}{%
      Sentences are referenced in simple numeric form.%
      \IndexOption{ref~=\PValue{sentencenumeric}}%
    }%
    \entry{\PValue{sentenceoff}, \PValue{nosentence}}{%
      Sentences have no reference. Note that
      \DescRef{\LabelBase.cmd.refSentence} has an empty result!%
      \IndexOption{ref~=\PValue{sentenceoff}}%
    }%
    \entry{\PValue{sentenceshort}, \PValue{shortsentence},
      \PValue{SentenceS}}{%
      Sentences are referenced in short textual form.%
      \IndexOption{ref~=\PValue{sentenceshort}}%
    }%
    \entry{\PValue{short}}{%
      Combination if \PValue{parshort} and \PValue{sentenceshort}.%
      \IndexOption{ref~=\PValue{value}}%
    }%
\end{desctabular}
\end{table}

\begin{Example}
  Supposed you would like to reference to paragraphs in the form ``paragraph 1
  in clause 1''. As scrjura lacks of a predefined command for this, you have
  to build your own definitions out of what's given:%
\begin{lstcode}
  \newcommand*{\refParM}[1]{%
    paragraph~\refParN[arabic]{#1} 
    in clause~\refClauseN{#1}%
  }
\end{lstcode}
  This new command can be used in the same way as
  \DescRef{\LabelBase.cmd.refParL}.%
\end{Example}%

\hyperref[tab:scrjura.refexamples]{Table~\ref*{tab:scrjura.refexamples}}
provides examples of the output of the fundamental commands, not configured.%
%
\begin{table}
  \KOMAoptions{captions=topbeside}%
  \setcapindent{0pt}%
  \begin{captionbeside}{Example outputs of the \Option{ref}-independent cross
      reference commands}[l]
    \begin{tabular}[t]{ll}
      \toprule
      Command                               & Example output \\
      \midrule
      \DescRef{\LabelBase.cmd.refL}\Parameter{label}           & § 1 paragraph 1 sentence 1 \\
      \DescRef{\LabelBase.cmd.refS}\Parameter{label}           & § 1 par. 1 sent. 1 \\
      \DescRef{\LabelBase.cmd.refN}\Parameter{label}           & § 1 I 1. \\
      \DescRef{\LabelBase.cmd.refClause}\Parameter{label}   & § 1 \\
      \DescRef{\LabelBase.cmd.refClauseN}\Parameter{label}  & 1 \\
      \DescRef{\LabelBase.cmd.refParL}\Parameter{label}        & paragraph 1 \\
      \DescRef{\LabelBase.cmd.refParS}\Parameter{label}        & par. 1 \\
      \DescRef{\LabelBase.cmd.refParN}\Parameter{label}        & I \\
      \DescRef{\LabelBase.cmd.refParN}\POParameter{arabic}\Parameter{label} & 1 \\
      \DescRef{\LabelBase.cmd.refParN}\POParameter{roman}\Parameter{label} & i \\
      \DescRef{\LabelBase.cmd.refSentenceL}\Parameter{label}   & sentence 1 \\
      \DescRef{\LabelBase.cmd.refSentenceS}\Parameter{label}   & sent. 1 \\
      \DescRef{\LabelBase.cmd.refSentenceN}\Parameter{label}   & 1. \\
      \bottomrule
   \end{tabular}
  \end{captionbeside}
  \label{tab:scrjura.refexamples}
\end{table}
\EndIndexGroup


\section{Additional Environments}
\label{sec:scrjura.newenv}

There are users of \Package{scrjura} who use it to draft neither contracts nor
commentaries on certain acts of law, but a compilation of,
e.\,g., different laws, which does not necessarly use the section prefix (\S)
before the title of each clause. Maybe somebody would like to write
something like ``Art. XY'' and needed an indpendent counter for each
contract environment.

\begin{Declaration}
  \Macro{DeclareNewJuraEnvironment}\Parameter{name}\OParameter{options}%
  \Parameter{start commands}\Parameter{end commands}
\end{Declaration}
This\ChangedAt{v0.9}{\Package{scrjura}} command allows to define new and
independent environments of the type contract. The argument \PName{name} is
the name of the new environment, of course. \PName{start commands} are
commands which will be executed at the beginning of the environment, as if
they were added directly after \Macro{begin}\Parameter{name}. Correspondingly
\PName{end commands} will be executed at the end of the environment, as if
added directly before \Macro{end}\Parameter{name}. Without any \PName{options}
the new environment behaves similiar to the \DescRef{\LabelBase.env.contract}
environment, but with its own counters. It is possible to set \PName{options}
in a comma separated list. Currently the following \PName{options} are
supported:
\begin{description}
\item[\OptionVName{Clause}{instruction}:] Defines on which \PName{instruction}
  inside the environment the command \DescRef{\LabelBase.cmd.Clause} is being
  mapped. The \PName{instruction} expects exactly one argument. To use it
  correctly, a deeper knowledge and understanding of the internal functions of
  \Package{scrjura} is needed. Furthermore the requirements for
  \PName{instruction} may change in future versions. It is recommended not to
  use this option.%
\item[\OptionVName{SubClause}{instruction}:] See explanation for
  \Option{Clause} above.
\item[\OptionVName{Sentence}{instruction}:] Defines on which
  \PName{instruction} inside the environment the command
  \DescRef{\LabelBase.cmd.Sentence} is being mapped. The \PName{instruction}
  must not have an argument. Typically it should add one to the counter
  \Counter{sentence}\IndexCounter{sentence} (using
  \Macro{refstepcounter}\IndexCmd{refstepcounter}) and display it
  somehow. Please avoid undesirable spaces.
\item[\OptionVName{ClauseNumberFormat}{instruction}:] Formats the numbers of
  clauses. Expects exactly one argument, the number of the clause. If the
  \PName{instruction} implements a series of instructions and the number is
  the last argument of a that series, you may directly use the series of
  instructions as \PName{instruction}.
\end{description}
\begin{Example}
  To define the environment we mentioned in the preface of this section,
  for articles, it is sufficient to write:
\begin{lstcode}
  \DeclareNewJuraEnvironment{Artikel}[ClauseNumberFormat=Art.]{}{}
\end{lstcode}
  In case paragraphs have to be separated by space between the
  paragraphs, \Package{scrjura} together with a \KOMAScript{} document class
  allows to write:
\begin{lstcode}
  \DeclareNewJuraEnvironment{Artikel}[ClauseNumberFormat=Art.~]
                            {\KOMAoptions{parskip}}{}
\end{lstcode}
  In cross references will ``Art.'' be used instead of ``\S'', of course.%
\end{Example}%
\EndIndexGroup


\section{Support for Different Languages}
\label{sec:scrjura.babel}

The package \Package{scrjura} has been developed in cooperation with an German
lawyer. Therefore primarily it has provided the languages \PValue{german},
\PValue{ngerman}, \PValue{austrian}, and \PValue{naustrian}. Nevertheless, it
has been designed to support common language packages like
\Package{babel}\important{\Package{babel}}\IndexPackage{babel}. Users can make
language adjustments simply using \DescRef{scrbase.cmd.providecaptionname}
(see \autoref{sec:scrbase.languageSupport},
\DescPageRef{scrbase.cmd.providecaptionname}). But if you have definite
information about the correct juristic terms and conventions of a language, it
is recommended to contact the \KOMAScript{} author. This has been happened for
English and therefore in the meantime \Package{scrjura} also provides terms
for languages \PValue{english}, \PValue{american}, \PValue{british},
\PValue{canadian}, \PValue{USenglish}, and \PValue{UKenglish}.

\begin{Declaration}
  \Macro{parname}%
  \Macro{parshortname}%
  \Macro{sentencename}%
  \Macro{sentenceshortname}
\end{Declaration}
These are the language-dependent terms used by \Package{scrjura}. The meaning
of the terms and the English defaults are shown in
\autoref{tab:scrjura.captionnames}. The package itself uses
\DescRef{scrbase.cmd.providecaptionname} inside
\Macro{begin}\PParameter{document} to define them. So pre-definitions for the
same language but before loading \Package{scrjura} will not be changed.  If
you use \Package{scrjura} with a language setting currently not supported, the
package throws an error.%
%
\begin{table}
  \KOMAoptions{captions=topbeside}%
  \setcapindent{0pt}%
  \begin{captionbeside}
    [{%
      Meanings and English defaults of language dependent terms%
    }]{%
      Meanings and English defaults of language dependent terms if not already
      defined%
    } [l]
    \begin{tabular}[t]{lll}
      \toprule
      Command                   & Meaning                   & Default \\
      \midrule
      \Macro{parname}           & long form ``paragraph''   & paragraph \\
      \Macro{parshortname}      & short form ``paragraph''  & par. \\
      \Macro{sentencename}      & long form ``sentence''    & sentence \\
      \Macro{sentenceshortname} & short form ``sentence''   & sent. \\
      \bottomrule
    \end{tabular}
  \end{captionbeside}
  \label{tab:scrjura.captionnames}
\end{table}
%
\EndIndexGroup


\section{A Detailed Example}
\label{sec:scrjura.example}

Remember the letter from \autoref{cha:scrlttr2}. A club member has written to
the board because of the general meeting that is regulated by the club
statutes. Such club statutes are a kind of contract and you can realise them
using \Package{scrjura}.\footnote{Please note, the example is still in German
  and has to be translated. Currently we have had not enough manpower to do
  the translation. Nevertheless, the contents of the example does not matter
  but the technical realisation.}

\lstinputcode[{xleftmargin=2em,%
  linerange=1-2}]{scrjuraexample.tex}%
We use class \Class{scrartcl}. Because paragraph distance instead of paragraph
indentation is usual in club statutes we load the class with option
\OptionValueRef{maincls}{parskip}{half} (see \autoref{sec:maincls.parmarkup},
\DescPageRef{maincls.option.parskip}).

\lstinputcode[{xleftmargin=2em,%
  linerange=4-4}]{scrjuraexample.tex}%
The club rules are in German. Therefore package \Package{babel} with option
\Option{ngerman} is used, too.

\lstinputcode[{xleftmargin=2em,%
  linerange={6-7,9-9}}]{scrjuraexample.tex}%
Default settings for the fonts are made. Additionally package
\Package{textcomp} is loaded, because it does not only provide a usable Euro
sign but also an improved section sign (\S).

\lstinputcode[{moretexcs=SelectInputMappings,xleftmargin=2em,%
  linerange=11-15}]{scrjuraexample.tex}%
We want to input special characters and umlauts without commands. To do so, we
let \LaTeX{} detect the input encoding. Alternatively we could use package
\Package{inputenc}.

\lstinputcode[{xleftmargin=2em,%
  linerange=17-17}]{scrjuraexample.tex}%
Later in the document we want lists numbered not with arabic numbers but with
lower letters. We can do this easily with package \Package{enumerate}.

\lstinputcode[{moretexcs={useshorthands,defineshorthand},%
  xleftmargin=2em,%
  linerange=19-27}]{scrjuraexample.tex}%
Now, it is time for \Package{scrjura}. With option
\OptionValueRef{\LabelBase}{clausemark}{forceboth} we enforce left an right
clause marks for the running head. On the other hand we do not want
\DescRef{maincls.cmd.section} to change the marks for the running
head. Therefore we use page style \PageStyle{myheadings}. This page style
generally does not provide automatic running heads.

Later we also want a table of contents with the clauses. This can be achieved
with option \DescRef{\LabelBase.option.juratotoc}. Doing so we will see, that
the clause number width is to large for default of the entry into the table of
contents. With \OptionValueRef{\LabelBase}{juratocnumberwidth}{2.5em} we
declare a larger reserved width.

The definition of short hands has already been shown in 
\autoref{sec:scrjura.shorthandexample}. We also use this to make the input
easier and more readable.

\lstinputcode[{xleftmargin=2em,%
  linerange=29-29}]{scrjuraexample.tex}%
It is time to begin the document.

\lstinputcode[{xleftmargin=2em,%
  linerange=31-35}]{scrjuraexample.tex}%
Like other documents the statutes have a title. We make it with the usual
\KOMAScript{} commands from \autoref{sec:maincls.titlepage} (see down from
\autopageref{sec:maincls.titlepage}).

\lstinputcode[{xleftmargin=2em,%
  linerange=37-37}]{scrjuraexample.tex}%
As already stated, we want to have a table of contents.

\lstinputcode[{xleftmargin=2em,%
  linerange=39-43}]{scrjuraexample.tex}%
Preambles are not unusual in club statutes. Here we use
\DescRef{maincls.cmd.addsec} to realise it, because we want to have an entry
into the table of contents.

\lstinputcode[{xleftmargin=2em,%
  linerange=45-45}]{scrjuraexample.tex}%
Here we use a tiny trick. The articles of the club statutes should be numbered
with uppercase letters instead of arabic numbers. This is the same like the
numbering of appendix sections of an article with \Class{scrartcl}.

\lstinputcode[{xleftmargin=2em,%
  linerange=47-49}]{scrjuraexample.tex}%
We begin the contract with the first article.

\lstinputcode[{xleftmargin=2em,%
  linerange=50-59}]{scrjuraexample.tex}%
The first clause has a number and a title. We will do the same with all
following clauses.

The first paragraph of the clause is very usual. Because it is not the only
paragraph, the output is done with a number before the text. Note that the
numbering of the first paragraph needs at least two \LaTeX{} runs like you
will for the table of contents.

In the second paragraph we have two sentences. Here we can see the short hands
\texttt{'S} and \texttt{'.} in action. The first one does only generate the
sentence number. The second one does not only print the full stop but also the
sentence number. With this, both sentences are numbered.

\lstinputcode[{xleftmargin=2em,%
  linerange=60-75}]{scrjuraexample.tex}%
The second clause: also with several paragraphs with one or more
sentences. The second paragraph additionally has a numbered list. At the last
paragraph we used a label, because we want to reference it later.

\lstinputcode[{xleftmargin=2em,%
  linerange=77-84}]{scrjuraexample.tex}%
The third clause has something special: a cross reference. Here we use the
long form with clause, paragraph and sentence. If we would decide, that
sentences should not be referenced, we could use option
\OptionValueRef{\LabelBase}{ref}{nosentence} globally.

\lstinputcode[{xleftmargin=2em,%
  linerange=86-87}]{scrjuraexample.tex}%
Here we have a special kind of clauses. In prior versions of the club statutes
this was a real clause. But then it has been removed. Nevertheless, the
numbering of the following clauses should not be changed by removing this
one. Therefore the \DescRef{\LabelBase.cmd.Clause} statement has not been
removed but supplemented by option \Option{dummy}. With this, we also can set
a label despite the clause will not be printed.

\lstinputcode[{xleftmargin=2em,%
  linerange=88-92}]{scrjuraexample.tex}%
Another article starts. To avoid problems with the paragraph numbering we
interrupt the \DescRef{\LabelBase.env.contract} environment.

\lstinputcode[{xleftmargin=2em,%
  linerange=93-93}]{scrjuraexample.tex}%
The first clause of the next article also has been removed.

\lstinputcode[{xleftmargin=2em,%
  linerange=95-104}]{scrjuraexample.tex}%
We have a real clause again. We cross reference one of the removed
clauses and also use a label.

\lstinputcode[{xleftmargin=2em,%
  linerange=107-112}]{scrjuraexample.tex}%
Once more, this is a special kind of clause. This time we have not removed a
clause but added one without renumbering of the following clauses. To do so,
we use \DescRef{\LabelBase.cmd.SubClause}. Therefore the clause number is the
same like the previous one but with an appended ``a''.

\lstinputcode[{xleftmargin=2em,%
  linerange=114-134}]{scrjuraexample.tex}%
The other clauses of this article are very usual. You already know all the
features used for them.

\lstinputcode[{xleftmargin=2em,%
  linerange=136-150}]{scrjuraexample.tex}%
More articles with known features are following.

\lstinputcode[{xleftmargin=2em,%
  linerange=152-152}]{scrjuraexample.tex}%
Then the \LaTeX{} document ends. You can see three pages from the front of the
document in \autoref{fig:scrjura.example}.%
%
\begin{figure}
  \setcapindent{0pt}%
  \iffree{%
    {\hfill
      \frame{\includegraphics[page=1,width=.482\textwidth,%
        height=.49\textheight,keepaspectratio]{scrjuraexample}}\enskip
      \frame{\includegraphics[page=2,width=.482\textwidth,%
        height=.49\textheight,keepaspectratio]{scrjuraexample}}\par
      \smallskip}
    \begin{captionbeside}[{%
        Example: Three pages from the front of the example club statutes of
        \protect\autoref{sec:scrjura.example}%
      }]{%
        Three pages from the front of the example club statutes of
        \protect\autoref{sec:scrjura.example}%
      }%
      [l]
      \frame{\includegraphics[page=3,width=.482\textwidth,%
        height=.49\textheight,keepaspectratio]{scrjuraexample}}\enskip
    \end{captionbeside}
  }{%
    {\hfill
      \frame{\includegraphics[page=1,width=.482\textwidth]{scrjuraexample}}%
      \enskip
      \frame{\includegraphics[page=2,width=.482\textwidth]{scrjuraexample}}\par
      \smallskip}
    \begin{captionbeside}[{%
        Example: Three pages from the front of the example club statutes of
        \protect\autoref{sec:scrjura.example}%
      }]{%
        Three pages from the front of the example club statutes of
        \protect\autoref{sec:scrjura.example}%
      }%
      [l]
      \frame{\includegraphics[page=3,width=.482\textwidth]{scrjuraexample}}%
      \enskip
    \end{captionbeside}
  }%
  \label{fig:scrjura.example}
\end{figure}

\section{State of Development}
\label{sec:scrjura.draft}

The package is part of \KOMAScript{} for several years and has been used by
lawyers even longer. Nevertheless, it has a version number less than 1. So you
should still regard it as work in progress. Here are the three reasons for
this:

The package has been designed much more general than it can be used
currently. For example several environments beside
\DescRef{\LabelBase.env.contract} has been expected. Later we find that this
one and only environment could be used very general. Nevertheless we also find
that it could be useful to be able to define additional
\DescRef{\LabelBase.env.contract} environments, e.\,g., for articles of
constitutional law. This has been implemented now.

Neither the cooperation with other packages nor the cooperation of the
\DescRef{\LabelBase.env.contract} environment with all kind of \LaTeX{}
environments or document classes has been tested. The main reason for this is
that the package is very special and the package author does not have any
requirement to use it. So all changes, all features, all improvement can only
base on detailed user feedback and only about two and a half users are willing
to send such feedback.

The low version number should state that things could change. The author
endeavours to preserve compatibility to prior versions. Nevertheless,
sometimes compatibility is less important than usability. So compatibility
cannot be guaranteed.%
%
\EndIndexGroup

\endinput

%%% Local Variables: 
%%% mode: latex
%%% mode: flyspell
%%% coding: iso-latin-1
%%% ispell-local-dictionary: "en_GB"
%%% TeX-PDF-mode: t
%%% TeX-master: "guide.tex"
%%% End: 

%  LocalWords:  reseted
