Date: Sun, 4 Apr 2004 20:30:37 +0100 From: Ceri Davies <ceri@submonkey.net> To: "Simon L. Nielsen" <simon@freebsd.org>, freebsd-doc@freebsd.org Subject: Re: Glossary [was: docs/64144: [patch] document procedure to add a new ports category to Committer's Guide] Message-ID: <20040404193037.GE364@submonkey.net> In-Reply-To: <20040404161630.GB39330@sumuk.de> References: <20040404134413.GB2933@zaphod.nitro.dk> <20040404161630.GB39330@sumuk.de>
next in thread | previous in thread | raw e-mail | index | archive | help
--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 > <aol text=3D"me too"/> 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--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20040404193037.GE364>