From owner-freebsd-doc@FreeBSD.ORG Sun Apr 4 12:30:40 2004 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 7009C16A4CF; Sun, 4 Apr 2004 12:30:40 -0700 (PDT) Received: from shaft.techsupport.co.uk (shaft.techsupport.co.uk [212.250.77.214]) by mx1.FreeBSD.org (Postfix) with ESMTP id 2EDA543D1F; Sun, 4 Apr 2004 12:30:40 -0700 (PDT) (envelope-from setantae@submonkey.net) Received: from cpc2-cdif3-6-0-cust204.cdif.cable.ntl.com ([81.103.67.204] helo=shrike.submonkey.net ident=mailnull) by shaft.techsupport.co.uk with esmtp (TLSv1:DHE-RSA-AES256-SHA:256) (Exim 4.31; FreeBSD) id 1BADKJ-0005aT-0b; Sun, 04 Apr 2004 20:30:39 +0100 Received: from setantae by shrike.submonkey.net with local (Exim 4.31; FreeBSD) id 1BADKH-0007pc-AJ; Sun, 04 Apr 2004 20:30:37 +0100 Date: Sun, 4 Apr 2004 20:30:37 +0100 From: Ceri Davies To: "Simon L. Nielsen" , freebsd-doc@freebsd.org Message-ID: <20040404193037.GE364@submonkey.net> Mail-Followup-To: Ceri Davies , "Simon L. Nielsen" , freebsd-doc@freebsd.org References: <20040404134413.GB2933@zaphod.nitro.dk> <20040404161630.GB39330@sumuk.de> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="AH+kv8CCoFf6qPuz" Content-Disposition: inline In-Reply-To: <20040404161630.GB39330@sumuk.de> X-PGP: finger ceri@FreeBSD.org User-Agent: Mutt/1.5.4i Sender: Ceri Davies Subject: Re: Glossary [was: docs/64144: [patch] document procedure to add a new ports category to Committer's Guide] X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 04 Apr 2004 19:30:40 -0000 --AH+kv8CCoFf6qPuz Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sun, Apr 04, 2004 at 06:16:30PM +0200, Martin Heinen wrote: > On Sun, Apr 04, 2004 at 03:44:14PM +0200, Simon L. Nielsen wrote: > > On 2004.04.02 02:27:26 +0100, Ceri Davies wrote: > >=20 > > > Regarding the glossary, how does everyone think that's working out? I > > > notice that it's been short of attention recently and wanted to check > > > that people still think it's a nice idea before I do some work on it. > >=20 > > Even though it hasn't been getting much attention I still think it's a > > very good idea. >=20 > OK, that's good news. > > > stylesheets to create links to the glossary term for firstterm and > > > acronym elements > >=20 > > That sounds like a real neat idea. Acronyms can appear many times on > > one page, so perhaps only the first occurrence on a page should be > > marked up with a link. Eg. like only the first occurrence a trademark > > on a page gets the trademark symbol. >=20 > Linking to the glossary might be a bad idea. As with > footnotes, linking will distract the reader. New items > should be explained on the first occurrence; I fear that > adding links will move the definition of important terms > solely to the glossary. That's a valid concern that hadn't occurred to me. Perhaps it would be better to warn when a firstterm or acronym is missing a corresponding glossary entry (or just do nothing?). > The glossary should enable the reader to look up important > terms without having to read a whole chapter. When I start > to read a book, I will skim over the glossary first. > While reading the book, I tend to ignore the glossary, > but often return to it afterwards. >=20 > The glossary should point the reader to relevant > chapters of the Handbook. For example, when > explaining ports, the glossary could link back > to the chapter "Packages and Ports". That should also be possible - I'm not %100 percent on how, but I'm confident that it wouldn't be very difficult once I get going. Ceri --=20 --AH+kv8CCoFf6qPuz Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.4 (FreeBSD) iD8DBQFAcGJdocfcwTS3JF8RAmztAJ9UoJ9dcTsMJROVN+OP6JGYGa5tOACbBrML PA7HwBPfpBrRr+mjctuB7yQ= =D6Dk -----END PGP SIGNATURE----- --AH+kv8CCoFf6qPuz--