From ue@nathan.ruhr.de  Sun Jul 23 15:33:38 2000
Return-Path: <ue@nathan.ruhr.de>
Received: from mail.ruhr.de (in-ruhr2.ruhr.de [141.39.224.60])
	by hub.freebsd.org (Postfix) with SMTP id 7738337BADB
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 23 Jul 2000 15:33:33 -0700 (PDT)
	(envelope-from ue@nathan.ruhr.de)
Received: (qmail 31097 invoked by alias); 23 Jul 2000 22:35:29 -0000
Received: (from ue@localhost)
	by nathan.ruhr.de (8.9.3/8.9.3) id AAA91863;
	Mon, 24 Jul 2000 00:33:45 +0200 (CEST)
	(envelope-from ue)
Message-Id: <200007232233.AAA91863@nathan.ruhr.de>
Date: Mon, 24 Jul 2000 00:33:45 +0200 (CEST)
From: Udo Erdelhoff <ue@nathan.ruhr.de>
Reply-To: ue@nathan.ruhr.de
To: FreeBSD-gnats-submit@freebsd.org
Subject: Entities missing from doc/share/sgml/man-refs.ent
X-Send-Pr-Version: 3.2

>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:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Jul 23 15:40:00 PDT 2000
>Closed-Date:    Wed Jul 26 13:04:28 PDT 2000
>Last-Modified:  Wed Jul 26 13:04:59 PDT 2000
>Originator:     Udo Erdelhoff
>Release:        FreeBSD 5.0-CURRENT i386
>Organization:
Association of frustrated authors armed with Perl
>Environment:

doc/share/sgml/man-refs.ent rev. 1.43

>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.

>How-To-Repeat:

Try to use &man.ng_ether.4; in a document for the FDP.
Or &man.netgraph.4;
Or &man.ipfw.4; (&man.ipfw.8; works, but I needed a reference to the
kernel interface)

>Fix:

A patch adding the entities from /usr/share/doc can be found at:
http://www.ruhr.de/home/nathan/FreeBSD/entity-diff.gz
The patch was not included because of its size (29 KByte).
MD5 (entity-diff.gz) = 1bdf3722855db56495ce13aeee6a140f

A port containing the perl scripts used to create and sort the entities
will follow in the next days (Where's a port Makefile template when I
need one?)

The distfile is already in place at
http://www.ruhr.de/home/nathan/FreeBSD/met-1.0.tar.gz
MD5 (met-1.0.tar.gz) = 4fadc7c6df1a62491bea7e98f62c125b
(Manual Entity Toolkit)

>Release-Note:
>Audit-Trail:

From: Jim Mock <jim@luna.osd.bsdi.com>
To: Udo Erdelhoff <ue@nathan.ruhr.de>
Cc: FreeBSD-gnats-submit@FreeBSD.ORG
Subject: Re: docs/20130: Entities missing from doc/share/sgml/man-refs.ent
Date: Sun, 23 Jul 2000 22:49:26 -0700

 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 */
 

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.
 
State-Changed-From-To: open->closed 
State-Changed-By: jim 
State-Changed-When: Wed Jul 26 13:04:28 PDT 2000 
State-Changed-Why:  
Committed, thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=20130 
>Unformatted:
