| 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 OS'es:
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.
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: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.
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.
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 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.
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 CD's or get it from http://www.openssh.com. This site also contains pointers to other SSH products for OS'es 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.
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 envvar 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 username):
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 |