From owner-freebsd-doc@FreeBSD.ORG Tue Jul 3 19:20:01 2007 Return-Path: X-Original-To: freebsd-doc@hub.freebsd.org Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 6EB0B16A46B for ; Tue, 3 Jul 2007 19:20:01 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [69.147.83.40]) by mx1.freebsd.org (Postfix) with ESMTP id 4CB1313C484 for ; Tue, 3 Jul 2007 19:20:01 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.13.4/8.13.4) with ESMTP id l63JK1VS067689 for ; Tue, 3 Jul 2007 19:20:01 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.13.4/8.13.4/Submit) id l63JK1a8067688; Tue, 3 Jul 2007 19:20:01 GMT (envelope-from gnats) Resent-Date: Tue, 3 Jul 2007 19:20:01 GMT Resent-Message-Id: <200707031920.l63JK1a8067688@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Ben Kaduk Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 45C3816A46D for ; Tue, 3 Jul 2007 19:12:15 +0000 (UTC) (envelope-from nobody@FreeBSD.org) Received: from www.freebsd.org (www.freebsd.org [69.147.83.33]) by mx1.freebsd.org (Postfix) with ESMTP id 34C7813C4AE for ; Tue, 3 Jul 2007 19:12:15 +0000 (UTC) (envelope-from nobody@FreeBSD.org) Received: from www.freebsd.org (localhost [127.0.0.1]) by www.freebsd.org (8.13.1/8.13.1) with ESMTP id l63JCF58091398 for ; Tue, 3 Jul 2007 19:12:15 GMT (envelope-from nobody@www.freebsd.org) Received: (from nobody@localhost) by www.freebsd.org (8.13.1/8.13.1/Submit) id l63JCFjb091397; Tue, 3 Jul 2007 19:12:15 GMT (envelope-from nobody) Message-Id: <200707031912.l63JCFjb091397@www.freebsd.org> Date: Tue, 3 Jul 2007 19:12:15 GMT From: Ben Kaduk To: freebsd-gnats-submit@FreeBSD.org X-Send-Pr-Version: www-3.0 Cc: Subject: docs/114265: grammar and other nits in handbook/basics section X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 03 Jul 2007 19:20:01 -0000 >Number: 114265 >Category: docs >Synopsis: grammar and other nits in handbook/basics section >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Tue Jul 03 19:20:00 GMT 2007 >Closed-Date: >Last-Modified: >Originator: Ben Kaduk >Release: 7.0-CURRENT >Organization: >Environment: System: FreeBSD prolepsis.scs.uiuc.edu 7.0-CURRENT FreeBSD 7.0-CURRENT #1: Sun Apr 1 16:59:00 UTC 2007 kaduk@prolepsis.scs.uiuc.edu:/usr/obj/usr/src/sys/GENERIC i386 >Description: I attach a diff with many small changes in it; I'll take them in order. o groups-->group: either add an apostrophe to make it possessive or take it out; as is, it's wrong o an administrator-->that administrators: recommend is transitive o every other file system-->other file systems: you can mount filesystems on non-root filesystems, as described later. This change makes the text more correct . o grafted on the root file system-->...parent file system: same as previous o should-->must: in context, the requirement of FreeBSD is that you give a fully-qualified slice name, which includes the disk name. Out of context, someone else might not require this, but the first half of the sentence implies that we are telling the user how to talk to FreeBSD o three partitions-->three data partitions: no, it has four partitions -- three for data and one for swap. Make the text less confusing o [no PID collisions]: just seems like it might save some confusion o daemons et al: change punctuation for style/readibility; remove sentence fragment o BIND: actually is domain, not daemon, as discussed fairly recently on cvs-doc@ o signals: the current text implies that signals are the only way to communicate with daemons; however, I seem to recall that some daemons listen on local sockets for commands, or read named pipes o kill: punctuation correction o occur-->appear: occur implies action (to me, at least); appear is more passive o help-->help with: verb transitivity again o variable key-->variable/key: it's a pair, so punctuate it as such (I didn't do a build and I don't remember if the slash is a special character for sgml -- do you?) o colon separated-->colon-separated (twice): style? o terminal-->type of terminal: so as to avoid confusion with (e.g.) ttyv0 >How-To-Repeat: http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/basics.html and the rest of the chapter >Fix: patch attached as chapter.sgml.diff.txt; I will skip inlining it since firefox/mac will probably trash the tabs. Patch attached with submission follows: --- chapter.sgml.orig 2007-06-29 15:19:47.000000000 -0500 +++ chapter.sgml 2007-07-03 13:55:40.000000000 -0500 @@ -558,7 +558,7 @@ A comma separated list can be provided when more than one set of changes to a file must be made. For example the following command - will remove the groups and world write permission + will remove the group and world write permission on FILE, then it adds the execute permissions for everyone: @@ -618,7 +618,7 @@ Several flags may only added or removed to files by the root user. In other cases, the file owner - may set these flags. It is recommended an administrator read + may set these flags. It is recommended that administrators read over the &man.chflags.1; and &man.chflags.2; manual pages for more information. @@ -634,11 +634,12 @@ /. This directory is the first one mounted at boot time and it contains the base system necessary to prepare the operating system for multi-user operation. The root - directory also contains mount points for every other file system - that you may want to mount. + directory also contains mount points for other file systems + that are mounted during the transition to multi-user + operation. A mount point is a directory where additional file systems can - be grafted onto the root file system. + be grafted onto a parent file system (usually the root file system). This is further described in . Standard mount points include /usr, /var, /tmp, @@ -1250,7 +1251,8 @@ When referring to a partition FreeBSD requires that you also name the slice and disk that contains the partition, and when referring to - a slice you should also refer to the disk name. Do this by listing + a slice you must also refer to the disk name. + Thus, you refer to a partition by listing the disk name, s, the slice number, and then the partition letter. Examples are shown in . @@ -1357,7 +1359,7 @@ two 2 GB slices (&ms-dos; partitions). The first slice contains a &ms-dos; disk, C:, and the second slice contains a FreeBSD installation. This example FreeBSD installation has three - partitions, and a swap partition. + data partitions, and a swap partition. The three partitions will each hold a file system. Partition a will be used for the root file system, @@ -1738,7 +1740,8 @@ As you can see in this example, the output from &man.ps.1; is organized into a number of columns. PID is the process ID discussed earlier. PIDs are assigned starting from 1, go up - to 99999, and wrap around back to the beginning when you run out. + to 99999, and wrap around back to the beginning when you run out + (a PID is not reassigned if it is already in use). The TT column shows the tty the program is running on, and can safely be ignored for the moment. STAT shows the program's state, and again, can be safely ignored. @@ -1755,7 +1758,8 @@ about all the running processes, not just your own. displays the username of the process' owner, as well as memory usage. displays information about daemon processes, and - causes &man.ps.1; to display the full command line, + causes &man.ps.1; to display the full command line + for each process, rather than truncating it once it gets too long to fit on the screen. @@ -1815,32 +1819,32 @@ example of this class of application. We call these programs daemons. Daemons were - characters in Greek mythology; neither good or evil, they were little - attendant spirits that, by and large, did useful things for mankind. - Much like the web servers and mail servers of today do useful things. - This is why the BSD mascot has, for a long time, been the cheerful - looking daemon with sneakers and a pitchfork. + characters in Greek mythology: neither good or evil, they were little + attendant spirits that, by and large, did useful things for mankind, + much like the web servers and mail servers of today do useful things. + This is why the BSD mascot has, for a long time, been the + cheerful-looking daemon with sneakers and a pitchfork. There is a convention to name programs that normally run as daemons with a trailing d. BIND is the - Berkeley Internet Name Daemon (and the actual program that executes is called - named), the Apache web - server program is called httpd, the line printer + Berkeley Internet Name Domain, but the actual program that executes is called + named; the Apache web + server program is called httpd; the line printer spooling daemon is lpd and so on. This is a convention, not a hard and fast rule; for example, the main mail daemon for the Sendmail application is called sendmail, and not maild, as you might imagine. - Sometimes you will need to communicate with a daemon process. These - communications are called signals, and you can - communicate with a daemon (or with any other running process) by sending it a - signal. There are a number of different signals that you can + Sometimes you will need to communicate with a daemon process. + One way to do so is to send it (or any other running process), + what is known as a signal. + There are a number of different signals that you can send—some of them have a specific meaning, others are interpreted by the application, and the application's documentation will tell you how that application interprets signals. You can only send a signal to a process that you own. If you send a signal to someone else's - process with &man.kill.1; or &man.kill.2; permission will be denied. + process with &man.kill.1; or &man.kill.2;, permission will be denied. The exception to this is the root user, who can send signals to everyone's processes. @@ -1918,7 +1922,7 @@ 198 ?? IWs 0:00.00 inetd -wW So the &man.inetd.8; PID is 198. In some cases the - grep inetd command might also occur in this + grep inetd command might also appear in this output. This is because of the way &man.ps.1; has to find the list of running processes. @@ -1979,7 +1983,7 @@ In FreeBSD, a lot of everyday work is done in a command line interface called a shell. A shell's main job is to take commands from the input channel and execute them. A lot of shells also have - built in functions to help everyday tasks such as file management, + built in functions to help with everyday tasks such as file management, file globbing, command line editing, command macros, and environment variables. FreeBSD comes with a set of shells, such as sh, the Bourne Shell, and tcsh, @@ -2018,7 +2022,7 @@ environment variables Another feature of the shell is the use of environment variables. - Environment variables are a variable key pair stored in the shell's + Environment variables are a variable/key pair stored in the shell's environment space. This space can be read by any program invoked by the shell, and thus contains a lot of program configuration. Here is a list of common environment variables and what they mean: @@ -2041,7 +2045,7 @@ PATH - Colon separated list of directories to search for + Colon-separated list of directories to search for binaries. @@ -2058,7 +2062,7 @@ TERM - The name of the user's terminal. Used to determine the + The name of the user's type of terminal. Used to determine the capabilities of the terminal. @@ -2091,7 +2095,7 @@ MANPATH - Colon separated list of directories to search for + Colon-separated list of directories to search for manual pages. >Release-Note: >Audit-Trail: >Unformatted: