[[PageOutline(2-5,Contents,pullout)]] = Code example box with syntax highlighting == Description This macro renders a code example box that supports syntax highlighting. It comes in the following forms: simple, correct, and incorrect. The examples can be used for code review and functional testing. Key features: * The '''SELECT ALL''' link highlights all of the code in the box to simplify the copy and paste action. * A mouse click on the header (title) will show or hide the code block. * Code from the repository can be displayed using TracLinks syntax. The multiple repository configuration (Trac >= 0.12) is supported. This plugin is to be used as follows: 1. Inside a wiki area you can invoke the `#!CodeExample` wiki processor to render a special formatted box containing specified source code, as shown and exemplified down: {{{ {{{ #!CodeExample ## parameter = value .... ## parameter = value #!language ...code... }}} }}} * Where `## parameter = value` can be one or many from: ||'''Argument'''[[BR]] ||'''Version'''[[BR]] ||'''Required (R)[[BR]]Optional (O)''' ||'''Description'''[[BR]] ||'''Default'''[[BR]] || || `## type` || || O || A type of box example: `simple`, `good`, `bad` [[BR]]* Example: {{{ ## type = bad }}} || `simple` || || `## title` || || O || The title of the example.[[BR]]* Example: {{{ ## title = Source from repository A }}} || If {{{## type = simple}}} then `EXAMPLE:`[[BR]]If {{{## type = good}}} then `CORRECT EXAMPLE:`[[BR]]If {{{## type = bad}}} then `INCORRECT EXAMPLE:` || || `## path` || || O || A file in the repository (using TracLinks format for source code)[[BR]]* Example: {{{ ## path = GPGMail/Source/GPGMailPreferences.m }}} || None || || `## repo` || || O || Repository to use (Trac 0.12 and upper only).[[BR]]* Example: {{{ ## repo = T.B.D. }}} || None || || `## regex` || || O || A regular expression indicates where to start an example.[[BR]]* Example: {{{ ## regex = ".*updater\s*{" }}} || None || || `## lines` || || O || Number of lines to show.[[BR]]* Example: {{{ ## lines = 3 }}} || None || || `#!language` || || O || Syntax highlighter. `language` is any supported by Trac. See TracSyntaxColoring.[[BR]]* Example: {{{ #!python }}} || `trac` || 2. The simple example: {{{ {{{ #!CodeExample #!python @staticmethod def get_templates_dirs(): """ Notify Trac about templates dir. """ from pkg_resources import resource_filename return [resource_filename(__name__, 'templates')] }}} }}} * will be rendered as:[[BR]] [[Image(example1.png)]][[BR]][[BR]] 1. The incorrect example: {{{ {{{ #!CodeExample ## type = bad #!haskell fibs = 0 : 1 : [ a + b | a <- fibs | b <- tail fibs ] }}} }}} * will be rendered as:[[BR]] [[Image(example2.png)]][[BR]][[BR]] 1. The correct example: {{{ {{{ #!CodeExample ## type = good #!haskell fibs = 0 : 1 : zipWith (+) fibs (tail fibs) }}} }}} * will be rendered as:[[BR]] [[Image(example3.png)]][[BR]][[BR]] 1. There is also support for getting sources from the repository: {{{ {{{ #!CodeExample ## path=GPGMail/Source/GPGMailPreferences.m ## regex=".*updater\s*{" ## lines=3 #!objective-c }}} }}} * will be rendered as:[[BR]] [[Image(example4.png)]] All rights reserved by [http://codedgers.com Codedgers Inc]. == Bugs/Feature Requests Existing bugs and feature requests for CodeExampleMacro are [report:9?COMPONENT=CodeExampleMacro here]. If you have any issues, create a [/newticket?component=CodeExampleMacro new ticket]. [[TicketQuery(component=CodeExampleMacro,group=type,format=progress)]] == Download Download the zipped source from [export:codeexamplemacro here]. == Source You can check out CodeExampleMacro from [/svn/codeexamplemacro here] using Subversion, or [source:codeexamplemacro browse the source] with Trac. == Installation {{{#!comment 1. '''Check''' dependencies: i. none required * `[sudo]` is optional in case you have authorisation to modify your server. }}} 1. '''Install''' plugin globally, for example with `easy_install`: {{{#!sh [sudo] easy_install https://trac-hacks.org/svn/codeexamplemacro }}} * `[sudo]` is optional in case you have authorisation to modify your server. * You might be required to select a specific `tag`, `branch`. Defaults to select from `trunk`. 1. '''Enable''' this component by updating TracIni file as follows: {{{#!ini [components] codeexample.code_example_processor.* = enabled }}} {{{#!comment 1. '''Configure''' this component in its own configuration section, by updating TracIni file as follows: i. none required {{{#!ini [plantuml] plantuml_jar = /path/to/plantuml.jar java_bin = /path/to/java_bin (optional, if Java binary is not on the search path) }}} * example `plantuml_jar = /project-resources/trac/plugins` * example `java_bin = java` assumes that the Java binary is on the search path. }}} 1. '''Restart''' web server on command line: {{{#!sh [sudo] /etc/init.d/apache2 restart }}} * `[sudo]` is optional in case you have authorisation to modify your server. 1. '''Test''' if this component is working properly. If the plugin is installed correctly, the examples as shown above should be displayed. == Recent Changes [[ChangeLog(codeexamplemacro, 3)]] == Author/Contributors '''Author:''' [wiki:nuald] [[BR]] '''Maintainer:''' [[Maintainer]], [wiki:rjollos] [[BR]] '''Contributors:'''