Defining my own “boxes”?

Question

What I want is a environment that lets me create my own "boxes" (or blocks? I keep confusing them...) with the following properties

1. They visually couple together a piece of sourcecode and a explanation, possibly a mathematical formula
2. They get indexed and named somehow so I can list them in a central directory somewhere

To get a feeling for what I want to place in the box:

\lstinputlisting[language=C++,basicstyle=\small]{fragments/leda-math-linear-solver.cpp}
\begin{equation}matrix * (x * x\_factor) = right\end{equation}

So its basicly a \lstinputlisting and a \begin{equation} ... \end{equation} I want to glue together. But I would prefer not to get nailed into the equation too much, as I might want to use some other explanation then a equation for some piece of sourcecode.

I did a few attempts to solve 1) by kidding around with answers I found here, especially the mdframed package. But how would I define my own command to avoid repeating the style markup over and over again?

For 2) I thought about piggybacking the theorem system. Would that be a viable way to go?

(And sorry for maybe badly mixing up latex terminology. I am currently in the process of learning the benefits of the whole system by taking a deep jump into it and holding on to everything that seems useful to me.)

Answer 1

Replace the \jobname.tex with your cpp example file

\documentclass{article}
\usepackage{listings}
\renewcommand\lstlistingname{Example}
\renewcommand\lstlistlistingname{Examples}

\newcommand\myExa[3][]{%
\lstinputlisting[language=C++,basicstyle=\small,#1]{#2}
  #3}
\begin{document}

\myExa[label=foo,caption=foobar]{\jobname.tex}{%
  \begin{equation}matrix * (x * x\_factor) = right\end{equation}}

\myExa[label=bar,caption=foobarbaz]{\jobname.tex}{%
  \begin{quotation}Some nonsense text here\end{quotation}}

as shown in Example~\ref{foo} and in Example~\ref{bar} \ldots

\lstlistoflistings

\end{document}