os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Increase clarity and reduce redundancy.

Browse source
This commit is contained in:
Warren Block 2013-06-26 15:28:00 +00:00
parent 5f945601f6
commit ce1e892895
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=42063
2 changed files with 62 additions and 64 deletions
en_US.ISO8859-1/books/fdp-primer
book.xml
overview
chapter.xml

71
en_US.ISO8859-1/books/fdp-primer/book.xml
View file

@ -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>

55
en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
View file

@ -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