diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/working-copy')
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml | 184 |
1 files changed, 0 insertions, 184 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml deleted file mode 100644 index 28f5fc2aa5..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml +++ /dev/null @@ -1,184 +0,0 @@ -<?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. - ---> -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" - xml: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>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.</para> - - <para><link - xlink:href="&url.books.handbook;/svn.html"><application>Subversion</application></link> - is used to manage the &os; documentation files. It is obtained by - installing the <application>Subversion</application> - package:</para> - - <screen>&prompt.root; <userinput>pkg install subversion</userinput></screen> - - <sect1 xml: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 xml:id="working-copy-choosing-directory"> - <title>Choosing a Directory</title> - - <para>&os; documentation is traditionally stored in - <filename>/usr/doc/</filename>, and system - source code with manual pages in - <filename>/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>~/doc</filename> - and <filename>~/src</filename>, both - subdirectories of the user's home directory.</para> - </sect1> - - <sect1 xml: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 https://svn.FreeBSD.org/doc/head <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 https://svn.FreeBSD.org/base/head <replaceable>~/src</replaceable></userinput></screen> - </sect1> - - <sect1 xml: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 xml:id="working-copy-revert"> - <title>Reverting Changes</title> - - <para>Sometimes it turns out that changes 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 xml:id="working-copy-making-diff"> - <title>Making a Diff</title> - - <para>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 <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><link - xlink:href="https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi">Submit - a &os; problem report</link></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> - - <sect1 xml:id="working-copy-subversion-references"> - <title><application>Subversion</application> References</title> - - <para>These examples show very basic usage of - <application>Subversion</application>. More detail is available - in the <link - xlink:href="http://svnbook.red-bean.com/">Subversion - Book</link> and the <link - xlink:href="http://subversion.apache.org/docs/">Subversion - documentation</link>.</para> - </sect1> -</chapter> |