%Documenation of the package mdframed
%%$Id: mdframed-doc-en.tex 101 2010-12-22 16:26:58Z marco $
%%$Rev: 101 $
%%$Author: marco $
%%$Dater:$
\setcounter{errorcontextlines}{999}
\def\mdversion{0.6a}
\documentclass[english,11pt,]{scrartcl}
%\usepackage{showframe}
\usepackage[nofancy,draft]{svninfo}
\svnInfo $Id: mdframed-doc-en.tex 101 2010-12-22 16:26:58Z marco $
\usepackage{babel}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}

\usepackage[de,T1,altbullet]{lucidabr}
\usepackage{microtype}
\usepackage[french=quotes]{csquotes}
%\let\glqq\flqq
%\let\grqq\frqq
\let\grqq\grqq

\usepackage{scrpage2}
\clearscrheadfoot
\pagestyle{scrheadings}
\automark[subsection]{section}
\renewcommand{\sectionmark}[1]{\markboth{\sectionmarkformat #1}{}}%
\renewcommand{\subsectionmark}[1]{\markright{\subsectionmarkformat #1}} %nur Titel ohne Nr.
\ihead{\rightmark}
\ohead{\leftmark}
\ofoot{\pagemark} 
\ifoot{\svnId}


\usepackage[left=5cm,right=3cm,top=3cm,bottom=2cm]{geometry}


\usepackage{xcolor}
\definecolor{titleblue}{rgb}{0,0,0.9}

\usepackage{amsmath,amsthm}

\usepackage[]{graphicx}

\usepackage[style=0]{mdframed}


\usepackage{xspace}
\usepackage{multicol}
\columnseprule0.4pt

\usepackage{listings}
\lstnewenvironment{mdexample}[1][]
  {\lstset{%
     basicstyle=\small,%
     xleftmargin=20pt,%
     xrightmargin=20pt,%
     frame=single,%
     rulecolor=\color{titleblue},%
     framesep=5pt,%
     framerule=1pt,%
     language=[LaTeX]TeX,#1,%
     columns=fixed,%
     fontadjust=true,%
     basewidth=0.65em,%
     breakatwhitespace=true}%
  }%
%  morekeywords={\usepackage,\end,\begin,\lipsum,\documentclass,\newtheorem,\newenvironment,\section,\label\mbox{ }}%
  {}

\makeatletter
\begingroup
  \text@command\relax
  \global\let\xspace@check@icr\check@icr
\endgroup
\xspaceaddexceptions{\xspace@check@icr}

\renewcommand\tableofcontents{%
\setcounter{tocdepth}{2}%
 \begin{multicols}{2}[\centering\textbf{\sffamily\Large\contentsname}]
        \@starttoc{toc}
 \end{multicols}
}
\makeatother
\newcommand*\mdoption[1]{\textsf{\bfseries\color{titleblue}#1}}
\newcommand*\mdname{\textsf{mdframed}\xspace}
\newcommand*\mdpack[1]{\textsf{#1}\xspace}
\newcommand*\mdsetting[1]{\textsf{#1}\xspace}
\newcommand*\mdcommand[1]{\texttt{\textbackslash #1}\xspace}

\newcommand*\mdDescribeMacro[2][]{\par\kern\baselineskip%
                                   \noindent\llap{%
                                   \textsf{\bfseries\color{titleblue}#2}%
                                   \quad}\mdDefault{#1}\ignorespaces}
\newcommand*{\mdDefault}[1]{%
 \ifx\relax#1\relax\else\marginpar{\small\mdsetting{default=#1}}\fi}

 \usepackage{pst-node}
 \usepackage{pstricks-add}

\usepackage{hyperref}
\hypersetup{%
pdftitle={Documenation of mdframed},%
pdfauthor={Marco Daniel},%
colorlinks=true,%
linkcolor=titleblue,
urlcolor=cyan,
bookmarksdepth=4,
}
%\usepackage{showframe}
\begin{document}
\thispagestyle{empty}
\begin{center}
  \color{titleblue}
   \Large\bfseries \sffamily The \mdname package\footnote{Extending the package \texttt{framed.sty}.}
  
    \vspace*{0.5\baselineskip}
     \normalfont\large\normalcolor auto-split frame environment
     
     \vspace*{.5\baselineskip}
      \href{mailto:marco.daniel@mada-nada.de}{Marco Daniel}%
       \footnote{With thanks to Heiko Oberdiek, Rolf Niepraschk,
                 Martin Scharrer and Herbert Voss.},
     \href{mailto:marco.daniel@mada-nada.de}{Elke Schubert}%
        \qquad \mdversion\ \qquad \today
\end{center}
\begin{abstract}
Working with the command \mdcommand{fbox} or \mdcommand{fcolorbox}, one has to handle page breaks by hand, meaning that you have to split up the \mdcommand{fbox} into two. The present package defines the environment \mdname which automatically deals with page breaks, whence the name \glqq breakable\grqq.
               
By using \mdcommand{newenvironment} the user may choose between several individual designs.
\end{abstract}
             
\tableofcontents

\section{Motivation}
Many users wish to (further) emphasize lemmata, definitions, proofs etc. The package \mdname allows to
create environments with breakable frames. I think an example is the best way to demonstrate the properties.
\begin{mdexample}
\newtheorem{mdtheorem}{Theorem}[section]
\newenvironment{theorem}{\begin{mdframed}%
   [linewidth=2,leftmargin=40,rightmargin=40,%
    backgroundcolor=yellow,linecolor=blue,%
    splittopskip=\topskip,skipbelow=\baselineskip,%
    skipabove=\baselineskip]%
   \begin{mdtheorem}}{\end{mdtheorem}\end{mdframed}}
\begin{theorem}[Pythagorean theorem]
In any right triangle, the area of the square whose
side is the hypotenuse is equal to the sum of the 
areas of the squares whose sides are the two legs.
\[ a^2+b^2=c^2 \]
\end{theorem}
\end{mdexample}

\newtheorem{mdtheorem}{Theorem}[section]
\newenvironment{theorem}{\begin{mdframed}%
   [linewidth=2,leftmargin=40,rightmargin=40,%
    backgroundcolor=yellow,linecolor=blue,%
    splittopskip=\topskip,skipbelow=\baselineskip,%
    skipabove=\baselineskip]%
   \begin{mdtheorem}}%
 {\end{mdtheorem}\end{mdframed}}

\begin{theorem}[Pythagorean theorem]
 In any right triangle, the area of the square whose side is the hypotenuse
 is equal to the sum of the areas of the squares whose sides are the two legs.
\[ a^2+b^2=c^2 \]
\end{theorem}

\section{Syntax}
The package itself loads the packages \mdpack{kvoptions}, \mdpack{etoolbox}, \mdpack{calc} and \mdpack{color}.
By setting the correct options \mdpack{mdframed} will load \mdpack{xcolor}, \mdpack{tikz} or \mdpack{pstricks}.

Load the package as usual:
\begin{mdexample}
 \usepackage[<GLOBAL OPTIONS>]{mdframed}
\end{mdexample}

The package defines only one environment with the following syntax:
\begin{mdexample}
 \begin{mdframed}[<LOCAL OPTIONS>]
    <CONTENT>
 \end{mdframed}
\end{mdexample}

\section{Options}
The package allows to set global and local options which are explained below.

\subsection{Global Options}
The following options are only global options.

\mdDescribeMacro[none]{xcolor}
By setting this key, the package \mdpack{xcolor} will
be loaded with the given value(s). Without any value \mbox{\mdname} loads
the package \mdpack{color} without any options.

\mdDescribeMacro[0]{style} 
With this key you can change the way frames are drawn. By using
\mdoption{style=0} the frames are drawn by the \LaTeX-command \mdcommand{rule}.
By setting the key to \mdoption{style=1} the package
\mdpack{tikz} will draw the frames. By setting the key to \mdoption{style=3} the
package \mdpack{pstricks} will draw the frames. The manipulation of the frames
depends on the \mdoption{style}. For further information see below.


\subsection{Global and Local Options}
The options listed below can be set globally or locally.
\mdDescribeMacro{\textbackslash mdfsetup}To set the options globally
you can use the optional argument of \mdcommand{usepackage} or
you can use the command \mdcommand{mdfsetup} which is not limited to the header.

\subsubsection{Options with lengths}

In figure \eqref{fig:laengen} you can see the adjustable lengths which will be described below. 
All lengths accept two kinds of input. The first one is a length (e.g. 2pt) and
the second one is a number (e.g. 2) which will be multiplied by \mdoption{1 defaultunit}.
\mdDescribeMacro[pt]{defaultunit} see the sentence above.

\begin{center}
% \includegraphics{laengen}
\psscalebox{0.7}{%
\Large
\begin{pspicture}(-2,-2)(12,8)
        %
 \psframe[fillstyle=vlines,linecolor=green!70!black,hatchcolor=green!70!black](2,2)(8,4)
 \rput*(5,3){Contents}
 \psframe[linecolor=red!70!black,linewidth=10pt](0,0)(10,6)
 \psframe[linecolor=blue!70!black,linewidth=10pt](!0 0.1 3 mul add
                                                  0 3 0.1 mul add )%
                                                 (! 10 0.1 3 mul neg add
                                                    6  0.1 3 mul neg add)
 \psframe[linecolor=yellow!70!black,linewidth=10pt](!0 0.2 3 mul add
                                                     0 3 0.2 mul add )%
                                                   (! 10 0.2 3 mul neg add
                                                      6  0.2 3 mul neg add)
 \psline{<->}(5,6)(5,8)
 \uput[0](5,7){skipabove}
 \psline{<->}(5,0)(5,-2)
 \uput[0](5,-1){skipbelow}
 \psline{<->}(5,4)(5,5.1)
 \uput*[90](5,4){innertopmargin}
 \psline{<->}(5,2)(5,0.9)
 \uput*[90](5,1){innerbottommargin}
 \psline{<->}(10,3)(12,3)
 \uput[0](10,2.8){rightmargin}
 \psline{<->}(0,3)(-2,3)
 \uput[180](0,2.8){leftmargin}
 \psline{<->}(8,3)(9.1,3)
 \uput*[0](8.2,3){\psrotateleft{innerrightmargin}}
 \psline{<->}(0.9,3)(2,3)
 \uput*[0](1.2,3){\psrotateleft{innerleftmargin}}
 \psline(-2,8)(12,8)\uput*[0](-2,8){text above}
 \psline(-2,-2)(12,-2)\uput*[0](-2,-2){text below}
\end{pspicture}
}
 \captionof{figure}{adjustable lengths of \mdpack{mdframed}}
 \label{fig:laengen}
\end{center}

\mdDescribeMacro[0pt]{skipabove} Sets an additional skip above the frame.
\mdDescribeMacro[0pt]{skipbelow} Sets an additional skip below the frame.
\mdDescribeMacro[]{margin} This option is not longer supported. Use \mdoption{leftmargin}
                           and \mdoption{rightmargin} instead.
\mdDescribeMacro[0pt]{leftmargin} Sets the length of the left margin of the environment.
\mdDescribeMacro[0pt]{rightmargin} Sets the length of the right margin of the environment.

\mdDescribeMacro[10pt]{innerleftmargin} Sets the length of the inner left margin of the environment.
\mdDescribeMacro[10pt]{innerrightmargin} Sets the length of the inner right margin of the environment.
\mdDescribeMacro[\newline.4\textbackslash baselineskip]{innertopmargin} Sets the length of the inner top margin of the environment.
\mdDescribeMacro[\newline.4\textbackslash baselineskip]{innerbottommargin} Sets the length of the inner bottom margin of the environment.

\paragraph*{The following lengths are not shown in figure \eqref{fig:laengen}.}

\mbox{}
\mdDescribeMacro[0pt]{splittopskip} Sets the length of the skip above the splitted part of the environment.
\mdDescribeMacro[0pt]{splitbottomskip} Sets the length of the skip below the splitted part of the environment.
                                        \textbf{This works only with \mdoption{style=0} and \mdoption{style=3}.}
\mdDescribeMacro[0.4pt]{linewidth} Sets the width of the line around the environment.
\mdDescribeMacro[0pt]{roundcorner} Sets the size of the radius of the corners of the frames.
                                    \textbf{This works only with \mdoption{style=1} and \mdoption{style=3}.}
\mdDescribeMacro[0pt]{innerlinewidth} Sets the width of the inner line around the environment.
                                        \textbf{This works only with \mdoption{style=1}.}
\mdDescribeMacro[0pt]{outerlinewidth} Sets the width of the outer line around the environment.
                                        \textbf{This works only with \mdoption{style=1}.}
\mdDescribeMacro[\newline linewidth]{middlelinewidth} Sets the width of the middle line around the environment.
                                        \textbf{This works only with \mdoption{style=1}.}


\subsubsection{Colored Options}
\mdDescribeMacro[black]{linecolor} Sets the color of the line around the environment.
\mdDescribeMacro[\newline linecolor]{innerlinecolor} Sets the color of the inner line around the environment.
                                        \textbf{This works only with \mdoption{style=1}.}
\mdDescribeMacro[\newline linecolor]{middlelinecolor} Sets the color of the middle line around the environment.
                                        \textbf{This works only with \mdoption{style=1}.} 
\mdDescribeMacro[\newline linecolor]{outerlinecolor} Sets the color of the outer line around the environment.
                                        \textbf{This works only with \mdoption{style=1}.}
\mdDescribeMacro[white]{backgroundcolor} Sets the color of the background of the environment.
\mdDescribeMacro[black]{fontcolor} Sets the color of the contents of the environment.

\subsection{Hidden Lines}
\textbf{The following options work only with \mdoption{style=0} and \mdoption{style=3}.}

\mdDescribeMacro[true]{topline} Draws a line at the top.
\mdDescribeMacro[true]{bottomline} Draws a line at the bottom.
\mdDescribeMacro[true]{leftline} Draws a line on the left.
\mdDescribeMacro[true]{rightline} Draws a line on the right.

\subparagraph{Remark:} By setting \mdoption{style=3} only the following combinations are implemented
\begin{itemize}
        \item \mdoption{leftline=true, rightline=true, bottomline=true, topline=true}
        \item \mdoption{leftline=true, rightline=true, bottomline=false, topline=true}
        \item \mdoption{leftline=true, rightline=true, bottomline=true, topline=false}
        \item \mdoption{leftline=true, rightline=false, bottomline=true, topline=true}
        \item \mdoption{leftline=false, rightline=true, bottomline=true, topline=true}
        \item \mdoption{leftline=false, rightline=false, bottomline=false, topline=false}
        \item \mdoption{leftline=false, rightline=false, bottomline=true, topline=true}
        \item \mdoption{leftline=true, rightline=true, bottomline=false, topline=false}
        \item \mdoption{leftline=true, rightline=false, bottomline=false, topline=false}
        \item \mdoption{leftline=false, rightline=true, bottomline=false, topline=false}
        \item \mdoption{leftline=false, rightline=false, bottomline=true, topline=false}
        \item \mdoption{leftline=false, rightline=false, bottomline=false, topline=true}
\end{itemize}                
\subsubsection{Useful options}




\mdDescribeMacro[false]{ntheorem} Before setting this boolkey, you have to load the package \mdpack{ntheorem}. 

                                 With this option you set the values \mdcommand{theorempreskipamount}
                                 and\newline \mdcommand{theorempostskipamount} to 0pt.
\mdDescribeMacro[none]{pstrickssetting} With this key you can pass several options to \mdcommand{psset}. For example 
                                        if you want all lines dashed you will have to set 
                                        \mdoption{pstrickssetting=\{linestyle=dashed\}}. It is very important
                                        to put the options of \mdoption{pstrickssetting} in brackets.
                                        \textbf{This works only with \mdoption{style=3}.}

 
\section{Known Problems}
 In this section I will collect known problems. In case you encounter any further problems, please
 drop me an email, \href{mailto:marco.daniel@mada-nada.de}{marco.daniel'at'mada-nada.de}.

   Do you have any ideas / wishes on further extensions to this package? Please let me know!

\begin{enumerate}
 \item So far the environment isn't compatible with the package \mdpack{gmverb}.
 \item So far it isn't possible to use the multicolumn environment.
 \item So far it isn't possible to use footnotes.
\end{enumerate}


\section{ToDo}
\begin{enumerate}
  \item see \glqq Known Problems\grqq.
  \item No limitations of any style.
  \item Create new styles.
  \item Improve page breaks.
\end{enumerate}                

\section{Acknowledgement}
Thanks for the bug reports and suggestions

\textsf{Dick Nickalls;\quad Dr. Dietrich Grau;\quad Piazza Luca}.
\medskip

\noindent Thanks for proofreading 

\textsf{Nahid Shajari}.                                       

\clearpage
\appendix
\section{More information}
\addtocontents{toc}{\protect\setcounter{tocdepth}{-4}}
In the following section I want to present how to create
your own frame.
\subsection{How does \mdpack{mdframed} work?}
With the environment \mdcommand{begin\{mdframed\}} \ldots \mdcommand{end\{mdframed\}}
the whole contents will be saved in a \mdcommand{savebox} called \mdcommand{@tempboxa}.
After the calculation of the width and the height of the \mdcommand{@tempboxa} the box 
will be set sequently. The following figure demonstrates this.

\begin{center}
\newcommand{\mybox}[1]{\psframebox[linecolor=gray,shadowcolor=lightgray]{\parbox{3.5cm}{\centering\small #1}}}        
%    \includegraphics{way}
\begin{psmatrix}[mnode=r,colsep=4,rowsep=1.2]
  [name=s1] \mybox{read in and save contents in \textbackslash @tempboxa} &
  [name=f1] \mybox{\textbackslash md@putbox@single} \\
  [name=s2] \mybox{split \textbackslash @tempboxa in \textbackslash tw@ to the free space of the page} &
  [name=f2] \mybox{\textbackslash md@putbox@first} \\
  [name=s3] \mybox{contents of \textbackslash @tempboxa have enough space on the new page} &
  [name=f3] \mybox{\textbackslash md@putbox@second} \\
  [name=s4] \mybox{split \textbackslash @tempboxa in \textbackslash tw@ to the free space of the page} &
  [name=f4] \mybox{\textbackslash md@putbox@middle} \\
  %
  \psset{arrowinset=0,arrowscale=1.3,nodesep=3pt}
  \ncline{->}{s1}{f1}\naput{enough space on page}    
  \ncline{->}{s1}{s2}\naput{not enough space on page}
  \ncline{->}{s2}{f2}\naput{type out \textbackslash tw@}    
  \ncline[angle=90]{->}{f2}{s3}\ncput*{calculate the height of the new \textbackslash @tempboxa}
  \ncline{->}{s3}{f3}\naput{yes}   
  \ncline{->}{s3}{s4}\naput{no}
  \ncline{->}{s4}{f4}\naput{type out \textbackslash tw@}
  \ncloop[angleA=180,angleB=-90,loopsize=4.5]{<-}{s3}{f4}
  \nbput{calculate the height of the new \textbackslash @tempboxa}
\end{psmatrix}

\captionof{figure}{Setting the contents of \mdpack{mdframed}}\label{fig:way}
\end{center}

The width of the contents is the result of the settings of \mdoption{leftmargin}, \mdoption{rightmargin}, \mdoption{linewidth}, \mdoption{innerleftmargin} and \mdoption{innerrightmargin} (see figure \eqref{fig:laengen}).
\subsection{The Framecommands}
The package \mdpack{mdframed} knows four kinds of \glqq Framecommand\grqq. These commands tell \LaTeX\ how to set the contents of \mdpack{mdframed}. 
\begin{description}
       \item[\mdcommand{md@putbox@single}] This command sets the contents of a single non-splitted frame.
       \item[\mdcommand{md@putbox@first}]  This command sets the contents of the first frame of a splitted frame.
       \item[\mdcommand{md@putbox@middle}] This command sets the contents of the middle frame of a splitted frame.
       \item[\mdcommand{md@putbox@second}] This command sets the contents of the last frame of a splitted frame.
\end{description}

Uses the explained commands we give an example. The command \mdcommand{box} use the contents of the savebox and types them out. 

First we want to type out the single box without any settings (but with the calculated width).
\begin{mdexample}
\makeatletter
 \def\md@putbox@single{\box\@tempboxa}
\makeatother
\end{mdexample}
I am using the command \mdcommand{leftline} to start the \glqq Framecommands\grqq\ at the left.
\begin{mdexample}
\makeatletter
 \def\md@putbox@single{\leftline{\box\@tempboxa}}
\makeatother
\end{mdexample}

Now you have to know how the lengths are named. Every length which can be modified by the options has the following syntax
\begin{mdexample}
\mdf@'Name of the Length'@length
\end{mdexample}
For example the leftmargin is

\begin{mdexample}
\mdf@leftmargin@length
\end{mdexample}

To create only a line at the left with the correct \mdoption{leftmargin} you can set \mdcommand{md@putboxsingle} as follows

\begin{mdexample}
\makeatletter
\def\md@putbox@single{%
         \leftline{%
             \hspace*{\mdf@leftmargin@length}%
             \rule[-\dp\@tempboxa]{\mdf@linewidth}%
                  {\ht\@tempboxa+\dp\@tempboxa}%
             \box\@tempboxa
         }%
}
\makeatother
\end{mdexample}

In this way you can do what you want. If you create your own style you
can save the file as \mdpack{md-frame-X.mdf}.
\mdpack{X} must be an integer. 
In this way you can use the option \mdoption{style} to
load the file by setting \mdoption{style=X}.


\end{document}

