Date: Wed, 8 Aug 2001 02:50:57 +0100 From: Nik Clayton <nik@freebsd.org> To: Murray Stokely <murray.stokely@windriver.com> Cc: freebsd-doc@FreeBSD.org Subject: Re: rethinking man page references in the Handbook Message-ID: <20010808025057.I23891@canyon.nothing-going-on.org> In-Reply-To: <20010807170037.O23183@windriver.com>; from murray.stokely@windriver.com on Tue, Aug 07, 2001 at 05:00:37PM -0700 References: <20010807170037.O23183@windriver.com>
next in thread | previous in thread | raw e-mail | index | archive | help
--ev7mvGV+3JQuI2Eo Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Tue, Aug 07, 2001 at 05:00:37PM -0700, Murray Stokely wrote: > 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. >=20 > 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. Put me down as preferring #2. > 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). It should be possible to auto-generate this using a bit of DSSSL. > 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. What do you find distracting? The number of links that are generated in the HTML output, or the proliferation of parentheses? If it's the former then that's some DSSSL that checks to see whether there's been any other <citerefentry> elements to the same man page in the outermost enclosing element (probably up to the <sect1> level) and omits the link if there have been. If it's the latter then it's a probably a style issue. Can you nominate a sample paragraph that you think goes over the top? N --=20 FreeBSD: The Power to Serve http://www.freebsd.org/ FreeBSD Documentation Project http://www.freebsd.org/docproj/ --- 15B8 3FFC DDB4 34B0 AA5F 94B7 93A8 0764 2C37 E375 --- --ev7mvGV+3JQuI2Eo Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.6 (FreeBSD) Comment: For info see http://www.gnupg.org iEYEARECAAYFAjtwmwAACgkQk6gHZCw343UTGACfXEnn2otHg/X1vP6KeuJe7cTr z4AAn1rk5Tqc2+1PGG4adk9C/I7rZOo8 =ZAHV -----END PGP SIGNATURE----- --ev7mvGV+3JQuI2Eo-- 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?20010808025057.I23891>