master f82f3d6: ; Improve recently added documentation

[Eli Zaretskii]

branch: master
commit f82f3d62adcf40af754bb391e156ad836303a094
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Improve recently added documentation
    
    * etc/NEWS:
    * doc/lispref/tips.texi (Documentation Tips): Improve and clarify
    recently-added documentation of man page references.
---
 doc/lispref/tips.texi | 8 +++++++-
 etc/NEWS              | 2 +-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 1ea439b..e56ddf3 100644
--- 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 40e85c6..115808d 100644
--- 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.
 
 +++