Guide to LaTeX (4th Edition) (Tools and Techniques

8.4. User-defined environments 197
which produces the desired result.
This example does not appear to be very practical since the same
effect can be achieved with less typing by adding \small\itshape at
the beginning of the quote environment. However, it is more consistent
with the concept of logical markup introduced in Section 1.2.2. This
special quotation environment may be used throughout the document
without worrying about its typographical details, which are specified in
its definition located in the document preamble. Doing it this way not
only ensures consistency, it also simplifies any substitution that may be
demanded later by a typographical expert.
Let us expand the previous example somewhat as follows:
\newcounter{com}
\newenvironment{comment}
{\noindent\slshape Comment:\begin{quote}\small\itshape}
{\stepcounter{com}\hfill(\arabic{com})\end{quote}}
where now beg def contains the text and commands
\noindent\slshape Comment:\begin{quote}\small\itshape
and end def is
\stepcounter{com}\hfill(\arabic{com})\end{quote}
where com is a user counter created by the \newcounter command. Now
since the command \begin{comment} inserts the text beg def at the start
of the environment and \end{comment} the text end def at the finish, it
should be clear that
\begin{comment} This is a comment.
Comments should ...
... in round parentheses.
\end{comment}
will generate the following type of structure:
Comment:
This is a comment. Comments should be preceded by the word Comment:
the text being in a small, italic typeface, indented on both sides
from the main margins. Each comment receives a running comment
number at the lower right in round parentheses. (1)
The user should examine the sequence of commands with the replacement
text of this example to see precisely what the effect of this
environment is. Two weaknesses should become apparent: what would
happen if \begin{comment} were called in the middle of a line of text
without a blank line before, and what would happen if the last line of the
comment text were so long that there was no more room for the running
comment number on the same line?
The following revision removes these two problems: