svn commit: r41934 - head/en_US.ISO8859-1/books/fdp-primer/overview
Dru Lavigne
dru at FreeBSD.org
Mon Jun 17 17:13:55 UTC 2013
Author: dru
Date: Mon Jun 17 17:13:54 2013
New Revision: 41934
URL: http://svnweb.freebsd.org/changeset/doc/41934
Log:
White space fix only, translators can ignore.
Approved by: bcr (mentor)
Modified:
head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
Modified: head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Mon Jun 17 15:47:47 2013 (r41933)
+++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Mon Jun 17 17:13:54 2013 (r41934)
@@ -34,24 +34,27 @@
<chapter id="overview">
<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
+ <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>
- <para>This document's main purpose is to explain
- how the <acronym>FDP</acronym> is organized, how to
- write and submit documentation, and
- how to effectively use the available tools.</para>
+ <para>This document's main purpose is to explain 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>
- <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>
-
- <para>After you have finished reading this document you
- will be able to:</para>
+ <para>After you have finished reading this document you will be
+ able to:</para>
<itemizedlist>
<listitem>
- <para>Identify which parts of &os; are maintained by the <acronym>FDP</acronym>.</para>
+ <para>Identify which parts of &os; are maintained by the
+ <acronym>FDP</acronym>.</para>
</listitem>
<listitem>
@@ -63,55 +66,57 @@
</listitem>
<listitem>
- <para>Submit changes back for review and
- eventual inclusion in the &os; documentation.</para>
+ <para>Submit changes back for review and eventual inclusion in
+ the &os; documentation.</para>
</listitem>
</itemizedlist>
<sect1 id="overview-doc">
<title>The &os; Documentation Set</title>
- <para>The <acronym>FDP</acronym> is responsible for four categories of &os;
- documentation.</para>
+ <para>The <acronym>FDP</acronym> is responsible for four
+ categories of &os; documentation.</para>
<itemizedlist>
- <listitem>
- <para><emphasis>Handbook</emphasis>: The Handbook is the comprehensive online
- resource and reference for &os; users.</para>
+ <listitem>
+ <para><emphasis>Handbook</emphasis>: The Handbook is the
+ comprehensive online resource and reference for &os;
+ users.</para>
</listitem>
-
<listitem>
- <para><emphasis>FAQ</emphasis>: The <acronym>FAQ</acronym> uses a short question and answer
- format to address questions that are frequently asked on
- the various mailing lists and forums devoted to
- &os;. This format does not permit long and
- comprehensive answers.</para>
+ <para><emphasis>FAQ</emphasis>: The <acronym>FAQ</acronym>
+ uses a short question and answer format to address questions
+ that are frequently asked on the various mailing lists and
+ forums devoted to &os;. This format does not permit long
+ and comprehensive answers.</para>
</listitem>
<listitem>
- <para><emphasis>Manual pages</emphasis>: The English language system manual pages are usually not
- written by the <acronym>FDP</acronym>, as they are part of the base system.
- However, the <acronym>FDP</acronym> can reword parts of existing
- manual pages to make them clearer or to correct
+ <para><emphasis>Manual pages</emphasis>: The English language
+ system manual pages are usually not written by the
+ <acronym>FDP</acronym>, as they are part of the base system.
+ However, the <acronym>FDP</acronym> can reword parts of
+ existing manual pages to make them clearer or to correct
inaccuracies.</para>
- </listitem>
+ </listitem>
<listitem>
- <para><emphasis>Web site</emphasis>: This is the main &os; presence on the
- web, visible at <ulink
+ <para><emphasis>Web site</emphasis>: This is the main &os;
+ presence on the web, visible at <ulink
url="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</ulink>
- and many mirrors around the world. The web site is typically
- a new user's first exposure to &os;.</para>
- </listitem>
+ and many mirrors around the world. The web site is
+ typically a new user's first exposure to &os;.</para>
+ </listitem>
</itemizedlist>
<para>Translation teams are responsible for translating
- the Handbook and web site into different languages. Manual pages are not translated.</para>
-
- <para>Documentation source for the &os; web site, Handbook, and <acronym>FAQ</acronym>
- is available in the Subversion
+ the Handbook and web site into different languages. Manual
+ pages are not translated.</para>
+
+ <para>Documentation source for the &os; web site, Handbook, and
+ <acronym>FAQ</acronym> is available in the Subversion
repository at
<literal>https://svn.FreeBSD.org/doc/</literal>.</para>
@@ -120,65 +125,63 @@
<literal>https://svn.FreeBSD.org/base/</literal>.</para>
<para>The commit messages to the <acronym>FDP</acronym>
- are visible to anyone using
- <application>svn</application>. They are also archived at
- &a.svn-doc-all.url;.</para>
+ are visible to anyone usingv<application>svn</application>.
+ They are also archived at &a.svn-doc-all.url;.</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 possible.</para>
+ <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
+ 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 <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
- 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 to documentation committer.</para>
+ to 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
+ 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
+ to documentation committer.</para>
<procedure>
<step>
- <para>
- Subscribe to the &a.doc;. Some members of the mailing
- list also interact on the <literal>#bsddocs</literal> <acronym>IRC</acronym>
- channel on <ulink
+ <para>Subscribe to the &a.doc;. Some members of the mailing
+ list also interact on the <literal>#bsddocs</literal>
+ <acronym>IRC</acronym> channel on <ulink
url="http://www.efnet.org/">EFnet</ulink>.</para>
- </step>
+ </step>
- <step>
+ <step>
<para>Install the
<filename role="package">textproc/docproj</filename>
- package or port. This meta-port
- installs all of the utilities needed by the <acronym>FDP</acronym>.</para>
- </step>
+ package or port. This meta-port installs all of the
+ utilities needed by the <acronym>FDP</acronym>.</para>
+ </step>
<step>
<para>Install a local working copy of the documentation
from a mirror of the &os; repository. For the fastest
download, pick the nearest mirror from the list of <ulink
- url="&url.books.handbook;/subversion-mirrors.html">Subversion mirror sites</ulink>.
- If <filename role="directory">/usr/doc</filename> already
- exists, move or delete it first to prevent file
- conflicts.</para>
+ url="&url.books.handbook;/subversion-mirrors.html">Subversion
+ mirror sites</ulink>. If <filename
+ role="directory">/usr/doc</filename> already exists, move
+ or delete it first to prevent file conflicts.</para>
<screen>&prompt.user; <userinput>svn checkout https://<replaceable>svn0.us-west.FreeBSD.org</replaceable>/doc/head <replaceable>/usr/doc</replaceable></userinput></screen>
</step>
<step>
<para>Before making any documentation edits, configure your
- editor to conform to <acronym>FDP</acronym> standards. How to do so varies
- by editor. Some editor configurations are listed in <xref
- linkend="writing-style"/>. The editor
+ editor to conform to <acronym>FDP</acronym> standards.
+ How to do so varies by editor. Some editor configurations
+ are listed in <xref linkend="writing-style"/>. The editor
should be configured as follows:</para>
<itemizedlist>
<listitem>
@@ -192,96 +195,100 @@
single tab.</para>
</listitem>
</itemizedlist>
- </step>
+ </step>
- <step>
- <para>Determine which file to edit. Run <command>svn up</command> within the
- local working copy to make sure that it is
- current. Before making major
+ <step>
+ <para>Determine which 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
the &a.doc;.</para>
- <para>When making edits, determine which
- tags and entities are needed to achieve the desired
- formatting. One way to learn is to compare some text in
- the <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
+ <para>When making edits, determine which tags and entities
+ are needed to achieve the desired formatting. One way to
+ learn is to compare some text in the
+ <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
found in <xref linkend="xml-markup"/>.</para>
</step>
- <step>
- <para>Once the edits are complete, check for problems by running:</para>
+ <step>
+ <para>Once the 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
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 that
- you deem fixable are resolved. If you get stuck trying to
- fix errors, ask for assistance on the &a.doc;.</para>
+ any remaining problems. Repeat until all of the errors
+ that you deem fixable are resolved. If you get stuck
+ trying to fix errors, ask for assistance on the
+ &a.doc;.</para>
</step>
- <step>
- <para><emphasis>Always</emphasis> build-test changes before submitting them. By
- default, typing <userinput>make</userinput> in the
- top-level directory of the type of documentation being
- edited will generate that documentation in
- split HTML format. For example, to build the English
- version of the Handbook, type <userinput>make</userinput>
- in the
+ <step>
+ <para><emphasis>Always</emphasis> build-test changes before
+ submitting them. By default, typing
+ <userinput>make</userinput> in the top-level directory of
+ the type of documentation being edited will generate that
+ documentation in split HTML format. For example, to build
+ the English version of the Handbook, type
+ <userinput>make</userinput> in the
<filename>en_US.ISO8859-1/books/handbook/</filename>
directory. This step is necessary to make sure that the
edits do not break the build.</para>
- </step>
+ </step>
- <step>
- <para>In order to build the output in other formats,
- other <application>make</application> targets are defined
- in <filename>head/share/mk/doc.docbook.mk</filename>.
- Use quotes around the list of formats when
- building more than one format with a single
- command.</para>
+ <step>
+ <para>In order to build the output in other formats, other
+ <application>make</application> targets are defined in
+ <filename>head/share/mk/doc.docbook.mk</filename>. Use
+ quotes around the list of formats when building more than
+ one format with a single command.</para>
- <para>For example, to convert the document to both
+ <para>For example, to convert the document to both
<literal>.html</literal> and <literal>.txt</literal>, use
this command:</para>
<screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen>
- <para>Once these steps are successfully completed,
- generate a <quote>diff file</quote> of the changes. While in
- <filename class="directory">/usr/doc</filename>, run this
- command, replacing <replaceable>bsdinstall</replaceable>
- with the name of the directory containing the edits:</para>
+ <para>Once these steps are successfully completed, generate a
+ <quote>diff file</quote> of the changes. While in <filename
+ class="directory">/usr/doc</filename>, run this command,
+ replacing <replaceable>bsdinstall</replaceable> with the
+ name of the directory containing the edits:</para>
<screen>&prompt.user; <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>
</step>
- <step>
- <para>Submit the diff file using the web-based <ulink
- url="&url.base;/support.html#gnats">Problem Report</ulink>
- system or with &man.send-pr.1;. If using the web form,
- input a synopsis of <emphasis>[patch] <replaceable>short description of problem</replaceable></emphasis>.
- Select the category <literal>docs</literal> and the
- class <literal>doc-bug</literal>. The body of the
- message should contain a short description of the edits
- and any important discussion points. Use the <guibutton>[ Browse... ]</guibutton> button to attach the
- <literal>.diff.txt</literal> file and enter the captcha
- phrase.</para>
-
- <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 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 &a.doc; and ask if anyone
- has had a chance to review the patch or if additional
- information is required.</para>
+ <step>
+ <para>Submit the diff file using the web-based <ulink
+ url="&url.base;/support.html#gnats">Problem
+ Report</ulink> system or with &man.send-pr.1;. If using
+ the web form, input a synopsis of <emphasis>[patch]
+ <replaceable>short description of
+ problem</replaceable></emphasis>. Select the category
+ <literal>docs</literal> and the class
+ <literal>doc-bug</literal>. The body of the message
+ should contain a short description of the edits and any
+ important discussion points. Use the
+ <guibutton>[ Browse... ]</guibutton> button to
+ attach the <literal>.diff.txt</literal> file and enter
+ the captcha phrase.</para>
+
+ <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
+ 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
+ &a.doc; and ask if anyone has had a chance to review the
+ patch or if additional information is required.</para>
</step>
</procedure>
</sect1>
- </chapter>
+ </chapter>
\ No newline at end of file
More information about the svn-doc-all
mailing list