`advise` Environment in listings package

Question

I was reading the documentation for the latex listings package and there are advises in it which look like so:

advise-environment in the listings documentation

I had a quick look in the source code for the documentation and it turns out that there is an advise environment:

\begin{advise}
\item Must I do that really?
    \advisespace
    Yes and no. Some books about programming say this is good.

It seems to be defined inside the package:

% \begin{environment}{advise}
% \begin{macro}{\advisespace}
% The environment uses |\@listi|.
%    \begin{macrocode}
 \def\advise{\par\list\labeladvise
    {\advance\linewidth\@totalleftmargin
     \@totalleftmargin\z@
     \@listi
     \let\small\footnotesize \small\sffamily
     \parsep \z@ \@plus\z@ \@minus\z@
     \topsep6\p@ \@plus1\p@\@minus2\p@
     \def\makelabel##1{\hss\llap{##1}}}}
\let\endadvise\endlist
%    \end{macrocode}
%    \begin{macrocode}
\def\advisespace{\hbox{}\qquad}
\def\labeladvise{$\to$}
%    \end{macrocode}
% \end{macro}
% \end{environment}

However, neither do I understand this code snippet nor do I get this to work (copy and paste does not work, and I do not know what the code in comments means).

Is there maybe an advise-package out there? Is there a way to get this piece of code working outside of the listings package? If so, how?

score 9 · Accepted Answer · edited Apr 13 '17 at 12:34

The code for advise is actually written as an environment, even though there's no \newenvironment syntax. That's because the author defined the start \advise and end \endadvise components separately. Regardless, advise is a list environment, and a list takes two arguments that specifies some of the parameters and labelling styles. Nowadays most people use packages to manipulate labels and spacing (like enumitem), but this can still be defined using the TeX fundamentals. For the specifics regarding \list, see source2e.pdf (section 56 List, and related environments, p 218). Here's an extract:

\list{<label>}{<commands>} ... \endlist

where <label> is \labeladvise and <commands> contain all the spacing and \makelabel commands/redefinitions.

The commented out code is a style for writing packages that are self-contained in terms of their code (.sty) and documentation (.tex and .pdf). Typically these packages are written as a .dtx & .ins pair, that is processed into various output files. See How do I install a .dtx file? or Can I convert a .dtx file to .tex file.

Here's an example using the code:

enter image description here

\documentclass{article}
\makeatletter
\def\advise{\par\list\labeladvise
  {\advance\linewidth\@totalleftmargin
   \@totalleftmargin\z@
   \@listi
   \let\small\footnotesize \small\sffamily
   \parsep \z@ \@plus\z@ \@minus\z@
   \topsep6\p@ \@plus1\p@\@minus2\p@
   \def\makelabel##1{\hss\llap{##1}}}}
\let\endadvise\endlist
\def\advisespace{\hbox{}\qquad}
\def\labeladvise{$\to$}
\makeatother
\begin{document}
\begin{advise}
  \item Must I do that really?
    \advisespace
    Yes and no. Some books about programming say this is good.
\end{advise}
\end{document}

Note the use of \makeatletter and \makeatother, since you're using @ as part of your macros. See What do \makeatletter and \makeatother do?

`advise` Environment in listings package

1 Answers1