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 f0c83133bd..e1e15426fa 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,294 @@ Overview - Welcome to the &os; Documentation Project (FDP). Quality - documentation is very important to the success of &os;. 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 explain - how the FDP is organized, how to - write and submit documentation, and - how to effectively use the available tools. + 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. + 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: + After you have finished reading this document you will be + able to: - Identify which parts of &os; are maintained by the FDP. + 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. + 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. + The FDP is responsible for four + categories of &os; documentation. - - Handbook: The Handbook is the comprehensive online - resource and reference for &os; users. + + 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. + 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 + 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 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;. - + 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 + 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;. + are visible to anyone usingvsvn. + 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. + 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. + 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 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. - + 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. - If /usr/doc already - exists, move or delete it first to prevent file - conflicts. + 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 + 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 + + 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 + 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: + + 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;. + 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 + + 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 + + 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: + 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. + + 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. - + \ No newline at end of file