%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[]{mdframed} \end{mdexample} The package defines only one environment with the following syntax: \begin{mdexample} \begin{mdframed}[] \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}