diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex
index 85eb3f3c154..00a465f0d5c 100644
--- a/Doc/doc/doc.tex
+++ b/Doc/doc/doc.tex
@@ -859,6 +859,14 @@ This \UNIX\ is also followed by a space.
       The name of a Usenet newsgroup.
     \end{macrodesc}
 
+    \begin{macrodesc}{note}{\p{text}}
+      An especially important bit of information about an API that a
+      user should be aware of when using whatever bit of API the
+      note pertains to.  This should be the last thing in the
+      paragraph as the end of the note is not visually marked in
+      any way.
+    \end{macrodesc}
+
     \begin{macrodesc}{pep}{\p{number}}
       A reference to a Python Enhancement Proposal.  This generates
       appropriate index entries.  The text \samp{PEP \var{number}} is
@@ -989,6 +997,15 @@ This \UNIX\ is also followed by a space.
       explanation makes sense and may vary as needed.
     \end{macrodesc}
 
+    \begin{macrodesc}{warning}{\p{text}}
+      An important bit of information about an API that a user should
+      be very aware of when using whatever bit of API the warning
+      pertains to.  This should be the last thing in the paragraph as
+      the end of the warning is not visually marked in any way.  This
+      differs from \macro{note} in that it is recommended over
+      \macro{note} for information regarding security.
+    \end{macrodesc}
+
 
   \subsection{Module-specific Markup \label{module-markup}}
 
diff --git a/Doc/perl/python.perl b/Doc/perl/python.perl
index 13e7aac3207..10dcdd0c00e 100644
--- a/Doc/perl/python.perl
+++ b/Doc/perl/python.perl
@@ -236,6 +236,16 @@ sub do_cmd_textbf{
     return use_wrappers(@_[0], '<b>', '</b>'); }
 sub do_cmd_textit{
     return use_wrappers(@_[0], '<i>', '</i>'); }
+sub do_cmd_note{
+    return use_wrappers(
+        @_[0],
+        "<span class=\"note\"><b class=\"label\">Note:</b>\n",
+        '</span>'); }
+sub do_cmd_warning{
+    return use_wrappers(
+        @_[0],
+        "<span class=\"warning\"><b class=\"label\">Warning:</b>\n",
+        '</span>'); }
 
 sub do_cmd_moreargs{
     return '...' . @_[0]; }
diff --git a/Doc/texinputs/python.sty b/Doc/texinputs/python.sty
index 9fa56cd66ef..0244466b4eb 100644
--- a/Doc/texinputs/python.sty
+++ b/Doc/texinputs/python.sty
@@ -881,6 +881,9 @@
   \end{center}
 }
 
+\newcommand{\note}[1]{\strong{Note:} #1}
+\newcommand{\warning}[1]{\strong{Warning:} #1}
+
 % Deprecation stuff.
 % Should be extended to allow an index / list of deprecated stuff.  But
 % there's a lot of stuff that needs to be done to make that automatable.
diff --git a/Doc/tools/sgmlconv/conversion.xml b/Doc/tools/sgmlconv/conversion.xml
index 1944b1f7849..248c9c1ccc6 100644
--- a/Doc/tools/sgmlconv/conversion.xml
+++ b/Doc/tools/sgmlconv/conversion.xml
@@ -55,6 +55,12 @@
     <content/>
     </macro>
   <macro name="shortversion"/>
+  <macro name="note">
+    <content/>
+    </macro>
+  <macro name="warning">
+    <content/>
+    </macro>
   <!-- These are broken:  we need to re-order the optional and required
        parameters, making the optional parameter the content for the
        element.  latex2esis.py is not powerful enough to handle this.