Bug 20130

On Mon, 24 Jul 2000 at 00:33:45 +0200, Udo Erdelhoff wrote:
> >Number:         20130
> >Category:       docs
> >Synopsis:       Entities missing from doc/share/sgml/man-refs.ent
> >Confidential:   no
> >Severity:       non-critical
> >Priority:       medium
> >Responsible:    freebsd-doc
> >State:          open

[snip..]

> >Description:
> 
> People writing documentation for the FDP are supposed to use entities
> in the form &man.foo.1; to refer to system commands etc.
> /usr/share/doc/man contains about 3500 manpages (entities needed),
> man-refs.ent contains 220 entities.

I think the major reason for this is that a) stuff that's needed can be
added when a document is written, and b) it keeps the file size down.
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.

- jim

-- 
/* jim mock - berkeley software design, inc - open source division */
/* documentation manager - jim@FreeBSD.org - jim@luna.osd.bsdi.com */

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.

Comment 3 Jim Mock 2000-07-26 21:04:28 UTC

State Changed
From-To: open->closed

Committed, thanks!