The K Desktop Environment

4.7. Checking Your Work

There are two things to check before committing your documentation to CVS:

  1. whether the SGML encoding is valid

  2. and if the spelling, grammar, style etc. are correct.

Usually, the SGML parser (in typical KDE DocBook setup this is Jade) will take care of the first point. Just run e.g. db2html as described in the "crash course" for DocBook (included with the ksgmltools) and the parser will tell you which lines of your translation contain what kind of SGML errors (if any). Besides, the HTML version you will get from your DocBook file this way may be a lot more readable than the file you are working on.

With regard to the following corrections of such SGML errors: Always start with the first errors listed in the parser output because SGML errors tend to have a "snowball effect" -- one error may produce many others. You will often cure a lot of these problems with just one correction if it's done at the top where, so to speak, "the snowball started rolling".

(X)Emacs can do basically the same in a separate buffer during your editing work. (You may want to activate line and maybe column numbering by entering (line-number-mode 1) and (column-number-mode 1) in your .emacs or .xemacs-options file to use this effectively.) The program also offers to lead you automatically from one "trouble spot" to the next, using an internal checking routine. Besides, (X)Emacs can also do some elementary spell checking for many languages while automatically ignoring the SGML tags. Still, it may be recommendable to design a system of mutual proofreading in your team like already suggested in the "practical hints" section.