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 f3a36601a3..26f53a2657 100644
--- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
@@ -1,312 +1,287 @@
Overview
- Welcome to the FreeBSD Documentation Project. Good quality
- documentation is very important to the success of FreeBSD, and the
- FreeBSD Documentation Project (FDP) is how a lot of that
- documentation is produced. Your contributions are very
+ Welcome to the &os; Documentation Project (FDP). Quality
+ documentation is very important to the success of &os;. Your contributions are very
valuable.
- This document's main purpose is to clearly explain
- how the FDP is organized, how to
- write and submit documentation to the FDP, and
- how to effectively use the tools available to you when
- writing documentation.
+ This document's main purpose is to explain
+ how the FDP is organized, how to
+ write and submit documentation, and
+ how to effectively use the available tools.
-
- Membership
-
- Everyone is welcome to join the FDP. There is no minimum
- membership requirement, no quota of documentation you need to
- produce per month. All you need to do is subscribe to the
- &a.doc;.
+ Everyone is welcome to contribute to the FDP. There is no membership requirement or minimum quota of
+ documentation that needs to be produced.
After you have finished reading this document you
- should:
+ will be able to:
- Know which documentation is maintained by the FDP.
+ Identify which parts of &os; are maintained by the FDP.
- Be able to read and understand the XML source code for
- the documentation maintained by the FDP.
+ Install the required tools and files.
- Be able to make changes to the documentation.
+ Make changes to the documentation.
- Be able to submit your changes back for review and
- eventual inclusion in the FreeBSD documentation.
+ Submit changes back for review and
+ eventual inclusion in the &os; documentation.
- The FreeBSD Documentation Set
+ The &os; Documentation Set
- The FDP is responsible for four categories of FreeBSD
+ The FDP is responsible for four categories of &os;
documentation.
-
-
- Manual pages
-
-
- The English language system manual pages are not
- written by the FDP, as they are part of the base system.
- However, the FDP can (and has) re-worded parts of existing
- manual pages to make them clearer, or to correct
- inaccuracies.
-
- The translation teams are responsible for translating
- the system manual pages into different languages. These
- translations are kept within the FDP.
-
-
-
-
- FAQ
-
-
- The FAQ aims to address (in short question and answer
- format) questions that are asked, or should be asked, on
- the various mailing lists and newsgroups devoted to
- FreeBSD. The format does not permit long and
- comprehensive answers.
-
-
-
-
- Handbook
-
-
- The Handbook aims to be the comprehensive on-line
- resource and reference for FreeBSD users.
-
-
-
-
- Web site
-
-
- This is the main FreeBSD presence on the World Wide
- Web, visible at http://www.FreeBSD.org/
- and many mirrors around the world. The web site is many
- people's first exposure to FreeBSD.
-
-
-
-
- The documentation for the web site, &os; Handbook, and FAQ
- are available in the doc/ Subversion
- repository, which is located at
- https://svn.FreeBSD.org/doc/.
-
- Manual pages are available in the src/
- Subversion repository, which is available at
- https://svn.FreeBSD.org/base/.
-
- This means that the logs of changes to these
- files are visible to anyone, and anyone can use
- svn to view the changes.
-
- In addition, many people have written tutorials or other web
- sites relating to FreeBSD. Some of these are stored in the
- Subversion repository as well (where the author has agreed to
- this). In other cases the author has decided to keep his
- documentation separate from the main FreeBSD repository. The
- FDP endeavors to provide links to as much of this documentation
- as possible.
-
-
-
- Before You Start
+
- This document assumes that you already know:
+
+ Handbook: The Handbook is the comprehensive online
+ resource and reference for &os; users.
+
+
-
- How to maintain an up-to-date local copy of the FreeBSD
- documentation by maintaining a local copy of the FreeBSD
- Subversion repository using
- svn.
+ 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.
- How to download and install new software using either
- the FreeBSD Ports system or &man.pkg.add.1;.
-
+ 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.
+
+ Documentation source for the &os; web site, Handbook, and FAQ
+ is available in the Subversion
+ repository at
+ https://svn.FreeBSD.org/doc/.
+
+ Source for manual pages is available in a separate
+ Subversion repository located at
+ https://svn.FreeBSD.org/base/.
+
+ The commit messages to the FDP
+ are visible to anyone using
+ svn. They are also archived at
+ &a.svn-doc-all.url;.
+
+ In addition, many people have written tutorials or how-to
+ articles about &os;. Some are stored in the
+ FDP. In other
+ cases, the author has decided to keep the documentation separate
+ from the FDP. The
+ FDP endeavors to provide links to as much of this documentation
+ as possible.
Quick Start
- If you just want to get going, and feel confident you can
- pick things up as you go along, follow these
- instructions.
+ This section outlines the steps which new contributors need
+ to follow before they can make changes to the FDP. New contributors
+ will interact with other members of
+ the &os; Documentation Team which can assist in learning
+ how to use XML and the . 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 members of the mailing
+ list also interact on the #bsddocs IRC
+ channel on EFnet.
+
+
+
Install the
textproc/docproj
- meta-port.
-
- &prompt.root; cd /usr/ports/textproc/docproj
-&prompt.root; make JADETEX=no install
-
+ package or port. This meta-port
+ installs all of the utilities needed by the FDP.
+
- Get a local copy of the FreeBSD doc
- tree using svn.
-
- If network bandwidth or local drive space is a concern,
- then at minimum, the head/share and
- head/language/share
- directories will need to be checked out. For
- example:
-
- &prompt.user; mkdir -p head/share
-&prompt.user; mkdir -p head/en_US.ISO8859-1/share
-&prompt.user; svn checkout https://svn0.us-east.FreeBSD.org/doc/head/share head/share
-&prompt.user; svn checkout https://svn0.us-east.FreeBSD.org/doc/head/en_US.ISO8859-1/share head/en_US.ISO8859-1/share
-
- If you have plenty of disk space then you could check
- out everything.
-
- &prompt.user; svn checkout https://svn0.us-east.FreeBSD.org/doc/head head
-
-
- svn0.us-east.FreeBSD.org
- is a public SVN server.
- Select the closest mirror and verify the mirror server
- certificate from the list of Subversion
- mirror sites.
-
+ 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 Subversion mirror sites.
+ If /usr/doc already
+ exists, move or delete it first to prevent file
+ conflicts.
+
+ &prompt.user; svn checkout https://svn0.us-west.FreeBSD.org/doc/head /usr/doc
+
+
+
+ Before making any documentation edits, configure your
+ editor to conform to FDP standards. How to do so varies
+ by editor. Some editor configurations are listed in . The editor
+ should be configured as follows:
+
+
+ Word wrap set to 70 characters.
+
+
+ Tab stops set to 2.
+
+
+ Replace each group of 8 leading spaces with a
+ single tab.
+
+
- If you are preparing a change to an existing book or
- article, check it out of the repository as necessary. If
- you are planning on contributing a new book or article then
- use an existing one as a guide.
+ Determine which file to edit. Run svn up 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;.
+
+ 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 HTML formatted version of the document to the tags
+ which surround the text or the entities that represent
+ that text in the XML file. A
+ reference to the commonly used tags and entities can be
+ found in .
+
- For example, if you want to contribute a new article
- about setting up a VPN between FreeBSD and Windows 2000 you
- might do the following.
-
-
- Check out the articles
- directory.
+ Once the edits are complete, check for problems by running:
- &prompt.user; svn checkout https://svn0.us-east.FreeBSD.org/doc/head/en_US.ISO8859-1/articles
-
+ &prompt.user; igor -R filename.xml | less -RS
-
- Copy an existing article to use as a template. In
- this case, you have decided that your new article
- belongs in a directory called
- vpn-w2k.
-
- &prompt.user; cd head/en_US.ISO8859-1/articles
-&prompt.user; svn export committers-guide vpn-w2k
-
-
-
- If you wanted to edit an existing document, such as the
- FAQ, which is in
- head/en_US.ISO8859-1/books/faq you
- would check it out of the repository like this.
-
- &prompt.user; svn checkout https://svn0.us-east.FreeBSD.org/doc/head/en_US.ISO8859-1/books/faq
-
+ 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;.
+
- Edit the .xml files using your
- editor of choice.
+ Always build-test changes before submitting them. By
+ default, typing make 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 make
+ in the
+ en_US.ISO8859-1/books/handbook/
+ directory. This step is necessary to make sure that the
+ edits do not break the build.
- Test the markup using the lint
- target. This will quickly find any errors in the document
- without actually performing the time-consuming
- transformation.
-
- &prompt.user; make lint
-
- When you are ready to actually build the document, you
- may specify a single format or a list of formats in the
- FORMATS variable. Currently,
- html, html-split,
- txt, ps,
- pdf, and rtf are
- supported. The most up to date list of supported formats is
- listed at the top of the
- head/share/mk/doc.docbook.mk file.
- Make sure to use quotes around the list of formats when you
- build more than one format with a single command.
-
- For example, to convert the document to
- html only, you would use:
+ In order to build the output in other formats,
+ other make targets are defined
+ in head/share/mk/doc.docbook.mk.
+ Use quotes around the list of formats when
+ building more than one format with a single
+ command.
- &prompt.user; make FORMATS=html
+ For example, to convert the document to both
+ .html and .txt, use
+ this command:
- But when you want to convert the document to both
- html and txt format,
- you could use either two separate &man.make.1; runs,
- with:
+ &prompt.user; make FORMATS="html txt"
- &prompt.user; make FORMATS=html
-&prompt.user; make FORMATS=txt
+ Once these steps are successfully completed,
+ generate a diff file
of the changes. While in
+ /usr/doc, run this
+ command, replacing bsdinstall
+ with the name of the directory containing the edits:
- or, you can do it in one command:
-
- &prompt.user; make FORMATS="html txt"
-
+ &prompt.user; svn diff > bsdinstall.diff.txt
+
- Submit your changes using &man.send-pr.1;.
-
-
-
-
+ Submit the diff file using the web-based Problem Report
+ system or with &man.send-pr.1;. If using the web form,
+ input a synopsis of [patch] short description of problem.
+ Select the category docs and the
+ class doc-bug. The body of the
+ message should contain a short description of the edits
+ and any important discussion points. Use the [ Browse... ] button to attach the
+ .diff.txt file and enter the captcha
+ phrase.
+
+ It is important to remember that the FDP
+ 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.
+
+
+
+