Date: Thu, 18 Jul 2013 22:49:39 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> 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 Message-ID: <201307182249.r6IMndco001294@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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</screen></entry> &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 @@ --> <!ENTITY chap.overview SYSTEM "overview/chapter.xml"> -<!ENTITY chap.xml-primer SYSTEM "xml-primer/chapter.xml"> <!ENTITY chap.tools SYSTEM "tools/chapter.xml"> +<!ENTITY chap.working-copy SYSTEM "working-copy/chapter.xml"> +<!ENTITY chap.structure SYSTEM "structure/chapter.xml"> +<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml"> +<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml"> +<!ENTITY chap.xml-primer SYSTEM "xml-primer/chapter.xml"> <!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml"> <!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml"> <!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml"> -<!ENTITY chap.structure SYSTEM "structure/chapter.xml"> -<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml"> <!ENTITY chap.translations SYSTEM "translations/chapter.xml"> <!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml"> <!ENTITY chap.psgml-mode SYSTEM "psgml-mode/chapter.xml"> <!ENTITY chap.see-also SYSTEM "see-also/chapter.xml"> -<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml"> <!ENTITY app.examples SYSTEM "examples/appendix.xml"> 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 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- Copyright (c) 2013 Warren Block + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials provided + with the distribution. + + THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS + IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS + FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, + INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR + OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, + EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> + +<chapter id="working-copy"> + <title>The Working Copy</title> + + <para>The <emphasis>working copy</emphasis> 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.</para> + + <para><ulink + url="&url.books.handbook;/svn.html"><application>Subversion</application></ulink> + is used to manage the &os; documentation files. It is installed + by <filename role="package">textproc/docproj</filename> as one of + the required applications.</para> + + <sect1 id="working-copy-doc-and-src"> + <title>Documentation and Manual Pages</title> + + <para>&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 <acronym>FDP</acronym>'s + territory. Two repositories are involved: + <literal>doc</literal> for the books and articles, and + <literal>base</literal> for the operating system and manual + pages. To edit manual pages, the <literal>base</literal> + repository must be checked out separately.</para> + + <para>Repositories may contain multiple versions of documentation + and source code. New modifications are almost always made only + to the latest version, called <literal>head</literal>.</para> + </sect1> + + <sect1 id="working-copy-choosing-mirror"> + <title>Choosing a Mirror</title> + + <para>To increase speed and reduce download time, select a mirror + from the list of <ulink + url="&url.books.handbook;/subversion-mirrors.html">Subversion + mirror sites</ulink> that is close to your location. + Substitute the chosen mirror <acronym>URL</acronym> for the + <replaceable>https://svn0.us-west.FreeBSD.org/</replaceable> + used in these examples.</para> + </sect1> + + <sect1 id="working-copy-choosing-directory"> + <title>Choosing a Directory</title> + + <para>&os; documentation is traditionally stored in + <filename class="directory">/usr/doc/</filename>, and system + source code with manual pages in + <filename class="directory">/usr/src/</filename>. 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 <filename class="directory">~/doc</filename> + and <filename class="directory">~/src</filename>, both + subdirectories of the user's home directory.</para> + </sect1> + + <sect1 id="working-copy-checking-out"> + <title>Checking Out a Copy</title> + + <para>A download of a working copy from the repository is called + a <emphasis>checkout</emphasis>, and done with + <command>svn checkout</command>. This example checks out a + copy of the latest version (<literal>head</literal>) of + the main documentation tree:</para> + + <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org/doc/head</replaceable> <replaceable>~/doc</replaceable></userinput></screen> + + <para>A checkout of the source code to work on manual pages is + very similar:</para> + + <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org/base/head</replaceable> <replaceable>~/src</replaceable></userinput></screen> + </sect1> + + <sect1 id="working-copy-updating"> + <title>Updating a Working Copy</title> + + <para>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 + <command>svn update</command> on the directory containing the + local working copy:</para> + + <screen>&prompt.user; <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen> + + <para>Get in the protective habit of using + <command>svn update</command> 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.</para> + </sect1> + + <sect1 id="working-copy-revert"> + <title>Reverting Changes</title> + + <para>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 <quote>reset</quote> to their unchanged form with + <command>svn revert</command>. For example, to erase the edits + made to <filename>chapter.xml</filename> and reset it to + unmodified form:</para> + + <screen>&prompt.user; <userinput>svn revert chapter.xml</userinput></screen> + </sect1> + + <sect1 id="working-copy-making-diff"> + <title>Making a Diff</title> + + <para>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 <emphasis>diff</emphasis> files are produced + by redirecting the output of <command>svn diff</command> into a + file:</para> + + <screen>&prompt.user; <userinput>cd <replaceable>~/doc</replaceable></userinput> +&prompt.user; <userinput>svn diff > <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen> + + <para>Give the file a meaningful name that identifies the + contents. The example above is for spelling fixes to the whole + documentation tree.</para> + + <para>If the diff file is to be submitted with the web + <quote><ulink url="&url.base;/send-pr.html">Submit a &os; + problem report</ulink></quote> interface, add a + <filename>.txt</filename> extension to give the earnest and + simple-minded web form a clue that the contents are plain + text.</para> + + <para>Be careful: <command>svn diff</command> 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:</para> + + <screen>&prompt.user; <userinput>cd <replaceable>~/doc</replaceable></userinput> +&prompt.user; <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> > <replaceable>disks-printers.diff</replaceable></userinput></screen> + </sect1> +</chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307182249.r6IMndco001294>