How to Write Documentation

The AbiWord documentation is maintained as a set of AbiWord files, which are converted to XHTML for release with the program. Thus, if you want to contribute to the documentation, you need to get the latest versions of the AbiWord files. These can be checked out of AbiWord CVS.

Getting the Files

These instructions are for people using unix variants, such as Linux, and assume that you have the cvs program installed on your system. (This is a fairly standard program, so it probably is installed, even if you don't know about it.)

Open a terminal window, because you need a command line. All lines preceded by '$' should be typed exactly as written. (These instructions are not magic. If you know what you are doing, you can alter them.)

Use cd to change to a suitable directory, and create a new directory to hold the AbiWord files.

$ mkdir abiword

$ cd abiword

Next, you need to set the CVSROOT environment variable, so that your system knows where the AbiWord files are.

$ CVSROOT=:pserver:anoncvs@cvs.abisource.com:/cvsroot

$ export CVSROOT

Now you can log in to the CVS server as an anonymous user. You should only need to do this once ever.

$ cvs login

The screen should then display:

(Logging in to anoncvs@cvs.abisource.com)

CVS Password:

The anoncvs password is anoncvs. (This isn't supposed to be secure -- the whole idea is that anyone can use it.)

Once you are logged in, you can checkout the files.

$ cvs co abiword-docs

This checks out the abiword-docs module. This is CVS HEAD -- the latest version. You may also want to check out the documentation for an earlier version of AbiWord. For example, the documentation for the 1.0.x series is on a CVS branch. You can check that out by typing the following:

$ cvs co -r ABI-1-0-0-STABLE abiword-docs

(The ABI-1-0-0-STABLE branch is now closed, but a new stable branch will probably be created soon for AbiWord 2.0.)

As this will try to create another directory with the name abiword-docs, you will have to create another higher level directory (stable-abi) if you want to keep both versions around.

CVS remembers which branch a directory comes from, so you don't need to enter the tag again while working in that directory.

You should update your document directories every so often. To do this, cd to the abiword-docs directory, and type:

$ cvs update -dP

This will get the latest versions of all the files.

The help files that you need to edit are in the ABW directory, in a directory for each language. If you need screenshots, there should be a full set in the screenshots directory.

Editing the Files

You should edit the help files in AbiWord, just like any normal document. Please use the Normal and Heading styles rather than applying formatting by hand, and create lists using AbiWord's list feature rather than by hand. This is because AbiWord exports these nicely to XHTML, and the formatting for the help files themselves is done using stylesheets.

Once you have edited a file, you need to edit the .info file that belongs with that file. So, if you edited this file, howtodocs.abw, you should also edit howtodocs.info. These are text files, and should be edited as such. The second line gives the copyright information. Make sure the date goes up to the current year, and add your name to the list.

If you want to include a hyperlink in the document, use AbiWord's Insert Hyperlink feature. Links to other help files should have .html as an extension, rather than .abw, but the relative positions in the directory hierarchy are preserved in the help system that ships with the program.

Adding New Files

Adding a new help file is very similar to editing the existing ones. Create and save the file in AbiWord, picking a name that fits with the style of the names already existing. This makes it easier to guess what a filename is when creating links.

Edit at least one other file to include a link to your new file, or else no-one will be able to get to it.

Finally, create a .info file for your new file.

The .info files are text files, not AbiWord files. The first line gives the title of the document. The second line is the copyright information: your name and the date. The third line gives the position of the file in the hierarchy.

The easiest way to do this is to edit the .info file belonging to another file linked from the same page as your new file. In this case you only need to change the name of the file at the end of the hierarchy, rather than entering the XHTML.

Getting Files Added

Once you have made your changes, you need to get them added to the CVS repository. If you already have commit privileges, you know what to do -- but please check with the current documentation maintainer first if you are doing anything major, to avoid conflicts.

If you do not have commit privileges (and, if you are using anoncvs, you don't), send an email to the abiword-dev mailing list saying that you have edited the documentation. Someone, probably the documentation maintainer, will get in touch with you, and ask you to send the files. He will check them, and most likely commit them. If you have made a translation, he is unlikely to check them, unless he speaks that language.

The current documentation maintainer is David Chart (linux@dchart.demon.co.uk).