Firebird Documentation IndexFirebird Docbuilding Howto → Getting the manual module from SF
Firebird Home Firebird Home Prev: Firebird Docbuilding HowtoFirebird Documentation IndexUp: Firebird Docbuilding HowtoNext: Building the Firebird docs

Getting the manual module from SourceForge

What is CVS?
CVS clients
Checking out the manual module

The manual module is part of the Firebird CVS repository at SourceForge. In order to download it, you need a piece of software called a CVS client. This section describes the necessary steps to get the software and the manual module. The actual doc building will be discussed in the next main section: Building the Firebird docs.

What is CVS?

CVS means Concurrent Versions System. It is a tool to manage software development, useful both for single developers and for teamwork. Practically all projects at SourceForge use CVS to store and develop their code base. The Firebird CVS tree is divided into several so-called modules, the manual module being one of them.

CVS clients

Downloading a module from a CVS repository is called checking out in CVS lingo. To do that, you need a CVS client; they exist for practically every operating system. Here's a list of CVS clients for some popular OSes:

Get one or more of the abovementioned clients and install according to the instructions that come with it. After that, you are ready to check out the manual module.

Checking out the manual module

There are two ways you can check out the manual module: as an anonymous user, or with your SourceForge login name. The last method is often termed SSH checkout (because it uses a Secure SHell) or EXT checkout (because it uses SSH as an EXTernal protocol).

Everybody can check out anonymously. Members of the Firebird project can also check out with their SourceForge login. (If you have an SF account but you aren't a Firebird project member, you can only check out anonymously.)

If you are a project member, you'll usually want to check out with your SF login because

  1. An anonymous checkout is not always up to date (delay may be several hours to several days);

  2. If you are going to contribute to the manual module yourself, you must checkout with your SF login or you won't be able to commit (= upload) your changes back to the server.

We'll describe both methods in the following subsections, starting with anon checkout. Click here to jump to the subsection on SSH checkouts (after you have read the warnings below).

Warnings

  • If you are behind a firewall, make sure that TCP port 2401 is open. If not, you won't be able to make a cvs connection to the repository. You session will simply “timeout” trying to connect.

  • If at all possible, check out to a local directory path that doesn't contain spaces or other characters that are susceptible to URL-encoding. Otherwise, problems may arise when you build certain types of document. These problems can be overcome, but it's better not to have them at all.

Anonymous checkout

The checkout procedure depends on which client you use. We'll give you the exact instructions for command line CVS, and generic info to be used with other clients.

Anonymous checkout using command line CVS
  1. If you are in a graphical environment, open a command window.

  2. First, you have to verify the password with the server and store it locally. Give the command:

    cvs -d:pserver:anonymous@firebird.cvs.sourceforge.net:/cvsroot/firebird login

    When prompted for a password, just hit Enter, because the password for user "anonymous" is empty. Your CVS client will store the password for later reuse, so you can skip this step in the future, as long as you don't login with other passwords in between.

  3. Now you can get the manual module. Give the command (on one line):

    cvs -z6 -d:pserver:anonymous@firebird.cvs.sourceforge.net:/cvsroot/firebird checkout manual

    If all goes well, a directory called manual will by created below your current dir, and the manual source tree will be downloaded into it. You can now build the docs – read further under Building the Firebird docs.

Anonymous checkout using other clients

There's too much variation to give exact instructions for all CVS clients here. Consult the help or documentation for your own client. Elements you may need to fill in at some point are:

protocol

this must be set to pserver (password server)

authentication method

same as protocol

server

firebird.cvs.sourceforge.net

repository

/cvsroot/firebird

user name

anonymous

module name

manual

cvsroot

usually a combination of server and repository, sometimes even with user name prepended (e.g. in WinCvs): firebird.cvs.sourceforge.net:/cvsroot/firebird or anonymous@firebird.cvs.sourceforge.net:/cvsroot/firebird

Fill in the necessary data and give your client's checkout command. If the checkout succeeds, you now have a local copy of the manual module on your computer and are ready to build the docs. Read further under Building the Firebird docs.

SSH checkout (with your SF login name)

To be able to perform an SSH checkout, a secure shell client must be present on your system. On most Unix systems, as well as on Mac OS X, OpenSSH is installed by default. If not, check the distribution CDs or get it from http://www.openssh.com. This site also contains pointers to other SSH products for OSes not supported by OpenSSH. Note however that installing and configuring SSH on some platforms (including Windows) is not a trivial task. You can make life easier for yourself by choosing a CVS client that has SSH built in, like TortoiseCVS for Windows.

As for the checking out itself: just as with anon checkouts, the procedure depends on which client you use. Again, we'll give exact instructions for command line CVS, and generic info for other clients.

Important

Whatever client you use, do not attempt to check out over an existing local copy, e.g. from a previous anonymous checkout. Always check out into a new or at least empty directory.

Warning

SourceForge may expire your password from time to time. When this happens to you, you will receive a 'Permission denied, please try again' error message. If this does happen, and you are sure that the password is correct, go to the SourceForge.org web page – http://sourceforge.net/index.php – and try to login using your account name and the password you are using to connect to the cvs repository. If your password has expired, you will be asked to change it.

After changing your password on SourceForge, you must start a new shell session or you will continue to receive the same error message, even with the new password.

SSH checkout using command line CVS
  1. If you are in a graphical environment, open a command window.

  2. First, make sure that you have an environment variable called CVS_RSH with the value “ssh” (or whatever your SSH client is called). How you must do this depends on your OS. On a DOS/Windows command line, use set CVS_RSH=ssh. Under Linux/bash: export CVS_RSH=ssh.

    You may want to make this envar permanent so you can skip this step in the future. How to do this depends on your OS. Consult its documentation if necessary.

  3. Give the following command to get the manual module (on one line, and substitute username with your own SF user name):

    cvs -z6 -d:ext:username@firebird.cvs.sourceforge.net:/cvsroot/firebird checkout manual

    Enter your password when prompted for it.

    If all goes well, a directory called manual will by created below your current dir, and the manual source tree will be downloaded into it. You can now build the docs – read further under Building the Firebird docs.

SSH checkout using other clients

There's too much variation to give exact instructions for all CVS clients here. Consult the help or documentation for your own client. Elements you may need to fill in at some point are:

protocol

this must be set to ext (or SSH, or SSL)

authentication method

same as protocol

server

firebird.cvs.sourceforge.net

repository

/cvsroot/firebird

user name

your SourceForge user name

module name

manual

cvsroot

usually a combination of server and repository, sometimes even with user name prepended (e.g. in WinCvs): firebird.cvs.sourceforge.net:/cvsroot/firebird or username@firebird.cvs.sourceforge.net:/cvsroot/firebird

Fill in the necessary data and give your client's checkout command. If the checkout succeeds, you now have a local copy of the manual module on your computer and are ready to build the docs. You can also commit changes you make locally back to the repository.

Prev: Firebird Docbuilding HowtoFirebird Documentation IndexUp: Firebird Docbuilding HowtoNext: Building the Firebird docs
Firebird Documentation IndexFirebird Docbuilding Howto → Getting the manual module from SF