From owner-svn-doc-all@FreeBSD.ORG Mon Jun 17 17:13:55 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id 0C13DCA9; Mon, 17 Jun 2013 17:13:55 +0000 (UTC) (envelope-from dru@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id E1EDB124A; Mon, 17 Jun 2013 17:13:54 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r5HHDsxt068010; Mon, 17 Jun 2013 17:13:54 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r5HHDspD068008; Mon, 17 Jun 2013 17:13:54 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201306171713.r5HHDspD068008@svn.freebsd.org> From: Dru Lavigne Date: Mon, 17 Jun 2013 17:13:54 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r41934 - head/en_US.ISO8859-1/books/fdp-primer/overview X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 17 Jun 2013 17:13:55 -0000 Author: dru Date: Mon Jun 17 17:13:54 2013 New Revision: 41934 URL: http://svnweb.freebsd.org/changeset/doc/41934 Log: White space fix only, translators can ignore. Approved by: bcr (mentor) Modified: head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Mon Jun 17 15:47:47 2013 (r41933) +++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Mon Jun 17 17:13:54 2013 (r41934) @@ -34,24 +34,27 @@ 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. @@ -63,55 +66,57 @@ - 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/. @@ -120,65 +125,63 @@ 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: @@ -192,96 +195,100 @@ 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. + + 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 + 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