In order to do production testing of the HP-UX binaries, I have spent much of my morning editing our configuration (the basis for configs_samples) to fold in hpux support. There were many changes required, I made several goofs along the way, and many parse errors resulted. I have since added the following comments to the beginning of macros.cfg--tips for debugging configuration file parse errors:
/////////////////////////////////////////////////////////////////////////////// // it should be emphasized that this file (and all the other sample // PIKT config files) serves at least the following purposes: // // --it is actual, though aliased, production code/data for our site // --it is a starter set to get the new user up and running fast // --it demos what PIKT can do // --it is input for the PIKT validation self-tests // // so, for example, there are a lot of extra "#ifndef generic" and // #ifdef doexec" preprocessor directives, that ordinarily wouldn't // be here; if this file (and others) looks awfully complex in places, // remember that this needn't be so: you can dispense with #ifdef // directives entirely if you wish, and there is no law forcing you to use // #if directives anywhere, or even macros for that matter; make your // config files as simple or as complex as you wish /////////////////////////////////////////////////////////////////////////////// // when attempting to debug parse errors, keep in mind the following: // // --"parse error (in defparse())" suggests that you have a mistaken // #ifdef-#endifdef construction somewhere (e.g., you omitted an ending // #endifdef) // --"parse error (in tagparse())" suggests that you have a mistaken // #if-#endif construction somewhere (e.g., you used #if where you should // have used #elif) // --"parse error (in cfgparse())" suggests that you have a garbled your // Pikt script syntax (e.g., you have misspelled a keyword, or forgotten // to close a quoted string, or ...) // --if none of the above applies, perhaps you have, for a machine or os, // omitted a stanza identifier or stanza contents; or failed to close a // #fix-#unfix; or used '#if sys1 || sys2' instead of '#if sys1 | sys2'; // or ...; really, there are many ways you could go wrong, but if a parse // error is reported, 99.99% of the time it's for real // --sometimes parse errors reported in one file actually stem from errors // made at or near the end of the previous file; the pikt preprocessor // processes files in the following order: systems.cfg, defines.cfg, // macros.cfg, alarms.cfg, alerts.cfg, programs.cfg, files.cfg, objects.cfg; // so a parse error reported at the beginning of objects.cfg might actually // be caused by a goof at the end of files.cfg // --remember that when debugging parse errors, comments are your friend; // try using /* */ comments to nullify entire sections of the configuration; // if your problem goes away, the fault is in the commented-out section; // be sure not to nest /* */ comments, of course! // --when all else fails and you are stuck trying to debug our convoluted // configuration (that you have since modified), throw it away and start // your own configuration from scratch; issue a 'piktc -cv +H ...' // every step along the way to validate your most recent changes ///////////////////////////////////////////////////////////////////////////////
And, as a reminder, I have added the following at the start of each of the other configuration files:
/////////////////////////////////////////////////////////////////////////////// // (please see the comments prefacing the sample macros.cfg about config file // complexity and parse error debugging) ///////////////////////////////////////////////////////////////////////////////
I know PIKT like the back of my own hand, so again I tend to discount the
difficulties you might face. As time goes by, and as I write more and more
of these list messages, I am appreciating the need to write a PIKT operations
manual. For now, I'll just continue sending along stuff as it comes to mind.
For more examples, see Developer's Notes.