docs-common/common cvs-en_US.xml,1.8,1.9
Paul W. Frields (pfrields)
fedora-docs-commits at redhat.com
Tue Jun 26 02:16:58 UTC 2007
Author: pfrields
Update of /cvs/docs/docs-common/common
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv4220
Modified Files:
cvs-en_US.xml
Log Message:
Content editing. I think I was supposed to do this quite a while ago
and probably got sidetracked. I'm doing this as part of the
documentation guide rehaul.
Index: cvs-en_US.xml
===================================================================
RCS file: /cvs/docs/docs-common/common/cvs-en_US.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- cvs-en_US.xml 26 Jun 2007 01:34:24 -0000 1.8
+++ cvs-en_US.xml 26 Jun 2007 02:16:55 -0000 1.9
@@ -12,15 +12,16 @@
<title>CVS</title>
<para>
The Concurrent Versions System (<application>CVS</application>)
- provides a framework where multiple users can edit the same files.
- As you can imagine, if a group of users edits the files in a single
- directory, chaos would reign. Using <application>CVS</application>,
- however, a group of people can safely work on the same set of files.
- <application>CVS</application> keeps the master copy of the files,
- and it records who changed what and when in a central repository. If
- conflicts arise, <application>CVS</application> lets you know.
- <application>CVS</application> is often used so that programmers can
- share code, but it also works well for documentation.
+ provides a framework for collaborative revision. Without such a
+ framework, a group of users editing files in a single directory
+ would cause chaos. Using <application>CVS</application>, however, a
+ group of people can safely work on the same set of files. The
+ <application>CVS</application> server keeps the master copy of the
+ files, and it records all changes and associated data, such as
+ authors and time, in a central repository. If conflicts arise,
+ <application>CVS</application> advises the users. Programmers often
+ use <application>CVS</application> to share code, but it also works
+ well for documentation.
</para>
<indexterm>
<primary>cvs</primary>
@@ -38,9 +39,6 @@
<para>
In most cases, each set of files that make up a package or project
is stored as a <firstterm>module</firstterm> on the CVS server.
- </para>
-
- <para>
When working with files from <application>CVS</application>, you
<firstterm>checkout</firstterm> a copy of the module on your local
file system. After modifying one or more files, you
@@ -50,14 +48,11 @@
<para>
With <application>CVS</application> you may edit a file without
- first getting permission or locking the file. The
- <wordasword>concurrent</wordasword> part of the
- <application>CVS</application> name comes from its ability to
- allow several different people to edit different parts of the same
- file. As long as none of the changes overlap,
- <application>CVS</application> can correctly record their changes.
- In case of duplicate changes, they are clearly marked in the files
- and the authors must resolve the issue among themselves.
+ first getting permission or locking the file. As long as none of
+ the changes overlap, <application>CVS</application> can correctly
+ record their changes. When duplicate changes occur, they are
+ clearly marked in the files and the authors must resolve the issue
+ among themselves.
</para>
<para>
@@ -68,12 +63,9 @@
file to the repository and then commit it. If you remove a file
from your local checkout of a module, you must specify that you
want to remove it from the repository on the CVS server and then
- commit the removal of the file.
- </para>
-
- <para>
- The specific commands to perform these actions are discussed in
- <xref linkend="sn-cvs-cvscommands"></xref>.
+ commit the removal of the file. The specific commands to perform
+ these actions are discussed in <xref
+ linkend="sn-cvs-cvscommands"/>.
</para>
<para>
@@ -82,15 +74,15 @@
<application>CVS</application> will try to merge the changes into
the master copy of the <application>CVS</application> server. If
the content you changed is in a different location in the file
- than the content changed by someone else, chances are, the commit
- action will go through without a <firstterm>conflict</firstterm>.
- If someone modified the same content as the content you just
- changed and tried to commit, you will see a message that a file
- conflict has occurred. Thus, you need to
- <firstterm>update</firstterm> your files frequently. It is a good
- practice to update them right before you start modifying a file.
- Refer to <xref linkend="sn-cvs-cvscommands-conflicts"></xref> for
- instructions on resolving conflicts.
+ than the content changed by someone else, the commit action will
+ likely go through without a <firstterm>conflict</firstterm>. If
+ someone modified the same content as the content you just changed
+ and tried to commit, you will see a message that a file conflict
+ has occurred. Thus, you need to <firstterm>update</firstterm> your
+ files frequently. It is a good practice to update them right
+ before you start modifying a file. Refer to <xref
+ linkend="sn-cvs-cvscommands-conflicts"/> for instructions on
+ resolving conflicts.
</para>
</section>
<section id="sn-cvs-preparation">
@@ -102,7 +94,7 @@
<para>
Before using <application>CVS</application>, you need to establish
an account with the <application>CVS</application> server. After
- getting an account, you do not need to perform these actions
+ you get an account, you do not need to perform these actions
again.
</para>
@@ -117,7 +109,7 @@
<abbrev>RPM</abbrev> package installed. Verify its presence by
typing the command:
</para>
-<screen><prompt>$ </prompt><command>rpm -q cvs</command></screen>
+ <screen><command>rpm -q cvs</command></screen>
<para>
If you see output similar to
<computeroutput>cvs-1.11.19-1</computeroutput>, then the package
@@ -179,7 +171,7 @@
key to work with version 2.0 protocol, at a shell prompt,
type the command:
</para>
-<screen><prompt>$ </prompt><command>ssh-keygen -t dsa</command></screen>
+ <screen><command>ssh-keygen -t dsa</command></screen>
<para>
Accept the default file location of
<filename>~/.ssh/id_dsa</filename>. You are strongly urged
@@ -194,16 +186,16 @@
Copy your new key to the correct file by typing the
following at a shell prompt.
</para>
-<screen><prompt>$ </prompt><command>cat ~/.ssh/id_dsa.pub>>~/.ssh/authorized_keys</command></screen>
+ <screen><command><![CDATA[cat ~/.ssh/id_dsa.pub >> ~/.ssh/authorized_keys]]></command></screen>
<note>
<para>
Check this command carefully before you press the
- <guibutton>ENTER</guibutton>
- key. If <filename>~/.ssh/authorized_keys</filename>
- already exists, the contents of
- <filename>~/.ssh/id_dsa.pub</filename> will be appended to
- the end of the <filename>~/.ssh/authorized_keys</filename>
- file.
+ <keycap>Enter</keycap> key. If
+ <filename>~/.ssh/authorized_keys</filename> already
+ exists, the contents of
+ <filename>~/.ssh/id_dsa.pub</filename> will be appended to
+ the end of the <filename>~/.ssh/authorized_keys</filename>
+ file.
</para>
</note>
</listitem>
@@ -212,8 +204,8 @@
Change the permissions of your <filename>~/.ssh</filename>
directory and your keys with the commands:
</para>
-<screen><prompt>$ </prompt><command>chmod 700 ~/.ssh</command>
-<prompt>$ </prompt><command>chmod 644 ~/.ssh/authorized_keys</command></screen>
+ <screen><command>chmod 700 ~/.ssh</command>
+<command>chmod 644 ~/.ssh/authorized_keys</command></screen>
</listitem>
</orderedlist>
<tip>
@@ -275,10 +267,10 @@
Create a file named <filename>~/.cvsrc</filename> in your home
directory. It should contain the following commands, one per
line:
-<screen><computeroutput>cvs -z3
+ <screen><computeroutput><![CDATA[cvs -z3
diff -uNp
rdiff -uNp
-update -dP</computeroutput></screen>
+update -dP]]></computeroutput></screen>
</para>
</section>
@@ -305,21 +297,19 @@
<application>CVS</application> to be located, and execute the
following commands:
</para>
-<screen><prompt>$ </prompt><command>export CVSROOT=:pserver:anonymous at cvs.fedoraproject.org:/cvs/docs</command>
-<prompt>$ </prompt><command>cvs login</command>
-<prompt>$ </prompt><command>cvs checkout</command> <replaceable>module-name</replaceable>
-<prompt>$ </prompt><command>cvs checkout</command> <replaceable>module-name</replaceable>
-<prompt>$ </prompt><command>cd</command> <replaceable>module-name</replaceable></screen>
- <para>
- Once you have checked the module out, it does not matter what
- your
- <envar>CVSROOT</envar>
- is set to because it is stored in the file
- <filename>CVS/Root</filename> for each directory in your local
- repository. As long as your current working directory has a
- <filename>CVS/</filename> directory, the
- <application>CVS</application> program will automatically locate
- the &FC; repository.
+ <screen><command>export CVSROOT=:pserver:anonymous at cvs.fedoraproject.org:/cvs/docs</command>
+<command>cvs login</command>
+<command>cvs checkout</command> <replaceable>module-name</replaceable>
+<command>cvs checkout</command> <replaceable>module-name</replaceable>
+<command>cd</command> <replaceable>module-name</replaceable></screen>
+ <para>
+ Once you have checked the module out, the value of your
+ <envar>$CVSROOT</envar> environment variable does not matter.
+ It is stored in the file <filename>CVS/Root</filename>
+ for each directory in your local repository. As long as your
+ current working directory has a <filename>CVS/</filename>
+ directory, the <application>CVS</application> program will
+ automatically locate the &FDP; repository.
</para>
</section>
@@ -343,27 +333,20 @@
</para>
<para>
- Every author, and that includes you once your self introduction
- has been received, has a unique
- <envar>$CVSROOT</envar>
- to access the <application>CVS</application> repository:
- </para>
-<screen><prompt>$ </prompt><command>export CVSROOT=:ext:</command><replaceable>yourname</replaceable><command>@cvs.fedoraproject.org:/cvs/docs</command>
-<prompt>$ </prompt><command>export CVS_RSH=/usr/bin/ssh</command></screen>
- <para>
- With the
- <envar>$CVSROOT</envar>
- and
- <envar>$CVS_RSH</envar>
- environment variables in place, you can access the repository:
+ Every author has a unique <envar>$CVSROOT</envar> to access the
+ <application>CVS</application> repository:
</para>
-<screen><prompt>$ </prompt><command>cvs co -c</command></screen>
+ <screen><command>export CVSROOT=:ext:<replaceable>yourname</replaceable>@cvs.fedoraproject.org:/cvs/docs</command>
+<command>export CVS_RSH=/usr/bin/ssh</command></screen>
+ <para>
+ With the <envar>$CVSROOT</envar> and <envar>$CVS_RSH</envar>
+ environment variables in place, you can access the repository:
+ </para>
+ <screen><command>cvs co -c</command></screen>
<para>
You will be asked for the passphrase for your
- <application>SSH</application> key. Press
- <guibutton>ENTER</guibutton>
- and you should receive a list of modules already in the
- repository.
+ <application>SSH</application> key. Press <keycap>Enter</keycap>
+ to receive a list of modules already in the repository.
</para>
</section>
</section>
@@ -380,18 +363,17 @@
<tip>
<title>Tip</title>
<para>
- To see if you need a correctly-set
- <envar>$CVSROOT</envar>
- variable, or the <option>-m </option>
- <replaceable>repository</replaceable> command line switch, see
- if you have a <filename>CVS/</filename> subdirectory in your
- working directory.
+ To see if you need a correctly-set <envar>$CVSROOT</envar>
+ variable, or the <option>-m </option>
+ <replaceable>repository</replaceable> command line switch, see
+ if you have a <filename>CVS/</filename> subdirectory in your
+ working directory.
</para>
<para>
If you have a <filename>CVS/</filename> directory,
- <application>CVS</application> ignores any
- <envar>$CVSROOT</envar>
- or <option>-m</option> command line switch.
+ <application>CVS</application> ignores any
+ <envar>$CVSROOT</envar> or <option>-m</option> command line
+ switch.
</para>
</tip>
<section id="sn-cvs-cvscommands-co">
@@ -401,20 +383,21 @@
<secondary>checking out modules</secondary>
</indexterm>
<para>
- You only need to checkout a module once. After a local copy of
- the module is on your system, it is on your system.
+ You only need to checkout a module once. Once a local copy of
+ the module is on your system, you may continue to use it for
+ additional work.
</para>
<para>
To checkout a module, use the following command:
</para>
-<screen><prompt>$ </prompt><command>cvs co</command> <replaceable><module-name></replaceable></screen>
+ <screen><command>cvs co <replaceable>module-name</replaceable></command></screen>
<para>
For example, to checkout the
<computeroutput>example-tutorial</computeroutput> module, change
to your work directory, and execute the following command:
</para>
-<screen><prompt>$ </prompt><command>cvs co example-tutorial</command></screen>
+ <screen><command>cvs co example-tutorial</command></screen>
<para>
A directory called <filename>example-tutorial/</filename> is
created in the current directory.
@@ -441,21 +424,22 @@
<para>
To checkout a branch of a module, use the following command:
</para>
-<screen><prompt>$ </prompt><command>cvs co</command> <option>-d</option> <replaceable><directory></replaceable> <option>-r</option> <replaceable><branchname></replaceable> <replaceable><module-name></replaceable></screen>
+ <screen><command>cvs co -d <replaceable>directory</replaceable> -r <replaceable>branchname</replaceable> <replaceable>module-name</replaceable></command></screen>
<para>
- A directory named <replaceable><directory></replaceable>
+ A directory named <replaceable>directory</replaceable>
is created, and the files for the
- <replaceable><branchname></replaceable> branch of the
- <replaceable><module-name></replaceable> module are
+ <replaceable>branchname</replaceable> branch of the
+ <replaceable>module-name</replaceable> module are
copied in the directory.
</para>
<para>
- For example, to checkout a branch named BRANCH-VERSION-1.2
- from the <computeroutput>mymodule</computeroutput> module, use
- the command:
+ For example, to checkout a branch named
+ <systemitem>BRANCH-VERSION-1.2</systemitem> from the
+ <computeroutput>mymodule</computeroutput> module, use the
+ command:
</para>
-<screen><prompt>$ </prompt><command>cvs co -d mymodule-1.2 -r BRANCH-VERSION-1.2 mymodule</command></screen>
+ <screen><command>cvs co -d mymodule-1.2 -r BRANCH-VERSION-1.2 mymodule</command></screen>
<para>
The BRANCH-VERSION-1.2 branch of the module is checked out in
the <filename>mymodule-1.2</filename> directory on your
@@ -466,26 +450,23 @@
To determine which branches and tags exist for a file, use the
command:
</para>
-<screen><prompt>$ </prompt><command>cvs status</command> <option>-v</option> <replaceable><filename></replaceable></screen>
+ <screen><command>cvs status -v <replaceable>filename</replaceable></command></screen>
<para>
For example, the status of the file
- <filename>foo.sgml</filename> is as follows:
+ <filename>foo.xml</filename> is as follows:
</para>
<screen>
-<computeroutput>
-===================================================================
-File: foo.sgml Status: Up-to-date
+<computeroutput><![CDATA[===================================================================
+File: foo.xml Status: Up-to-date
Working revision: 1.47
- Repository revision: 1.47 /cvs/docs/custom-guide/rhl-cg-en_US.sgml,v
+ Repository revision: 1.47 /cvs/docs/foo-guide/foo.xml,v
Sticky Tag: (none)
Sticky Date: (none)
Sticky Options: (none)
Existing Tags:
- BRANCH-VERSION-1.2 (branch: 1.25.2)
-</computeroutput>
-</screen>
+ BRANCH-VERSION-1.2 (branch: 1.25.2)]]></computeroutput></screen>
<para>
Only tags marked as branches in the second column under the
<computeroutput>Existing Tags</computeroutput> section can be
@@ -505,7 +486,7 @@
to the directory that contains the files for the module and
execute the command:
</para>
-<screen><command>cvs update</command></screen>
+ <screen><command>cvs update</command></screen>
<para>
The latest versions of all the files in the module are
downloaded into your local copy. If you notice a file conflict,
@@ -524,15 +505,16 @@
them to save the changes on the <application>CVS</application>
server:
</para>
-<screen><prompt>$ </prompt><command>cvs commit</command> <option>-m</option> "<replaceable>some log message</replaceable>" <replaceable>filename</replaceable></screen>
+ <screen><command>cvs commit -m "<replaceable>some log message</replaceable>" <replaceable>filename</replaceable></command></screen>
<note>
<para>
If you would prefer to write your log message with your
- favorite text editor, as defined by the $VISUAL or the $EDITOR
- environment variable, just omit the <userinput>-m "some
- log message"</userinput>. The buffer will already contain
- comments describing the change; you do not need to delete them
- as you enter your own text.
+ favorite text editor, as defined by the <envar>$VISUAL</envar>
+ or the <envar>$EDITOR</envar> environment variable, just omit
+ the <userinput>-m "<replaceable>some log
+ message</replaceable>"</userinput>. The buffer will
+ already contain comments describing the change. You do not
+ need to delete them as you enter your own text.
</para>
</note>
@@ -546,22 +528,26 @@
</para>
<para>
- The <replaceable><filename></replaceable> can be one
+ The <replaceable>filename</replaceable> can be one
filename, a series of filenames separated by spaces, or a group
of filenames specified using wildcards such as
- <filename>*.png</filename> or <filename>foo-*.sgml</filename>.
+ <filename>*.png</filename> or <filename>foo-*.xml</filename>.
</para>
<para>
If no filename or group of filenames is specified in the
<command>commit</command> command, all outstanding changes of
any kind are committed to the server. The command is recursive
- and will include changes in any subdirectories of the module.
- Use caution when issuing the <command>commit</command> command
- without any filenames because you might not remember exactly
- what files changed.
- </para>
-
+ and will include changes in any subdirectories of the
+ module.</para>
+ <caution>
+ <title>Committing Changes</title>
+ <para>
+ Use caution when issuing the <command>commit</command> command
+ without any filenames because you might not remember exactly
+ what files changed.
+ </para>
+ </caution>
<para>
If you notice a file conflict, refer to
<xref linkend="sn-cvs-cvscommands-conflicts"></xref>.
@@ -578,12 +564,12 @@
To add a file to a module, create the file in your local copy
then execute the following command:
</para>
-<screen><prompt>$ </prompt><command>cvs add</command> <replaceable>file-to-add</replaceable></screen>
+ <screen><command>cvs add</command> <replaceable>file-to-add</replaceable></screen>
<para>
After adding the file, you must <command>commit</command> the
<command>add</command> to copy it to the server:
</para>
-<screen><prompt>$ </prompt><command>cvs commit</command> <option>-m</option> "<replaceable>some log message</replaceable>" <replaceable>file-to-add</replaceable></screen>
+ <screen><command>cvs commit -m "<replaceable>some log message</replaceable>" <replaceable>file-to-add</replaceable></command></screen>
</section>
<section id="sn-cvs-cvscommands-admin">
@@ -593,20 +579,20 @@
<secondary>binary files</secondary>
</indexterm>
<para>
- The most commonly-archived files are simple text files but
- sometimes binary files are also archived. The
- <application>cvs</application> program recognizes most common
- filename extentions such as <filename>.png</filename> or
- <filename>.jpg</filename>, so <application>cvs</application>
- usually "does the right thing".
+ The most commonly-archived files are simple text files, but
+ sometimes binary files are also archived. The
+ <application>cvs</application> program recognizes most common
+ filename extensions such as <filename>.png</filename> or
+ <filename>.jpg</filename>, and usually behaves as the user
+ intends.
</para>
<para>
When a copy of a file is checked out of the repository,
- <application>cvs</application> scans it for special keywords,
- such as "<computeroutput>$id:$</computeroutput>" and
- replaces the string with a generated value, such as the file
- version number.
+ <application>cvs</application> scans it for special keywords
+ such as <computeroutput>$id:$</computeroutput>. The
+ <application>cvs</application> program replaces the keyword with
+ a generated value such as the file version number.
</para>
<para>
@@ -616,22 +602,22 @@
binary, and thus needing the keyword expansion turned off, use
the command:
</para>
-<screen width="60"><prompt>$ </prompt><command>cvs</command> <option>admin</option> <option>-kk</option> <replaceable>filename</replaceable></screen>
+ <screen><command>cvs admin -kk <replaceable>filename</replaceable></command></screen>
<para>
Note that the file must already be checked in to the
- <abbrev>CVS</abbrev> repository before the
- <option>admin</option> command can be used. This is OK, since
- the keyword expansion is done as the file is checked out and
- copied to the local directory, not when the file is committed to
- the repository.
+ <abbrev>CVS</abbrev> repository before the
+ <option>admin</option> command can be used. This is acceptable,
+ since the keyword expansion is done as the file is checked out
+ and copied to the local directory, not when the file is
+ committed to the repository.
</para>
<tip>
<title>Recovering a binary file</title>
<para>
If you check a binary file into the repository and then find
- it corrupted when it is checked out, do not panic. Simply use
- the <option>admin</option> command as described above, delete
- your local file copy, and check it out again.
+ it corrupted when it is checked out, do not panic. Use the
+ <option>admin</option> command as described above, delete your
+ local file copy, and check it out again.
</para>
</tip>
</section>
@@ -651,12 +637,12 @@
be retrieved at any time with the <command>add</command>
command.
</para>
-<screen><prompt>$ </prompt><command>cvs rm -f</command> <replaceable>file-to-remove</replaceable></screen>
+ <screen><command>cvs rm -f</command> <replaceable>file-to-remove</replaceable></screen>
<para>
After removing the file, you must <command>commit</command> the
removal:
</para>
-<screen><prompt>$ </prompt><command>cvs commit</command> <option>-m</option>"<replaceable>some log message</replaceable>" <replaceable>file-to-remove</replaceable></screen>
+ <screen><command>cvs commit -m "<replaceable>some log message</replaceable>" <replaceable>file-to-remove</replaceable></command></screen>
<para>
You can not use wildcards in the <command>commit</command>
command to identify removed files. They must be specified with a
@@ -668,8 +654,7 @@
the <application>CVS</application> server so that the history of
the file is preserved. If you need to rename a file, send an
email to
- <ulink url="mailto:cvsdocs-administrator at fedoraproject.org"><filename>cvsdocs-administrator at fedoraproject.org</filename>
- </ulink> asking to have the file renamed.
+ <ulink url="mailto:cvsdocs-administrator at fedoraproject.org">cvsdocs-administrator at fedoraproject.org</ulink> asking to have the file renamed.
</para>
</section>
@@ -685,7 +670,7 @@
<application>CVS</application> module. To view the status of a
file, use the command:
</para>
-<screen><prompt>$ </prompt><command>cvs status</command> <replaceable>filename</replaceable></screen>
+ <screen><command>cvs status</command> <replaceable>filename</replaceable></screen>
<para>
The status report of a repository file is as follows:
</para>
@@ -812,42 +797,34 @@
similar to the following when committing the file or updating
your local copy of the module:
</para>
-<screen>
-<computeroutput>
-RCS file: /cvs/docs/module-name/filename.sgml,v
+ <screen><computeroutput><![CDATA[RCS file: /cvs/docs/module-name/filename.sgml,v
retrieving revision 1.12
retrieving revision 1.13
Merging differences between 1.12 and 1.13 into filename.sgml
rcsmerge: warning: conflicts during merge
cvs server: conflicts found in filename.sgml
-C filename.sgml
-</computeroutput>
-</screen>
+C filename.sgml]]></computeroutput></screen>
<para>
To resolve the conflict, open the file, search for
- <computeroutput><<<<<<<</computeroutput>
+ <computeroutput><![CDATA[<<<<<<<]]></computeroutput>
and determine which version of the content is correct. For
example:
</para>
-<screen>
-<computeroutput>
-<para>
-Some sentence.
-<<<<<<< filename.sgml
-A sentence that was changed in the working copy.
+ <screen><computeroutput><![CDATA[<para>
+ Some sentence.
+<<<<<<< filename.sgml
+ A sentence that was changed in the working copy.
=======
-A same sentence that was changed differently and committed.
->>>>>>> 1.13
-</para>
-</computeroutput>
-</screen>
+ A same sentence that was changed differently and committed.
+>>>>>>> 1.13
+</para>]]></computeroutput></screen>
<para>
The content between the
- <computeroutput><<<<<<<</computeroutput>,
+ <computeroutput><![CDATA[<<<<<<<]]></computeroutput>,
and the <computeroutput>=======</computeroutput> is the content
from your working copy. The content between the
<computeroutput>=======</computeroutput> and the
- <computeroutput>>>>>>>></computeroutput> is
+ <computeroutput><![CDATA[>>>>>>>]]></computeroutput> is
the content from the server.
</para>
@@ -855,7 +832,7 @@
Resolve the conflict by editing your copy, and commit the file.
</para>
</section>
-
+ <!-- Stopped editing here temporarily :: PWF 2007-06-25 -->
<section id="sn-cvs-cvscommands-summary">
<title>Summary</title>
<indexterm>
More information about the Fedora-docs-commits
mailing list