The LDP is providing CVS access to authors. There are a few good reasons for this:
CVS will keep an off-site backup of your documents. In the event that you hand over a document to another author, they can just retrieve the document from CVS and continue on. In the event you need to go back to a previous version of a document, you can retrieve it as well.
It's great to have many people working on the same document. You can have CVS tell you what changes were made while you were editing your copy by another author, and integrate those changes in.
CVS keeps a log of what changes were made. These logs (and a date stamp) can be placed automatically inside the document when you use some special tags that get processed before the SGML processor.
It can provide for a way for a program to automatically update the LDP web site with new documentation as it's written and submitted. This is not in place yet, but it is a potential goal. Currently, CVS updates signal the HOWTO coordinator to update the LDP web page, meaning that if you use CVS, you're not required to e-mail your SGML code.
If you're completely new to CVS, there are a few web pages you may want to look at which can help you out:
First you'll need to get an account at the LDP's CVS Repository. This is pretty much the root directory that is used by CVS, with various projects (HOWTOs, mini HOWTOs, etc.) created as subdirectories of it.
Please fill the form: http://tldp.org/cvs/
During filling the form we want you to inform us about your plans, eg. which Howto you maintain.
Your unique CVSROOT directory will be created and you'll get an e-mail with a response. When you get your response, log into your CVSROOT and make sure everything is set up properly:
bash$ export CVSROOT=:pserver:your_userid@cvs.tldp.org:/cvsroot bash$ cvs -d $CVSROOT login |
(Replace the your_userid with what you were sent in the response e-mail).
You will be asked for your password, and then be given access to the CVS Repository in read-write mode. Once you've used cvs login once and have been given access to the system, your password is stored in .cvspass and you will not have to use cvs login again. Just set the CVSROOT and continue on. You can get the entire repository with this command:
bash$ cvs get LDP |
Or you can get the SGML source for your own document with these commands:
bash$ cvs get LDP/howto/docbook/YOUR-HOWTO.sgml bash$ cvs get guide/docbook/YOURGUIDE |
You can access the CVS repository via the web at http://cvsview.tldp.org/.
There are graphical interfaces to CVS, and you can get a list of them at http://freshmeat.net/appindex. Search for CVS.
CVS has a special tag, $Id$, that you can use to automatically insert the date and version directly into the document. After committing, CVS will turn this tag into $Id: cvs.xml,v 1.9 2002/04/21 09:44:26 serek Exp $ . By including this tag in your document, you can have that automatically change each time you change the file, allowing the revision mark to increment each time.
When you're ready to upload changes to the CVS server, use the command cvs ci -m "comment" YOUR-HOWTO.sgml. The -m "comment" isn't necessary, but if you don't include it, you'll be brought into the editor (usually vi, or whatever your EDITOR environment variable is) and be given the chance to add a comment about the changes.
You can follow more of the CVS discussion on the discuss list.
If you are using the LDP CVS tree while developing your document, the LDP will need to be notified when your document is ready to be published. There are two methods:
You can add to the CVS commit message a text similar to "- ready for publish."
You can notify us by e-mail. E-mail should be sent to <submit@en.tldp.org>. Indicate within the message the title of your document and the relative path to the file(s) in the LDP CVS tree.
We prefer CVS users to trigger a publishing operation thru their 'commits' message.
If your document contains graphics or multiple files, you may come to a point where you need to add new files to your cvs repository.
To do this, make sure that your HOWTO is in its own directory. You may want to coordinate with the people at <submit@en.tldp.org> to ensure you can add graphics or other files to your HOWTO.
Once this is set up, use cvs get to get the latest copy of your HOWTO. In most cases, the command will be similar to cvs get LDP/howto/docbook/YOUR-HOWTO/ assuming that your CVSROOT is set.
Copy in the files that you want to add to the repository. The command cvs add filename will tell the CVS server that you want to add filename to the repository. You can now use cvs commit to commit the changes to the CVS server. When finished, the files are now part of the repository.
Occasionally, you may want to create what you call a stable release. This is an effective way to signal to the LDP coordinator that your document is ready for release. This tag release indicates a specific version of your HOWTO. This allows you to continue creating new versions of your HOWTO without them being accidentally put on the web site.
The downside of creating a stable (or tag) release is that it uses the current version of the files - the last ones submitted. Use cvs commit to make sure that your files are synced up, then use cvs -q tag Release-x_y.
You can replace the Release-x_y with whatever you like. However, to create a wall between CVS revisions and tag releases, the tag release nust start with a letter, and contain letters, numbers, hyphens, or underscores.
There you are, typing away, when you screw up. Real bad. Doesn't matter what it is, but suffice it to say that you've toasted not only the version on your local drive, but created a new version on the CVS server. What you need to do is go back in time and resurrect and older version of your file.
To do this, you'll need to know the version number of the file you want to retrieve. cvs diff will give a list of revisions if there are differences. You can pick the revision number, subtract one, and that is probably the revision you want to look at.
The command cvs -Q update -p -r revision filename will output to stdout the contents of the revision version of filename. You can pipe it to more or redirect the output to a file. Conveniently, you can redirect stdout to a file called filename. Your local file is now the revision you want, and cvs update will update the CVS server with the new (old) version of filename.