From owner-freebsd-doc Tue Aug 7 17:42:55 2001 Delivered-To: freebsd-doc@freebsd.org Received: from bazooka.unixfreak.org (bazooka.unixfreak.org [63.198.170.138]) by hub.freebsd.org (Postfix) with ESMTP id 691C037B401 for ; Tue, 7 Aug 2001 17:42:50 -0700 (PDT) (envelope-from dima@unixfreak.org) Received: by bazooka.unixfreak.org (Postfix, from userid 1000) id 9A9E13E31; Tue, 7 Aug 2001 17:42:38 -0700 (PDT) Received: from bazooka.unixfreak.org (localhost [127.0.0.1]) by bazooka.unixfreak.org (Postfix) with ESMTP id 8D0033C12D; Tue, 7 Aug 2001 17:42:38 -0700 (PDT) To: Murray Stokely Cc: freebsd-doc@FreeBSD.org Subject: Re: rethinking man page references in the Handbook In-Reply-To: <20010807170037.O23183@windriver.com>; from murray.stokely@windriver.com on "Tue, 7 Aug 2001 17:00:37 -0700" Date: Tue, 07 Aug 2001 17:42:33 -0700 From: Dima Dorfman Message-Id: <20010808004238.9A9E13E31@bazooka.unixfreak.org> 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 Murray Stokely writes: > 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. I'd prefer to see them called "manual pages" over "man pages"; the latter may not be very clear to some people, since "man" is a common word by itself, and not everybody can immediately make the man->manual connection. > 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. Nobody has ever defined when one should use a manual page entity, and when one should use . I've seen this asked on the list before, and the answer is generally "whichever you want". What you suggest sounds pretty good. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message