en/handbook/users: proposed corrections

Warren Block wblock at wonkity.com
Wed Nov 27 16:52:22 UTC 2013


On Tue, 26 Nov 2013, Taras Korenko wrote:

>  Good day, doc@ folks.
>
>  I'd like to introduce some corrections to handbook/users chapter.  However,
> there might be moot points, so any comments will be appreciated.
>  Thanks.

Thanks for working on this!  Comments inline below, preceded with WB: 
for easy location.

Index: en_US.ISO8859-1/books/handbook/users/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/handbook/users/chapter.xml	(revision 43253)
+++ en_US.ISO8859-1/books/handbook/users/chapter.xml	(working copy)
@@ -78,8 +78,8 @@

  	<listitem>
  	  <para>The user name is typed at the <prompt>login:</prompt>
-	    prompt.  User names must be unique on the system as no two
-	    users can have the same user name.  There are a number of
+	    prompt.  User names must be unique on the system. 
+	    There are a number of

WB: I agree with this simplification, and would like to take it even 
farther.  How about "Each user must have a unique user name."?

  	    rules for creating valid user names, documented in
  	    &man.passwd.5;.  Typically user names consist of eight or
  	    fewer all lower case characters in order to maintain
@@ -91,9 +91,8 @@
  	<term>Password</term>

  	<listitem>
-	  <para>Each account has an associated password.  While the
-	    password can be blank, this is highly discouraged and
-	    every account should have a password.</para>
+	  <para>Each account has an associated password.  The password can be
+	    blank, however this is highly discouraged.</para>

WB: This makes me think of "Do not look into laser with remaining eye." 
Let's just remove the sentence about setting a blank password.

  	</listitem>
        </varlistentry>

@@ -149,7 +148,7 @@

  	<listitem>
  	  <para>By default &os; does not force users to change their
-	    passwords periodically.  Password expiration can be
+	    passwords.  Password expiration can be
  	    enforced on a per-user basis, forcing some or all users to
  	    change their passwords after a certain amount of time has
  	    elapsed.</para>

WB: Agreed, the original sentence is not very good.  How about "By 
default, passwords do not expire.", and then use "enabled" rather than 
"enforced" in the next sentence.

@@ -377,7 +376,7 @@
  	<primary><filename>/usr/share/skel</filename></primary>
        </indexterm>
        <indexterm><primary>skeleton directory</primary></indexterm>
-      <para>&man.adduser.8; is a simple program for adding new users
+      <para>&man.adduser.8; is a simple program for adding new users.
  	When a new user is added, this program automatically updates
  	<filename>/etc/passwd</filename> and
  	<filename>/etc/group</filename>.  It also creates a home
@@ -527,7 +526,7 @@

        <para>When passed no options, aside from an optional username,
  	&man.chpass.1; displays an editor containing user information.
-	When the user exists from the editor, the user database is
+	When the user exits from the editor, the user database is

WB: good catch!

  	updated with the new information.</para>

        <note>
@@ -773,8 +772,7 @@
  	    this limit too small may hinder a user's productivity as
  	    it is often useful to be logged in multiple times or to
  	    execute pipelines.  Some tasks, such as compiling a large
-	    program, spawn multiple processes and other intermediate
-	    preprocessors.</para>
+	    program, spawn lots of processes.</para>

WB: "start" may be more clear than "spawn".

  	</listitem>
        </varlistentry>

@@ -818,7 +816,7 @@

  	<listitem>
  	  <para>The limit on the amount of network memory, and
-	    thus mbufs<indexterm><primary>sbsize</primary></indexterm><indexterm><primary>limiting users</primary><secondary>sbsize</secondary></indexterm>, a user may consume in order to limit network
+	    thus mbufs<indexterm><primary>sbsize</primary></indexterm><indexterm><primary>limiting users</primary><secondary>sbsize</secondary></indexterm>, a user may consume.  This can be generally used to limit network
  	    communications.</para>
  	</listitem>
        </varlistentry>
@@ -960,7 +958,7 @@
      <para>In this example, the argument to <option>-m</option> is a
        comma-delimited list of users who are to be added to the group.
        Unlike the previous example, these users are appended to the
-      group list and do not replace the list of existing users in the
+      group and do not replace the list of existing users in the
        group.</para>

      <example>


More information about the freebsd-doc mailing list