diff --git a/Doc/doc/doc.tex b/Doc/doc/doc.tex
index 4bb2a641983..df6576fef5b 100644
--- a/Doc/doc/doc.tex
+++ b/Doc/doc/doc.tex
@@ -778,7 +778,10 @@ This \UNIX\ is also followed by a space.
     \begin{macrodesc}{deprecated}{\p{version}\p{what to do}}
       Declare whatever is being described as being deprecated starting 
       with release \var{version}.  The text given as \var{what to do}
-      should recommend something to use instead.
+      should recommend something to use instead.  It should be
+      complete sentences.  The entire deprecation notice will be
+      presented as a separate paragraph; it should either preceed or
+      succeed the description of the deprecated feature.
     \end{macrodesc}
 
     \begin{macrodesc}{dfn}{\p{term}}