; Improve recently added documentation

* etc/NEWS:
* doc/lispref/tips.texi (Documentation Tips): Improve and clarify
recently-added documentation of man page references.

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 1ea439b531b3de2b882c024bd0d2f4a2c18640df..e56ddf3c288a76b3a9c7df296e3464daa7d69b1f 100644 (file)
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -760,9 +760,15 @@ man page, preceded by @samp{Man page}, @samp{man page}, or @samp{man
 page for}.  For example,
 
 @smallexample
-See the man page `chmod' for details.
+See the man page `chmod(1)' for details.
 @end smallexample
 
+@noindent
+The Info documentation is always preferable to man pages, so be sure
+to link to an Info manual where available.  For example,
+@command{chmod} is documented in the GNU Coreutils manual, so it is
+better to link to that instead of the man page.
+
 To link to a customization group, write the single-quoted name of the
 group, preceded by @samp{customization group} (the first character in
 each word is case-insensitive).  For example,

diff --git a/etc/NEWS b/etc/NEWS
index 40e85c67c0589edf935b65c6ee99386cfee670f8..115808d05805fd692937cd5e0521b2a785b4b198 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3710,7 +3710,7 @@ customization group.
 
 +++
 ** Doc strings can now link to man pages.
-Text like "man page `chmod'" will be made into a button.  When
+Text like "man page `chmod(1)'" will be made into a button.  When
 clicked, it will open a Man mode buffer displaying that man page.
 
 +++