Date: Tue, 07 Aug 2001 17:42:33 -0700 From: Dima Dorfman <dima@unixfreak.org> To: Murray Stokely <murray.stokely@windriver.com> Cc: freebsd-doc@FreeBSD.org Subject: Re: rethinking man page references in the Handbook Message-ID: <20010808004238.9A9E13E31@bazooka.unixfreak.org> In-Reply-To: <20010807170037.O23183@windriver.com>; from murray.stokely@windriver.com on "Tue, 7 Aug 2001 17:00:37 -0700"
next in thread | previous in thread | raw e-mail | index | archive | help
Murray Stokely <murray.stokely@windriver.com> 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 <command> > 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 <command>. 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010808004238.9A9E13E31>