From owner-freebsd-doc Fri Aug 10 13:56:56 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 F1EEB37B406; Fri, 10 Aug 2001 13:56:52 -0700 (PDT) (envelope-from murray@stokely.org) Received: by mao.stokely.org (Postfix, from userid 2074) id 8C02A4B65D; Fri, 10 Aug 2001 14:02:56 -0700 (PDT) Date: Fri, 10 Aug 2001 14:02:56 -0700 From: Murray Stokely To: Nik Clayton Cc: freebsd-doc@freebsd.org Subject: Re: rethinking man page references in the Handbook Message-ID: <20010810140256.D28591@windriver.com> References: <20010807170037.O23183@windriver.com> <20010808025057.I23891@canyon.nothing-going-on.org> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-md5; protocol="application/pgp-signature"; boundary="UlVJffcvxoiEqYs2" Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <20010808025057.I23891@canyon.nothing-going-on.org>; from nik@freebsd.org on Wed, Aug 08, 2001 at 02:50:57AM +0100 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 --UlVJffcvxoiEqYs2 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Wed, Aug 08, 2001 at 02:50:57AM +0100, Nik Clayton wrote: > > 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. >=20 > What do you find distracting? The number of links that are generated in > the HTML output, or the proliferation of parentheses? Both. > If it's the former then that's some DSSSL that checks to see whether > there's been any other elements to the same man page in > the outermost enclosing element (probably up to the level) and > omits the link if there have been. >=20 > 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? Yep, how about this one : http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/backup-programs.h= tml (top of page) I think that most of the man entities here should be replaced with s. Its distracting to read this section online or in print format. - Murray --UlVJffcvxoiEqYs2 Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.6 (SunOS) Comment: For info see http://www.gnupg.org iD8DBQE7dEv/tNcQog5FH30RAvRMAJ4wAydC0FUsMEQi+jQPZ3nn0mPoVACdH0ck te45EFBy1mJrydn2QVCfOrg= =27Gr -----END PGP SIGNATURE----- --UlVJffcvxoiEqYs2-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message