Author: tfischer Date: Sat Mar 23 16:22:38 2013 New Revision: 1460187 URL: http://svn.apache.org/r1460187 Log: improve logging documentation; add debugging documentation
Added: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging-debugging.xml - copied, changed from r1456690, db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging.xml Removed: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging.xml Modified: db/torque/torque4/trunk/torque-site/src/site/site.xml Modified: db/torque/torque4/trunk/torque-site/src/site/site.xml URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/site.xml?rev=1460187&r1=1460186&r2=1460187&view=diff ============================================================================== --- db/torque/torque4/trunk/torque-site/src/site/site.xml (original) +++ db/torque/torque4/trunk/torque-site/src/site/site.xml Sat Mar 23 16:22:38 2013 @@ -97,7 +97,7 @@ <item name="Configuration" href="/documentation/codegen-reference/configuration.html"/> <item name="Extending" href="/documentation/codegen-reference/extending.html"/> <item name="Target Modes" href="/documentation/codegen-reference/existing-target-modes.html"/> - <item name="Logging" href="/documentation/codegen-reference/logging.html"/> + <item name="Logging and Debugging" href="/documentation/codegen-reference/logging-debugging.html"/> <item name="Generator Internals" href="/documentation/codegen-reference/generator-internals/index.html" collapse="true"> <item name="Outlet Types" href="/documentation/codegen-reference/generator-internals/outletTypes.html"/> </item> Copied: db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging-debugging.xml (from r1456690, db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging.xml) URL: http://svn.apache.org/viewvc/db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging-debugging.xml?p2=db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging-debugging.xml&p1=db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging.xml&r1=1456690&r2=1460187&rev=1460187&view=diff ============================================================================== --- db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging.xml (original) +++ db/torque/torque4/trunk/torque-site/src/site/xdoc/documentation/codegen-reference/logging-debugging.xml Sat Mar 23 16:22:38 2013 @@ -21,15 +21,97 @@ <document> <properties> - <title>Logging</title> + <title>Logging and Debugging</title> </properties> <body> - <section name="Logging in the Torque generator"> + + <section name="Logging Output of the Torque generator"> <p> - The Torque generator uses logging to visualize the work it is doing - at the moment. It commons-logging as logging abstraction, so in principle, - it is logging-framework agnostic. + The Torque generator uses logging to visualize the work it does. + The log information is written to the console, plus it is written + to the file target/torque-gen/log/torque-gen.log. The default log + level is INFO. The log level can be changed in two places: + </p> + <ul> + <li> + The templates can define a default log level + using the loglevel attribute of the control element + in the control.xml configuration file. + </li> + <li> + When executing the templates, another log level can be passed in, + overriding the log level defined in the templates. + </li> + </ul> + + <p> + How to set the log level on template execution depends on the way + the generator is started: + </p> + <ul> + <li> + Torque Maven Plugin: set the property loglevel + on the goal generate to trace, debug, info, warn or error. + </li> + <li> + Torque Ant Task: set the property loglevel to true + on the Torque generator task to trace, debug, info, warn or error. + </li> + <li> + Plain Java: use the setLoglevel method in the UnitDescriptor + you pass in when starting the generator. + </li> + </ul> + + <p> + Note that the loglevel from the control.xml configuration file + is applied after the configuration is read, so the log level before this + point may be different. + </p> + <p> + In principle, one can also overwrite the logging behaviour by + overwriting the logging configuration file in the class path. + (the file used is org.apache.torque.generator.log4j.properties). + There are several (typically hacky) ways to do this, depending + on your execution environment; one of them is simply exchanging the + logging configuration file in the generator jar you use + (or remove it from the jar and add it to the classpath by another means). + </p> + </section> + + <section name="Adding debug information to the output"> + <p> + You can add debug information to the currently generated output. + This feature is typically switched off but can be switched on + per generation run. How to set the flag depends on the way to start the + generation: + </p> + <ul> + <li> + Torque Maven Plugin: set the property addDebuggingInfoToOutput to true + on the goal generate. + </li> + <li> + Torque Ant Task: set the property addDebuggingInfoToOutput to true + on the Torque generator task. + </li> + <li> + Plain Java: call setAddDebuggingInfoToOutput(true) on the + UnitDescriptor used for the generation. + </li> + </ul> + </section> + + <section name="Logging Implementation for the Torque generator"> + <p> + Note: This section is for people who want to change the underlying logging + framework for the Torque generator. This is not needed when using + the Torque Maven Plugin or Torque Ant tasks to start the generator. + </p> + <p> + The Torque generator uses commons-logging as logging abstraction, + so in principle, it is logging-framework agnostic. </p> <p> However, the loglevel of the Torque generator can be changed by its @@ -62,7 +144,5 @@ By default, the <code>Log4jLoggingAdapter</code> is used. </p> </section> - - </body> </document> \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: torque-dev-unsubscr...@db.apache.org For additional commands, e-mail: torque-dev-h...@db.apache.org