svn commit: r42063 - in head/en_US.ISO8859-1/books/fdp-primer: . overview
Warren Block
wblock at FreeBSD.org
Wed Jun 26 15:28:01 UTC 2013
Author: wblock
Date: Wed Jun 26 15:28:00 2013
New Revision: 42063
URL: http://svnweb.freebsd.org/changeset/doc/42063
Log:
Increase clarity and reduce redundancy.
Modified:
head/en_US.ISO8859-1/books/fdp-primer/book.xml
head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
Modified: head/en_US.ISO8859-1/books/fdp-primer/book.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/book.xml Wed Jun 26 12:31:21 2013 (r42062)
+++ head/en_US.ISO8859-1/books/fdp-primer/book.xml Wed Jun 26 15:28:00 2013 (r42063)
@@ -72,16 +72,16 @@
<abstract>
<para>Thank you for becoming a part of the FreeBSD Documentation
- Project. Your contribution is extremely valuable.</para>
+ Project. Your contribution is extremely valuable, and we appreciate it.</para>
<para>This primer covers details needed
to start contributing to the FreeBSD Documentation
- Project, from the tools and software (both
- mandatory and recommended) to the philosophy behind the
+ Project, or <acronym>FDP</acronym>, including tools, software,
+ and the philosophy behind the
Documentation Project.</para>
- <para>This document is a work in progress. Corrections and
- additions are welcomed.</para>
+ <para>This is a work in progress. Corrections and
+ additions are always welcome.</para>
</abstract>
</bookinfo>
@@ -91,10 +91,9 @@
<sect1 id="preface-prompts">
<title>Shell Prompts</title>
- <para>The following table shows the default system prompt and
- superuser prompt. The examples will use this prompt to
- indicate which user you should be running the example
- as.</para>
+ <para>This table shows the default system prompt and
+ superuser prompt. The examples use these prompts to
+ indicate which type of user is running the example.</para>
<informaltable frame="none" pgwide="1">
<tgroup cols="2">
@@ -123,7 +122,7 @@
<sect1 id="preface-conventions">
<title>Typographic Conventions</title>
- <para>The following table describes the typographic conventions
+ <para>This table describes the typographic conventions
used in this book.</para>
<informaltable frame="none" pgwide="1">
@@ -148,44 +147,44 @@
</row>
<row>
- <entry>On screen computer output.</entry>
+ <entry>On-screen computer output.</entry>
<entry><screen>You have mail.</screen></entry>
</row>
<row>
- <entry>What you type, when contrasted with on-screen
+ <entry>What the user types, contrasted with on-screen
computer output.</entry>
- <entry><screen>&prompt.user; <userinput>su</userinput>
-Password:</screen></entry>
+ <entry><screen>&prompt.user; <userinput>date +"The time is %H:%M"</userinput>
+The time is 09:18</screen></entry>
</row>
<row>
<entry>Manual page references.</entry>
- <entry>Use &man.su.1; to change user names.</entry>
+ <entry>Use &man.su.1; to change user identity.</entry>
</row>
<row>
- <entry>User and group names</entry>
+ <entry>User and group names.</entry>
<entry>Only <username>root</username> can do
this.</entry>
</row>
<row>
- <entry>Emphasis</entry>
- <entry>You <emphasis>must</emphasis> do this.</entry>
+ <entry>Emphasis.</entry>
+ <entry>The user <emphasis>must</emphasis> do this.</entry>
</row>
<row>
- <entry>Command line variables; replace with the real
- name or variable.</entry>
- <entry>To delete a file, type <command>rm
- <filename><replaceable>filename</replaceable></filename></command></entry>
+ <entry>Text that the user is expected to replace with
+ the actual text.</entry>
+ <entry>To search for a keyword in the manual pages, type <command>man -k
+ <replaceable>keyword</replaceable></command></entry>
</row>
<row>
- <entry>Environment variables</entry>
- <entry><envar>$HOME</envar> is your home
+ <entry>Environment variables.</entry>
+ <entry><envar>$HOME</envar> is set to the user's home
directory.</entry>
</row>
</tbody>
@@ -197,32 +196,32 @@ Password:</screen></entry>
<title>Notes, Tips, Important Information, Warnings, and
Examples</title>
- <para>Within the text appear notes, warnings, and
- examples.</para>
+ <para>Notes, warnings, and examples appear within the
+ text.</para>
<note>
<para>Notes are represented like this, and contain information
- that you should take note of, as it may affect what you
- do.</para>
+ to take note of, as it may affect what the user
+ does.</para>
</note>
<tip>
<para>Tips are represented like this, and contain information
- that you might find useful, or lead to an easier way to do
+ helpful to the user, like showing an easier way to do
something.</para>
</tip>
<important>
<para>Important information is represented like this.
- Typically they flag extra steps you may need to carry
- out.</para>
+ Typically, these show extra steps the user may need to
+ take.</para>
</important>
<warning>
<para>Warnings are represented like this, and contain
- information warning you about possible damage if you do not
- follow the instructions. This damage may be physical, to
- your hardware or to you, or it may be non-physical, such as
+ information warning about possible damage if the
+ instructions are not followed. This damage may be physical, to
+ the hardware or the user, or it may be non-physical, such as
the inadvertent deletion of important files.</para>
</warning>
@@ -230,8 +229,8 @@ Password:</screen></entry>
<title>A Sample Example</title>
<para>Examples are represented like this, and typically
- contain examples you should walk through, or show you what
- the results of a particular action should be.</para>
+ contain examples showing a walkthrough, or
+ the results of a particular action.</para>
</example>
</sect1>
Modified: head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Wed Jun 26 12:31:21 2013 (r42062)
+++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Wed Jun 26 15:28:00 2013 (r42063)
@@ -35,21 +35,20 @@
<title>Overview</title>
<para>Welcome to the &os; Documentation Project
- (<acronym>FDP</acronym>). Quality documentation is very important
- to the success of &os;. Your contributions are very
- valuable.</para>
+ (<acronym>FDP</acronym>). Quality documentation is crucial
+ to the success of &os;, and we value your contributions very
+ highly.</para>
- <para>This document's main purpose is to explain how the
+ <para>This document describes how the
<acronym>FDP</acronym> is organized, how to write and submit
documentation, and how to effectively use the available
tools.</para>
<para>Everyone is welcome to contribute to the
- <acronym>FDP</acronym>. There is no membership requirement or
- minimum quota of documentation that needs to be produced.</para>
+ <acronym>FDP</acronym>. Willingness to contribute is the only membership requirement.</para>
- <para>After you have finished reading this document you will be
- able to:</para>
+ <para>This Primer shows the reader how
+ to:</para>
<itemizedlist>
<listitem>
@@ -58,7 +57,7 @@
</listitem>
<listitem>
- <para>Install the required tools and files.</para>
+ <para>Install the required documentation tools and files.</para>
</listitem>
<listitem>
@@ -124,27 +123,27 @@
Subversion repository located at
<literal>https://svn.FreeBSD.org/base/</literal>.</para>
- <para>The commit messages to the <acronym>FDP</acronym>
- are visible to anyone usingv<application>svn</application>.
- They are also archived at &a.svn-doc-all.url;.</para>
+ <para>Documentation commit messages
+ are visible with <application>svn</application>.
+ Commit messages are also archived at <ulink url="&a.svn-doc-all.url;"></ulink>.</para>
<para>In addition, many people have written tutorials or how-to
- articles about &os;. Some are stored in the
- <acronym>FDP</acronym>. In other cases, the author has decided
- to keep the documentation separate from the
- <acronym>FDP</acronym>. The <acronym>FDP</acronym> endeavors to
- provide links to as much of this documentation as
+ articles about &os;. Some are stored as part of the
+ <acronym>FDP</acronym> files. In other cases, the author has decided
+ to keep the documentation separate.
+ The <acronym>FDP</acronym> endeavors to
+ provide links to as much of this external documentation as
possible.</para>
</sect1>
<sect1 id="overview-quick-start">
<title>Quick Start</title>
- <para>This section outlines the steps which new contributors need
- to follow before they can make changes to the
+ <para>Here we describe the steps contributors must
+ follow before they can make changes to the
<acronym>FDP</acronym>. New contributors will interact with
- other members of the &os; Documentation Team which can assist in
- learning how to use <acronym>XML</acronym> and the <xref
+ other members of the &os; Documentation Team, which can assist in
+ learning to use <acronym>XML</acronym> and the suggestions in <xref
linkend="writing-style-guide"/>. If a new user contributes
regularly, a Documentation Team member may be assigned as a
mentor to guide the user through the process from contributor
@@ -198,10 +197,10 @@
</step>
<step>
- <para>Determine which file to edit. Run
+ <para>Locate the file to edit. Run
<command>svn up</command> within the local working copy
- to make sure that it is current. Before making major
- changes to a file, discuss the proposed changes first with
+ to make sure that it is up to date. Before making major
+ changes to a file, discuss the proposed changes with
the &a.doc;.</para>
<para>When making edits, determine which tags and entities
@@ -210,18 +209,18 @@
<acronym>HTML</acronym> formatted version of the document
to the tags which surround the text or the entities that
represent that text in the <acronym>XML</acronym> file.
- A reference to the commonly used tags and entities can be
+ References to the commonly used tags and entities can be
found in <xref linkend="xhtml-markup"/> and
<xref linkend="docbook-markup"/>.</para>
</step>
<step>
- <para>Once the edits are complete, check for problems by
+ <para>After edits are complete, check for problems by
running:</para>
<screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen>
- <para>While reviewing the output, edit the file to fix the
+ <para>Review the output and edit the file to fix any
listed tab errors, spelling mistakes, and improper
grammar. Save the changes and rerun this command to find
any remaining problems. Repeat until all of the errors
@@ -283,7 +282,7 @@
<para>It is important to remember that the
<acronym>FDP</acronym> is comprised of volunteers who
review edits in their spare time and who live in different
- time zones across the globe. It takes time to review
+ time zones around the globe. It takes time to review
edits and to either commit them or respond if additional
edits are required. If you do not receive a response in a
reasonable amount of time, send a follow-up email to the
More information about the svn-doc-head
mailing list