This manual is for GNU RCS (version 5.8, 8 August 2011).
Copyright © 2010, 2011 Thien-Thi Nguyen
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the appendix entitled “GNU Free Documentation License”.
--- The Detailed Node Listing ---
Overview
Usage
Common elements
GNU RCS (Revision Control System) manages multiple revisions of files. RCS can store, retrieve, log, identify, and merge revisions. It is useful for files that are revised frequently, e.g. programs, documentation, graphics, and papers. It can handle text as well as binary files, although functionality is reduced for the latter.
A normal installation includes the commands: ci, co, ident, merge, rcs, rcsclean, rcsdiff, rcsmerge and rlog (see Usage). These are small and fast programs (amenable to scripting) and indeed the distribution also includes the script rcsfreeze showing some of the possibilities.
If you use RCS heavily, you may also be interested in GNU CVS.
RCS was designed and built by Walter F. Tichy of Purdue University. RCS version 3 was released in 1983.
Adam Hammer, Thomas Narten, and Daniel Trinkle of Purdue supported RCS through version 4.3, released in 1990. Guy Harris of Sun contributed many porting fixes. Paul Eggert of System Development Corporation contributed bug fixes and tuneups. Jay Lepreau contributed 4.3BSD support.
Paul Eggert of Twin Sun wrote the changes for RCS versions 5.5 and 5.6 (1991). Rich Braun of Kronos and Andy Glew of Intel contributed ideas for new options. Bill Hahn of Stratus contributed ideas for setuid support. Ideas for piece tables came from Joe Berkovitz of Stratus and Walter F. Tichy. Matt Cross of Stratus contributed test case ideas. Adam Hammer of Purdue QAed.
Paul Eggert wrote most of the changes for RCS 5.7. K. Richard Pixley of Cygnus Support contributed several bug fixes. Robert Lupton of Princeton and Daniel Trinkle contributed ideas for ‘$Name’ expansion. Brendan Kehoe of Cygnus Support suggested rlog's -N option. Paul D. Smith of Data General suggested improvements in option and error processing. Adam Hammer of Purdue QAed.
Thien-Thi Nguyen is responsibile for RCS 5.8. He modernized the code base, build system, and manual pages, fixing some bugs on the way. He added standard --help, --version processing, and wrote the documentation you are reading (gladly taking inspiration from the paper1 and manpages originally written by Walter F. Tichy). To support Cygwin, RCS 5.8 embeds a small LGPL library written by Panagiotis E. Hadjidoukas.
[Question for pretesters: Perhaps the following subsections should be given their own nodes so that they can be xref'ed more precisely?]
The interaction model is straightforward. For each working file, you initialize its RCS file once, then enter a cycle of checkout, modification, and checkin operations. Along the way, you can tweak some of the RCS file's metadata, as well. All of this is done through RCS commands; you need not modify the RCS file directly (and in fact you should probably avoid doing so lest RCS become confused). This model is somewhat analogous to using a library (of books). With a library, you sign up for a library card (initialize), then enter a cycle of taking a book home (checkout), enjoying it (NB: without modification, one hopes), and returning it to the library (checkin).
Furthermore, you can compare revisions in the RCS file against each other, examine the user- (hopefully high) quality descriptions of the changes each revision embodies, merge selected revisions, and so forth.
RCS commands operate on one pair of files at a time. The working file is what you normally view and edit (e.g., a file of C programming language source code named a.c). Because the working file's contents can be extracted from the RCS file (called instantiating a working file), it can be safely deleted to regain some disk space.
The RCS file is a separate file, conventionally placed in the subdirectory RCS, wherein RCS commands organize the initial and subsequent revisions of the working file, associating with each revision a unique revision number along with the remembered particulars of the checkin that produced it. It also contains a description of the working file and various other metadata, described below.
The RCS file is also known (colloquially) as the “comma-v file”, due to its name often ending in ,v (e.g., a.c,v).
A revision number is a branch number followed by a dot followed by an integer, and a branch number is an odd number of integers separated by dot. A revision number with one dot (implying a branch number without any dots) is said to be on the trunk. All integers are positive. For example:
1.1 -- revision number for initial checkin (typically);
branch number: 1
9.4.1.42 -- more complicated (perhaps after much gnarly hacking);
branch number: 9.4.1
333.333.333 -- not a valid revision number;
however, a perfectly valid branch number
The branch point of a non-trunk branch is the revision number formed by removing the branch's trailing integer. To compute the next higher branch or revision number, add one to the trailing integer. The highest-numbered revision on a branch is called the tip of the branch (or branch tip). Continuing the example:
1.1 -- on trunk; no branch point;
next higher branch number: 2
next higher revision number: 1.2
9.4.1.42 -- not on trunk; branch point: 9.4
next higher branch number: 9.4.2
next higher revision number: 9.4.1.43
333.333.333 -- not on trunk; branch point: 333.333
next higher branch number: 333.333.334
next higher revision number: 333.333.333.1
In addition to this “tree” of thus-linked revisions, the RCS file keeps track of the default branch, i.e., the branch whose tip corresponds to the most recent checkin; as well as the symbolic names, a list of associations between a user-supplied (and presumably meaningful) symbol and an underlying branch or revision number.
The RCS file contains two pieces of information used to implement its
access control policy. The first is a list of usernames. If
non-empty, only those users listed can modify the RCS file (via RCS
commands). The second is a list of locks, i.e., association
between a username and a revision number. If a lock
username:revno exists, that means only username
may modify revno (that is, do a checkin operation to deposit the
next higher revision, or a higher revision number on the same branch as
revno).
Compatability Note: RCS files made with RCS 2.x may also contain suffix information. If you run into such a file (unlikely, as that file format became obsolete in 1982), you will need to rebuild RCS with ‘configure --enable-compat2’ to be able to read it. Note that RCS commands never write out suffix information, even with ‘configure --enable-compat2’.
The checkin operation records the contents of the working file in the RCS file, assigning it a new (normally the next higher) revision number and recording the username, timestamp, state (a short symbol), and user-supplied log message (a textual description of the changes leading to that revision). It uses diff to find the differences between the tip of the default branch and the working file, thereby writing the minimal amount of information needed to be able to recreate the contents of the previous tip.
The checkout operation identifies a specific revision from the RCS file and either displays the content to standard output or instantiates a working file, overwriting any current instantiation with the selected revision. In either case, the content may undergo keyword expansion, which replaces text of the form ‘$Keyword$’ with (possibly) different text comprising the keyword and its value, depending on the current keyword expansion mode (see Substitution mode option).
The keywords and their values are:
AuthorDateHeaderIdLockerLogExisting log messages are not replaced. Instead, the new log message is inserted after ‘$Log:...$’. This is useful for accumulating a complete change log in a source file.
Each inserted line is prefixed by the string that prefixes the ‘$Log$’ line. For example, if the ‘$Log$’ line is
// $Log: tan.cc $
then RCS prefixes each line of the log with ‘// ’ (slash, slash, space). This is useful for languages with comments that go to the end of the line.
The convention for other languages is to use a ‘ * ’ (space, asterisk, space) prefix inside a multiline comment. For example, the initial log comment of a C program conventionally is of the following form:
/*
* $Log: rcs.html,v $
* Revision 1.1 2011/08/30 12:12:34 ttn
* Add manaul for RCS 5.8.
*
* * manual/: New directory.
* * manual/html_node/: New directory.
* * manual/index.html: New file.
* * manual/rcs.dvi.gz: New file.
* * manual/rcs.html: New file.
* * manual/rcs.html.gz: New file.
* * manual/rcs.html_node.tar.gz: New file.
* * manual/rcs.info.tar.gz: New file.
* * manual/rcs.pdf: New file.
* * manual/rcs.ps.gz: New file.
* * manual/rcs.texi.tar.gz: New file.
* * manual/rcs.txt: New file.
* * manual/rcs.txt.gz: New file.
* * manual/html_node/Common-elements.html: New file.
* * manual/html_node/Concepts.html: New file.
* * manual/html_node/Credits.html: New file.
* * manual/html_node/Date-option.html: New file.
* * manual/html_node/Description-option.html: New file.
* * manual/html_node/Environment.html: New file.
* * manual/html_node/GNU-FDL.html: New file.
* * manual/html_node/Index.html: New file.
* * manual/html_node/Log-message-option.html: New file.
* * manual/html_node/Misc-common-options.html: New file.
* * manual/html_node/Overview.html: New file.
* * manual/html_node/Quick-tour.html: New file.
* * manual/html_node/Reporting-bugs.html: New file.
* * manual/html_node/Revision-options.html: New file.
* * manual/html_node/Still-missing.html: New file.
* * manual/html_node/Substitution-mode-option.html: New file.
* * manual/html_node/Usage.html: New file.
* * manual/html_node/ci.html: New file.
* * manual/html_node/co.html: New file.
* * manual/html_node/ident.html: New file.
* * manual/html_node/index.html: New file.
* * manual/html_node/merge.html: New file.
* * manual/html_node/rcs.html: New file.
* * manual/html_node/rcsclean.html: New file.
* * manual/html_node/rcsdiff.html: New file.
* * manual/html_node/rcsmerge.html: New file.
* * manual/html_node/rlog.html: New file.
*
*/
For backwards compatibility with older versions of RCS, if the log
prefix is ‘/*’ or ‘(*’ surrounded by optional white space,
inserted log lines contain a space instead of ‘/’ or ‘(’;
however, this usage is obsolescent and should not be relied on.
NameRCSfileRevisionSourceStateThis section complements the preceding section (see Concepts), presenting a handful of RCS commands in quick succession. For details on individual RCS commands, See Usage.
Suppose you have a file f.c that you wish to put under control of RCS. If you have not already done so, make an RCS directory with the command:
mkdir RCS
Then invoke the checkin command:
ci f.c
This command creates an RCS file in directory RCS, stores f.c into it as revision 1.1, and deletes f.c. It also asks you for a description. The description should be a synopsis of the contents of the file. All later checkin commands will ask you for a log entry, which should summarize the changes that you made.
To get back the working file f.c in the previous example, use the checkout command:
co f.c
This command extracts the latest revision from the RCS file and writes it into f.c. If you want to edit f.c, you must lock it as you check it out, with the command:
co -l f.c
You can now edit f.c. Suppose after some editing you want to know what changes that you have made. The command:
rcsdiff f.c
tells you the difference between the most recently checked-in version and the working file. You can check the file back in by invoking:
ci f.c
This increments the revision number properly. If ci complains with the message:
ci error: no lock set by your name
then you have tried to check in a file even though you did not lock it when you checked it out. Of course, it is too late now to do the checkout with locking, because another checkout would overwrite your modifications. Instead, invoke:
rcs -l f.c
This command will lock the latest revision for you, unless somebody else got ahead of you already. In this case, you'll have to negotiate with that person.
Locking assures that you, and only you, can check in the next update, and avoids nasty problems if several people work on the same file. Even if a revision is locked, it can still be checked out for reading, compiling, etc. All that locking prevents is a checkin by anybody but the locker.
If your RCS file is private, i.e., if you are the only person who is going to deposit revisions into it, strict locking is not needed and you can turn it off. If strict locking is turned off, the owner of the RCS file need not have a lock for checkin; all others still do. Turning strict locking off and on is done with the commands:
rcs -U f.c # disable strict locking
rcs -L f.c # enable strict locking
If you don't want to clutter your working directory with RCS files, create a subdirectory called RCS in your working directory, and move all your RCS files there. RCS commands will look first into that directory to find needed files. All the commands discussed above will still work, without any modification. See Common elements.
To avoid the deletion of the working file during checkin (in case you want to continue editing or compiling), invoke one of:
ci -l f.c # checkin + locked checkout
ci -u f.c # checkin + unlocked checkout
These commands check in f.c as usual, then perform an implicit checkout. The first form also locks the checked in revision, the second one doesn't. Thus, these options save you one checkout operation. The first form is useful if you want to continue editing, the second one if you just want to read the file. Both update the keyword substitutions in your working file see Concepts.
You can give ci the number you want assigned to a checked-in revision. Assume all your revisions were numbered 1.1, 1.2, 1.3, etc., and you would like to start release 2. Either of the commands:
ci -r2 f.c
ci -r2.1 f.c
assigns the number 2.1 to the new revision. From then on, ci will number the subsequent revisions with 2.2, 2.3, etc. The corresponding co commands:
co -r2 f.c
co -r2.1 f.c
retrieve the latest revision numbered 2.x and the revision 2.1, respectively. co without a revision number selects the latest revision on the trunk, i.e. the highest revision with a number consisting of two fields. Numbers with more than two fields are needed for branches. For example, to start a branch at revision 1.3, invoke:
ci -r1.3.1 f.c
This command starts a branch numbered 1 at revision 1.3, and assigns the number 1.3.1.1 to the new revision. Here is a diagram showing the new revision in relation to its branch and the trunk.
1.1 -- 1.2 -- 1.3 -- 1.4 -- 1.5
|
[1.3.1] -- 1.3.1.1
For more information about branches, See Concepts.
This chapter describes how to invoke RCS commands, including common command-line elements, as well options specific to each command.
All RCS commands accept --help and --version. See Command-Line Interfaces.
Aside from --help and --version, RCS commands take the form ‘-letter[arg]’, i.e., a hyphen followed by a single letter, optionally followed by extra information. The square braces mean that the extra information is optional. (No square braces means that the extra information is required.) In any case, when specified, the extra information must abut the letter; there can be no intervening whitespace.
co -u 1.4 foo # wrong, space between -u and 1.4
co -u1.4 foo # ok
Furthermore, options must appear before file names (if any) on the command line.
ident foo -q # wrong, option after file name
ident -q foo # ok
Lastly, pairs of RCS and working files can be specified in three ways: (a) both are given, (b) only the working file is given, (c) only the RCS file is given. For (a), both RCS and working files may have arbitrary directory components; RCS commands pair them up intelligently. For (b), RCS commands will look first into the directory ./RCS, if it exists, to find the associated RCS file.
As to be expected in a revision control system, many options are of the form ‘-flag[rev]’, where flag is a single letter (e.g., ‘r’). If ommitted, rev defaults to the latest revision on the default branch. A revision can be specified in many ways:
+ 1,
while for other commands n would be simply i.
$For commands that accept a range of revisions, the syntax is
generally rev1:rev2, i.e., two revisions
(specified as described above) separated by a colon.
Some commands accept an option of the form ‘-ddate’ to specify a date, an absolute point in time (to second resolution), expressed in a date format. These also accept ‘-zzone’ to specify the timezone. The special value ‘LT’ stands for the local time zone. RCS recognizes many date formats and time zones. For example, the following dates are equivalent if local time is January 11, 1990, 8pm Pacific Standard Time, eight hours west of Coordinated Universal Time (UTC):
8:00 pm lt
4:00 AM, Jan. 12, 1990 default is UTC
1990-01-12 04:00:00+00 ISO 8601 (UTC)
1990-01-11 20:00:00-08 ISO 8601 (local time)
1990/01/12 04:00:00 traditional RCS format
Thu Jan 11 20:00:00 1990 LT output of ctime(3) + LT
Thu Jan 11 20:00:00 PST 1990 output of date(1)
Fri Jan 12 04:00:00 GMT 1990
Thu, 11 Jan 1990 20:00:00 -0800 Internet RFC 822
12-January-1990, 04:00 WET
Most fields in the date and time can be defaulted. The default time zone is normally UTC, but this can be overridden by the -z option. The other defaults are determined in the order year, month, day, hour, minute, and second (most to least significant). At least one of these fields must be provided. For omitted fields that are of higher significance than the highest provided field, the time zone's current values are assumed. For all other omitted fields, the lowest possible values are assumed. For example, without -z, the date ‘20, 10:30’ defaults to ‘10:30:00 UTC’ of the 20th of the UTC time zone's current month and year. Note that for the shell, the date/time must be quoted if it contains spaces.
RCS also accepts some other formats which specify only the date portion (omitting the time portion):
-DDD-wWW-DSome commands accept an option of the form ‘-t-text’ or ‘-tfile-name’. This option is to set or update the RCS file description text. In the first form, text is used directly, excluding the leading hyphen (‘-’) that distinguishes the two forms. In the second form, the description text is taken from the contents of file-name.
Some commands accept an option of the form -ksubst, used to control how keywords (see Concepts) are expanded in the working file. In the following table of subst values, the example keyword is ‘Revision’ and its value is ‘5.13’.
kvHeader,
Id and Locker keyword strings only as a file is being locked,
i.e., by ci -l and co -l.
This is the default substitution mode.
kvlkLog keywords even if -kk is
specified, since this tends to be more useful when merging changes.
obvBoth ci and rcs allow a log message to be specified with the -m option. If the msg argument to this option is empty, RCS uses the default ‘*** empty log message ***’. This particular message is handled specially (i.e., filtered out) by rlog.
Other common options are -I, -q, -s, -T, -V, -w, -x.
-I-q-sstate-TThis can be useful if the RCS file is found in a makefile target's
list of prerequisites (see Rule Syntax),
that is, if some target should be rebuilt if the RCS file is newer
than it. In that case, you can do ‘rcs -u -T’, for example, to
unlock a revision in the RCS file without triggering a recompilation.
-V-Vn-wlogin-xsuffThis basename search occurs within (i.e., starting from the beginning) the larger directory search loop, which comprises two candidates: d/RCS and d, where d is the directory component of the working file name. For example, given the working file a.c in the current directory, RCS tries, in order, these candidates:
./RCS/a.c,v
./RCS/a.c
./a.c,v
./a.c
Note that the last candidate is impossible (and is in fact discarded), because the working and RCS files cannot have the same name.
Various environment variables influence how RCS works.
Another way to set common options is with the ‘RCSINIT’ environment variable. This is a space-separated list of options. Use ‘\’ (backslash) to escape significant space. For example:
# Set the value; make it available to subsequent commands. RCSINIT="-q -x/,v -zLT" export RCSINIT # Use it (implicitly). rlog -L fooThis example, in Bourne shell syntax, arranges for RCS commands to operate as if each command-line had prepended ‘-q -x/,v -zLT’ to the rest of the command-line. The effective command-line that rlog sees is thus ‘-q -x/,v -zLT -L foo’.
Normally, for speed, commands either memory map or copy into memory the RCS file if its size is less than the memory limit, currently defaulting to 256 kilobytes. Otherwise the commands fall back to using standard i/o routines.
You can adjust the memory limit by setting the ‘RCS_MEM_LIMIT’ environment variable to a numeric value (measured in kilobytes). An empty value is silently ignored.
Commands sometimes create temporary files, normally in a system-dependent directory, such as /tmp. You can override this directory by specifying another one as the value of one of the environment variables
TMPDIR,TMP, orTEMP(checked in that order).
Absent -wlogin, or when login is omitted (see Misc common options), commands check environment variables
LOGNAMEandUSER(in that order). If neither of these are set, RCS queries the host for, and uses, your login.
ci [options] file ...
The ci command adds a revision to the RCS file reflecting the current state of the working file. This operation is also known as “checkin”.
-f[rev]-I[rev]-q[rev]-i[rev]-j[rev]-k[rev]-r-rrev-l[rev]-u[rev]-M[rev]Multiple flags in -{fiIjklMqru} may be given, except for
-r, -l, -u, which are mutually exclusive.
For a fully specified revision of the
form br.n, n must be greater
than any existing on br, or br must be new.
If rev is omitted, compute it from the last lock
(co -l), perhaps starting a new branch.
If there is no lock, use defbr.(L+1).
See Revision options.
-d[date]-zzone-m[msg]-nname-Nname-sstate-t-text-tfile-name-T-wwho-V-Vn-xsuffco [options] file ...
The co command retrieves a revision from the RCS file, writing a new working file. This operation is also known as “checkout”.
-f[rev]-I[rev]-q[rev]-p[rev]-r[rev]-l[rev]-u[rev]-M[rev]Multiple flags in -{fIlMpqru} may be given, except for
-r, -l, -u, which are mutually exclusive.
See Revision options.
-ksubst-ddate-zzone-jjoins:rev pairs.
NB: This option is obsolete (see rcsmerge).
-sstate-T-wwho-V-Vn-xsuffident [options] [file ...]
If no file is specified, scan standard input. The ident command scans its input for keywords (see Concepts), displaying to standard output what it finds.
-q-Vmerge [options] receiving-sibling parent other-sibling
The merge command combines the differences between a the parent and the other sibling, and the differences between the parent and the receiving sibling. It writes the result to the receiving sibling.
-A-E-e-p-q-Llabel-Vrcs [options] file ...
The rcs command performs various administrative operations on the RCS file, depending on the options given.
-i-L-U-M-T-I-q-alogins-e[logins]-Afile-name-b[rev]-l[rev]-u[rev]-cstring-ksubst-mrev:[msg]-nname[:[rev]]-Nname[:[rev]]-orange:rev2:rev:-sstate[:rev]-t-text-tfile-name-V-Vn-xsuff-zzonercsclean [options] [file ...]
The rcsclean command removes working files that are not being worked on. If given -u, it also unlocks and removes working files that are being worked on but have not changed. If no file is specified, operate on all the working files in the current directory.
-r[rev]-u[rev]-n[rev]-q[rev]-ksubst-T-V-Vn-xsuff-zzonercsdiff [options] file ...
The rcsdiff command runs diff to compare two revisions in an RCS file. See Invoking diff.
-rrev-ksubst-q-V-Vn-xsuff-zzoneAdditionally, the following options (and their argument, if any) are passed to the underlying diff command:
-0, -1, -2, -3, -4, -5, -6, -7, -8, -9, -B, -C, -D, -F, -H, -I,
-L, -U, -W, -a, -b, -c, -d, -e, -f, -h, -i, -n, -p, -t, -u, -w, -y,
long options (that start with "--")
(Not all of these options are meaningful.)
rcsmerge [options] file
The rcsmerge command incorporates the changes between two revisions of an RCS file into the corresponding working file.
-p[rev]-q[rev]-rrevOne or two revisions must be specified (using -p, -q, -r). If only one is specified, the second revision defaults to the latest revision on the default branch.
-ksubst-V-Vn-xsuff-zzonerlog [options] file ...
The rlog command displays information about RCS files.
-L-R-h-t-N-b-ddates<d2>d1<d>>d<Instead of ‘<’ or ‘>’, you can use ‘<=’ or ‘>=’,
respectively, to specify inclusive ranges.
dates may also be a list of semicolon-separated specs.
-l[who]-r[revs]:,
:rev, rev1:rev2.
-sstates-w[who]-V-Vn-xsuff-zzone-qRCS is still missing some features. The following is an unordered list of “to-do musings” kept by the RCS maintainers. If you would like to hack on an item, See Reporting bugs.
getdate by
Moraes. None of these getdate implementations are as robust as RCS's
old warhorse in avoiding problems like arithmetic overflow, so they'll
have to be fixed first. (Perhaps we can use gnulib module getdate.)
vc-annotate, q.v. —ttn]
To report bugs or suggest enhancements for GNU RCS, please visit its homepage (http://www.gnu.org/software/rcs/) to find directions on how to “file a bug report” online, or send electronic mail to help-rcs@gnu.org. (If you use the web interface, you don't need to also send email, since that is done automatically.)
For bug reports, please include enough information for the maintainers to reproduce the problem. Generally speaking, that means:
When in doubt whether something is needed or not, include it. It's better to include too much than to leave out something important.
Patches are welcome; if possible, please make them with ‘git format-patch’ and include ChangeLog entries (see Change Log). Please follow the existing coding style.
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
http://fsf.org/
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being list their titles, with
the Front-Cover Texts being list, and with the Back-Cover Texts
being list.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
LOGNAME: EnvironmentRCS_MEM_LIMIT: EnvironmentRCSINIT: EnvironmentTEMP: EnvironmentTMP: EnvironmentTMPDIR: EnvironmentUSER: Environment