Date: Sun, 12 Aug 2001 22:07:30 +0100 From: John Murphy <jfm@blueyonder.co.uk> To: Murray Stokely <murray@FreeBSD.org> Cc: doc@freebsd.org Subject: Re: rethinking man page references in the Handbook Message-ID: <qqqdntcv4bqhnghjj6sq6jvqlqa89sntsr@4ax.com> In-Reply-To: <20010810140256.D28591@windriver.com> References: <20010807170037.O23183@windriver.com> <20010808025057.I23891@canyon.nothing-going-on.org> <20010810140256.D28591@windriver.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Murray Stokely <murray@FreeBSD.org> 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 <command> >> > 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 <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. >>=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 ><command>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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?qqqdntcv4bqhnghjj6sq6jvqlqa89sntsr>