Dev:Troubleshooting

Troubleshooting - Developer guide to adding troubleshooting messages

Online troubleshooting documentation is generated automatically from source code comments entered immediately after the code that generates the message in question. For example, the user receives the message

FATAL: the GLPATH environment variable is not set

and must find out how to fix the problem. The message was generated from a line of code

output_fatal("the GLPATH environment variable is not set");

which must be documented. To document the troubleshooting information, you must add a C-style comment on the next line

output_fatal("the GLPATH environment variable is not set"); /* TROUBLESHOOT GridLAB-D requires that GLPATH be set before the system starts. Make sure the environment variable is set and try again. */

No exception is made for line continuations, therefore the code

output_fatal("the GLPATH environment variable '%s' contains a folder that does not exist",   getenv("GLPATH"));

can only be documented either as

output_fatal("the GLPATH environment variable '%s' contains a folder that does not exist", getenv("GLPATH")); /* TROUBLESHOOT GridLAB-D requires that GLPATH environment variable refer to   folders that exist. Make sure the environment variable is set correctly and/or all the folders are accessible and try again. */

(which is preferred) or as

output_fatal("the GLPATH environment variable '%s' contains a folder that does not exist", /* TROUBLESHOOT    GridLAB-D requires that GLPATH environment variable refer to    folders that exist.  Make sure the environment variable is set    correctly and/or all the folders are accessible and try again.  */    getenv("GLPATH"));

if the argument list is particularly long

= Processing script =

The troubleshooting guide is generated automatically by the nightly build process. The processing script source code is in  and generates an HTML file that should be placed in the root document of the   web site. There is a CSS stylesheet that also needs to be copied to the root document that is placed in the same source folder.

The command generate the HTML troubleshooting guide is

host% (cd trunk; ./utilities/troubleshooting.awk */*.{c,cpp} ) > $HTML/troubleshooting.html host% (cd trunk; cp utilities/troubleshooting.css $HTML)