From owner-freebsd-doc Sun Aug 12 14: 5:41 2001 Delivered-To: freebsd-doc@freebsd.org Received: from blueyonder.co.uk (pcow024o.blueyonder.co.uk [195.188.53.126]) by hub.freebsd.org (Postfix) with ESMTP id ABD9537B406; Sun, 12 Aug 2001 14:05:37 -0700 (PDT) (envelope-from jfm@blueyonder.co.uk) Received: from lexx.my.domain ([62.31.194.122]) by blueyonder.co.uk with Microsoft SMTPSVC(5.5.1877.687.68); Sun, 12 Aug 2001 22:05:43 +0100 From: John Murphy To: Murray Stokely Cc: doc@freebsd.org Subject: Re: rethinking man page references in the Handbook Date: Sun, 12 Aug 2001 22:07:30 +0100 Organization: poor Reply-To: jfm@blueyonder.co.uk Message-ID: References: <20010807170037.O23183@windriver.com> <20010808025057.I23891@canyon.nothing-going-on.org> <20010810140256.D28591@windriver.com> In-Reply-To: <20010810140256.D28591@windriver.com> X-Mailer: Forte Agent 1.8/32.548 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable 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 wrote: >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-program= s.html > (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. ISWYM: Viewing with IE5.5, man links are colored, underlined _and_ show = the section number in brackets. I can switch off the underlining in the = browser, but I'd hope not to see underlined URLs etc. in the printed Handbook. = They seem distracting in Mr. Mittelstaedt's book. Perhaps the hyperlinked versions need nothing more than to be a link, = with the sektion number not shown. I can't think of a better way to express a manual reference in the printed (monochrome) target, than a bracketed = number; though the URL to which you refer is (hopefully) the most tedious case. OTOH: Maybe a different type face for manable words would look cool, for the printed version, if stated in the "Conventions used in this Book" = section. John. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message