4.3. Tools for Writing, Editing and Maintaining your Document
 | Reminder |
|---|---|
You do not need to submit your initial document to the LDP in anything more than plain text! The LDP volunteers will convert your document to DocBook for you. Once it has been converted you will need to maintain your document in DocBook format. |
4.3.1. Editing Tools
You may use any word processing or text editing tool to write your initial document. When you get to the markup stage you may want to use a text editor which recognizes DocBook files. At a minimum a program which adds syntax highlighting to your markup will make life a lot easier. For a description of editors which can handle DocBook files please skip to Section B.2.
4.3.2. Concurrent Versions System (CVS)
The LDP provides optional CVS access to its authors. This enables collaborative writing and has the following positive effects:
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.
However difficult from an organizational point of view, it's great to have multiple people working on the same document. CVS enables you to do this. You can have CVS tell you what changes were made by another author while you were editing your copy, and integrate those changes.
CVS keeps a log of what changes were made. These logs (and a date stamp) can be placed automatically inside your documents when they are published.
CVS can be combined with scripts 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 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 XML code. (Although you do still need to send the submit list an email when you are ready for your document to be published, because the whole publishing process has not been fully automated yet.)
For more information on how to use CVS to maintain your LDP documents, please read Appendix C.
4.3.3. Spell Check
Some writing tools will come with their own built-in spell check tools. This list is only if your application does not have a spell check option.
Spell Check Software
- aspell http://aspell.sourceforge.net
This spell check application can work around XML tags. By distinguishing between content and markup aspell is able to check your content and ignore the bits it shouldn't be looking at. If you are getting spelling errors in your markup tags you may be using an old version and should upgrade.
The aspell command comes with the aspell package, included on most Linux distributions. Use the command as follows:
aspell -c file
An interactive user interface allows for fast and easy correction of errors. Use the --help to read more about aspell features.
- ispell http://www.cs.hmc.edu/~geoff/ispell.html
Similar to aspell, but tries to spell check your markup tags. If you have a choice, use aspell, if not, ispell is a very acceptable substitute.