docs/114265: grammar and other nits in handbook/basics section
Ben Kaduk
minimarmot at gmail.com
Tue Jul 3 19:20:01 UTC 2007
>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 at 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 @@
<para>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 <quote>world</quote> write permission
+ will remove the group and <quote>world</quote> write permission
on <replaceable>FILE</replaceable>, then it adds the execute
permissions for everyone:</para>
@@ -618,7 +618,7 @@
<para>Several flags may only added or removed to files by the
<username>root</username> 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.</para>
</sect2>
@@ -634,11 +634,12 @@
<quote>/</quote>. 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.</para>
+ directory also contains mount points for other file systems
+ that are mounted during the transition to multi-user
+ operation.</para>
<para>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 <xref linkend="disk-organization">.
Standard mount points include
<filename>/usr</filename>, <filename>/var</filename>, <filename>/tmp</filename>,
@@ -1250,7 +1251,8 @@
<para>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, <literal>s</literal>, the slice number, and then the
partition letter. Examples are shown in
<xref linkend="basics-disk-slice-part">.</para>
@@ -1357,7 +1359,7 @@
two 2 GB slices (&ms-dos; partitions). The first slice contains a &ms-dos;
disk, <devicename>C:</devicename>, and the second slice contains a
FreeBSD installation. This example FreeBSD installation has three
- partitions, and a swap partition.</para>
+ data partitions, and a swap partition.</para>
<para>The three partitions will each hold a file system. Partition
<literal>a</literal> will be used for the root file system,
@@ -1738,7 +1740,8 @@
<para>As you can see in this example, the output from &man.ps.1; is
organized into a number of columns. <literal>PID</literal> 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 <literal>TT</literal> column shows the tty the program is running on, and can
safely be ignored for the moment. <literal>STAT</literal> shows the
program's state, and again, can be safely ignored.
@@ -1755,7 +1758,8 @@
about all the running processes, not just your own. <option>u</option>
displays the username of the process' owner, as well as memory usage.
<option>x</option> displays information about daemon processes, and
- <option>ww</option> causes &man.ps.1; to display the full command line,
+ <option>ww</option> 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.</para>
@@ -1815,32 +1819,32 @@
example of this class of application.</para>
<para>We call these programs <firstterm>daemons</firstterm>. 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.</para>
+ 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.</para>
<para>There is a convention to name programs that normally run as daemons
with a trailing <quote>d</quote>. <application>BIND</application> is the
- Berkeley Internet Name Daemon (and the actual program that executes is called
- <command>named</command>), the <application>Apache</application> web
- server program is called <command>httpd</command>, the line printer
+ Berkeley Internet Name Domain, but the actual program that executes is called
+ <command>named</command>; the <application>Apache</application> web
+ server program is called <command>httpd</command>; the line printer
spooling daemon is <command>lpd</command> and so on. This is a
convention, not a hard and fast rule; for example, the main mail daemon
for the <application>Sendmail</application> application is called
<command>sendmail</command>, and not <command>maild</command>, as you
might imagine.</para>
- <para>Sometimes you will need to communicate with a daemon process. These
- communications are called <firstterm>signals</firstterm>, 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
+ <para>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 <firstterm>signal</firstterm>.
+ 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
<username>root</username> user, who can send signals to everyone's
processes.</para>
@@ -1918,7 +1922,7 @@
198 ?? IWs 0:00.00 inetd -wW</screen>
<para>So the &man.inetd.8; PID is 198. In some cases the
- <literal>grep inetd</literal> command might also occur in this
+ <literal>grep inetd</literal> command might also appear in this
output. This is because of the way &man.ps.1; has to find the list
of running processes.</para>
</step>
@@ -1979,7 +1983,7 @@
<para>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
<command>sh</command>, the Bourne Shell, and <command>tcsh</command>,
@@ -2018,7 +2022,7 @@
<indexterm><primary>environment variables</primary></indexterm>
<para>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:</para>
@@ -2041,7 +2045,7 @@
<row>
<entry><envar>PATH</envar></entry>
- <entry>Colon separated list of directories to search for
+ <entry>Colon-separated list of directories to search for
binaries.</entry>
</row>
@@ -2058,7 +2062,7 @@
<row>
<entry><envar>TERM</envar></entry>
- <entry>The name of the user's terminal. Used to determine the
+ <entry>The name of the user's type of terminal. Used to determine the
capabilities of the terminal.</entry>
</row>
@@ -2091,7 +2095,7 @@
<row>
<entry><envar>MANPATH</envar></entry>
- <entry>Colon separated list of directories to search for
+ <entry>Colon-separated list of directories to search for
manual pages.</entry>
</row>
</tbody>
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list