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>
index | next in thread | previous in thread | raw e-mail
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. >> >> 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. >> >> 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.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 messagehelp
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?qqqdntcv4bqhnghjj6sq6jvqlqa89sntsr>