Index: head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml (revision 50694) +++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml (revision 50695) @@ -1,254 +1,259 @@ 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. Quick Start Some preparatory steps must be taken before editing the &os; documentation. First, subscribe to the &a.doc;. Some team members also interact on the #bsddocs IRC channel on EFnet. These people can help with questions or problems involving the documentation. Install the - textproc/docproj - package or port. This meta-port installs all of the - software needed to edit and build &os; documentation. + textproc/docproj meta-package + and Subversion. + This meta-package installs all of the software needed to + edit and build &os; documentation. The + Subversion package is needed to + obtain a working of the documentation and generate patches with. + + &prompt.root; pkg install docproj subversion Install a local working copy of the documentation from the &os; repository in ~/doc (see ). &prompt.user; svn checkout https://svn.FreeBSD.org/doc/head ~/doc 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. Specific editor configurations are listed 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 mailing list 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 are resolved. Always build-test changes before submitting them. Running make in the top-level directory of the documentation being edited will generate that documentation in split HTML format. For example, to build the English version of the Handbook in HTML, run make in the en_US.ISO8859-1/books/handbook/ directory. When changes are complete and tested, generate a diff file: &prompt.user; cd ~/doc &prompt.user; svn diff > bsdinstall.diff.txt 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. If using the web form, enter a Summary of [patch] short description of problem. Select the Component Documentation. In the Description field, enter a short description of the changes and any important details about them. Use the [ Add an attachment ] button to attach the diff file. Finally, use the [ Submit Bug ] button to submit your diff to the problem report system. 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 &a.svn-doc-all.url;. Web frontends to both of these repositories are available at and . 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. Index: head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml (revision 50694) +++ head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml (revision 50695) @@ -1,176 +1,176 @@ The Working Copy The working copy is a copy of the &os; repository documentation tree downloaded onto the local computer. Changes are made to the local working copy, tested, and then submitted as patches to be committed to the main repository. A full copy of the documentation tree can occupy 700 megabytes of disk space. Allow for a full gigabyte of space to have room for temporary files and test versions of various output formats. Subversion - is used to manage the &os; documentation files. It is installed - by textproc/docproj as one of - the required applications. + is used to manage the &os; documentation files. It is obtained by installing the Subversion package: + + &prompt.root; pkg install subversion Documentation and Manual Pages &os; documentation is not just books and articles. Manual pages for all the commands and configuration files are also part of the documentation, and part of the FDP's territory. Two repositories are involved: doc for the books and articles, and base for the operating system and manual pages. To edit manual pages, the base repository must be checked out separately. Repositories may contain multiple versions of documentation and source code. New modifications are almost always made only to the latest version, called head. Choosing a Directory &os; documentation is traditionally stored in /usr/doc/, and system source code with manual pages in /usr/src/. These directory trees are relocatable, and users may want to put the working copies in other locations to avoid interfering with existing information in the main directories. The examples that follow use ~/doc and ~/src, both subdirectories of the user's home directory. Checking Out a Copy A download of a working copy from the repository is called a checkout, and done with svn checkout. This example checks out a copy of the latest version (head) of the main documentation tree: &prompt.user; svn checkout https://svn.FreeBSD.org/doc/head ~/doc A checkout of the source code to work on manual pages is very similar: &prompt.user; svn checkout https://svn.FreeBSD.org/base/head ~/src Updating a Working Copy The documents and files in the &os; repository change daily. People modify files and commit changes frequently. Even a short time after an initial checkout, there will already be differences between the local working copy and the main &os; repository. To update the local version with the changes that have been made to the main repository, use svn update on the directory containing the local working copy: &prompt.user; svn update ~/doc Get in the protective habit of using svn update before editing document files. Someone else may have edited that file very recently, and the local working copy will not include the latest changes until it has been updated. Editing the newest version of a file is much easier than trying to combine an older, edited local file with the newer version from the repository. Reverting Changes Sometimes it turns out that changes were not necessary after all, or the writer just wants to start over. Files can be reset to their unchanged form with svn revert. For example, to erase the edits made to chapter.xml and reset it to unmodified form: &prompt.user; svn revert chapter.xml Making a Diff After edits to a file or group of files are completed, the differences between the local working copy and the version on the &os; repository must be collected into a single file for submission. These diff files are produced by redirecting the output of svn diff into a file: &prompt.user; cd ~/doc &prompt.user; svn diff > doc-fix-spelling.diff Give the file a meaningful name that identifies the contents. The example above is for spelling fixes to the whole documentation tree. If the diff file is to be submitted with the web Submit a &os; problem report interface, add a .txt extension to give the earnest and simple-minded web form a clue that the contents are plain text. Be careful: svn diff includes all changes made in the current directory and any subdirectories. If there are files in the working copy with edits that are not ready to be submitted yet, provide a list of only the files that are to be included: &prompt.user; cd ~/doc &prompt.user; svn diff disks/chapter.xml printers/chapter.xml > disks-printers.diff <application>Subversion</application> References These examples show very basic usage of Subversion. More detail is available in the Subversion Book and the Subversion documentation.