Add a new environment for whole-paragraph (or longer) notes & warnings.

Doc/doc/doc.tex

@@ -1010,6 +1010,25 @@ This \UNIX\ is also followed by a space.
     \end{macrodesc}
 
 
+  \subsection{Miscellaneous Text Markup \label{misc-text-markup}}
+
+  In addition to the inline markup, some additional ``block'' markup
+  is defined to make it easier to bring attention to various bits of
+  text.  The markup described here serves this purpose, and is
+  intended to be used when marking one or more paragraphs or other
+  block constructs (such as \env{verbatim} environments).
+
+  \begin{envdesc}{notice}{\op{type}}
+    Label some paragraphs as being worthy of additional attention from
+    the reader.  What sort of attention is warrented can be indicated
+    by specifying the \var{type} of the notice.  The only values
+    defined for \var{type} are \code{note} and \code{warning}; these
+    are equivalent in intent to the inline markup of the same name.
+    If \var{type} is omitted, \code{note} is used.  Additional values
+    may be defined in the future.
+  \end{envdesc}
+
+
   \subsection{Module-specific Markup \label{module-markup}}
 
   The markup described in this section is used to provide information

Doc/perl/python.perl

@@ -236,17 +236,36 @@ sub do_cmd_textbf{
     return use_wrappers(@_[0], '<b>', '</b>'); }
 sub do_cmd_textit{
     return use_wrappers(@_[0], '<i>', '</i>'); }
+# This can be changed/overridden for translations:
+%NoticeNames = ('note' => 'Note:',
+                'warning' => 'Warning:',
+                );
+
 sub do_cmd_note{
+    my $label = $NoticeNames{'note'};
     return use_wrappers(
         @_[0],
-        "<span class=\"note\"><b class=\"label\">Note:</b>\n",
+        "<span class=\"note\"><b class=\"label\">$label</b>\n",
         '</span>'); }
 sub do_cmd_warning{
+    my $label = $NoticeNames{'warning'};
     return use_wrappers(
         @_[0],
-        "<span class=\"warning\"><b class=\"label\">Warning:</b>\n",
+        "<span class=\"warning\"><b class=\"label\">$label</b>\n",
         '</span>'); }
 
+sub do_env_notice{
+    local($_) = @_;
+    my $notice = next_optional_argument();
+    if (!$notice) {
+        $notice = 'note';
+    }
+    my $label = $NoticeNames{$notice};
+    return ("<div class=\"$notice\"><b class=\"label\">$label</b>\n"
+            . $_
+            . '</div>');
+}
+
 sub do_cmd_moreargs{
     return '...' . @_[0]; }
 sub do_cmd_unspecified{

Doc/texinputs/python.sty

@@ -919,8 +919,13 @@
   \end{tabular}
 }
 
-\newcommand{\note}[1]{\strong{Note:} #1}
-\newcommand{\warning}[1]{\strong{Warning:} #1}
+\newcommand{\py@noticelabel@note}{Note:}
+\newcommand{\py@noticelabel@warning}{Warning:}
+\newenvironment{notice}[1][note]{
+  \par\strong{\csname py@noticelabel@#1\endcsname}
+}{}
+\newcommand{\note}[1]{\strong{\py@noticelabel@note} #1}
+\newcommand{\warning}[1]{\strong{\py@noticelabel@warning} #1}
 
 % Deprecation stuff.
 % Should be extended to allow an index / list of deprecated stuff.  But