diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
index 6616d9591b..6646cf9659 100644
--- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
@@ -1,265 +1,262 @@
Overview
Welcome to the &os; Documentation Project
(FDP). Quality documentation is crucial
to the success of &os;, and we value your contributions very
highly.
This document describes how the FDP is
organized, how to write and submit documentation, and how to
effectively use the available tools.
Everyone is welcome to contribute to the
FDP. Willingness to contribute is the only
membership requirement.
This primer shows how to:
Identify which parts of &os; are maintained by the
FDP.
Install the required documentation tools and files.
Make changes to the documentation.
Submit changes back for review and inclusion in the &os;
documentation.
The &os; Documentation Set
The FDP is responsible for four
categories of &os; documentation.
Handbook: The Handbook is the
comprehensive online resource and reference for &os;
users.
FAQ: The FAQ
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.
Manual pages: The English language
system manual pages are usually not written by the
FDP, as they are part of the base system.
However, the FDP can reword parts of
existing manual pages to make them clearer or to correct
inaccuracies.
Web site: This is the main &os;
presence on the web, visible at http://www.FreeBSD.org/
and many mirrors around the world. The web site is
typically a new user's first exposure to &os;.
Translation teams are responsible for translating the
Handbook and web site into different languages. Manual pages
are not translated at present.
Documentation source for the &os; web site, Handbook, and
FAQ is available in the documentation
repository at
https://svn.FreeBSD.org/doc/.
Source for manual pages is available in a separate
source repository located at
https://svn.FreeBSD.org/base/.
Documentation commit messages are visible with
svn log. Commit messages are also
archived at .
- Many people have written tutorials or how-to
- articles about &os;. Some are stored as part of the
- FDP files. In other cases, the author has
- decided to keep the documentation separate. The
- FDP endeavors to provide links to as much of
- this external documentation as possible.
+ Many people have written tutorials or how-to articles about
+ &os;. Some are stored as part of the FDP
+ files. In other cases, the author has decided to keep the
+ documentation separate. The FDP endeavors to
+ provide links to as much of this external documentation as
+ possible.
Quick Start
- Some preparatory steps must be taken before
- editing the &os; documentation. New
- contributors will interact with other members of the &os;
- Documentation Team, which can assist in learning to use
- XML and the suggestions in
+ Some preparatory steps must be taken before editing the &os;
+ documentation. New contributors will interact with other
+ members of the &os; Documentation Team, which can assist in
+ learning to use XML and the suggestions in
. 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.
- Subscribe to the &a.doc;. Some mailing list
- members also interact on the #bsddocs
+ Subscribe to the &a.doc;. Some mailing list members
+ also interact on the #bsddocs
IRC channel on EFnet.
Install the
textproc/docproj
package or port. This meta-port installs all of the
software needed to edit and build &os; documentation.
Install a local working copy of the documentation
- from a mirror of the &os; repository (see ) in ~/doc.
+ from a mirror of the &os; repository (see
+ ) in
+ ~/doc.
&prompt.user; svn checkout https://svn0.us-west.FreeBSD.org/doc/head /usr/doc
+
+
+
+ Configure the text editor:
+
+
+
+ Word wrap set to 70 characters.
+
+
+
+ Tab stops set to 2.
+
+
+
+ Replace each group of 8 leading spaces with a
+ single tab.
+
+
+
+ Specific editor configurations are listed in
+ .
+
+
+
+ Update the local working copy:
+
+ &prompt.user; svn up ~/doc
+
+
+
+ Edit the documentation files that require changes. If a
+ file needs major changes, consult the &a.doc; for
+ input.
+
+ References to tag and entity usage can be found in
+ and
+ .
+
-
-
-
- Configure the text editor:
-
-
-
- Word wrap set to 70 characters.
-
-
-
- Tab stops set to 2.
-
-
-
- Replace each group of 8 leading spaces with a
- single tab.
-
-
-
-
- Specific editor configurations
- are listed in .
-
-
-
- Update the local working copy:
-
- &prompt.user; svn up ~/doc
-
-
-
- Edit the documentation files that require
- changes. If a file needs major changes, consult the
- &a.doc; for input.
-
- References to tag and entity usage can be found in
- and
- .
-
-
-
- After editing, check for problems by
- running:
-
- &prompt.user; igor -R filename.xml | less -RS
-
- Review the output and edit the file to fix any
- problems shown, then rerun the command to find any
- remaining problems. Repeat until all of the errors that
- are fixable are resolved. If an error seems unsolvable,
- ask for assistance on the &a.doc;.
-
-
-
- Always build-test changes before
- submitting them. Running
- make in the top-level directory of
- the documentation being edited will generate that
- documentation in split HTML format. For example, to build
- the English version of the Handbook in
- HTML, type make in
- the en_US.ISO8859-1/books/handbook/
- directory.
-
-
-
- When changes are complete and tested,
- generate a diff file
:
-
- &prompt.user; cd /usr/doc
+
+ After editing, check for problems by running:
+
+ &prompt.user; igor -R filename.xml | less -RS
+
+ Review the output and edit the file to fix any problems
+ shown, then rerun the command to find any remaining
+ problems. Repeat until all of the errors that are fixable
+ are resolved. If an error seems unsolvable, ask for
+ assistance on the &a.doc;.
+
+
+
+ Always build-test changes before
+ submitting them. Running make in the
+ top-level directory of the documentation being edited will
+ generate that documentation in split HTML format. For
+ example, to build the English version of the Handbook in
+ HTML, type make in the
+ en_US.ISO8859-1/books/handbook/
+ directory.
+
+
+
+ When changes are complete and tested, generate a
+ diff file
:
+
+ &prompt.user; cd /usr/doc
&prompt.user; svn diff > bsdinstall.diff.txt
- Give the diff file a descriptive name.
- In the example above, changes have been made to the
- bsdinstall portion
- of the Handbook.
-
-
-
- Submit the diff file using the web-based Problem
- Report system or with &man.send-pr.1;. If using
- the web form, enter a synopsis of [patch]
- short description of
- problem. Select the category
- docs and the class
- doc-bug. In the body of the message,
- enter a short description of the changes and any
- important details about them. Use the
- [ Browse... ] button to
- attach the .diff.txt.
-
-
-
-
+ Give the diff file a descriptive name. In the example
+ above, changes have been made to the
+ bsdinstall portion of
+ the Handbook.
+
+
+
+ Submit the diff file using the web-based
+ Problem
+ Report system or with &man.send-pr.1;. If using
+ the web form, enter a synopsis of
+ [patch] short description of
+ problem. Select the category
+ docs and the class
+ doc-bug. In the body of the message,
+ enter a short description of the changes and any important
+ details about them. Use the
+ [ Browse... ] button to
+ attach the .diff.txt.
+
+
+
+