svn commit: r42322 - in head/en_US.ISO8859-1/books/fdp-primer: . working-copy
Warren Block
wblock at FreeBSD.org
Thu Jul 18 22:49:40 UTC 2013
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>
More information about the svn-doc-all
mailing list