docs/52467: [patch] Add note about manref/command usage to FDP

[Simon L.Nielsen]

>Number:         52467
>Category:       docs
>Synopsis:       [patch] Add note about manref/command usage to FDP
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Tue May 20 04:40:04 PDT 2003
>Closed-Date:
>Last-Modified:
>Originator:     Simon L. Nielsen
>Release:        FreeBSD 4.8-STABLE i386
>Organization:
>Environment:
>Description:
Add a description of when to use a manual page reference and when to
use <command> to markup commands in SGML docbook.

This was discussed on FreeBSD-doc in the thread starting with
http://www.freebsd.org/cgi/getmsg.cgi?fetch=125961+0+current/freebsd-doc

>How-To-Repeat:
>Fix:
--- doc-fdp-manref-command.patch begins here ---
Index: sgml-markup/chapter.sgml
===================================================================
RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v
retrieving revision 1.53
diff -u -d -r1.53 chapter.sgml
--- sgml-markup/chapter.sgml	26 Apr 2003 07:40:04 -0000	1.53
+++ sgml-markup/chapter.sgml	20 May 2003 13:25:57 -0000
@@ -1741,6 +1741,14 @@
 	<para>Use <sgmltag>option</sgmltag> to mark up a command's
 	  options.</para>
 
+	<para>When referring to the same command multiple times in
+	  close proximity it preferred to use the
+	  <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal>
+	  notation to markup the first reference and use
+	  <sgmltag>command</sgmltag> to markup subsequent references.
+	  This makes the generated output, especially HTML, appear
+	  visually better.</para>
+
 	<para>This can be confusing, and sometimes the choice is not always
 	  clear.  Hopefully this example makes it clearer.</para>
 
--- doc-fdp-manref-command.patch ends here ---


>Release-Note:
>Audit-Trail:
>Unformatted: