Date: Mon, 24 Jul 2000 13:10:04 -0700 (PDT) From: Udo Erdelhoff <ue@nathan.ruhr.de> To: freebsd-doc@freebsd.org Subject: Re: docs/20130: Entities missing from doc/share/sgml/man-refs.ent Message-ID: <200007242010.NAA97283@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
The following reply was made to PR docs/20130; it has been noted by GNATS.
From: Udo Erdelhoff <ue@nathan.ruhr.de>
To: Jim Mock <jim@luna.osd.bsdi.com>
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 <!-- needs man-refs.ent v3.14 or higher -->.
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200007242010.NAA97283>