From owner-svn-doc-all@FreeBSD.ORG Mon Jun 17 14:00:36 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 0433C277; Mon, 17 Jun 2013 14:00:36 +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 DA2621849; Mon, 17 Jun 2013 14:00:35 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r5HE0ZAF003548; Mon, 17 Jun 2013 14:00:35 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r5HE0ZSu003547; Mon, 17 Jun 2013 14:00:35 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201306171400.r5HE0ZSu003547@svn.freebsd.org> From: Warren Block Date: Mon, 17 Jun 2013 14:00:35 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r41932 - 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 14:00:36 -0000 Author: wblock Date: Mon Jun 17 14:00:35 2013 New Revision: 41932 URL: http://svnweb.freebsd.org/changeset/doc/41932 Log: Modernize the FDP introduction and Quick Start sections. Submitted 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 Mon Jun 17 08:10:55 2013 (r41931) +++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Mon Jun 17 14:00:35 2013 (r41932) @@ -34,279 +34,254 @@ Overview - Welcome to the FreeBSD Documentation Project. Good quality - documentation is very important to the success of FreeBSD, and the - FreeBSD Documentation Project (FDP) is how a lot of that - documentation is produced. 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 clearly explain - how the FDP is organized, how to - write and submit documentation to the FDP, and - how to effectively use the tools available to you when - writing documentation. - - - Membership - - Everyone is welcome to join the FDP. There is no minimum - membership requirement, no quota of documentation you need to - produce per month. All you need to do is subscribe to the - &a.doc;. + 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 - should: + will be able to: - Know which documentation is maintained by the FDP. + Identify which parts of &os; are maintained by the FDP. - Be able to read and understand the XML source code for - the documentation maintained by the FDP. + Install the required tools and files. - Be able to make changes to the documentation. + Make changes to the documentation. - Be able to submit your changes back for review and - eventual inclusion in the FreeBSD documentation. + Submit changes back for review and + eventual inclusion in the &os; documentation. - The FreeBSD Documentation Set + The &os; Documentation Set - The FDP is responsible for four categories of FreeBSD + The FDP is responsible for four categories of &os; documentation. - - - Manual pages - - - The English language system manual pages are not - written by the FDP, as they are part of the base system. - However, the FDP can (and has) re-worded parts of existing - manual pages to make them clearer, or to correct - inaccuracies. - - The translation teams are responsible for translating - the system manual pages into different languages. These - translations are kept within the FDP. - - - - - FAQ - - - The FAQ aims to address (in short question and answer - format) questions that are asked, or should be asked, on - the various mailing lists and newsgroups devoted to - FreeBSD. The format does not permit long and - comprehensive answers. - - - - - Handbook - - - The Handbook aims to be the comprehensive on-line - resource and reference for FreeBSD users. - - - - - Web site - - - This is the main FreeBSD presence on the World Wide - Web, visible at http://www.FreeBSD.org/ - and many mirrors around the world. The web site is many - people's first exposure to FreeBSD. - - - - - The documentation for the web site, &os; Handbook, and FAQ - are available in the doc/ Subversion - repository, which is located at - https://svn.FreeBSD.org/doc/. - - Manual pages are available in the src/ - Subversion repository, which is available at - https://svn.FreeBSD.org/base/. - - This means that the logs of changes to these - files are visible to anyone, and anyone can use - svn to view the changes. - - In addition, many people have written tutorials or other web - sites relating to FreeBSD. Some of these are stored in the - Subversion repository as well (where the author has agreed to - this). In other cases the author has decided to keep his - documentation separate from the main FreeBSD repository. The - FDP endeavors to provide links to as much of this documentation - as possible. - - - - Before You Start + - This document assumes that you already know: + + Handbook: The Handbook is the comprehensive online + resource and reference for &os; users. + + - - How to maintain an up-to-date local copy of the FreeBSD - documentation by maintaining a local copy of the FreeBSD - Subversion repository using - svn. + 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. - How to download and install new software using either - the FreeBSD Ports system or &man.pkg.add.1;. - + 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 - If you just want to get going, and feel confident you can - pick things up as you go along, follow these - instructions. + 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 - meta-port. - - &prompt.root; cd /usr/ports/textproc/docproj -&prompt.root; make JADETEX=no install - - - - Get a local copy of the FreeBSD doc - tree using svn. - - If network bandwidth or local drive space is a concern, - then at minimum, the head/share and - head/language/share - directories will need to be checked out. For - example: - - &prompt.user; mkdir -p head/share -&prompt.user; mkdir -p head/en_US.ISO8859-1/share -&prompt.user; svn checkout https://svn0.us-east.FreeBSD.org/doc/head/share head/share -&prompt.user; svn checkout https://svn0.us-east.FreeBSD.org/doc/head/en_US.ISO8859-1/share head/en_US.ISO8859-1/share - - If you have plenty of disk space then you could check - out everything. - - &prompt.user; svn checkout https://svn0.us-east.FreeBSD.org/doc/head head - - - svn0.us-east.FreeBSD.org - is a public SVN server. - Select the closest mirror and verify the mirror server - certificate from the list of Subversion - mirror sites. - + 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. + + &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. + + - If you are preparing a change to an existing book or - article, check it out of the repository as necessary. If - you are planning on contributing a new book or article then - use an existing one as a guide. - - For example, if you want to contribute a new article - about setting up a VPN between FreeBSD and Windows 2000 you - might do the following. + 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 . + - - Check out the articles - directory. + Once the edits are complete, check for problems by running: - &prompt.user; svn checkout https://svn0.us-east.FreeBSD.org/doc/head/en_US.ISO8859-1/articles - + &prompt.user; igor -R filename.xml | less -RS - - Copy an existing article to use as a template. In - this case, you have decided that your new article - belongs in a directory called - vpn-w2k. - - &prompt.user; cd head/en_US.ISO8859-1/articles -&prompt.user; svn export committers-guide vpn-w2k - - - - If you wanted to edit an existing document, such as the - FAQ, which is in - head/en_US.ISO8859-1/books/faq you - would check it out of the repository like this. - - &prompt.user; svn checkout https://svn0.us-east.FreeBSD.org/doc/head/en_US.ISO8859-1/books/faq - - - - Edit the .xml files using your - editor of choice. - - - - Test the markup using the lint - target. This will quickly find any errors in the document - without actually performing the time-consuming - transformation. - - &prompt.user; make lint - - When you are ready to actually build the document, you - may specify a single format or a list of formats in the - FORMATS variable. Currently, - html, html-split, - txt, ps, - pdf, and rtf are - supported. The most up to date list of supported formats is - listed at the top of the - head/share/mk/doc.docbook.mk file. - Make sure to use quotes around the list of formats when you - build more than one format with a single command. - - For example, to convert the document to - html only, you would use: - - &prompt.user; make FORMATS=html - - But when you want to convert the document to both - html and txt format, - you could use either two separate &man.make.1; runs, - with: - - &prompt.user; make FORMATS=html -&prompt.user; make FORMATS=txt - - or, you can do it in one command: - - &prompt.user; make FORMATS="html txt" - - - - Submit your changes using &man.send-pr.1;. - - - - + 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. + + + +