From simon@arthur.nitro.dk  Tue May 20 04:36:10 2003
Return-Path: <simon@arthur.nitro.dk>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 37B4D37B401
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 20 May 2003 04:36:10 -0700 (PDT)
Received: from arthur.nitro.dk (port324.ds1-khk.adsl.cybercity.dk [212.242.113.79])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 8FBB043F93
	for <FreeBSD-gnats-submit@freebsd.org>; Tue, 20 May 2003 04:36:09 -0700 (PDT)
	(envelope-from simon@arthur.nitro.dk)
Received: by arthur.nitro.dk (Postfix, from userid 1000)
	id 1F06D10BF84; Tue, 20 May 2003 13:36:08 +0200 (CEST)
Message-Id: <20030520113608.1F06D10BF84@arthur.nitro.dk>
Date: Tue, 20 May 2003 13:36:08 +0200 (CEST)
From: Simon L.Nielsen <simon@nitro.dk>
Reply-To: Simon L.Nielsen <simon@nitro.dk>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [patch] Add note about manref/command usage to FDP
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>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:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Tue May 20 04:40:04 PDT 2003
>Closed-Date:    Tue May 20 14:19:05 PDT 2003
>Last-Modified:  Tue May 20 14:19:05 PDT 2003
>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>&amp;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:
State-Changed-From-To: open->closed 
State-Changed-By: ceri 
State-Changed-When: Tue May 20 14:18:51 PDT 2003 
State-Changed-Why:  
Committed, thanks again. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=52467 
>Unformatted:
