| Firebird Docset → Firebird Docwriters' Docs → Firebird Docbuilding Howto → Getting the manual module from SF |
|
|
|
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.
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.
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:
Linux, BSD and other Unices
Command-line CVS is often pre-installed. If it isn't, use the admin tools of your distribution to install it – you'll typically find it in the development category. If that doesn't work for you, get it at http://www.cvshome.org
gCvs – a graphical CVS interface, at http://cvsgui.sourceforge.net/download.html
Windows
Command-line CVS at http://www.cvshome.org
WinCVS: Very powerful, but maybe a bit overwhelming if you are new to it. At http://cvsgui.sourceforge.net/download.html
TortoiseCVS: A Windows Explorer plugin. Brilliantly designed, very intuitive. Lacks some of the more advanced CVS functions, but has everything you need. Get it at http://tortoisecvs.sourceforge.net/download.shtml
Mac OS X
Mac OS X comes with command-line CVS already included.
Fink (Unix tools for OS X) contains a newer version of CVS. http://fink.sourceforge.net/download/index.php
MacCvsX at http://cvsgui.sourceforge.net/download.html – same project as gCvs and WinCvs. Note: OS X version still in beta.
MacCVS Pro at http://sourceforge.net/projects/maccvspro/
Mac Classic
MacCvs at http://cvsgui.sourceforge.net/download.html – same project as gCvs and WinCvs
MacCVS Pro at http://sourceforge.net/projects/maccvspro/
Others
Try your luck at http://www.cvshome.org, google for it, or ask in the gnu.cvs.help newsgroup or on the firebird-docs mailing list.
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.
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
An anonymous checkout is not always up to date (delay may be several hours to several days);
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.
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.
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.
If you are in a graphical environment, open a command window.
First, you have to verify the password with the server and store it locally. Give the command:
cvs -d:pserver:[email protected]:/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.
Now you can get the manual module. Give the command (on one line):
cvs -z6 -d:pserver:[email protected]:/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.
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:
this must be set to pserver (password server)
same as protocol
firebird.cvs.sourceforge.net
/cvsroot/firebird
anonymous
manual
usually a combination of server and repository, sometimes even with user name prepended (e.g. in WinCvs): firebird.cvs.sourceforge.net:/cvsroot/firebird or [email protected]:/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.
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.
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.
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.
If you are in a graphical environment, open a command window.
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.
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.
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:
this must be set to ext (or SSH, or SSL)
same as protocol
firebird.cvs.sourceforge.net
/cvsroot/firebird
your SourceForge user name
manual
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.
|
| Firebird Docset → Firebird Docwriters' Docs → Firebird Docbuilding Howto → Getting the manual module from SF |