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 26f53a2657..f0c83133bd 100644 --- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml @@ -1,287 +1,287 @@ Overview 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 explain 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. There is no membership requirement or minimum quota of documentation that needs to be produced. After you have finished reading this document you will be able to: Identify which parts of &os; are maintained by the FDP. Install the required tools and files. Make changes to the documentation. Submit changes back for review and eventual 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. 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 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 package or port. This meta-port installs all of the utilities needed by the FDP. 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. + url="&url.books.handbook;/subversion-mirrors.html">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. 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 . Once the edits are complete, check for problems by running: &prompt.user; igor -R filename.xml | less -RS 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;. 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. 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. For example, to convert the document to both .html and .txt, use this command: &prompt.user; make FORMATS="html 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: &prompt.user; svn diff > bsdinstall.diff.txt 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.