Chapter 15. Validating Changes

Now that you have a Makefile, you can validate the documentation changes you have previously made:

$ cd phpdoc
$ make test

Which will generate output similar to this:

touch .manual.xml
CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
creating manual.xml
nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml

If you made a mistake such as forgetting to close a tag or using an invalid tag name, make test will report the error and give you the line number it found the error at.

touch .manual.xml
CONFIG_FILES=manual.xml CONFIG_HEADERS= ./config.status
creating manual.xml
nsgmls -i lang-en -s ./phpdocxml.dcl manual.xml
nsgmls:en/chpaters/intro.xml:54:13:E: end tag for "para" omitted, but OMITTAG NO was specified
make: *** [test] Error 1

In the above example output, the parser expected to see an end tag for <para> at line 54 in the file en/chapters/intro.xml. Using this information, you can go back to the file and correct the mistake before committing your changes.

In order to check the validity of your XML you may use make test_xml as this executes a xmllint check on the entire phpdoc tree. This will find problems make test ignores, problems like a missing ; or & for an entity. xmllint is much slower than the SGML check and will take roughly 4 times longer to execute (and will consume much more memory).

$ cd phpdoc
$ make test_xml

Or to simply check the XML validity of one file you may use the xml-check.php script found in the phpdoc scripts/ directory. This is much faster than make test or make test_xml if you have only modified one file. Use it like so:

$ scripts/xml-check.php en/reference/mysql/functions/mysql-connect.xml

It is important to do a test before committing, because if you commit files with errors, this single file will cause the automatic build process to halt, and the manual files and downloads will not be updated online. This can make phpdoc people angry.

When adding a new file: If you're adding a new file be sure to run ./configure again before make test so that your new file will also be checked for validity.