From owner-svn-doc-all@FreeBSD.ORG Thu Jul 18 22:49:40 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 633E525A; Thu, 18 Jul 2013 22:49:40 +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 5356EDAE; Thu, 18 Jul 2013 22:49:40 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r6IMnedi001300; Thu, 18 Jul 2013 22:49:40 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r6IMndco001294; Thu, 18 Jul 2013 22:49:39 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307182249.r6IMndco001294@svn.freebsd.org> From: Warren Block Date: Thu, 18 Jul 2013 22:49:39 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42322 - in head/en_US.ISO8859-1/books/fdp-primer: . working-copy 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: Thu, 18 Jul 2013 22:49:40 -0000 Author: wblock Date: Thu Jul 18 22:49:39 2013 New Revision: 42322 URL: http://svnweb.freebsd.org/changeset/doc/42322 Log: Add a chapter on the working copy, and rearrange the other chapters to get the details closer to the order they are needed by the reader. Reviewed by: bjk, eadler Added: head/en_US.ISO8859-1/books/fdp-primer/working-copy/ head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml (contents, props changed) Modified: head/en_US.ISO8859-1/books/fdp-primer/Makefile head/en_US.ISO8859-1/books/fdp-primer/book.xml head/en_US.ISO8859-1/books/fdp-primer/chapters.ent Modified: head/en_US.ISO8859-1/books/fdp-primer/Makefile ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/Makefile Thu Jul 18 21:33:31 2013 (r42321) +++ head/en_US.ISO8859-1/books/fdp-primer/Makefile Thu Jul 18 22:49:39 2013 (r42322) @@ -32,6 +32,7 @@ SRCS+= doc-build/chapter.xml SRCS+= the-website/chapter.xml SRCS+= tools/chapter.xml SRCS+= translations/chapter.xml +SRCS+= working-copy/chapter.xml SRCS+= writing-style/chapter.xml SRCS+= examples/appendix.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/book.xml Thu Jul 18 21:33:31 2013 (r42321) +++ head/en_US.ISO8859-1/books/fdp-primer/book.xml Thu Jul 18 22:49:39 2013 (r42322) @@ -250,13 +250,14 @@ The time is 09:18 &chap.overview; &chap.tools; + &chap.working-copy; + &chap.structure; + &chap.doc-build; + &chap.the-website; &chap.xml-primer; &chap.xhtml-markup; &chap.docbook-markup; &chap.stylesheets; - &chap.structure; - &chap.doc-build; - &chap.the-website; &chap.translations; &chap.writing-style; &chap.psgml-mode; Modified: head/en_US.ISO8859-1/books/fdp-primer/chapters.ent ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/chapters.ent Thu Jul 18 21:33:31 2013 (r42321) +++ head/en_US.ISO8859-1/books/fdp-primer/chapters.ent Thu Jul 18 22:49:39 2013 (r42322) @@ -11,17 +11,18 @@ --> - + + + + + - - - Added: head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml Thu Jul 18 22:49:39 2013 (r42322) @@ -0,0 +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. + + Subversion + is used to manage the &os; documentation files. It is installed + by textproc/docproj as one of + the required applications. + + + 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 Mirror + + To increase speed and reduce download time, select a mirror + from the list of Subversion + mirror sites that is close to your location. + Substitute the chosen mirror URL for the + https://svn0.us-west.FreeBSD.org/ + used in these examples. + + + + 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://svn0.us-west.FreeBSD.org/doc/head ~/doc + + A checkout of the source code to work on manual pages is + very similar: + + &prompt.user; svn checkout https://svn0.us-west.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 some changes made locally 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 complete, 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 + +