svn commit: r43887 - head/en_US.ISO8859-1/books/handbook/mirrors
Dru Lavigne
dru at FreeBSD.org
Wed Feb 12 21:01:00 UTC 2014
Author: dru
Date: Wed Feb 12 21:00:59 2014
New Revision: 43887
URL: http://svnweb.freebsd.org/changeset/doc/43887
Log:
Finish initial pass through CTM chapter.
Sponsored by: iXsystems
Modified:
head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml Wed Feb 12 19:38:42 2014 (r43886)
+++ head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml Wed Feb 12 21:00:59 2014 (r43887)
@@ -148,7 +148,7 @@
to obtain up to three deltas per day for the most active
branches. Update sizes are always kept as
small as possible and are typically less than 5K. About one in very ten
- update is 10-50K in size and rarely there will be an update
+ updates is 10-50K in size, and there will occasionally be an update
larger than 100K+.</para>
<para>When using <application>CTM</application> to track &os; development,
@@ -172,8 +172,7 @@
email.</para>
<para><acronym>FTP</acronym> deltas can be obtained from the following mirror sites.
- Download the relevant directory and read its
- <filename>README</filename>. When using anonymous <acronym>FTP</acronym> to obtain <application>CTM</application> deltas,
+ When using anonymous <acronym>FTP</acronym> to obtain <application>CTM</application> deltas,
select a geographically close mirror.
In case of problems, contact the &a.ctm-users.name;
mailing list.</para>
@@ -228,10 +227,10 @@
</variablelist>
<para>To instead receive deltas through email, subscribe to one of the
- <application>CTM</application> distribution lists.
- &a.ctm-src-cur.name; supports the entire source tree,
+ <literal>ctm-src</literal> distribution lists available from
+ <uri xlink:href="http://lists.freebsd.org/mailman/listinfo">http://lists.freebsd.org/mailman/listinfo</uri>. For example,
&a.ctm-src-cur.name; supports the HEAD of the development
- branch, and &a.ctm-src-9.name; supports the 9.X release branch.</para>
+ branch and &a.ctm-src-9.name; supports the 9.X release branch.</para>
<para>As
<application>CTM</application> updates arrive through email,
@@ -253,154 +252,142 @@
</sect2>
<sect2>
- <title>Using <application>CTM</application> for the First
- Time</title>
+ <title><application>CTM</application> Usage</title>
<para>Before <application>CTM</application>
- deltas can be used, a starting point for the
- deltas must be produced from an <quote>empty</quote> directory.
- An initial <quote>Empty</quote> delta is used to start
- the local <application>CTM</application>-supported tree.</para>
-
- <para>Since the trees are many tens of megabytes, you should
- prefer to start from something already at hand. If you have a
- -RELEASE CD, you can copy or extract an initial source from
- it. This will save a significant transfer of data.</para>
-
- <para>You can recognize these <quote>starter</quote> deltas by
- the <literal>X</literal> appended to the number
- (<filename>src-cur.3210XEmpty.gz</filename> for instance).
+ deltas can be used for the first time, a starting point
+ must be produced.</para>
+
+ <para>One method is to apply a <quote>starter</quote> delta to an
+ empty directory. A
+ starter delta can be recognized by
+ the <filename>XEmpty</filename> in its name, such as
+ <filename>src-cur.3210XEmpty.gz</filename>.
The designation following the <literal>X</literal> corresponds
- to the origin of your initial <quote>seed</quote>.
- <filename>Empty</filename> is an empty directory. As a rule a
+ to the origin of the initial <quote>seed</quote>, where
+ <filename>Empty</filename> is an empty directory. As a rule, a
base transition from <literal>Empty</literal> is produced
- every 100 deltas. By the way, they are large! 70 to 80
+ every 100 deltas. Be aware that starter deltas are large and
+ 70 to 80
Megabytes of <command>gzip</command>'d data is common for the
<filename>XEmpty</filename> deltas.</para>
- <para>Once you have picked a base delta to start from, you will
- also need all deltas with higher numbers following it.</para>
- </sect2>
-
- <sect2>
- <title>Using <application>CTM</application> in Your Daily
- Life</title>
-
- <para>To apply the deltas, simply say:</para>
-
- <screen>&prompt.root; <userinput>cd /where/ever/you/want/the/stuff</userinput>
-&prompt.root; <userinput>ctm -v -v /where/you/store/your/deltas/src-xxx.*</userinput></screen>
-
- <para><application>CTM</application> understands deltas which
- have been put through <command>gzip</command>, so you do not
- need to <command>gunzip</command> them first, this saves disk
+ <para>Another method is to copy or extract an initial source from
+ a
+ RELEASE media as this can
+ save a significant transfer of data from the Internet.</para>
+
+ <para>Once a base delta has been created, apply
+ all deltas with higher numbers. To apply the deltas:</para>
+
+ <screen>&prompt.root; <userinput>cd /directory/to/store/the/stuff</userinput>
+&prompt.root; <userinput>ctm -v -v /directory/which/stores/the/deltas/src-xxx.*</userinput></screen>
+
+ <para>Multiple deltas can be applied at one time as they
+ will be processed one at a time and any deltas that are already
+ applied will be ignored. <application>CTM</application> understands deltas which
+ have been put through <command>gzip</command>, which saves disk
space.</para>
- <para>Unless it feels very secure about the entire process,
- <application>CTM</application> will not touch your tree. To
- verify a delta you can also use the <option>-c</option> flag
- and <application>CTM</application> will not actually touch
- your tree; it will merely verify the integrity of the delta
- and see if it would apply cleanly to your current tree.</para>
-
- <para>There are other options to <application>CTM</application>
- as well, see the manual pages or look in the sources for more
- information.</para>
-
- <para>That is really all there is to it. Every time you get a
- new delta, just run it through <application>CTM</application>
- to keep your sources up to date.</para>
-
- <para>Do not remove the deltas if they are hard to download
- again. You just might want to keep them around in case
- something bad happens. Even if you only have floppy disks,
- consider using <command>fdwrite</command> to make a
- copy.</para>
+ <para>To
+ verify a delta without applying it, include <option>-c</option>.
+ <application>CTM</application> will not actually touch
+ the local tree but will instead verify the integrity of the delta
+ to see if it would apply cleanly. Refer to &man.ctm.1; for
+ more information about available switches and an overview of
+ the process <application>CTM</application> uses when applying
+ deltas.</para>
+
+ <para>To keep the local source tree up-to-date, every time a
+ new delta becomes available, apply it through <application>CTM</application>.</para>
+
+ <para>Once applied, it is recommended to not delete the deltas if it is a burden to download
+ them again. This way, a local copy is available in case
+ something bad happens.</para>
</sect2>
<sect2>
- <title>Keeping Your Local Changes</title>
+ <title>Keeping Local Changes</title>
- <para>As a developer one would like to experiment with and
- change files in the source tree.
+ <para>Developers often experiment with and
+ change files in thier local source tree.
<application>CTM</application> supports local modifications in
- a limited way: before checking for the presence of a file
- <filename>foo</filename>, it first looks for
- <filename>foo.ctm</filename>. If this file exists,
- <application>CTM</application> will operate on it instead of
- <filename>foo</filename>.</para>
-
- <para>This behavior gives us a simple way to maintain local
- changes: simply copy the files you plan to modify to the
- corresponding file names with a <filename>.ctm</filename>
- suffix. Then you can freely hack the code, while
- <application>CTM</application> keeps the
- <filename>.ctm</filename> file up-to-date.</para>
+ a limited way: before checking for the presence of a file,
+ it first looks for a file with the same name and a
+ <filename>.ctm</filename> extension. If this file exists,
+ <application>CTM</application> will operate on it instead of the
+ original filename.</para>
+
+ <para>This behavior provides a simple way to maintain local
+ changes. Before modifying a file, make a copy with a
+ <filename>.ctm</filename>
+ suffix. Make any changes to the original filename, knowing that
+ <application>CTM</application> will only apply updates to the file with the
+ <filename>.ctm</filename> suffix.</para>
</sect2>
<sect2>
- <title>Other Interesting <application>CTM</application>
+ <title>Other <application>CTM</application>
Options</title>
- <sect3>
- <title>Finding Out Exactly What Would Be Touched by an
- Update</title>
-
- <para>You can determine the list of changes that
- <application>CTM</application> will make on your source
- repository using the <option>-l</option> option to
- <application>CTM</application>.</para>
-
- <para>This is useful if you would like to keep logs of the
- changes, pre- or post- process the modified files in any
- manner, or just are feeling a tad paranoid.</para>
- </sect3>
+ <variablelist>
+ <varlistentry>
+ <term>Finding Out Exactly What Would Be Touched by an
+ Update</term>
- <sect3>
- <title>Making Backups Before Updating</title>
+ <listitem>
+ <para>To determine the list of changes that
+ <application>CTM</application> will make to the local source
+ repository, use <option>-l</option>. This option is useful for creating logs of the
+ changes or when performing pre- or post-processing on any of the modified files.</para>
+ </listitem>
+ </varlistentry>
- <para>Sometimes you may want to backup all the files that
- would be changed by a <application>CTM</application>
- update.</para>
+ <varlistentry>
+ <term>Making Backups Before Updating</term>
- <para>Specifying the <option>-B backup-file</option> option
- causes <application>CTM</application> to backup all files
- that would be touched by a given
+ <listitem>
+ <para>To backup all of the files that
+ would be changed by a <application>CTM</application>
+ update, specify <option>-B backup-file</option>. This option
+ tells <application>CTM</application> to backup all files
+ touched by the applied
<application>CTM</application> delta to
<filename>backup-file</filename>.</para>
- </sect3>
+ </listitem>
+ </varlistentry>
- <sect3>
- <title>Restricting the Files Touched by an Update</title>
+ <varlistentry>
+ <term>Restricting the Files Touched by an Update</term>
- <para>Sometimes you would be interested in restricting the
+ <listitem>
+ <para>To restrict the
scope of a given <application>CTM</application> update, or
- may be interested in extracting just a few files from a
- sequence of deltas.</para>
-
- <para>You can control the list of files that
- <application>CTM</application> would operate on by
- specifying filtering regular expressions using the
- <option>-e</option> and <option>-x</option> options.</para>
+ to extract just a few files from a
+ sequence of deltas,
+ filtering regular expressions can be specified using
+ <option>-e</option>, which specifies which files to process, or <option>-x</option>, which specifies which files to ignore.</para>
<para>For example, to extract an up-to-date copy of
- <filename>lib/libc/Makefile</filename> from your collection
- of saved <application>CTM</application> deltas, run the
- commands:</para>
+ <filename>lib/libc/Makefile</filename> from a collection
+ of saved <application>CTM</application> deltas:</para>
- <screen>&prompt.root; <userinput>cd /where/ever/you/want/to/extract/it/</userinput>
-&prompt.root; <userinput>ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*</userinput></screen>
+ <screen>&prompt.root; <userinput>cd /directory/to/extract/to/</userinput>
+&prompt.root; <userinput>ctm -e '^lib/libc/Makefile' /directory/which/stores/the/deltas/src-xxx.*</userinput></screen>
<para>For every file specified in a
- <application>CTM</application> delta, the
- <option>-e</option> and <option>-x</option> options are
- applied in the order given on the command line. The file is
+ <application>CTM</application> delta,
+ <option>-e</option> and <option>-x</option> are
+ applied in the order given on the command line. A file is
processed by <application>CTM</application> only if it is
- marked as eligible after all the <option>-e</option> and
- <option>-x</option> options are applied to it.</para>
- </sect3>
+ marked as eligible after all <option>-e</option> and
+ <option>-x</option> options are applied.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</sect2>
-
+<!--
+Comment out for now until these can be verified.
<sect2>
<title>Future Plans for <application>CTM</application></title>
@@ -425,6 +412,7 @@
<literal>ports</literal> collection too, but interest has not
been all that high yet.</para>
</sect2>
+ -->
</sect1>
<sect1 xml:id="svn">
More information about the svn-doc-all
mailing list