From owner-freebsd-doc Tue Aug 7 16:54:34 2001 Delivered-To: freebsd-doc@freebsd.org Received: from mao.stokely.org (mao.stokely.org [65.84.64.228]) by hub.freebsd.org (Postfix) with ESMTP id 45FB137B401 for ; Tue, 7 Aug 2001 16:54:31 -0700 (PDT) (envelope-from murray@stokely.org) Received: by mao.stokely.org (Postfix, from userid 2074) id 2A8B04B658; Tue, 7 Aug 2001 17:00:37 -0700 (PDT) Date: Tue, 7 Aug 2001 17:00:37 -0700 From: Murray Stokely To: freebsd-doc@FreeBSD.org Subject: rethinking man page references in the Handbook Message-ID: <20010807170037.O23183@windriver.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i X-GPG-Key-ID: 1024D/0E451F7D X-GPG-Key-Fingerprint: E2CA 411D DD44 53FD BB4B 3CB5 B4D7 10A2 0E45 1F7D Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org I think there are two problems with the way we currently refer to man pages in the FreeBSD Handbook. First of all, there is no consistency to how we refer the user to a man page for more information : 1) Please see sio(4). 2) For more information see sio(4). 3) For more information see the sio(4) man page. 4) For more information see the man page sio(4). 5) For more information see the sio(4) manual page. It wouldn't be too much work to pick one of these and standardize on it throughout the Handbook. #1 definitely doesn't work for the printed output, so those need to be changed anyway. Do we want to add a standard section to the back of each chapter that lists the relevant man pages that contain more information? Or should we continue to add these in an ad-hoc fashion throughout most of the book (with at least a little more standardization). The second problem is that we simply use &man.cmd.sec; entities too often. There are many paragraphs that contain the same man entity 4-5 times which is very distracting. These entities are very useful but I think that we should only use them them the first time that a command is mentioned in a section, and then markup the command in for future references in that paragraph and following ones. Thoughts? - Murray To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message