From nobody@FreeBSD.org  Sun Feb 20 21:14:36 2000
Return-Path: <nobody@FreeBSD.org>
Received: from freefall.freebsd.org (freefall.FreeBSD.ORG [204.216.27.21])
	by hub.freebsd.org (Postfix) with ESMTP id 8683137BE70
	for <freebsd-gnats-submit@FreeBSD.org>; Sun, 20 Feb 2000 21:14:36 -0800 (PST)
	(envelope-from nobody@FreeBSD.org)
Received: (from nobody@localhost)
	by freefall.freebsd.org (8.9.3/8.9.2) id VAA81625;
	Sun, 20 Feb 2000 21:14:36 -0800 (PST)
	(envelope-from nobody@FreeBSD.org)
Message-Id: <200002210514.VAA81625@freefall.freebsd.org>
Date: Sun, 20 Feb 2000 21:14:36 -0800 (PST)
From: bobj@atlantic.net
Sender: nobody@FreeBSD.org
To: freebsd-gnats-submit@FreeBSD.org
Subject: Typos from Chapter 4 of FreeBSD Handbook
X-Send-Pr-Version: www-1.0

>Number:         16854
>Category:       docs
>Synopsis:       Typos from Chapter 4 of FreeBSD Handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    jim
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Feb 20 21:20:03 PST 2000
>Closed-Date:    Mon Feb 21 23:38:23 PST 2000
>Last-Modified:  Mon Feb 21 23:38:50 PST 2000
>Originator:     Bob Johnson
>Release:        www.freebsd.org as of 20 Feb 00 (P.M.)
>Organization:
>Environment:
n/a
>Description:
Found the following typos and other problems in the HTML version of 
The FreeBSD Handbook as published on www.freebsd.org.  URL references 
are to the web page in which a particular error is found (in this 
case they are all in http://www.freebsd.org/handbook/porting.html).

============

In URL http://www.freebsd.org/handbook/porting.html
Section 4.4.5.1. ldconfig 

"Anybody who does this will be shot and cut in 65,536 
pieces by a rusty knife and have is liver chopped out..."

The word "is" should probably be "his", unless you want 
to be non-gender-specific, in which case "their" is 
commonly used.

-------------

Same URL
Section 4.4.6. ELF support

"...we wish to unofficially support the 2.2 as long as 
possible."  

The 2.2 what?  The 2.2 ports?  The 2.2 binaries?  I think 
a word is missing here.  

-------------

Same URL
Section 4.4.9 Manpages

"Additionally ${PREFIX}/man/man8/alt-name.8.gz may or may-not be 
installed by your port."  

Change "may-not" to "may not".

------------

Same URL
Section 4.4.12. Info files 

"If your port installs any info documents, please follow this 
instructions so your port/package will correctly update the 
user's PREFIX/info/dir file."  

Change "this" to "these".

------------

Same URL
Section 4.4.13.5. Changing the names of files in the pkg subdirectory 

"This is especially useful when you are sharing the same pkg 
subdirectory among several ports or have to write to one of the 
above files (see writing to places other than WRKDIR for why it 
is a bad idea to write directly in to the pkg subdirectory."

Mismatched parentheses.  Need a closing paren before the 
period.

-----------

Same URL
Section 4.4.16. Do's and Dont's 

"Here is a list of common do's and dont's that you encounter 
during the porting process."  As mentioned in a previous 
typos submission, "Do's and Dont's" is not spelled correctly.
It should be "Dos and Don'ts", but you have to play games 
with fonts for it to make sense.

-----------

Same URL
Section 4.4.16.5. Differentiating operating systems and OS versions 

      3.3-RELEASE             
      3.3-STABLE 
      3.3-STABLE after adding mkstemps() to libc 
??-->
      4.0-CURRENT after 3/4 branch 
      4.0-CURRENT after change in dynamic linker handling 
      4.0-CURRENT after C++ constructor/destructor order change 

The list of values for __FreeBSD_version does not include 
entries for 3.4-RELEASE or 3.4-STABLE.

-----------

Same URL
Section 4.4.16.6. Writing something after bsd.port.mk 

In the list of variables the entry for PORTOBJFORMAT

"PORTOBJFORMAT    The object format of the system (aout or elf "

has no closing parenthesis.

-----------

Same URL
Same Section, 4.4.16.6. Writing something after bsd.port.mk 

"Here are some examples of things you can write after 
bsd.port.pre.mk; "

I would end this with a colon instead of a semicolon.
I'm pretty sure I would be correct in doing so...

-----------

Same URL
Section 4.4.16.22. If you are stuck... 

"Do look at existing examples and the bsd.port.mk file before 
asking us questions! ;) "  

Although it looks fine in plain text, this emoticon does not 
look right when rendered in italics on my browser.  
It needs a nose.  In other places it is rendered as ;-)

-----------

Same URL
Section 4.4.17. A Sample Makefile 

"[maintainer; *mandatory*!  This is the person (preferably 
with commit privileges) who a user can contact for questions 
and bug reports "

"who" should be "whom", although few people care these days.

-----------

Same URL
Section 4.4.18. Automated package list creation 

"If your port honours PREFIX (which it should) you can then 
install the port and create the package list. "

This uses the British spelling "honours".  I haven't noticed 
British usage in earlier sections, although perhaps I 
wasn't looking.  If consistency is considered important, 
someone should decide whether British or American spellings 
will be used, or perhaps create SGML tags that allow alternate 
spellings to be specified so that regional editions of the 
Handbook can be easily rendered.  Creating a tool to automate 
the search for words so affected would then also be handy.

-----------

Same URL
Section 4.4.19. Package Names 

"2. The name part should be all lowercases, except for a 
really large package (with lots of programs in it)."

I would say "all lowercase" rather than "all lowercases".

----------

Same URL
Section 4.4.20.1. Current list of categories 

"afterstep*     Ports to support AfterStep window manager "

Reads better as "Ports to support the Afterstep...".  Add 
the word "the".  Also, there should be a period at the end 
to be consistent with other entries in the list.

-----------

Same URL
Same Section

"devel    Development utilities. Do not put libraries here 
          just because they are libraries--unless they truly 
          do not belong to anywhere else, they should not 
          be in this category. "

I would change "belong to anywhere else" to "belong anywhere
else".

-----------

Same URL
Same Section

"irc    Internet Chat Relay utilities. "

Should say "Internet Relay Chat", at least in my dialect.

-----------

Same URL
Same Section

"misc   Miscellaneous utilities--basically things that 
        does not belong to anywhere else."

"does" should be "do".  Also, I would drop "to" so it 
says "...things that do not belong anywhere else."

-----------

Same URL
Section 4.4.20.2. Choosing the right category 

"Also, you do not need to list net when the port belongs 
to either of irc, mail, mbone, news, security, or www. "

To me, "either" implies a choice between two options; 
either a or b.  I would change "either" to "any".  I'm 
not sure how the rest of the world feels about this.

-----------

Same URL
Same Section, 4.4.20.2. Choosing the right category 

"If you are not sure about the category, please put a 
comment to that effect in your send-pr submission so 
we can discuss it before import it."

There should be a word between "before" and "import".  
Probably "we".  Also, the parentheses around the 
next sentence should be removed (a  sentence that 
consists of nothing but a parenthetical phrase doesn't 
seem quite right).


>How-To-Repeat:
See referenced URLs.
>Fix:
Implement my suggestions if you agree with them.


>Release-Note:
>Audit-Trail:

From: Will Andrews <andrews@technologist.com>
To: bobj@atlantic.net
Cc: freebsd-gnats-submit@FreeBSD.ORG
Subject: Re: docs/16854: Typos from Chapter 4 of FreeBSD Handbook
Date: Mon, 21 Feb 2000 02:40:27 -0500

 On Sun, Feb 20, 2000 at 09:14:36PM -0800, bobj@atlantic.net wrote:
 > Same URL
 > Section 4.4.6. ELF support
 > 
 > "...we wish to unofficially support the 2.2 as long as 
 > possible."  
 > 
 > The 2.2 what?  The 2.2 ports?  The 2.2 binaries?  I think 
 > a word is missing here.  
 
 I think they meant "[...] 2.2 a.out binary format".
 
 > Same URL
 > Section 4.4.16. Do's and Dont's 
 > 
 > "Here is a list of common do's and dont's that you encounter 
 > during the porting process."  As mentioned in a previous 
 > typos submission, "Do's and Dont's" is not spelled correctly.
 > It should be "Dos and Don'ts", but you have to play games 
 > with fonts for it to make sense.
 
 I think it depends on your point of view. Personally I prefer "Do's and
 Don'ts"..
 
 > Same URL
 > Section 4.4.16.5. Differentiating operating systems and OS versions 
 > 
 >       3.3-RELEASE             
 >       3.3-STABLE 
 >       3.3-STABLE after adding mkstemps() to libc 
 > ??-->
 >       4.0-CURRENT after 3/4 branch 
 >       4.0-CURRENT after change in dynamic linker handling 
 >       4.0-CURRENT after C++ constructor/destructor order change 
 > 
 > The list of values for __FreeBSD_version does not include 
 > entries for 3.4-RELEASE or 3.4-STABLE.
 
 Hmm.. I could swear I saw that list somewhere else that had 3.4-R and
 3.4-S in there. Maybe the web's version is outdated.
 
 > Same URL
 > Section 4.4.16.22. If you are stuck... 
 > 
 > "Do look at existing examples and the bsd.port.mk file before 
 > asking us questions! ;) "  
 > 
 > Although it looks fine in plain text, this emoticon does not 
 > look right when rendered in italics on my browser.  
 > It needs a nose.  In other places it is rendered as ;-)
 
 Cosmetic bug. :-)
 
 > Same URL
 > Section 4.4.18. Automated package list creation 
 > 
 > "If your port honours PREFIX (which it should) you can then 
 > install the port and create the package list. "
 > 
 > This uses the British spelling "honours".  I haven't noticed 
 > British usage in earlier sections, although perhaps I 
 > wasn't looking.  If consistency is considered important, 
 > someone should decide whether British or American spellings 
 > will be used, or perhaps create SGML tags that allow alternate 
 > spellings to be specified so that regional editions of the 
 > Handbook can be easily rendered.  Creating a tool to automate 
 > the search for words so affected would then also be handy.
 
 I don't think it matters which way it goes, but I suppose your
 suggestion could be taken by the doc team. There's other words like
 "colour", too, that would be affected.
 
 > Same URL
 > Section 4.4.20.1. Current list of categories 
 > 
 > "afterstep*     Ports to support AfterStep window manager "
 > 
 > Reads better as "Ports to support the Afterstep...".  Add 
 > the word "the".  Also, there should be a period at the end 
 > to be consistent with other entries in the list.
 
 How about "Ports that support the AfterStep window manager" ?
 
 > Same URL
 > Same Section
 > 
 > "irc    Internet Chat Relay utilities. "
 > 
 > Should say "Internet Relay Chat", at least in my dialect.
 
 Oops! *attempts to find somebody to blame for this* :-)
 
 > Same URL
 > Section 4.4.20.2. Choosing the right category 
 > 
 > "Also, you do not need to list net when the port belongs 
 > to either of irc, mail, mbone, news, security, or www. "
 > 
 > To me, "either" implies a choice between two options; 
 > either a or b.  I would change "either" to "any".  I'm 
 > not sure how the rest of the world feels about this.
 
 I agree with your opinion.
 
 > Same URL
 > Same Section, 4.4.20.2. Choosing the right category 
 > 
 > "If you are not sure about the category, please put a 
 > comment to that effect in your send-pr submission so 
 > we can discuss it before import it."
 > 
 > There should be a word between "before" and "import".  
 > Probably "we".  Also, the parentheses around the 
 
 Agreed.
 
 > next sentence should be removed (a  sentence that 
 > consists of nothing but a parenthetical phrase doesn't 
 > seem quite right).
 
 You mean like your last sentence there? :-)
 
 -- 
 Will Andrews <andrews@technologist.com>
 GCS/E/S @d- s+:+>+:- a--->+++ C++ UB++++ P+ L- E--- W+++ !N !o ?K w---
 ?O M+ V-- PS+ PE++ Y+ PGP+>+++ t++ 5 X++ R+ tv+ b++>++++ DI+++ D+ 
 G++>+++ e->++++ h! r-->+++ y?
 
Responsible-Changed-From-To: freebsd-doc->jim 
Responsible-Changed-By: jim 
Responsible-Changed-When: Mon Feb 21 23:07:53 PST 2000 
Responsible-Changed-Why:  
I'll take this one. 
State-Changed-From-To: open->closed 
State-Changed-By: jim 
State-Changed-When: Mon Feb 21 23:38:23 PST 2000 
State-Changed-Why:  
Changes committed, thanks again Bob! 
>Unformatted:
