From owner-svn-doc-all@FreeBSD.ORG Sun Jul 14 13:03:01 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 62471A25; Sun, 14 Jul 2013 13:03:01 +0000 (UTC) (envelope-from wblock@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 5394A6D; Sun, 14 Jul 2013 13:03:01 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r6ED30Yb030541; Sun, 14 Jul 2013 13:03:00 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r6ED30C4030540; Sun, 14 Jul 2013 13:03:00 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307141303.r6ED30C4030540@svn.freebsd.org> From: Warren Block Date: Sun, 14 Jul 2013 13:03:00 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42279 - 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: Sun, 14 Jul 2013 13:03:01 -0000 Author: wblock Date: Sun Jul 14 13:03:00 2013 New Revision: 42279 URL: http://svnweb.freebsd.org/changeset/doc/42279 Log: Simplify and clarify. Reviewed by: dru 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 Sun Jul 14 08:24:02 2013 (r42278) +++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Sun Jul 14 13:03:00 2013 (r42279) @@ -47,7 +47,7 @@ FDP. Willingness to contribute is the only membership requirement. - This primer shows the reader how to: + This primer shows how to: @@ -64,7 +64,7 @@ - Submit changes back for review and eventual inclusion in + Submit changes back for review and inclusion in the &os; documentation. @@ -110,22 +110,22 @@ Translation teams are responsible for translating the Handbook and web site into different languages. Manual pages - are not translated. + are not translated at present. Documentation source for the &os; web site, Handbook, and - FAQ is available in the Subversion + FAQ is available in the documentation repository at https://svn.FreeBSD.org/doc/. Source for manual pages is available in a separate - Subversion repository located at + source repository located at https://svn.FreeBSD.org/base/. Documentation commit messages are visible with - svn. Commit messages are also + svn log. Commit messages are also archived at . - In addition, many people have written tutorials or how-to + 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 @@ -136,8 +136,8 @@ Quick Start - Here we describe the steps contributors must take before - making changes to the FDP. New + 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 @@ -148,8 +148,8 @@ - Subscribe to the &a.doc;. Some members of the mailing - list also interact on the #bsddocs + Subscribe to the &a.doc;. Some mailing list + members also interact on the #bsddocs IRC channel on EFnet. @@ -158,26 +158,25 @@ Install the textproc/docproj package or port. This meta-port installs all of the - utilities needed by the FDP. + software needed to edit and build &os; documentation. 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 + + For the fastest download, pick the nearest mirror from + the list of Subversion + mirror sites. - 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 + The editor to be used should be configured as follows: @@ -194,38 +193,43 @@ single tab. + + + Some specific editor configurations + are listed in . - Locate the file to edit. Run - svn up within the local working copy to - make sure that it is up to date. Before making major - changes to a file, discuss the proposed changes with the + 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;. - 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 + 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 tags which surround the text or the entities that - represent that text in the XML file. + to the text, tags, and entities + in the XML file. References to the commonly used tags and entities can be found in and . - After edits are complete, check for problems by + 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 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;. + 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;. @@ -234,34 +238,24 @@ 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 + 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 the + directory. This step is necessary to make sure that 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: + After successfully completing the previous steps, generate + a diff file of the changes: + + &prompt.user; cd /usr/doc +&prompt.user; svn diff > bsdinstall.diff.txt - &prompt.user; svn diff > bsdinstall.diff.txt + Give the diff file a name that describes the contents. + In the example above, changes have been made to the + bsdinstall portion + of the Handbook. @@ -276,15 +270,13 @@ 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. + attach the .diff.txt. - It is important to remember that the + 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 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 + 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.