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 cf948a087f..6616d9591b 100644 --- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml @@ -1,282 +1,265 @@ 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. 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 . 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 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. If /usr/doc already exists, move - or delete it first to prevent file conflicts. + from a mirror of the &os; repository (see ) in ~/doc. &prompt.user; svn checkout https://svn0.us-west.FreeBSD.org/doc/head /usr/doc - For the fastest download, pick the nearest mirror from - the list of Subversion - mirror sites. - The editor to be used should be configured as - follows: + 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. - Some specific editor configurations - are listed in . + Specific editor configurations + are listed in . - Run svn up to update the local - working copy. Edit the documentation files that need - changes. Before making major changes to a file, ask for - input on the &a.doc;. - - To learn which tags and entities are needed to achieve - the desired formatting, compare some text in the - HTML formatted version of the document - to the text, tags, and entities in the - XML file. References to the commonly - used tags and entities can be found 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. By default, typing + submitting them. Running make in the top-level directory of - the type of documentation being edited will generate that + 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. This step is necessary to make sure that edits - do not break the build. + directory. - After successfully completing the previous steps, - generate a diff file of the changes: + 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 name that describes the contents. + 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, input a synopsis of [patch] + the web form, enter 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 + 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. - - Remember that the FDP is comprised - of volunteers who review edits in their spare time and who - live in different time zones around the globe. It can - take some time to review changes. If a response is not - received 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.