[[PageOutline(2-5,Contents,pullout)]]

= Shell Example

== Description

This is a wiki processor to display command line shell examples in Trac wiki pages.

This plugin has only been tested on Trac 0.12, and may work for later versions.

== Example

A typical example might look like this:

{{{ 
{{{
#!ShellExample
(full example showing how to use openssl to connect to a pops mail server)
$ openssl s_client -connect mail.foo.com:995
CONNECTED(00000003)
depth=0 /C=US/ST=Nowhere/O=Foo/OU=bar/CN=mail.foo.com
$$---
---
+OK Dovecot ready. <1c32.1a611.4c4859c2.BEuUvAEtnt0du+msvFig0w==@mail.foo.com>
$$ user {username}
+OK
$$ pass {password}
+OK Logged in.
$$ stat
+OK 509 15659197
$$ quit
+OK Logging out.
closed
}}}
}}}

Produces output like this:

[[Image(ShellExample-example.png)]]

Additional examples are available [http://svn.umtri.umich.edu/trac/bio/wiki/useful/ShellExample/readme here].

== More Details

This is a [wiki:WikiProcessors WikiProcessor] so it is used with the standard `#!` notation. This processor injects css code into Trac, so you should get formatted output by default. Any tagged code is inside a span element, and the following classes are used:
 * se-input
 * se-input-userreplacement
 * se-input-string
 * se-input-continuation
 * se-input-option
 * se-input-delayed
 * se-prompt
 * se-prompt-start
 * se-prompt-user
 * se-prompt-userhostseparator
 * se-prompt-host
 * se-prompt-path
 * se-prompt-end
 * se-root
 * se-unprivileged
 * se-note
 * se-output
 * se-output-snipped

{{{
{{{
#!ShellExample
{user@foo ~/path/to}$ foo --user {username}
}}}
}}}

results in something like the following (expanded for easier reading):

{{{#!xml
<div class="code">
  <pre>
    <span class="se-prompt">
        <span class="se-prompt-start">{</span>
        <span class="se-prompt-user">user</span>
        <span class="se-prompt-userhostseparator">@</span>
        <span class="se-prompt-host">foo</span> 
        <span class="se-prompt-path">~/path/to</span>
        <span class="se-prompt-end">}</span>
    </span>
    <span class="se-unprivileged">$ </span>
    <span class="se-input">foo <span class="se-input-option">--user</span> <span class="se-input-userreplacement">{username}</span></span>
  </pre>
</div>
}}}

== Bugs/Feature Requests

Existing bugs and feature requests for ShellExampleMacro are 
[report:9?COMPONENT=ShellExampleMacro here].

If you have any issues, create a 
[/newticket?component=ShellExampleMacro new ticket].

[[TicketQuery(component=ShellExampleMacro&group=type,format=progress)]]

== Download

Download the current source (0.12.2) from [/svn/shellexamplemacro/0.12/tags/shellexample-0.12.2.tar.gz here].

There is also a version on [pypi:TracShellExampleMacro PyPi].

== Source

You can check out ShellExampleMacro from [/svn/shellexamplemacro/0.12/trunk/ here] using Subversion, or [source:shellexamplemacro browse the source] with Trac.

== Installation

You can install this software as a normal Trac plugin.

 1. Uninstall ShellExample wiki processor if you have installed before.
 1. Change to the directory containing `setup.py`.
 1. If you want to install this plugin globally, that will install this plugin to the Python path:
 {{{#!python
python setup.py install
}}}
 1. If you want to install this plugin to Trac instance only:
 {{{#!python
python setup.py bdist_egg
copy the generated egg file to the trac instance's plugin directory
cp dist/*.egg /srv/trac/env/plugins
}}}
 1. Configure your `trac.ini` file:
 {{{#!ini
[components]
shellexample.* = enabled
}}}

== Recent Changes

[[ChangeLog(shellexamplemacro, 3)]]

== Author/Contributors

This plugin was originally developed by [mailto:moolighttpd@gmail.com mOo]. [wiki:nmadura Nathaniel Madura] significantly updated this plugin, and took over maintenance of it.

'''Author:''' [wiki:nmadura] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''