summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex601
1 files changed, 601 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex
new file mode 100644
index 00000000000..c527b42415e
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-scopes.tex
@@ -0,0 +1,601 @@
+% Copyright 2003 by Till Tantau <tantau@cs.tu-berlin.de>.
+%
+% This program can be redistributed and/or modified under the terms
+% of the LaTeX Project Public License Distributed from CTAN
+% archives in directory macros/latex/base/lppl.txt.
+
+
+\section[Hierarchical Structures: Package, Environments, Scopes, and Text]
+{Hierarchical Structures:\\
+ Package, Environments, Scopes, and Text}
+
+
+\subsection{Overview}
+
+\pgfname\ uses two kinds of hierarchical structuring: First, the
+package itself is structured hierarchically, consisting of different
+packages that are built on top of each other. Second, \pgfname\ allows you
+to structure your graphics hierarchically using environments and scopes.
+
+\subsubsection{The Hierarchical Structure of the Package}
+
+The \pgfname\ system consists of several layers:
+
+\begin{description}
+\item[System layer.]
+ The lowest layer is called the \emph{system layer}, though it might
+ also be called ``driver layer'' or perhaps ``backend layer.'' Its
+ job is to provide an abstraction of the details of which driver
+ is used to transform the |.dvi| file. The system layer is
+ implemented by the package |pgfsys|, which will load appropriate
+ driver files as needed.
+
+ The system layer is documented in Part~\ref{part-system}.
+\item[Basic layer.]
+ The basic layer is loaded by the package |pgf|. Some
+ applications do not need all of the functionality of the basic
+ layer, so it is possible to load only the |pgfcore| and some other
+ packages starting with |pgfbase|.
+
+ The basic layer is documented in the present part.
+\item[Frontend layer.]
+ The frontend layer is not loaded by a single packages. Rather,
+ different packages, like \tikzname\ or \textsc{pgfpict2e}, are
+ different frontends to the basic layer.
+
+ The \tikzname\ frontend is documented in Part~\ref{part-tikz}.
+\end{description}
+
+Each layer will automatically load the necessary files of the layers below
+it.
+
+In addition to the packages of these layers, there are also some
+library packages. These packages provide additional definitions of
+things like new arrow tips or new plot handlers.
+
+The library packages are documented in Part~\ref{part-libraries}.
+
+
+
+
+\subsubsection{The Hierarchical Structure of Graphics}
+
+Graphics in \pgfname\ are typically structured
+hierarchically. Hierarchical structuring can be used to identify
+groups of graphical elements that are to be treated ``in the same
+way.'' For example, you might group together a number of paths, all of
+which are to be drawn in red. Then, when you decide later on that you
+like them to be drawn in, say, blue, all you have to do is to change
+the color once.
+
+The general mechanism underlying hierarchical structuring is known as
+\emph{scoping} in computer science. The idea is that all changes to
+the general ``state'' of the graphic that are done inside a scope are
+local to that scope. So, if you change the color inside a scope, this
+does not affect the color used outside the scope. Likewise, when you
+change the line width in a scope, the line width outside is not
+changed, and so on.
+
+There are different ways of starting and ending scopes of graphic
+parameters. Unfortunately, these scopes are sometimes ``in conflict''
+with each other and it is sometimes not immediately clear which scopes
+apply. In essence, the following scoping mechanisms are available:
+
+\begin{enumerate}
+\item
+ The ``outermost'' scope supported by \pgfname\ is the |{pgfpicture}|
+ environment. All changes to the graphic state done inside a
+ |{pgfpicture}| are local to that picture.
+
+ In general, it is \emph{not} possible to set graphic parameters
+ globally outside any |{pgfpicture}| environments. Thus, you can
+ \emph{not} say |\pgfsetlinewidth{1pt}| at the beginning of your
+ document to have a default line width of one point. Rather, you have
+ to (re)set all graphic parameters inside each |{pgfpicture}|. (If
+ this is too bothersome, try defining some macro that does the job
+ for you.)
+\item
+ Inside a |{pgfpicture}| you can use a |{pgfscope}| environment to
+ keep changes of the graphic state local to that environment.
+
+ The effect of commands that change the graphic state are local to
+ the current |{pgfscope}| but not always to the current \TeX\
+ group. Thus, if you open a \TeX\ group (some text in curly braces)
+ inside a |{pgfscope}|, and if you change, for example, the dash
+ pattern, the effect of this changed dash pattern will persist till
+ the end of the |{pgfscope}|.
+
+ Unfortunately, this is not always the case. \emph{Some} graphic
+ parameters only persist till the end of the current \TeX\ group. For
+ example, when you use |\pgfsetarrows| to set the arrow tip
+ inside a \TeX\ group, the effect lasts only till the end of the
+ current \TeX\ group.
+\item
+ Some graphic parameters are not scoped by |{pgfscope}| but
+ ``already'' by \TeX\ groups. For example, the effect of coordinate
+ transformation commands is always local to the current \TeX\
+ group.
+
+ Since every |{pgfscope}| automatically creates a \TeX\ group, all
+ graphic parameters that are local to the current \TeX\ group are
+ also local to the current |{pgfscope}|.
+\item
+ Some graphic parameters can only be scoped using \TeX\ groups, since
+ in some situations it is not possible to introduce a
+ |{pgfscope}|. For example, a path always has to be completely
+ constructed and used in the same |{pgfscope}|. However, we might
+ wish to have different coordinate transformations apply to different
+ points on the path. In this case, we can use \TeX\ groups to keep
+ the effect local, but we could not use |{pgfscope}|.
+\item
+ The |\pgftext| command can be used to create a scope in which \TeX\
+ ``escapes back'' to normal \TeX\ mode. The text passed to the
+ |\pgftext| is ``heavily guarded'' against having any effect on the
+ scope in which it is used. For example, it is possibly to use
+ another |{pgfpicture}| environment inside the argument of
+ |\pgftext|.
+\end{enumerate}
+
+
+Most of the complications can be avoided if you stick to the following
+rules:
+
+\begin{itemize}
+\item
+ Give graphic commands only inside |{pgfpicture}| environments.
+\item
+ Use |{pgfscope}| to structure graphics.
+\item
+ Do not use \TeX\ groups inside graphics, \emph{except} for keeping
+ the effect of coordinate transformations local.
+\end{itemize}
+
+
+
+\subsection{The Hierarchical Structure of the Package}
+
+Before we come to the structuring commands provided by \pgfname\ to
+structure your graphics, let us first have a look at the structure of
+the package itself.
+
+\subsubsection{The Main Package}
+
+To use \pgfname, include the following package:
+
+\begin{package}{pgf}
+ This package loads the complete ``basic layer'' of \pgfname. That
+ is, it will load all of the commands described in the current part
+ of this manual, but it will not load frontends like \tikzname.
+
+ In detail, this package will load the following packages, each of
+ which can also be loaded individually:
+ \begin{itemize}
+ \item
+ |pgfsys|, which is the lowest layer of \pgfname\ and which is
+ always needed. This file will read |pgf.cfg| to discern which
+ driver is to be used. See Section~\ref{section-pgfsys} for
+ details.
+ \item
+ |pgfcore|, which is the central core of \pgfname\ and which is
+ always needed unless you intend to write a new basic layer from
+ scratch.
+ \item
+ |pgfbaseimage|, which provides commands for declaring and
+ using images. An example is |\pgfuseimage|.
+ \item
+ |pgfbaseshapes|, which provides commands for declaring and using
+ shapes. An example is |\pgfdeclareshape|.
+ \item
+ |pgfbaseplot|, which provides commands for plotting functions.
+ \end{itemize}
+
+ Including any of the last three packages will automatically load the
+ first two.
+\end{package}
+
+In \LaTeX, the package takes two options:
+\begin{packageoption}{draft}
+ When this option is set, all images will be replaced by empty
+ rectangles. This can speedup compilation.
+\end{packageoption}
+
+\begin{packageoption}{version=\meta{version}}
+ Indicates that the commands of version \meta{version} need to be
+ defined. If you set \meta{version} to |0.65|, then a large bunch of
+ ``compatibility commands'' are loaded. If you set \meta{version} to
+ |0.96|, then these compatibility commands will not be loaded.
+
+ If this option is not given at all, then the commands of all
+ versions are defined.
+\end{packageoption}
+
+
+\subsubsection{The Core Package}
+
+\begin{package}{pgfcore}
+ This package defines all of the basic layer's commands, except for
+ the commands defined in the additional packages like
+ |pgfbaseplot|. Typically commands defined by the core include
+ |\pgfusepath| or |\pgfpoint|. The core is internally structured
+ into several subpackages, but the subpackages cannot be loaded
+ individually since they are all ``interrelated.''
+\end{package}
+
+
+\subsubsection{The Optional Basic Layer Packages}
+
+The |pgf| package automatically loads the following packages, but you
+can also load them individually (all of them automatically include the
+core):
+
+\begin{itemize}
+ \item |pgfbaseshapes|
+ This package provides commands for drawing nodes and shapes. These
+ commands are explained in Section~\ref{section-shapes}.
+
+ \item |pgfbaseplot|
+ This package provides commands for plotting function. The
+ commands are explained in Section~\ref{section-plots}.
+
+ \item |pgfbaseimage|
+ This package provides commands for including (external) images. The
+ commands are explained in Section~\ref{section-images}.
+\end{itemize}
+
+
+
+
+
+\subsection{The Hierarchical Structure of the Graphics}
+
+\subsubsection{The Main Environment}
+
+
+Most, but not all, commands of the \pgfname\ package must be given
+within a |{pgfpicture}| environment. The only commands that (must) be
+given outside are commands having to do with including images (like
+|\pgfuseimage|) and with inserting complete shadings (like
+|\pgfuseshading|). However, just to keep life entertaining, the
+|\pgfshadepath| command must be given \emph{inside} a |{pgfpicture}|
+environment.
+
+\begin{environment}{{pgfpicture}}
+ This environment will insert a \TeX\ box containing the graphic drawn by
+ the \meta{environment contents} at the current position.
+
+ \medskip
+ \textbf{The size of the bounding box.}
+ The size of the box is determined in the following
+ manner: While \pgfname\ parses the \meta{environment contents}, it
+ keeps track of a bounding box for the graphic. Essentially, this
+ bounding box is the smallest box that contains all coordinates
+ mentioned in the graphics. Some coordinates may be ``mentioned'' by
+ \pgfname\ itself; for example, when you add circle to the current
+ path, the support points of the curve making up the circle are also
+ ``mentioned'' despite the fact that you will not ``see'' them in
+ your code.
+
+ Once the \meta{environment contents} has been parsed completely, a
+ \TeX\ box is created whose size is the size of the computed bounding
+ box and this box is inserted at the current position.
+
+\begin{codeexample}[]
+Hello \begin{pgfpicture}
+ \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
+ \pgfusepath{stroke}
+\end{pgfpicture} World!
+\end{codeexample}
+
+ Sometimes, you may need more fine-grained control over the size of
+ the bounding box. For example, the computed bounding box may be too
+ large or you intensionally wish the box to be ``too small.'' In
+ these cases, you can use the command
+ |\pgfusepath{use as bounding box}|, as described in
+ Section~\ref{section-using-bb}.
+
+
+ \medskip
+ \textbf{The baseline of the bounding box.}
+ When the box containing the graphic is inserted into the normal
+ text, the baseline of the graphic is normally at the bottom of the
+ graphic. For this reason, the following two sets of code lines have
+ the same effect, despite the fact that the second graphic uses
+ ``higher'' coordinates than the first:
+
+\begin{codeexample}[]
+Rectangles \begin{pgfpicture}
+ \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
+ \pgfusepath{stroke}
+\end{pgfpicture} and \begin{pgfpicture}
+ \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}}
+ \pgfusepath{stroke}
+\end{pgfpicture}.
+\end{codeexample}
+
+ You can change the baseline using the |\pgfsetbaseline| command, see
+ below.
+
+\begin{codeexample}[]
+Rectangles \begin{pgfpicture}
+ \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
+ \pgfusepath{stroke}
+ \pgfsetbaseline{0pt}
+\end{pgfpicture} and \begin{pgfpicture}
+ \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}}
+ \pgfusepath{stroke}
+ \pgfsetbaseline{0pt}
+\end{pgfpicture}.
+\end{codeexample}
+
+ \medskip
+ \textbf{Including text and images in a picture.}
+ You cannot directly include text and images in a picture. Thus, you
+ should \emph{not} simply write some text in a |{pgfpicture}| or use
+ a command like |\includegraphics| or even |\pgfimage|. In all these
+ cases, you need to place the text inside a |\pgftext| command. This
+ will ``escape back'' to normal \TeX\ mode, see
+ Section~\ref{section-text-command} for details.
+\end{environment}
+
+\begin{plainenvironment}{{pgfpicture}}
+ The plain \TeX\ version of the environment. Note that in this
+ version, also, a \TeX\ group is created around the environment.
+\end{plainenvironment}
+
+\makeatletter
+\begin{command}{\pgfsetbaseline\marg{dimension}}
+ This command specifies a $y$-coordinate of the picture that should
+ be used as the baseline of the whole picture. When a \pgfname\
+ picture has been typeset completely, \pgfname\ must decide at which
+ height the baseline of the picture should lie. Normally, the
+ baseline is set to the $y$-coordinate of the bottom of the picture,
+ but it is often desirable to use another height.
+
+\begin{codeexample}[]
+Text \tikz{\pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}},
+ \tikz{\pgfsetbaseline{0pt}
+ \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}},
+ \tikz{\pgfsetbaseline{.5ex}
+ \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}},
+ \tikz{\pgfsetbaseline{-1ex}
+ \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}}.
+\end{codeexample}
+\end{command}
+
+\subsubsection{Graphic Scope Environments}
+
+Inside a |{pgfpicture}| environment you can substructure your picture
+using the following environment:
+
+\begin{environment}{{pgfscope}}
+ All changes to the graphic state done inside this environment are
+ local to the environment. The graphic state includes the following:
+ \begin{itemize}
+ \item
+ The line width.
+ \item
+ The stroke and fill colors.
+ \item
+ The dash pattern.
+ \item
+ The line join and cap.
+ \item
+ The miter limit.
+ \item
+ The canvas transformation matrix.
+ \item
+ The clipping path.
+ \end{itemize}
+ Other parameters may also influence how graphics are rendered, but they
+ are \emph{not} part of the graphic state. For example, the arrow tip
+ kind is not part of the graphic state and the effect of commands
+ setting the arrow tip kind are local to the current \TeX\ group, not
+ to the current |{pgfscope}|. However, since |{pgfscope}| starts and
+ ends a \TeX\ group automatically, a |{pgfscope}| can be used to
+ limit the effect of, say, commands that set the arrow tip kind.
+
+\begin{codeexample}[]
+\begin{pgfpicture}
+ \begin{pgfscope}
+ {
+ \pgfsetlinewidth{2pt}
+ \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{2ex}}
+ \pgfusepath{stroke}
+ }
+ \pgfpathrectangle{\pgfpoint{3ex}{0ex}}{\pgfpoint{2ex}{2ex}}
+ \pgfusepath{stroke}
+ \end{pgfscope}
+ \pgfpathrectangle{\pgfpoint{6ex}{0ex}}{\pgfpoint{2ex}{2ex}}
+ \pgfusepath{stroke}
+\end{pgfpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{pgfpicture}
+ \begin{pgfscope}
+ {
+ \pgfsetarrows{-to}
+ \pgfpathmoveto{\pgfpointorigin}\pgfpathlineto{\pgfpoint{2ex}{2ex}}
+ \pgfusepath{stroke}
+ }
+ \pgfpathmoveto{\pgfpoint{3ex}{0ex}}\pgfpathlineto{\pgfpoint{5ex}{2ex}}
+ \pgfusepath{stroke}
+ \end{pgfscope}
+ \pgfpathmoveto{\pgfpoint{6ex}{0ex}}\pgfpathlineto{\pgfpoint{8ex}{2ex}}
+ \pgfusepath{stroke}
+\end{pgfpicture}
+\end{codeexample}
+
+ At the start of the scope, the current path must be empty, that is,
+ you cannot open a scope while constructing a path.
+
+ It is usually a good idea \emph{not} to introduce \TeX\ groups
+ inside a |{pgfscope}| environment.
+\end{environment}
+
+\begin{plainenvironment}{{pgfscope}}
+ Plain \TeX\ version of the |{pgfscope}| environment.
+\end{plainenvironment}
+
+
+The following scopes also encapsulate certain properties of the
+graphic state. However, they are typically not used directly by the
+user.
+
+\begin{environment}{{pgfinterruptpath}}
+ This environment can be used to temporarily interrupt the
+ construction of the current path. The effect will be that the path
+ currently under construction will be ``stored away'' and restored at
+ the end of the environment. Inside the environment you can construct
+ a new path and do something with it.
+
+ An example application of this environment is the arrow tip
+ caching. Suppose you ask \pgfname\ to use a specific arrow tip
+ kind. When the arrow tip needs to be rendered for the first time,
+ \pgfname\ will ``cache'' the path that makes up the arrow tip. To do
+ so, it interrupts the current path construction and then protocols
+ the path of the arrow tip. The |{pgfinterruptpath}| environment is
+ used to ensure that this does not interfere with the path to which
+ the arrow tips should be attached.
+
+ This command does \emph{not} install a |{pgfscope}|. In particular,
+ it does not call any |\pgfsys@| commands at all, which would,
+ indeed, be dangerous in the middle of a path construction.
+\end{environment}
+
+\begin{environment}{{pgfinterruptpicture}}
+ This environment can be used to temporarily interrupt a
+ |{pgfpicture}|. However, the environment is intended only to be used
+ at the beginning and end of a box that is (later) inserted into a
+ |{pgfpicture}| using |\pgfqbox|. You cannot use this environment
+ directly inside a |{pgfpicture}|.
+
+\begin{codeexample}[]
+\begin{pgfpicture}
+ \pgfpathmoveto{\pgfpoint{0cm}{0cm}} % In the middle of path, now
+ \newbox\mybox
+ \setbox\mybox=\hbox{
+ \begin{pgfinterruptpicture}
+ Sub-\begin{pgfpicture} % a subpicture
+ \pgfpathmoveto{\pgfpoint{1cm}{0cm}}
+ \pgfpathlineto{\pgfpoint{1cm}{1cm}}
+ \pgfusepath{stroke}
+ \end{pgfpicture}-picture.
+ \end{pgfinterruptpicture}
+ }
+ \pgfqbox{\mybox}%
+ \pgfpathlineto{\pgfpoint{0cm}{1cm}}
+ \pgfusepath{stroke}
+\end{pgfpicture}\hskip3.9cm
+\end{codeexample}
+\end{environment}
+
+
+\subsubsection{Inserting Text and Images}
+
+\label{section-text-command}
+
+Often, you may wish to add normal \TeX\ text at a certain point inside
+a |{pgfpicture}|. You cannot do so ``directly,'' that is, you cannot
+simply write this text inside the |{pgfpicture}| environment. Rather,
+you must pass the text as an argument to the |\pgftext| command.
+
+You must \emph{also} use the |\pgftext| command to insert an image or
+a shading into a |{pgfpicture}|.
+
+\begin{command}{\pgftext\opt{\oarg{options}}\marg{text}}
+ This command will typeset \meta{text} in normal \TeX\ mode and
+ insert the resulting box into the |{pgfpicture}|. The bounding box
+ of the graphic will be updated so that all of the text box is
+ inside. Be default, the text box is centered at the origin, but this
+ can be changed either by giving appropriate \meta{options} or by
+ applying an appropriate coordinate transformation beforehand.
+
+ The \meta{text} may contain verbatim text. (In other words, the
+ \meta{text} ``argument'' is not a normal argument, but is put in a
+ box and some |\aftergroup| hackery is used to find the end of the
+ box.)
+
+ \pgfname's current (high-level) coordinate transformation is
+ synchronized with the canvas transformation matrix temporarily
+ when the text box is inserted. The effect is that if there is
+ currently a high-level rotation of, say, 30 degrees, the \meta{text}
+ will also be rotated by thirty degrees. If you do not want this
+ effect, you have to (possibly temporarily) reset the high-level
+ transformation matrix.
+
+ The following \meta{options} may be given as conveniences:
+ \begin{itemize}
+ \itemoption{left}
+ causes the text box to be placed such that its left border is on the origin.
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[left] {lovely}}
+\end{codeexample}
+ \itemoption{right}
+ causes the text box to be placed such that its right border is on the origin.
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[right] {lovely}}
+\end{codeexample}
+ \itemoption{top}
+ causes the text box to be placed such that its top is on the
+ origin. This option can be used together with the |left| or
+ |right| option.
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[top] {lovely}}
+\end{codeexample}
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[top,right] {lovely}}
+\end{codeexample}
+ \itemoption{bottom}
+ causes the text box to be placed such that its bottom is on the
+ origin.
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[bottom] {lovely}}
+\end{codeexample}
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[bottom,right] {lovely}}
+\end{codeexample}
+ \itemoption{base}
+ causes the text box to be placed such that its baseline is on the
+ origin.
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[base] {lovely}}
+\end{codeexample}
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[base,right] {lovely}}
+\end{codeexample}
+ \itemoption{at}|=|\meta{point}
+ Translates the origin (that is, the point where the text is
+ shown) to \meta{point}.
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[base,at={\pgfpoint{1cm}{0cm}}] {lovely}}
+\end{codeexample}
+ \itemoption{x}|=|\meta{dimension}
+ Translates the origin by \meta{dimension} along the $x$-axis.
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[base,x=1cm,y=-0.5cm] {lovely}}
+\end{codeexample}
+ \itemoption{y}|=|\meta{dimension}
+ works like the |x| option.
+ \itemoption{rotate}|=|\meta{degree}
+ Rotates the coordinate system by \meta{degree}. This will also
+ rotate the text box.
+\begin{codeexample}[]
+\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
+ \pgftext[base,x=1cm,y=-0.5cm,rotate=30] {lovely}}
+\end{codeexample}
+ \end{itemize}
+
+\end{command}
+
+