From owner-freebsd-doc Mon Jul 24 13:10: 7 2000 Delivered-To: freebsd-doc@freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.ORG [204.216.27.21]) by hub.freebsd.org (Postfix) with ESMTP id 4195237BD41 for ; Mon, 24 Jul 2000 13:10:04 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.9.3/8.9.2) id NAA97283; Mon, 24 Jul 2000 13:10:04 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Date: Mon, 24 Jul 2000 13:10:04 -0700 (PDT) Message-Id: <200007242010.NAA97283@freefall.freebsd.org> To: freebsd-doc@freebsd.org Cc: From: Udo Erdelhoff Subject: Re: docs/20130: Entities missing from doc/share/sgml/man-refs.ent Reply-To: Udo Erdelhoff Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org The following reply was made to PR docs/20130; it has been noted by GNATS. From: Udo Erdelhoff To: Jim Mock Cc: FreeBSD-gnats-submit@FreeBSD.ORG Subject: Re: docs/20130: Entities missing from doc/share/sgml/man-refs.ent Date: Mon, 24 Jul 2000 21:43:46 +0200 Jim, > I think the major reason for this is that > a) stuff that's needed can be added when a document is written, and right now, only a few people use the FDP toolchain and the "one entity at a time" policy seems to work. The reason for the tools behind the patch was the following cycle: 1) I want to/have to use &man.foo.x; 2) Switch to another window, check man-refs.ent 3) Swear, go to the start of the document, copy&paste a definition and add the entity I need 4) Go back and continue writing or 1) "I'm sure I can use &man.foo.x;" 2) make 3) "jade... general entity man.foo.x not defined... 4) open document, add the definition, go to step 2 It's extremly frustrating (not to mention a waste of time) that almost every use of &man.foo.x causes a loop through one of this cycles. Ok, that's the price for going where nobody has gone before (writing a PPPoE-HOWTO). But that's only the first step. I've finished my document and I have a couple entity definitions in it. That's just a bandaid, so I'll have to write a PR, somebody has to read it, add the entities and commit the changes. I get the "entities added, thanks" mail and run cvsup to get the new man-refs.ent. But I can't remove my entity definitions unless I replace them with a . The current system (add when needed) works because almost all of the .sgml-files are either documents for the FreeBSD Documentation Project or translations of them; and they update their /usr/doc-trees regularily. If people start to use the tools outside this context, this system will break. > b) it keeps the file size down. 200 KByte are a small price to remove the problems outlined above. I was afraid that the build times would explode. Fortunately, that's not the case. > If we add entities for every single man page, chances are, we'll never > use at least half of them, so it's kind of overkill to have a huge, > bloated man-refs.ent file when it's not necessary. Hmm, using s/man page/command/ s/entities/man pages/ s/man-refs.ent/\/usr\/share\/man/ on your statement gives: "If we add man pages for every single command, chances are, we'll never use at least half of them, so it's kind of overkill to have a huge, bloated /usr/share/man file when it's not necessary." A similiar argument could be used against 90% of the ports, the files and directories in /usr/share/locale and most of the translation projects. All three exist for a good reason. /s/Udo -- Der Einsatz von M$-Mailsystemen ist sehr erfolgreich, aber leider vor allem bei der Verbreitung von Viren wie Melissa, Papa oder explore.zip. Dies ist durchaus auch in der Architektur dieser Software begruendet. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message