# wiki

name: TracWorkflow
author: trac
text:
  = The Trac Ticket Workflow System

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

  The Trac ticket system provides a configurable workflow on how tickets are treated.

  == The Default Ticket Workflow

  When a new environment is created, a default workflow is configured in your `trac.ini`. This workflow is the basic workflow, as specified in [trac:source:branches/1.4-stable/trac/ticket/workflows/basic-workflow.ini basic-workflow.ini]:

  {{{#!Workflow width=700 height=300
  leave = * -> *
  leave.operations = leave_status
  leave.default = 1

  create = <none> -> new
  create.default = 1

  create_and_assign = <none> -> assigned
  create_and_assign.label = assign
  create_and_assign.permissions = TICKET_MODIFY
  create_and_assign.operations = may_set_owner

  accept = new,assigned,accepted,reopened -> accepted
  accept.permissions = TICKET_MODIFY
  accept.operations = set_owner_to_self

  resolve = new,assigned,accepted,reopened -> closed
  resolve.permissions = TICKET_MODIFY
  resolve.operations = set_resolution

  reassign = new,assigned,accepted,reopened -> assigned
  reassign.permissions = TICKET_MODIFY
  reassign.operations = set_owner

  reopen = closed -> reopened
  reopen.permissions = TICKET_CREATE
  reopen.operations = del_resolution
  }}}

  == Additional Ticket Workflows

  There are example workflows provided in the Trac source tree, see [trac:source:branches/1.4-stable/contrib/workflow contrib/workflow] for `.ini` config sections. One of those may be a good match for what you want. They can be pasted into the `[ticket-workflow]` section of your `trac.ini` file. However, if you have existing tickets then there may be issues if those tickets have states that are not in the new workflow.

  Here are some [trac:WorkFlow/Examples diagrams] of the above examples.

  == Basic Ticket Workflow Customization

  '''Note''': Ticket "statuses" or "states" are not separately defined. The states a ticket can be in are automatically generated by the transitions defined in a workflow. Therefore, creating a new ticket state simply requires defining a state transition in the workflow that starts or ends with that state.

  In the `[ticket-workflow]` section of `trac.ini`, each entry is an action that may be taken on a ticket.
  For example, consider the `accept` action from `simple-workflow.ini`:

  {{{#!ini
  accept = new,accepted -> accepted
  accept.permissions = TICKET_MODIFY
  accept.operations = set_owner_to_self
  }}}

  The first line in this example defines the `accept` action, along with the states the action is valid in (`new` and `accepted`), and the new state of the ticket when the action is taken (`accepted`).

  The `accept.permissions` line specifies the permissions the user must have to use this action. [trac:ExtraPermissionsProvider] can define new permissions to be used here.

  The `accept.operations` line specifies changes that will be made to the ticket in addition to the status change when the action is taken. In this case, when a user clicks on `accept`, the ticket owner field is updated to the logged in user. Multiple operations may be specified in a comma separated list.

  The available operations are:
  - **del_owner** -- Clears the owner field.
  - **set_owner** -- Sets the owner to the selected or entered owner. Defaults to the current user. When `[ticket] restrict_owner = true`, the select will be populated with users that have `TICKET_MODIFY` permission and an authenticated session.
   - ''actionname''`.set_owner` may optionally specify a comma delimited list of users that will be used to populate the select, or a single user. Groups and permissions may also be included in the list //(Since 1.1.3)//. When groups or permissions are specified the select is populated with all members of the group or all users that possess the permission.
  - **set_owner_to_self** -- Sets the owner to the logged in user.
  - **may_set_owner** -- Sets the owner to the selected or entered owner. Defaults to the existing owner. //(Since 1.1.2)//.
  - **del_resolution** -- Clears the resolution field.
  - **set_resolution** -- Sets the resolution to the selected value.
   - ''actionname''`.set_resolution` may optionally be set to a comma delimited list or a single value. The resolution(s) specified in this attribute must be defined in the database. Example:
   {{{#!ini
  resolve_new = new -> closed
  resolve_new.label = resolve
  resolve_new.operations = set_resolution
  resolve_new.permissions = TICKET_MODIFY
  resolve_new.set_resolution = invalid,wontfix
  }}}
  - **leave_status** -- Displays "leave as <current status>" and makes no change to the ticket.
  - **reset_workflow** -- Resets the status of tickets that are in states no longer defined.
  '''Note:''' Specifying conflicting operations, such as `set_owner` and `del_owner`, has unspecified results.

  The example that follows demonstrates the `.label` attribute. The action here is `resolve_accepted`, but it will be presented to the user as `resolve`.

  {{{#!ini
  resolve_accepted = accepted -> closed
  resolve_accepted.label = resolve
  resolve_accepted.permissions = TICKET_MODIFY
  resolve_accepted.operations = set_resolution
  }}}

  The `.label` attribute is new in Trac 1.1.3 and is functionally the same as the `.name` attribute, which is now deprecated. If neither `.label` or `.name` is specified, the action will be presented to the user as //resolve accepted//, the underscores having been replaced by whitespace (//Since 1.1.3//).

  For actions that should be available in all states, `*` may be used in place of the state. The obvious example is the `leave` action:
  {{{#!ini
  leave = * -> *
  leave.operations = leave_status
  leave.default = 1
  }}}

  The transition to `*` (`-> *`) means the workflow operation determines the next status. The only configurable ticket workflow operation that determines the next status is `leave_status`. However, another workflow controller can operate on an action with new status `*` and determine the next status.

  This also shows the use of the `.default` attribute. This value is expected to be an integer, and the order in which the actions are displayed is determined by this value. The action with the highest `.default` value is listed first, and is selected by default. The rest of the actions are listed in order of decreasing `.default` values.
  If not specified for an action, `.default` is 0. The value may be negative.

  There is one hard-coded constraint to the workflow: tickets are expected to have a `closed` state. The default reports/queries treat any state other than `closed` as an open state.

  === Ticket Create Action

  The ticket create actions are specified by a transition from the special `<none>` state. At least one create action must be available to the user in order for tickets to be created. The create actions defined in the default workflow are:
  {{{#!ini
  create = <none> -> new
  create.default = 1

  create_and_assign = <none> -> assigned
  create_and_assign.label = assign
  create_and_assign.permissions = TICKET_MODIFY
  create_and_assign.operations = may_set_owner
  }}}

  === Ticket Reset Action

  The special `_reset` action is added by default for tickets that are in states that are no longer defined. This allows tickets to be individually "repaired" after the workflow is changed, although it's recommended that the administrator perform the action by batch modifying the affected tickets. By default the `_reset` action is available to users with the `TICKET_ADMIN` permission and reset tickets are put in the //new// state. The default `_reset` action is equivalent to the following `[ticket-workflow]` action definition:

  {{{#!ini
  _reset = -> new
  _reset.label = reset
  _reset.operations = reset_workflow
  _reset.permissions = TICKET_ADMIN
  _reset.default = 0
  }}}

  Since [trac:milestone:1.0.3] the `_reset` action can be customized by redefining the implicit action. For example, to allow anyone with `TICKET_MODIFY` to perform the `_reset` action, the workflow action would need to be defined:

  {{{#!ini
  _reset = -> new
  _reset.label = reset
  _reset.operations = reset_workflow
  _reset.permissions = TICKET_MODIFY
  _reset.default = 0
  }}}

  == Workflow Visualization

  Workflows can be visualized by rendering them on the wiki using the [WikiMacros#Workflow-macro Workflow macro].

  Workflows can also be visualized using the `contrib/workflow/workflow_parser.py` script. The script outputs `.dot` files that [https://www.graphviz.org GraphViz] understands. The script can be used as follows (your install path may be different):

  {{{#!sh
  $ cd /var/local/trac_devel/contrib/workflow/
  $ ./showworkflow /srv/trac/PlannerSuite/conf/trac.ini
  }}}
  The script outputs `trac.pdf` in the same directory as the `trac.ini` file.

  == Example: Adding optional Testing with Workflow

  The following adds a `testing` action. When the ticket has status `new`, `accepted` or `needs_work`, you can choose to submit it for testing. When it's in the testing status the user gets the option to reject it and send it back to `needs_work`, or pass the testing and send it along to `closed`. If they accept it, then it is automatically marked as `closed` and the resolution is set to `fixed`. Since all the old workflow remains, a ticket can skip this entire section.

  {{{#!ini
  testing = new,accepted,needs_work,assigned,reopened -> testing
  testing.label = Submit to reporter for testing
  testing.permissions = TICKET_MODIFY

  reject = testing -> needs_work
  reject.label = Failed testing, return to developer

  pass = testing -> closed
  pass.label = Passes Testing
  pass.operations = set_resolution
  pass.set_resolution = fixed
  }}}

  == Example: Add simple optional generic review state

  Sometimes Trac is used in situations where "testing" can mean different things to different people so you may want to create an optional workflow state that is between the default workflow's `assigned` and `closed` states, but does not impose implementation-specific details. The only new state you need to add for this is a `reviewing` state. A ticket may then be "submitted for review" from any state that it can be reassigned. If a review passes, you can re-use the `resolve` action to close the ticket, and if it fails you can re-use the `reassign` action to push it back into the normal workflow.

  The new `reviewing` state along with its associated `review` action looks like this:

  {{{#!ini
  review = new,assigned,reopened -> reviewing
  review.operations = set_owner
  review.permissions = TICKET_MODIFY
  }}}

  To integrate this with the default workflow, you also need to add the `reviewing` state to the `accept` and `resolve` actions:

  {{{#!ini
  accept = new,reviewing -> assigned
  […]
  resolve = new,assigned,reopened,reviewing -> closed
  }}}

  Optionally, you can also add a new action that allows you to change the ticket's owner without moving the ticket out of the `reviewing` state. This enables you to reassign review work without pushing the ticket back to the `new` status:

  {{{#!ini
  reassign_reviewing = reviewing -> *
  reassign_reviewing.label = reassign review
  reassign_reviewing.operations = set_owner, leave_status
  reassign_reviewing.permissions = TICKET_MODIFY
  }}}

  The full `[ticket-workflow]` configuration will be:

  {{{#!ini
  [ticket-workflow]
  create = <none> -> new
  create.default = 1
  create_and_assign = <none> -> assigned
  create_and_assign.label = assign
  create_and_assign.permissions = TICKET_MODIFY
  create_and_assign.operations = may_set_owner
  accept = new,reviewing -> assigned
  accept.operations = set_owner_to_self
  accept.permissions = TICKET_MODIFY
  leave = * -> *
  leave.default = 1
  leave.operations = leave_status
  reassign = new,assigned,accepted,reopened -> assigned
  reassign.operations = set_owner
  reassign.permissions = TICKET_MODIFY
  reopen = closed -> reopened
  reopen.operations = del_resolution
  reopen.permissions = TICKET_CREATE
  resolve = new,assigned,reopened,reviewing -> closed
  resolve.operations = set_resolution
  resolve.permissions = TICKET_MODIFY
  review = new,assigned,reopened -> reviewing
  review.operations = set_owner
  review.permissions = TICKET_MODIFY
  reassign_reviewing = reviewing -> *
  reassign_reviewing.operations = set_owner, leave_status
  reassign_reviewing.label = reassign review
  reassign_reviewing.permissions = TICKET_MODIFY
  }}}

  == Advanced Ticket Workflow Customization

  If the customizations above do not meet your needs, you can extend the workflow with plugins. Plugins can provide additional operations for the workflow, like code review, or implement side-effects for an action, such as triggering a build, that may not be merely simple state changes. Look at [trac:source:branches/1.4-stable/sample-plugins/workflow sample-plugins/workflow] for a few examples to get started.

  But if even that is not enough, you can disable the !ConfigurableTicketWorkflow component and create a plugin that completely replaces it. See also the [https://trac-hacks.org/wiki/AdvancedTicketWorkflowPlugin AdvancedTicketWorkflowPlugin], which provides additional operations.

  == Adding Workflow States to Milestone Progress Bars

  If you add additional states to your workflow, you may want to customize your milestone progress bars as well. See the [TracIni#milestone-groups-section "[milestone-groups]"] section.

  == Ideas for next steps

  Enhancement ideas for the workflow system should be filed as enhancement tickets against the [trac:query:?status=assigned&status=new&status=reopened&keywords=~workflow&component=ticket+system ticket system] component. You can also document ideas on the [trac:TracIdeas/TracWorkflow TracIdeas/TracWorkflow] page.


name: WikiDeletePage
author: trac
text:
  = Deleting a Wiki Page =

  Wiki pages can be completely deleted using the //Delete page// or the //Delete this version// button at the bottom of the wiki page. These buttons are only visible for users that have the `WIKI_DELETE` permission.

  '''Note:''' Deleting a wiki page is an irreversible operation.

  Deleting specific versions or even complete pages can make sense to remove spam or other abusive submissions.

  However, if you want to delete a page because you re-created a new page with the same content but a different name, it is recommended to keep the page and use it as a redirection page instead of completely deleting it. This will avoid frustrating the visitor with broken links, particularly when coming to the site from a search engine.

  In this situation, chances are that you actually wanted to [[WikiNewPage#renaming|rename]] the page instead of doing a copy and delete.
  The //Rename// operation offers you the possibility to create a redirection page.
  A redirection page is a short page that  contains a link such as  “See !SomeOtherPage”.

  ----
  See also: TracWiki, TracPermissions


name: WikiFormatting
author: trac
text:
  = WikiFormatting

  [[TracGuideToc]]

  Wiki markup is a core feature in Trac, tightly integrating all the other parts of Trac into a flexible and unified whole.

  Trac has a powerful wiki rendering engine that implements a subset of the commands from other popular Wikis, such as [https://moinmo.in/ MoinMoin] and [trac:WikiCreole].

  The sections below provide an overview for the most common syntax, each link in the ''Category'' column leads you to the more detailed explanation later in this page.

  The following wiki pages present the advanced features of the Trac wiki markup in more depth:
   - TracLinks covers all the possible ways to refer to any Trac resource or parts thereof.
   - WikiPageNames covers the various names a wiki page can take, whether in CamelCase or not.
   - WikiMacros lists the macros available for generating dynamic content.
   - WikiProcessors and WikiHtml details how parts of the wiki text can be processed in special ways.
   - [trac:wiki:TracDev/Proposals/AdvancedWikiOperations AdvancedWikiOperations] provides some operations in uncommon or administrative scenarios.

  == Common wiki markup

  ||= '''Category''' =||= '''Wiki Markup''' =||= '''Display''' =||
  |-----------------------------------------------------------
  {{{#!th rowspan=3
  [#FontStyles Font Styles]
  }}}
  || `'''bold'''`, `''italic''`, `'''''Wikipedia style'''''` || \
  || '''bold''', ''italic'', '''''Wikipedia style''''' ||
  || `**bold**`, `//italic//`, `**//!WikiCreole style//**` || \
  || **bold**, //italic//, **//!WikiCreole style//** ||
  || {{{`monospaced (''other markup ignored'')`}}} || \
  || `monospaced (''other markup ignored'')` ||
  |-----------------------------------------------------------
  ||= [#Headings Headings] =||\
  {{{#!td
   {{{
   == Level 2
   === Level 3 ^([#hn note])^
   }}}
  }}}
  {{{#!td style="padding-left: 2em"
  == Level 2
  === Level 3 ^([#hn note])^
  }}}
  |-----------------------------------------------------------
  ||= [#Paragraphs Paragraphs]  =||\
  {{{#!td
   {{{
   First paragraph
   on multiple lines.

   Second paragraph.
   }}}
  }}}
  {{{#!td
  First paragraph
  on multiple lines.

  Second paragraph.
  }}}
  |-----------------------------------------------------------
  ||= [#Lists Lists] =||\
  {{{#!td
   {{{
   * bullet list
     on multiple lines
     1. nested list
       a. different numbering
          styles
   }}}
  }}}
  {{{#!td
  * bullet list
    on multiple lines
    1. nested list
      a. different numbering
         styles
  }}}
  |-----------------------------------------------------------
  {{{#!th
  [#DefinitionLists Definition Lists]
  }}}
  {{{#!td
   {{{
    term:: definition on
           multiple lines
   }}}
  }}}
  {{{#!td
   term:: definition on
          multiple lines
  }}}
  |-----------------------------------------------------------
  ||= [#PreformattedText Preformatted Text] =||\
  {{{#!td
   {{{
   {{{
   multiple lines, ''no wiki'',
         white space respected
   }}}
   }}}
  }}}
  {{{#!td
   {{{
   multiple lines, ''no wiki'',
         white space respected
   }}}
  }}}
  |-----------------------------------------------------------
  ||= [#Blockquotes Blockquotes] =||\
  {{{#!td
   {{{
     if there's some leading
     space the text is quoted
   }}}
  }}}
  {{{#!td
   if there's some leading
   space the text is quoted
  }}}
  |-----------------------------------------------------------
  ||= [#DiscussionCitations Discussion Citations] =||\
  {{{#!td
   {{{
   >> ... (I said)
   > (he replied)
   }}}
  }}}
  {{{#!td
  >>... (I said)
  > (he replied)
  }}}
  |-----------------------------------------------------------
  ||= [#Tables Tables] =||\
  {{{#!td
   {{{
   ||= Table Header =|| Cell ||
   ||||  (details below)  ||
   }}}
  }}}
  {{{#!td
  ||= Table Header =|| Cell ||
  ||||  (details below)  ||
  }}}
  |-----------------------------------------------------------
  {{{#!th rowspan=2
  [#Links Links]
  }}}
  || `https://trac.edgewall.org` ||\
  || https://trac.edgewall.org ||
  || `WikiFormatting (CamelCase)` ||\
  || WikiFormatting (CamelCase) ||
  |-----------------------------------------------------------
  {{{#!th rowspan=5
  [#TracLinks TracLinks]
  }}}
  || `wiki:WikiFormatting`, `wiki:"WikiFormatting"` ||\
  || wiki:WikiFormatting, wiki:"WikiFormatting" ||
  || `#1 (ticket)`, `[1] (changeset)`, `{1} (report)` ||\
  || #1 (ticket), [1] (changeset), {1} (report) ||
  || `ticket:1, ticket:1#comment:1, comment:1:ticket:1` ||\
  || ticket:1, ticket:1#comment:1, comment:1:ticket:1 ||
  || `Ticket [ticket:1]`, `[ticket:1 ticket one]` ||\
  || Ticket [ticket:1], [ticket:1 ticket one] ||
  || `Ticket [[ticket:1]]`, `[[ticket:1|ticket one]]` ||\
  || Ticket [[ticket:1]], [[ticket:1|ticket one]] ||
  |-----------------------------------------------------------
  {{{#!th rowspan=2
  [#SettingAnchors Setting Anchors]
  }}}
  || `[=#point1 (1)] First...` ||\
  || [=#point1 (1)] First... ||
  || `see [#point1 (1)]` ||\
  || see [#point1 (1)] ||
  |-----------------------------------------------------------
  {{{#!th rowspan=3
  [#Escaping Escaping Markup]
  }}}
  || `!'' doubled quotes` ||\
  || !'' doubled quotes ||
  || `!wiki:WikiFormatting`, `!WikiFormatting` ||\
  || !wiki:WikiFormatting, !WikiFormatting ||
  || [[html(<code>`{{{-}}}` triple curly brackets</code>)]] ||\
  || `{{{-}}}` triple curly brackets ||
  |-----------------------------------------------------------
  ||= [#Images Images] =|| `[[Image(`''link''`)]]` || [[Image(htdocs:../common/trac_logo_mini.png)]] ||
  |-----------------------------------------------------------
  {{{#!th rowspan=2
  [#Macros Macros]
  }}}
  || `[[MacroList(*)]]` ||  ''(short list of all available macros)''  ||
  || `[[Image?]]` ||  ''(help for the Image macro)''  ||
  |-----------------------------------------------------------
  ||= [#Processors Processors] =||\
  {{{#!td
   {{{
   {{{#!div style="font-size: 80%"
   Code highlighting:
     {{{#!python
     hello = lambda: "world"
     }}}
   }}}
   }}}
  }}}
  {{{#!td style="padding-left: 2em"
   {{{#!div style="font-size: 80%"
   Code highlighting:
     {{{#!python
     hello = lambda: "world"
     }}}
   }}}
  }}}
  |-----------------------------------------------------------
  ||= [#Comments Comments] =||\
  {{{#!td
   {{{
   {{{#!comment
   Note to Editors: ...
   }}}
   }}}
  }}}
  ||  ''(comment is shown in edit mode only)''  ||
  |-----------------------------------------------------------
  ||= [#Miscellaneous Miscellaneous] =||\
  {{{#!td
   {{{
   Line [[br]] break
   Line \\ break
   ----
   }}}
  }}}
  {{{#!td style="padding-left: 2em"
  Line [[br]] break
  Line \\ break
  ----
  }}}

  == Font Styles

  The Trac wiki supports the following font styles:
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
     * '''bold''',
       ''' triple quotes !'''
       can be bold too if prefixed by ! ''',
     * ''italic''
     * '''''bold italic''''' or ''italic and
       ''' italic bold ''' ''
     * __underline__
     * {{{monospace}}} or `monospace`
       (hence `{{{` or {{{`}}} quoting)
     * ~~strike-through~~
     * ^superscript^
     * ,,subscript,,
     * **also bold**, //italic as well//,
       and **'' bold italic **'' //(since 0.12)//
     * [[span(style=color: #FF0000, a red text )]]
    }}}
  }}}
  {{{#!td
   * '''bold''',
     ''' triple quotes !'''
     can be bold too if prefixed by ! ''',
   * ''italic''
   * '''''bold italic''''' or ''italic and
     ''' italic bold ''' ''
   * __underline__
   * {{{monospace}}} or `monospace`
     (hence `{{{` or {{{`}}} quoting)
   * ~~strike-through~~
   * ^superscript^
   * ,,subscript,,
   * **also bold**, //italic as well//,
     and **'' bold italic **'' //(since 0.12)//
   * [[span(style=color: #FF0000, a red text )]]
  }}}

  Notes:
   * `{{{...}}}` and {{{`...`}}} commands not only select a monospace font, but also treat their content as verbatim text, meaning that no further wiki processing is done on this text.
   * {{{ ! }}} tells wiki parser to not take the following characters as wiki format, so pay attention to put a space after `!`, e.g. when ending bold.
   * all the font styles marks have to be used in opening/closing pairs,
     and they must nest properly; in particular, an `''` italic can't be paired
     with a `//` one, and `'''` can't be paired with `**`.

  == Headings

  You can create a heading by starting a line with one up to six ''equal'' characters (`=`) followed by a single space and the headline text.

  [=#hn]
  The headline text can be followed by the same number of `=` characters, but this is not mandatory. That is, `=== Section3 ===` is identical to `=== Section3`.

  Finally, the heading might optionally be followed by an explicit id. If not, an implicit but nevertheless readable id will be generated.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    = Heading =
    == Subheading
    === About ''this'' ===
    === Explicit id === #using-explicit-id-in-heading
    == Subheading #sub2
  }}}
  }}}
  {{{#!td style="padding: 1em;"
    {{{
    #!div
    = Heading =
    == Subheading
    === About ''this'' ===
    === Explicit id === #using-explicit-id-in-heading
    == Subheading #sub2
    }}}
  }}}

  == Paragraphs

  A new text paragraph is created whenever two blocks of text are separated by one or more empty lines.

  A forced line break can also be inserted, using:
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    Line 1[[BR]]Line 2
    }}}
    {{{
    Paragraph
    one

    Paragraph
    two
    }}}
  }}}
  {{{#!td
    Line 1[[BR]]Line 2

    Paragraph
    one

    Paragraph
    two
  }}}

  == Lists

  The wiki supports both ordered/numbered and unordered lists.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
     * Item 1
       * Item 1.1
          * Item 1.1.1
          * Item 1.1.2
          * Item 1.1.3
       * Item 1.2
     * Item 2
    - items can start at the beginning of a line
      and they can span multiple lines
      - be careful though to continue the line
      with the appropriate indentation, otherwise
    that will start a new paragraph...

     1. Item 1
       a. Item 1.a
       a. Item 1.b
          i. Item 1.b.i
          i. Item 1.b.ii
     1. Item 2
    And numbered lists can also be restarted
    with an explicit number:
     3. Item 3
    }}}
  }}}
  {{{#!td
   * Item 1
     * Item 1.1
        * Item 1.1.1
        * Item 1.1.2
        * Item 1.1.3
     * Item 1.2
   * Item 2
  - items can start at the beginning of a line
    and they can span multiple lines
    - be careful though to continue the line
    with the appropriate indentation, otherwise
  that will start a new paragraph...

   1. Item 1
     a. Item 1.a
     a. Item 1.b
        i. Item 1.b.i
        i. Item 1.b.ii
   1. Item 2
  And numbered lists can also be restarted with an explicit number:
   3. Item 3
  }}}

  == Definition Lists

  The wiki also supports definition lists.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
     llama::
       some kind of mammal, with hair
     ppython::
       some kind of reptile, without hair
       (can you spot the typo?)
    }}}
  }}}
  {{{#!td
   llama::
     some kind of mammal, with hair
   ppython::
     some kind of reptile, without hair
     (can you spot the typo?)
  }}}

  Note that you need a space in front of the defined term.

  == Preformatted Text

  Block containing preformatted text are suitable for source code snippets, notes and examples. Use three ''curly braces'' wrapped around the text to define a block quote. The curly braces need to be on a separate line.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    {{{
    def HelloWorld():
        print '''Hello World'''
    }}}
    }}}
  }}}
  {{{#!td
    {{{
    def HelloWorld():
        print '''Hello World'''
    }}}
  }}}

  Note that this kind of block is also used for selecting lines that should be processed through WikiProcessors.

  == Blockquotes

  In order to mark a paragraph as blockquote, indent that paragraph with two spaces.

  ||= Wiki Markup =||= Display =||
  {{{#!td
  {{{
  Paragraph
    This text is a quote from someone else.
  }}}
  }}}
  {{{#!td
  Paragraph
    This text is a quote from someone else.
  }}}

  == Discussion Citations

  To delineate a citation in an ongoing discussion thread, such as the ticket comment area, email-like citation marks (`>`, `>>`, etc.) may be used.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    >> Someone's original text
    > Someone else's reply text
    >  - which can be any kind of Wiki markup
    My reply text
    }}}
  }}}
  {{{#!td
  >> Someone's original text
  > Someone else's reply text
  >  - which can be any kind of Wiki markup
  My reply text
  }}}

  == Tables
  === Simple Tables

  Simple tables can be created:
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    ||Cell 1||Cell 2||Cell 3||
    ||Cell 4||Cell 5||Cell 6||
    }}}
  }}}
  {{{#!td style="padding: 2em;"
  ||Cell 1||Cell 2||Cell 3||
  ||Cell 4||Cell 5||Cell 6||
  }}}

  Cell headings can be specified by wrapping the content in a pair of `=` characters.
  Note that the `=` characters have to stick to the cell separators:
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    ||        ||= stable =||= latest =||
    ||= 0.10 =||  0.10.5  || 0.10.6dev||
    ||= 0.11 =||  0.11.6  || 0.11.7dev||
    }}}
  }}}
  {{{#!td style="padding: 2em;"
  ||        ||= stable =||= latest =||
  ||= 0.10 =||  0.10.5  || 0.10.6dev||
  ||= 0.11 =||  0.11.6  || 0.11.7dev||
  }}}

  Finally, specifying an empty cell means that the next non empty cell will span the empty cells:
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    || 1 || 2 || 3 ||
    |||| 1-2 || 3 ||
    || 1 |||| 2-3 ||
    |||||| 1-2-3 ||
    }}}
  }}}
  {{{#!td style="padding: 2em;"
  || 1 || 2 || 3 ||
  |||| 1-2 || 3 ||
  || 1 |||| 2-3 ||
  |||||| 1-2-3 ||
  }}}

  Note that if the content of a cell sticks to one side of the cell and only one, then the text will be aligned on that side:
  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    ||=Text =||= Numbers =||
    ||left align    ||        1.0||
    ||  center      ||        4.5||
    ||      right align||     4.5||
    || default alignment ||   2.5||
    ||default||         2.5||
    ||  default ||      2.5||
    || default ||       2.5||
    }}}
  }}}
  {{{#!td style="padding: 2em;"
  ||=Text =||= Numbers =||
  ||left align    ||        1.0||
  ||  center      ||        4.5||
  ||      right align||     4.5||
  || default alignment ||   2.5||
  ||default||         2.5||
  ||  default ||      2.5||
  || default ||       2.5||
  }}}

  If contrary to the example above, the cells in your table contain more text, it might be convenient to spread a table row over multiple lines of markup. The `\` character placed at the end of a line after a cell separator tells Trac to not start a new row for the cells on the next line:

  ||= Wiki Markup =||
  {{{#!td
    {{{
    || this is column 1 [https://trac.edgewall.org/newticket new ticket] || \
    || this is column 2 [https://trac.edgewall.org/roadmap the road ahead] || \
    || that's column 3 and last one ||
    }}}
  }}}
  |-------------
  ||= Display =||
  {{{#!td style="padding: 2em;"
  || this is column 1 [https://trac.edgewall.org/newticket new ticket] || \
  || this is column 2 [https://trac.edgewall.org/roadmap the road ahead] || \
  || that's column 3 and last one ||
  }}}

  === Complex Tables

  If the possibilities offered by the simple pipe-based markup (`||`) for tables described above are not enough for your needs, you can create more elaborate tables by using [#Processors-example-tables WikiProcessor based tables].

  == Links

  Hyperlinks are automatically created for WikiPageNames and URLs. !WikiPageLinks can be disabled by prepending an exclamation mark (`!`), such as `!WikiPageLink`.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    TitleIndex, https://www.edgewall.com/, !NotAlink
    }}}
  }}}
  {{{#!td
  TitleIndex, https://www.edgewall.com/, !NotAlink
  }}}

  Links can be given a more descriptive title by writing the link followed by a space and a title and all this inside square brackets.
  If the descriptive title is omitted, then the explicit prefix is discarded, unless the link is an external link. This can be useful for wiki pages not adhering to the WikiPageNames convention.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
     * [https://www.edgewall.com Edgewall Software]
     * [wiki:TitleIndex Title Index]
     * [wiki:TitleIndex]
     * [wiki:ISO9000]
    }}}
  }}}
  {{{#!td
     * [https://www.edgewall.com Edgewall Software]
     * [wiki:TitleIndex Title Index]
     * [wiki:TitleIndex]
     * [wiki:ISO9000]
  }}}

  Following the [trac:WikiCreole] trend, the descriptive title can also be specified by writing the link followed by a pipe (`|`) and a title and all this inside //double// square brackets.

  {{{#!td
    {{{
     * [[https://www.edgewall.com|Edgewall Software]]
     * [[wiki:TitleIndex|Title Index]]
       or even [[TitleIndex|Title Index]]
     * [[wiki:TitleIndex]]
       ''' but not ![[TitleIndex]]! '''
     * [[ISO9000]]
    }}}
  }}}
  {{{#!td
     * [[https://www.edgewall.com|Edgewall Software]]
     * [[wiki:TitleIndex|Title Index]]
       or even [[TitleIndex|Title Index]]
     * [[wiki:TitleIndex]]
       ''' but not ![[TitleIndex]]! '''
     * [[ISO9000]]
  }}}

  '''Note''': the [trac:WikiCreole] style for links is quick to type and certainly looks familiar as it is the one used on Wikipedia and in many other wikis. Unfortunately it conflicts with the syntax for [#Macros macros].
  So in the rare case when you need to refer to a page which is named after a macro (typical examples being TitleIndex, InterTrac and InterWiki), by writing `[[TitleIndex]]` you will actually call the macro instead of linking to the page.

  == Trac Links

  Wiki pages can link directly to other parts of the Trac system. Pages can refer to tickets, reports, changesets, milestones, source files and other Wiki pages using the following notations:

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
     * Tickets: #1 or ticket:1
     * Reports: {1} or report:1
     * Changesets: r1, [1] or changeset:1
     * ...
     * targeting other Trac instances,
       so called InterTrac links:
       - Tickets: #Trac1 or Trac:ticket:1
       - Changesets: [Trac1] or Trac:changeset:1
    }}}
  }}}
  {{{#!td
   * Tickets: #1 or ticket:1
   * Reports: {1} or report:1
   * Changesets: r1, [1] or changeset:1
   * ...
   * targeting other Trac instances,
     so called InterTrac links:
     - Tickets: #Trac1 or Trac:ticket:1
     - Changesets: [Trac1] or Trac:changeset:1
  }}}

  There are many more flavors of Trac links, see TracLinks for more in-depth information and a reference for all the default link resolvers.

  == Setting Anchors

  An anchor, or more correctly speaking, an [https://www.w3.org/TR/REC-html40/struct/links.html#h-12.2.1 anchor name] can be added explicitly at any place in the Wiki page, to uniquely identify a position in the document:

  {{{
  [=#point1]
  }}}

  This syntax was chosen to match the format for explicitly naming the header id [#Headings documented above]:
  {{{
  == Long title == #title
  }}}

  It is also very close to the syntax for the corresponding link to that anchor:
  {{{
  [#point1]
  }}}

  Optionally, a label can be given to the anchor:
  {{{
  [=#point1 '''Point 1''']
  }}}

  ||= Wiki Markup =||= Display =||
  |----------------------------------
  {{{#!td
    {{{
    [#point2 jump to the second point]

    ...

    Point2:  [=#point2] Jump here
    }}}
  }}}
  {{{#!td
    [#point2 jump to the second point]

    ...

    Point2:  [=#point2] Jump here
  }}}

  For more complex anchors (eg when a custom title is wanted), you can use the Span macro: `[[span(id=point2, class=wikianchor, title=Point 2, ^(2)^)]]`.

  == Escaping Links, WikiPageNames and other Markup == #Escaping

  You may avoid making hyperlinks out of TracLinks by preceding an expression with a single exclamation mark (`!`).

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
     !NoHyperLink
     !#42 is not a link
    }}}
    {{{
  Various forms of escaping for list markup:
   ^^- escaped minus sign \\
   ^^1. escaped number  \\
   ^^* escaped asterisk sign
    }}}
  }}}
  {{{#!td
   !NoHyperLink
   !#42 is not a link

  Various forms of escaping for list markup:
   ^^- escaped minus sign \\
   ^^1. escaped number  \\
   ^^* escaped asterisk sign
  }}}

  == Images

  Urls ending with `.png`, `.gif` or `.jpg` are no longer automatically interpreted as image links, and converted to `<img>` tags.

  You now have to use the ![[Image]] macro. The simplest way to include an image is to upload it as attachment to the current page, and put the filename in a macro call like `[[Image(picture.gif)]]`.

  In addition to the current page, it is possible to refer to other resources:
   * `[[Image(wiki:WikiFormatting:picture.gif)]]` (referring to attachment on another page)
   * `[[Image(ticket:1:picture.gif)]]` (file attached to a ticket)
   * `[[Image(htdocs:picture.gif)]]` (referring to a file inside the [TracEnvironment environment] `htdocs` directory)
   * `[[Image(source:/trunk/trac/htdocs/trac_logo_mini.png)]]` (a file in repository)

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    [[Image(htdocs:../common/trac_logo_mini.png)]]
    }}}
  }}}
  {{{#!td
  [[Image(htdocs:../common/trac_logo_mini.png)]]
  }}}

  See WikiMacros for further documentation on the `[[Image()]]` macro, which has several useful options (`title=`, `link=`, etc.)

  == Macros

  Macros are ''custom functions'' that insert dynamic content in a page.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    [[RecentChanges(Trac,3)]]
    }}}
  }}}
  {{{#!td style="padding-left: 2em"
  [[RecentChanges(Trac,3)]]
  }}}

  See WikiMacros for more information, and a list of installed macros.

  The detailed help for a specific macro can also be obtained more directly by appending a `?` to the macro name.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    [[MacroList?]]
    }}}
  }}}
  {{{#!td style="padding-left: 2em"
  [[MacroList?]]
  }}}

  == Processors

  Trac supports alternative markup formats using WikiProcessors. For example, processors are used to write pages in
  [wiki:WikiRestructuredText reStructuredText] or [wiki:WikiHtml HTML].

  ||= Wiki Markup =||= Display =||
  |--------------------------------------------------------
  {{{#!td align="center" colspan=2 style="border: 0px; font-size: 90%"

     [=#Processors-example-html Example 1:] HTML

  }}}
  |--------------------------------------------------------
  {{{#!td style="border: 0px"
    {{{
    {{{#!html
    <h1 style="text-align: right; color: blue">
     HTML Test
    </h1>
    }}}
    }}}
  }}}
  {{{#!td valign="top"  style="border: 0px"

  {{{#!html
  <h1 style="text-align: right; color: blue">HTML Test</h1>
  }}}

  }}}
  |--------------------------------------------------------
  {{{#!td align="center" colspan=2 style="border: 0px; font-size: 90%"

     [=#Processors-example-highlight Example 2:] Code Highlighting

  }}}
  |--------------------------------------------------------
  {{{#!td style="border: 0px"
    {{{
    {{{#!python
    class Test:

        def __init__(self):
            print "Hello World"
    if __name__ == '__main__':
       Test()
    }}}
    }}}
  }}}
  {{{#!td valign="top"  style="border: 0px"

  {{{#!python
  class Test:
      def __init__(self):
          print "Hello World"
  if __name__ == '__main__':
     Test()
  }}}

  }}}
  |--------------------------------------------------------
  {{{#!td align="center" colspan=2 style="border: 0px; font-size: 90%"

         [=#Processors-example-tables Example 3:] Complex Tables

  }}}
  |--------------------------------------------------------
  {{{#!td style="border: 0px"
    {{{
    {{{#!th rowspan=4 align=justify
    With the `#td` and `#th` processors,
    table cells can contain any content:
    }}}
    |----------------
    {{{#!td
      - lists
      - embedded tables
      - simple multiline content
    }}}
    |----------------
    {{{#!td
    As processors can be easily nested,
    so can be tables:
      {{{#!th
      Example:
      }}}
      {{{#!td style="background: #eef"
      || must be at the third level now... ||
      }}}
    }}}
    |----------------
    {{{#!td
    Even when you don't have complex markup,
    this form of table cells can be convenient
    to write content on multiple lines.
    }}}
    }}}
  }}}
  {{{#!td  valign="top"  style="border: 0px"

    {{{#!th rowspan=4 align=justify
    With the `#td` and `#th` processors,
    table cells can contain any content:
    }}}
    |----------------
    {{{#!td
      - lists
      - embedded tables
      - simple multiline content
    }}}
    |----------------
    {{{#!td
    As processors can be easily nested,
    so can be tables:
      {{{#!th
      Example:
      }}}
      {{{#!td style="background: #eef"
      || must be at the third level now... ||
      }}}
    }}}
    |----------------
    {{{#!td
    Even when you don't have complex markup,
    this form of table cells can be convenient
    to write content on multiple lines.
    }}}

  }}}

  See WikiProcessors for more information.

  == Comments

  Comments can be added to the plain text. These will not be rendered and will not display in any other format than plain text.

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    Nothing to
    {{{#!comment
    Your comment for editors here
    }}}
    see.
    }}}
  }}}
  {{{#!td
    Nothing to
    {{{#!comment
    Your comment for editors here
    }}}
    see.
  }}}

  == Miscellaneous

  ||= Wiki Markup =||= Display =||
  {{{#!td
    Horizontal line:
    {{{
    Four or more dashes will be replaced
    by a horizontal line (<HR>)
    ----
    See?
    }}}
  }}}
  {{{#!td
  Four or more dashes will be replaced
  by a horizontal line (<HR>)
  ----
  See?
  }}}
  |----------------------------------
  {{{#!td
    Two examples of line breaks:
    {{{
    "macro" style [[BR]] line break
    }}}
    or:
    {{{
    !WikiCreole style \\ line\\break
    }}}
  }}}
  {{{#!td
  "macro" style [[BR]] line break

  !WikiCreole style \\ line\\break
  }}}
  |----------------------------------


name: WikiHtml
author: trac
text:
  = Using HTML in Wiki Text

  Trac supports the display of HTML in any wiki context, by using the `#!html` [wiki:WikiProcessors WikiProcessor].

  However, this HTML has to be [https://en.wikipedia.org/wiki/Well-formed_element well-formed].
  In particular, you can't insert a start tag in an `#!html` block, resume normal wiki text and insert the corresponding end tag in a second `#!html` block.

  For creating styled `<div>`s, `<span>`s  or even complex tables containing arbitrary Wiki text, there is a powerful alternative: `#!div`, `#!span` and `#!table`, `#!tr`, `#!td` and `#!th` blocks. Those Wiki processors are built-in and do not require additional packages to be installed.

  == How to use `#!html` #HowtoUseHTML
  To inform the wiki engine that a block of text should be treated as HTML, use the ''html'' processor:

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    {{{#!html
    <h1 style="text-align: right; color: blue">HTML Test</h1>
    }}}
    }}}
  }}}
  {{{#!td style="padding-left: 2em"
    {{{#!html
    <h1 style="text-align: right; color: blue">HTML Test</h1>
    }}}
  }}}

  Note that Trac sanitizes your HTML code before displaying it. That means that potentially dangerous constructs, such as Javascript event handlers, will be removed from the output.

  The filtering is done by [https://genshi.edgewall.org/ Genshi] and the output will be a well-formed fragment of HTML. This means that you cannot use two HTML blocks, one for opening a <div> and another for closing it, in order to wrap arbitrary wiki text.

  == How to use `#!div` and `#!span` == #HowtoUseDivSpan

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    {{{#!div class="important"
    **important** is a predefined class.
    }}}
    }}}
    {{{
    {{{#!div style="border: 1pt dotted; margin: 1em"
    **wikipage** is another predefined class that will
    be used when no class is specified.
    }}}
    }}}
    {{{
    {{{#!div class="compact" style="border: 1pt dotted; margin: 1em"
    **compact** is another predefined class reducing
    the padding within the `<div>` to a minimum.
    }}}
    }}}
    {{{
    {{{#!div class="wikipage compact" style="border: 1pt dotted"
    Classes can be combined (here **wikipage** and **compact**)
    which results in this case in reduced //vertical//
    padding but there's still some horizontal space for coping
    with headings.
    }}}
    }}}
    {{{
    {{{#!div class="" style="border: 1pt dotted; margin: 1em"
    Explicitly specifying no classes is //not// the same
    as specifying no class attribute, as this will remove
    the //wikipage// default class.
    }}}
    }}}
  }}}
  {{{#!td style="padding-left: 2em"

    {{{#!div class="important"
    **important** is a predefined class.
    }}}

    {{{#!div style="border: 1pt dotted; margin: 1em"
    **wikipage** is another predefined class that will
    be used when no class is specified.
    }}}

    {{{#!div class="compact" style="border: 1pt dotted; margin: 1em"
    **compact** is another predefined class reducing
    the padding within the `<div>` to a minimum.
    }}}

    {{{#!div class="wikipage compact" style="border: 1pt dotted"
    Classes can be combined (here **wikipage** and **compact**)
    which results in this case in reduced //vertical//
    padding but there's still some horizontal space for coping
    with headings.
    }}}

    {{{#!div class="" style="border: 1pt dotted; margin: 1em"
    Explicitly specifying no classes is //not// the same
    as specifying no class attribute, as this will remove
    the //wikipage// default class.
    }}}

  }}}

  Note that the contents of a `#!div` block are contained in one or more paragraphs, which have a non-zero top and bottom margin. This leads to the top and bottom padding in the example above. To remove the top and bottom margin of the content, add the `compact` class to the `#!div`. Another predefined class besides `wikipage` and `compact` is `important`, which can be used to make a paragraph stand out. Extra CSS classes can be defined via [TracInterfaceCustomization#SiteAppearance site/style.css].

  For spans, you should use the Macro call syntax:
  ||= Wiki Markup =||
  {{{#!td
    {{{
    Hello
    [[span(''WORLD'' (click [#anchor here]), style=color: green; font-size: 120%, id=anchor)]]!
    }}}
  }}}
  |---------------------------------------------------------------------------------
  ||= Display =||
  {{{#!td style="padding-left: 2em"
    Hello
    [[span(''WORLD'' (click [#anchor here]), style=color: green; font-size: 120%, id=anchor)]]!
  }}}

  == How to use `#!td` and other table related processors #Tables

  The `#!td` or `#!th` processors should be used to create table data and table header cells, respectively. The other processors `#!table` and `#!tr` are not required for introducing a table structure, as `#!td` and `#!th` will do this automatically. The `|-` row separator can be used to start a new row when needed, but some may prefer to use a `#!tr` block for that, as this introduces a more formal grouping and offers the possibility to use an extra level of indentation. The main purpose of the `#!table` and `#!tr` is to give the possibility to specify HTML attributes, like ''style'' or ''valign'' to these elements.

  ||= Wiki Markup =||= Display =||
  {{{#!td
   {{{
   Simple 2x2 table with rich content:
   {{{#!th align=left
    - Left
    - Header
   }}}
   {{{#!th align=left
    - Right
    - Header
   }}}
   |----------------------------------
   {{{#!td style="background: #ffd"
    - Left
    - Content
   }}}
   {{{#!td style="vertical-align: top"
   !RightContent
   }}}
   |----------------------------------
   || ... and this can be mixed||\
   ||with pipe-based cells ||
   {{{#!td colspan=2
   Pick the style the more appropriate
   to your content

   See WikiFormatting#Tables for details
   on the pipe-based table syntax.
   }}}

   If one needs to add some
   attributes to the table itself...

   {{{#!table style="border:none;text-align:center;margin:auto"
     {{{#!tr ====================================
       {{{#!th style="border: none"
       Left header
       }}}
       {{{#!th style="border: none"
       Right header
       }}}
     }}}
     {{{#!tr ==== style="border: 1px dotted grey"
       {{{#!td style="border: none"
       1.1
       }}}
       {{{#!td style="border: none"
       1.2
       }}}
     }}}
     {{{#!tr ====================================
       {{{#!td style="border: none"
       2.1
       }}}
       {{{#!td
       2.2
       }}}
     }}}
   }}}


   }}}
  }}}
  {{{#!td valign=top
  Simple 2x2 table with rich content:
  {{{#!th align=left
   - Left
   - Header
  }}}
  {{{#!th align=left
   - Right
   - Header
  }}}
  |----------------------------------
  {{{#!td style="background: #ffd"
   - Left
   - Content
  }}}
  {{{#!td style="vertical-align: top"
  !RightContent
  }}}
  |----------------------------------
  || ... and this can be mixed||\
  ||with pipe-based cells ||
  {{{#!td colspan=2
  Pick the style the more appropriate
  to your content

  See WikiFormatting#Tables for details
  on the pipe-based table syntax.
  }}}

  If one needs to add some
  attributes to the table itself...

  {{{#!table style="border:none;text-align:center;margin:auto"
    {{{#!tr ====================================
      {{{#!th style="border: none"
      Left header
      }}}
      {{{#!th style="border: none"
      Right header
      }}}
    }}}
    {{{#!tr ==== style="border: 1px dotted grey"
      {{{#!td style="border: none"
      1.1
      }}}
      {{{#!td style="border: none"
      1.2
      }}}
    }}}
    {{{#!tr ====================================
      {{{#!td style="border: none"
      2.1
      }}}
      {{{#!td
      2.2
      }}}
    }}}
  }}}
  }}}

  Note that by default tables are assigned the "wiki" CSS class, which gives a distinctive look to the header cells and a default border to the table and cells, as can be seen for the tables on this page. By removing this class (`#!table class=""`), one regains complete control on the table presentation. In particular, neither the table nor the rows nor the cells will have a border, so this is a more effective way to get such an effect rather than having to specify a `style="border: no"` parameter everywhere.

  {{{#!table class=""
  ||= Wiki Markup =||= Display =||
   {{{#!td
    {{{
    {{{#!table class=""
    ||  0||  1||  2||
    || 10|| 20|| 30||
    || 11|| 22|| 33||
    ||||||=  numbers  =||
    }}}
    }}}
   }}}
   {{{#!td
    {{{#!table class=""
    ||  0||  1||  2||
    || 10|| 20|| 30||
    || 11|| 22|| 33||
    ||||||=  numbers  =||
    }}}
   }}}
  }}}

  Other classes can be specified as alternatives (remember that you can define your own in [TracInterfaceCustomization#SiteAppearance site/style.css]).

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    {{{#!table class="listing"
    ||  0||  1||  2||
    || 10|| 20|| 30||
    || 11|| 22|| 33||
    ||||||=  numbers  =||
    }}}
    }}}
  }}}
  {{{#!td
    {{{#!table class="listing"
    ||  0||  1||  2||
    || 10|| 20|| 30||
    || 11|| 22|| 33||
    ||||||=  numbers  =||
    }}}
  }}}

  == HTML comments
  HTML comments are stripped from the output of the `html` processor. To add an HTML comment to a wiki page, use the `htmlcomment` processor, available since Trac 0.12:
  ||= Wiki Markup =||
  {{{#!td
    {{{
    {{{#!htmlcomment
    This block is translated to an HTML comment.
    It can contain <tags> and &entities; that will not be escaped in the output.
    }}}
    }}}
  }}}
  |---------------------------------------------------------------------------------
  ||= Display =||
  {{{#!td
    {{{
    <!--
    This block is translated to an HTML comment.
    It can contain <tags> and &entities; that will not be escaped in the output.
    -->
    }}}
  }}}

  The character sequence `--` is not allowed in HTML comments, and will generate a rendering error.


  == More Information

   * https://www.w3.org/ -- World Wide Web Consortium
   * https://www.w3.org/MarkUp/ -- HTML Markup Home Page

  ----
  See also:  WikiFormatting, WikiProcessors, WikiRestructuredText


name: WikiMacros
author: trac
text:
  = Trac Macros

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

  '''Trac macros''' extend Trac with custom functionality. Macros are a special type of plugin and are written in Python. A macro generates HTML in any context supporting WikiFormatting.

  The macro syntax is `[[macro-name(optional-arguments)]]`.

  '''WikiProcessors''' are another kind of macro, commonly used for source code highlighting using a processor like `!#python` or `!#apache`:

  {{{
  {{{#!wiki-processor-name
  ...
  }}}
  }}}

  == Using Macros

  Macro calls are enclosed in double-square brackets `[[..]]`. Like Python functions macros can have arguments, which take the form of a comma separated list within parentheses `[[..(,)]]`. A common macro used is a list of the 3 most recent changes to a wiki page, or here, for example, all wiki pages starting with 'Trac':

  ||= Wiki Markup =||= Display =||
  {{{#!td
    {{{
    [[RecentChanges(Trac,3)]]
    }}}
  }}}
  {{{#!td style="padding-left: 2em;"
  [[RecentChanges(Trac,3)]]
  }}}

  === Getting Detailed Help

  The list of available macros and the full help can be obtained using the !MacroList macro, see [#AvailableMacros below].

  A brief list can be obtained via `[[MacroList(*)]]` or `[[?]]`.

  Detailed help on a specific macro can be obtained by passing it as an argument to !MacroList, e.g. `[[MacroList(MacroList)]]`, or more conveniently, by appending a question mark (`?`) to the macro's name, like in `[[MacroList?]]`.

  == Available Macros

  [[MacroList]]

  == Contributed macros

  The [https://trac-hacks.org/ Trac Hacks] site provides a large collection of macros and other Trac [TracPlugins plugins] contributed by the Trac community. If you are looking for new macros, or have written one that you would like to share, please visit that site.

  == Developing Custom Macros

  Macros, like Trac itself, are written in the [https://python.org/ Python programming language] and are a type of [TracPlugins plugin].

  Here are 2 simple examples showing how to create a Macro. For more information about developing macros, see the [trac:TracDev development resources] and [trac:browser:branches/1.4-stable/sample-plugins sample-plugins].

  === Macro without arguments

  To test the following code, copy it to `timestamp_sample.py` in the TracEnvironment's `plugins/` directory.

  {{{#!python
  from trac.util.datefmt import datetime_now, format_datetime, utc
  from trac.util.html import tag
  from trac.wiki.macros import WikiMacroBase

  class TimestampMacro(WikiMacroBase):
      _description = "Inserts the current time (in seconds) into the wiki page."

      def expand_macro(self, formatter, name, content, args=None):
          t = datetime_now(utc)
          return tag.strong(format_datetime(t, '%c'))
  }}}

  === Macro with arguments

  To test the following code, copy it to `helloworld_sample.py` in the TracEnvironment's `plugins/` directory.

  {{{#!python
  from trac.util.translation import cleandoc_
  from trac.wiki.macros import WikiMacroBase

  class HelloWorldMacro(WikiMacroBase):
      _description = cleandoc_(
      """Simple HelloWorld macro.

      Note that the name of the class is meaningful:
       - it must end with "Macro"
       - what comes before "Macro" ends up being the macro name

      The documentation of the class (i.e. what you're reading)
      will become the documentation of the macro, as shown by
      the !MacroList macro (usually used in the WikiMacros page).
      """)

      def expand_macro(self, formatter, name, content, args=None):
          """Return some output that will be displayed in the Wiki content.

          `name` is the actual name of the macro (no surprise, here it'll be
          `'HelloWorld'`),
          `content` is the text enclosed in parenthesis at the call of the
            macro. Note that if there are ''no'' parenthesis (like in, e.g.
            [[HelloWorld]]), then `content` is `None`.
          `args` will contain a dictionary of arguments when called using the
            Wiki processor syntax and will be `None` if called using the
            macro syntax.
          """
          return 'Hello World, content = ' + unicode(content)
  }}}

  Note that `expand_macro` optionally takes a 4^th^ parameter ''`args`''. When the macro is called as a [WikiProcessors WikiProcessor], it is also possible to pass `key=value` [WikiProcessors#UsingProcessors processor parameters]. If given, those are stored in a dictionary and passed in this extra `args` parameter. When called as a macro, `args` is `None`.

  For example, when writing:
  {{{
  {{{#!HelloWorld style="polite" -silent verbose
  <Hello World!>
  }}}

  {{{#!HelloWorld
  <Hello World!>
  }}}

  [[HelloWorld(<Hello World!>)]]
  }}}

  One should get:
  {{{
  Hello World, text = <Hello World!>, args = {'style': u'polite', 'silent': False, 'verbose': True}
  Hello World, text = <Hello World!>, args = {}
  Hello World, text = <Hello World!>, args = None
  }}}

  Note that the return value of `expand_macro` is '''not''' HTML escaped. Depending on the expected result, you should escape it yourself (using `return Markup.escape(result)`), or if this is indeed HTML, wrap it in a Markup object: `return Markup(result)` (`from trac.util.html import Markup`).

  You can also recursively use a wiki formatter to process the `content` as wiki markup:

  {{{#!python
  from trac.wiki.formatter import format_to_html
  from trac.wiki.macros import WikiMacroBase

  class HelloWorldMacro(WikiMacroBase):
      def expand_macro(self, formatter, name, content, args):
          content = "any '''wiki''' markup you want, even containing other macros"
          # Convert Wiki markup to HTML
          return format_to_html(self.env, formatter.context, content)
  }}}


name: WikiNewPage
author: trac
text:
  = Steps to Add a New Wiki Page =
  [[TracGuideToc]]

  You can create a new wiki page by typing the CamelCase name of the page in the quick-search field at the top of the page, or by trying to view a wiki page of that name. Note that a page is "orphaned" by default until it is linked to from another page.

  You must be granted permission to create wiki pages. If you don't see the **Create this page** button when visiting a non-existent wiki page, you lack appropriate permission. Contact your local Trac administrator for more information.

  A new wiki page can also be created as follows:

  1. Choose a name for your new page. See WikiPageNames for naming conventions.
  1. Edit an existing page or any other resource that support WikiFormatting and add a [TracLinks link] to your new page. If your page name is CamelCase, you can simply type the page name, provided the [TracIni#wiki-section ignore_missing_pages option] is `disabled` (the default).
  1. Save your changes.
  1. Follow the link you created to take you to the new page.
  1. Click the **Create this page** button to enter edit mode and add content to your new page.
  1. Save your changes to publish your page.

  == Rename a page #renaming

  While choosing a good [WikiPageNames page name] is important for usability purposes, you can always rename the page later. You will need the WIKI_RENAME permission to rename pages.

  When renaming a page, you'll be offered the possibility to create a page at the old location that contains a link to the new page, so that links pointing to the old location are not "dangling" (i.e. pointing to a non-existent page).

  ----
  See also: TracWiki, PageTemplates, WikiFormatting, TracLinks, WikiDeletePage


name: WikiPageNames
author: trac
text:
  = Wiki Page Names
  [[TracGuideToc]]

  Wiki page names commonly use the CamelCase convention. Within wiki text, any word in CamelCase automatically becomes a hyperlink to the wiki page with that name.

  CamelCase page names follow these rules:

   1. The name must consist of '''alphabetic characters only'''; no digits, spaces, punctuation or underscores are allowed.
   1. A name must have at least two capital letters.
   1. The first character must be capitalized.
   1. Every capital letter must be followed by one or more lower-case letters.
   1. The use of slash ( / ) is permitted in page names, where it typically represents a hierarchy.

  If you want to create a wiki page that does not follow CamelCase rules. you can use the following syntax:
  {{{
   * [wiki:Wiki_page], [wiki:ISO9000],
     and with a label: [wiki:ISO9000 ISO 9000 standard]
   * [wiki:"Space Matters"]
     and with a label: [wiki:"Space Matters" all about white space]
   * or simply: ["WikiPageName"]s
   * even better, the [[WikiCreole link style]]
     and with a label: [[WikiCreole link style|WikiCreole style links]]
  }}}

  This will be rendered as:
   * [wiki:Wiki_page], [wiki:ISO9000],
     and with a label: [wiki:ISO9000 ISO 9000 standard]
   * [wiki:"Space Matters"] ''(that page name embeds space characters)''
     and with a label: [wiki:"Space Matters" all about white space]
   * or simply: ["WikiPageName"]s
   * even better, the [[WikiCreole link style]]
     and with a label: [[WikiCreole link style|WikiCreole style links]]

  It is possible to link to a specific ''version'' of a Wiki page as you would do for a specific version of a file, for example: WikiStart@1.

  You can prevent a !CamelCase name from being interpreted as a [TracLinks link] by quoting it with an exclamation mark: `!CamelCase`. See TracLinks#EscapingLinks.

  As in the example above, you can append an anchor to a Wiki page name to link to a specific section within that page. The anchor can be seen by hovering the mouse over a section heading, then clicking on the [[html(&para;)]] sign that appears at its end. The anchor is usually generated automatically, but it is also possible to specify it explicitly: see WikiFormatting#using-explicit-id-in-heading.

  There are a few options that govern the rendering of WikiPageNames:
  * CamelCase linking to missing pages can be disabled with the `ignore_missing_pages` [https://trac.edgewall.org/wiki/TracIni#wiki-section option]. Linking to missing pages is enabled by default.
  * The `split_page_names` option, when enabled, will split CamelCase words when rendering a link. For example, WikiStart will be rendered as [WikiStart Wiki Start].

  ----
  See also: WikiNewPage, WikiFormatting, TracWiki, TracLinks


name: WikiProcessors
author: trac
text:
  = Wiki Processors

  Processors are WikiMacros that provide alternative markup formats for the [TracWiki Wiki engine]. Processors can be thought of as ''macro functions to process user-edited text''.

  Wiki processors can be used in any Wiki text throughout Trac, such as:
   - [#CodeHighlightingSupport syntax highlighting] or for rendering text verbatim
   - rendering [#HTMLrelated Wiki markup inside a context] such as <div> or <span> blocks or within <td> or <th> table cells
   - using an alternative markup syntax, like [WikiHtml raw HTML] and [WikiRestructuredText Restructured Text] or [https://www.booked.net/textism.html textile]

  == Using Processors

  To use a processor on a block of text, first delimit the lines using a Wiki ''code block'':
  {{{
  {{{
  The lines
  that should be processed...
  }}}
  }}}

  Immediately after the `{{{` or on the line just below, add `#!` followed by the ''processor name'':

  {{{
  {{{
  #!processorname
  The lines
  that should be processed...
  }}}
  }}}

  This is the "shebang" notation, familiar to most UNIX users.

  Besides their content, some Wiki processors can also accept ''parameters'', which are then given as `key=value` pairs after the processor name and on the same line. If `value` has to contain space, as it's often the case for the style parameter, a quoted string can be used (`key="value with space"`).

  As some processors are meant to process Wiki markup, it's quite possible to ''nest'' processor blocks.
  You may want to indent the content of nested blocks for increased clarity, this extra indentation will be ignored when processing the content.

  == Examples

  ||= Wiki Markup =||= Display =||
  {{{#!td colspan=2 align=center style="border: none"

                  '''Example 1''': Inserting raw HTML
  }}}
  |-----------------------------------------------------------------
  {{{#!td style="border: none"
  {{{
  {{{
  #!html
  <h1 style="color: grey">This is raw HTML</h1>
  }}}
  }}}
  }}}
  {{{#!td valign=top style="border: none; padding-left: 2em"
  {{{
  #!html
  <h1 style="color: grey">This is raw HTML</h1>
  }}}
  }}}
  |-----------------------------------------------------------------
  {{{#!td colspan=2 align=center style="border: none"

       '''Example 2''': Highlighted Python code in a <div> block with custom style
  }}}
  |-----------------------------------------------------------------
  {{{#!td style="border: none"
    {{{
    {{{#!div style="background: #ffd; border: 3px ridge"

    This is an example of embedded "code" block:

      {{{
      #!python
      def hello():
          return "world"
      }}}

    }}}
    }}}
  }}}
  {{{#!td valign=top style="border: none; padding: 1em"
    {{{#!div style="background: #ffd; border: 3px ridge"

    This is an example of embedded "code" block:

      {{{
      #!python
      def hello():
          return "world"
      }}}

    }}}
  }}}
  |-----------------------------------------------------------------
  {{{#!td colspan=2 align=center style="border: none"

       '''Example 3''': Searching tickets from a wiki page, by keywords.
  }}}
  |-----------------------------------------------------------------
  {{{#!td style="border: none"
    {{{
    {{{
    #!html
    <form action="/query" method="get"><div>
    <input type="text" name="keywords" value="~" size="30"/>
    <input type="submit" value="Search by Keywords"/>
    <!-- To control what fields show up use hidden fields
    <input type="hidden" name="col" value="id"/>
    <input type="hidden" name="col" value="summary"/>
    <input type="hidden" name="col" value="status"/>
    <input type="hidden" name="col" value="milestone"/>
    <input type="hidden" name="col" value="version"/>
    <input type="hidden" name="col" value="owner"/>
    <input type="hidden" name="col" value="priority"/>
    <input type="hidden" name="col" value="component"/>
    -->
    </div></form>
    }}}
    }}}
  }}}
  {{{#!td valign=top style="border: none; padding: 1em"
    {{{
    #!html
    <form action="/query" method="get"><div>
    <input type="text" name="keywords" value="~" size="30"/>
    <input type="submit" value="Search by Keywords"/>
    <!-- To control what fields show up use hidden fields
    <input type="hidden" name="col" value="id"/>
    <input type="hidden" name="col" value="summary"/>
    <input type="hidden" name="col" value="status"/>
    <input type="hidden" name="col" value="milestone"/>
    <input type="hidden" name="col" value="version"/>
    <input type="hidden" name="col" value="owner"/>
    <input type="hidden" name="col" value="priority"/>
    <input type="hidden" name="col" value="component"/>
    -->
    </div></form>
    }}}
  }}}

  == Available Processors

  The following processors are included in the Trac distribution:

  || '''`#!default`''' || Present the text verbatim in a preformatted text block. This is the same as specifying ''no'' processor name (and no `#!`). ||
  || '''`#!comment`''' || Do not process the text in this section, i.e. contents exist only in the plain text - not in the rendered page. ||
  || '''`#!rtl`''' || Introduce a Right-To-Left block with appropriate CSS direction and styling. ''(since 0.12.2)'' ||
  |||| ||
  ||||= '''[=#HTMLrelated HTML related]''' =||
  || '''`#!html`''' || Insert custom HTML in a wiki page. ||
  || '''`#!htmlcomment`''' || Insert an HTML comment in a wiki page. (''since 0.12'') ||
  || || Note that `#!html` blocks have to be ''self-contained'', i.e. you can't start an HTML element in one block and close it later in a second block. Use the following processors for achieving a similar effect.  ||
  || '''`#!div`''' || Wrap wiki content inside a <div> element. ||
  || '''`#!span`''' || Wrap wiki content inside a <span> element. ||
  || '''`#!td`''' || Wrap wiki content inside a <td> element. (''since 0.12'') ||
  || '''`#!th`''' || Wrap wiki content inside a <th> element. (''since 0.12'') ||
  || '''`#!tr`''' || Can optionally be used for wrapping `#!td` and `#!th` blocks, either for specifying row attributes or better visual grouping. (''since 0.12'') ||
  || '''`#!table`''' || Can optionally be used for wrapping `#!tr`, `#!td` and `#!th` blocks, for specifying table attributes. One current limitation however is that tables cannot be nested. (''since 0.12'') ||
  || || See WikiHtml for example usage and more details about these processors. ||
  |||| ||
  ||||= '''Other Markups''' =||
  || '''`#!rst`''' || Trac support for Restructured Text. See WikiRestructuredText. ||
  || '''`#!textile`''' || Supported if [https://pypi.org/project/textile Textile] is installed. See [https://www.booked.net/textism.html a Textile reference]. ||
  |||| ||
  ||||= '''[=#CodeHighlightingSupport Code Highlighting Support]''' =||
  || '''`#!c`''' [[BR]] '''`#!cpp`''' (C++) [[BR]] '''`#!python`''' [[BR]] '''`#!perl`''' [[BR]] '''`#!ruby`''' [[BR]] '''`#!php`''' [[BR]] '''`#!asp`''' [[BR]] '''`#!java`''' [[BR]] '''`#!js`''' (Javascript) [[BR]] '''`#!sql`''' [[BR]] '''`#!xml`''' (XML or HTML) [[BR]] '''`#!sh`''' (!Bourne/Bash shell) [[BR]] || Trac includes processors to provide inline syntax highlighting for source code in various languages. [[BR]] [[BR]] Trac relies on [http://pygments.org Pygments] for syntax coloring. [[BR]] [[BR]] See TracSyntaxColoring for information about which languages are supported and how to enable support for more languages. ||
  |||| ||

  Since 1.1.2 the default, coding highlighting and MIME-type processors support the argument `lineno` for adding line numbering to the code block. When a value is specified, as in `lineno=3`, the numbering will start at the specified value. When used in combination with the `lineno` argument, the `marks` argument is also supported for highlighting lines. A single line number, set of line numbers and range of line numbers are allowed. For example, `marks=3`, `marks=3-6`, `marks=3,5,7` and `marks=3-5,7` are all allowed. The specified values are relative to the numbered lines, so if `lineno=2` is specified to start the line numbering at 2, `marks=2` will result in the first line being highlighted.

  Using the MIME type as processor, it is possible to syntax-highlight the same languages that are supported when browsing source code.

  ||||= '''MIME Type Processors''' =||
  {{{#!tr
  {{{#!td
  Some examples:
   {{{
  {{{#!text/html
  <h1>text</h1>
  }}}
   }}}
  }}}
  {{{#!td
  The result will be syntax highlighted HTML code:
   {{{#!text/html
  <h1>text</h1>
   }}}

  The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime types supported].
  }}}
  }}}
  {{{#!td
   {{{
  {{{#!diff
  --- Version 55
  +++ Version 56
  @@ -115,8 +115,9 @@
       name='TracHelloWorld', version='1.0',
       packages=find_packages(exclude=['*.tests*']),
  -    entry_points = """
  -        [trac.plugins]
  -        helloworld = myplugs.helloworld
  -    """,
  +    entry_points = {
  +        'trac.plugins': [
  +            'helloworld = myplugs.helloworld',
  +        ],
  +    },
   )
  }}}
   }}}
  }}}
  {{{#!td
  '''`#!diff`''' has a particularly nice renderer:
   {{{#!diff
  --- Version 55
  +++ Version 56
  @@ -115,8 +115,9 @@
       name='TracHelloWorld', version='1.0',
       packages=find_packages(exclude=['*.tests*']),
  -    entry_points = """
  -        [trac.plugins]
  -        helloworld = myplugs.helloworld
  -    """,
  +    entry_points = {
  +        'trac.plugins': [
  +            'helloworld = myplugs.helloworld',
  +        ],
  +    },
   )
   }}}
  }}}

  Line numbers can be added to code blocks and lines can be highlighted //(since 1.1.2)//.
  {{{
  {{{#!python lineno=3 marks=3,9-10,16
  def expand_markup(stream, ctxt=None):
      """A Genshi stream filter for expanding `genshi.Markup` events.

      Note: Expansion may not be possible if the fragment is badly
      formed, or partial.
      """
      for event in stream:
          if isinstance(event[1], Markup):
              try:
                  for subevent in HTML(event[1]):
                      yield subevent
              except ParseError:
                  yield event
          else:
              yield event
  }}}
  }}}
  {{{#!python lineno=3 marks=3,9-10,16
  def expand_markup(stream, ctxt=None):
      """A Genshi stream filter for expanding `genshi.Markup` events.

      Note: Expansion may not be possible if the fragment is badly
      formed, or partial.
      """
      for event in stream:
          if isinstance(event[1], Markup):
              try:
                  for subevent in HTML(event[1]):
                      yield subevent
              except ParseError:
                  yield event
          else:
              yield event
  }}}

  For more processor macros developed and/or contributed by users, visit the [https://trac-hacks.org Trac Hacks] community site.

  Processors are implemented using the same interfaces as Wiki macros, only the usage syntax differs. To develop a processor, see WikiMacros#DevelopingCustomMacros.

  ----
  See also: WikiMacros, WikiHtml, WikiRestructuredText, TracSyntaxColoring, WikiFormatting, TracGuide


name: WikiRestructuredText
author: trac
text:
  = reStructuredText Support in Trac

  == Introduction


  Trac supports [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructuredText (RST)] as an alternative to wiki markup where WikiFormatting is used.

  From the reStucturedText webpage:
   "reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains."

  If you want a file from your Subversion repository to be displayed as reStructuredText in the Trac source browser, set `text/x-rst` as the value for the Subversion property `svn:mime-type`, or add the extension `rst` to the filename. See [trac:source:branches/1.4-stable/INSTALL.rst this example].

  The examples will only be rendered as reStructuredText if docutils is installed. If Pygments is installed but docutils is not installed, the examples will be syntax-highlighted rather than rendered as reStructuredText.

  === Requirements

  To activate RST support in Trac, install the python docutils package with the command `easy_install docutils`, or through your operating system package manager. If not already available on your operating system, you can download it from [https://pypi.python.org/pypi/docutils PyPI].

  === More information on RST

   * [http://docutils.sourceforge.net/rst.html reStructuredText Website]
   * [http://docutils.sourceforge.net/docs/rst/quickref.html RST Quick Reference]

  == Using RST in Trac

  To specify that a block of text should be parsed using RST, use the ''rst'' processor.

  === TracLinks in reStructuredText

   * Trac provides a custom RST directive `trac::` to allow TracLinks from within RST text.
     ||= Wiki Markup ||= Display ||
     {{{#!td
       {{{
       {{{#!rst
       This is a reference to |a ticket|

       .. |a ticket| trac:: #42
       }}}
       }}}
     }}}
     {{{#!td
       {{{#!rst
       This is a reference to |a ticket|

       .. |a ticket| trac:: #42
       }}}
     }}}

   * You can also use the custom `:trac:` role to create TracLinks in RST.
     ||= Wiki Markup ||= Display ||
     {{{#!td
       {{{
       {{{#!rst
       This is a reference to ticket `#12`:trac:

       To learn how to use Trac, see `TracGuide`:trac:
       }}}
       }}}
     }}}
     {{{#!td
       {{{#!rst
       This is a reference to ticket `#12`:trac:

       To learn how to use Trac, see `TracGuide`:trac:
       }}}
     }}}

   For a complete example of all uses of the `:trac:` role, see WikiRestructuredTextLinks.

  === Syntax highlighting in reStructuredText

  There is a directive for doing TracSyntaxColoring in RST as well. The directive is called code-block:

  ||= Wiki Markup ||= Display ||
  {{{#!td
    {{{
    {{{#!rst

    .. code-block:: python

       class Test:

           def TestFunction(self):
               pass

    }}}
    }}}
  }}}
  {{{#!td
    {{{#!rst

    .. code-block:: python

       class Test:

           def TestFunction(self):
               pass

    }}}
  }}}
  Note the need to indent the code at least one character after the `.. code-block` directive.

  === Wiki Macros in reStructuredText

  To enable [WikiMacros Wiki Macros] in RST, you use the same `code-block` directive as for syntax highlighting:

  ||= Wiki Markup ||= Display ||
  {{{#!td
    {{{
    {{{#!rst

    .. code-block:: RecentChanges

       Trac,3

    }}}
    }}}
  }}}
  {{{#!td
    {{{#!rst

    .. code-block:: RecentChanges

       Trac,3

    }}}
  }}}

  Or use the `:code-block:` role for a more concise Wiki Macro-like syntax:

  ||= Wiki Markup ||= Display ||
  {{{#!td
    {{{
    {{{
    #!rst

    :code-block:`RecentChanges:Trac,3`
    }}}
    }}}
  }}}
  {{{#!td
    {{{#!rst

    :code-block:`RecentChanges:Trac,3`
    }}}
  }}}

  === Bigger RST Example

  The example below should be self-explanatory:

  ||= Wiki Markup ||= Display ||
  {{{#!td
  {{{#!html
  <pre class="wiki">{{{#!rst
  FooBar Header
  =============
  reStructuredText is **nice**. It has its own webpage_.

  A table:

  =====  =====  ======
     Inputs     Output
  ------------  ------
    A      B    A or B
  =====  =====  ======
  False  False  False
  True   False  True
  False  True   True
  True   True   True
  =====  =====  ======

  RST TracLinks
  -------------

  See also ticket `#42`:trac:.

  .. _webpage: http://docutils.sourceforge.net/rst.html
  }}}</pre>
  }}}
  }}}
  {{{#!td
  {{{#!rst
  FooBar Header
  =============
  reStructuredText is **nice**. It has its own webpage_.

  A table:

  =====  =====  ======
     Inputs     Output
  ------------  ------
    A      B    A or B
  =====  =====  ======
  False  False  False
  True   False  True
  False  True   True
  True   True   True
  =====  =====  ======

  RST TracLinks
  -------------

  See also ticket `#42`:trac:.

  .. _webpage: http://docutils.sourceforge.net/rst.html
  }}}
  }}}

  ----
  See also: WikiRestructuredTextLinks, WikiProcessors, WikiFormatting


name: WikiRestructuredTextLinks
author: trac
text:
  = TracLinks in reStructuredText =
  [[TracGuideToc]]

  This document illustrates how to use the `:trac:` role in [http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html reStructuredText]. The page is written like:

  {{{
  {{{#!rst
  Examples:

   * Tickets: :trac:`#1` or :trac:`ticket:1`
   * Ticket comments: :trac:`comment:ticket:1:2`
   * Reports: :trac:`{1}` or :trac:`report:1`
   * Changesets: :trac:`r1`, :trac:`[1]` or :trac:`changeset:1`
   * Revision log: :trac:`r1:3`, :trac:`[1:3]` or :trac:`log:@1:3`, :trac:`log:trunk@1:3`
   * Diffs: :trac:`diff:@20:30`, :trac:`diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default` or :trac:`diff:trunk/trac@3538//sandbox/vc-refactoring/trac@3539`
   * Wiki pages: :trac:`CamelCase` or :trac:`wiki:CamelCase`
   * Milestones: :trac:`milestone:1.0`
   * Attachment: :trac:`attachment:ticket:944:attachment.1073.diff`
   * Files: :trac:`source:trunk/COPYING`
   * A specific file revision: :trac:`source:/trunk/COPYING@200`
   * A particular line of a specific file revision: :trac:`source:/trunk/COPYING@200#L25`

  An explicit label can be specified, separated from the link by a space:

   * See :trac:`#1 ticket 1` and the :trac:`source:trunk/COPYING license`.
  }}}
  }}}

  Provided you have [http://docutils.sourceforge.net/ docutils] installed, the above block will render as:
  ----
  {{{#!rst
  Examples:

   * Tickets: :trac:`#1` or :trac:`ticket:1`
   * Ticket comments: :trac:`comment:ticket:1:2`
   * Reports: :trac:`{1}` or :trac:`report:1`
   * Changesets: :trac:`r1`, :trac:`[1]` or :trac:`changeset:1`
   * Revision log: :trac:`r1:3`, :trac:`[1:3]` or :trac:`log:@1:3`, :trac:`log:trunk@1:3`
   * Diffs: :trac:`diff:@20:30`, :trac:`diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default` or :trac:`diff:trunk/trac@3538//sandbox/vc-refactoring/trac@3539`
   * Wiki pages: :trac:`CamelCase` or :trac:`wiki:CamelCase`
   * Milestones: :trac:`milestone:1.0`
   * Attachment: :trac:`attachment:ticket:944:attachment.1073.diff`
   * Files: :trac:`source:trunk/COPYING`
   * A specific file revision: :trac:`source:/trunk/COPYING@200`
   * A particular line of a specific file revision: :trac:`source:/trunk/COPYING@200#L25`

  An explicit label can be specified, separated from the link by a space:

   * See :trac:`#1 ticket 1` and the :trac:`source:trunk/COPYING license`.
  }}}
  ----

  Note that the above could have been written using substitution references and the `trac::` directive:
  {{{
  {{{#!rst
  See |ticket123|.

   .. |ticket123| trac:: ticket:123 this ticket
  }}}
  }}}

  This renders as:
  ----

  {{{#!rst
  See |ticket123|.

   .. |ticket123| trac:: ticket:123 this ticket
  }}}

  ----
  See also: WikiRestructuredText, TracLinks


# report

title: Aktive Tickets
description:
  * List all active tickets by priority.
  * Color each row based on priority.

query:
  SELECT p.value AS __color__,
     t.id AS ticket, t.summary, t.component, t.version, t.milestone,
     t.type AS type, t.owner, t.status, t.time AS created,
     t.changetime AS _changetime, t.description AS _description,
     t.reporter AS _reporter
    FROM ticket t
    LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
    WHERE t.status <> 'closed'
    ORDER BY CAST(p.value AS integer), t.milestone, t.type, t.time


title: Meine Tickets
query:
  SELECT p.value AS __color__,
         (CASE
           WHEN t.owner = $USER AND t.status = 'accepted' THEN 'Accepted'
           WHEN t.owner = $USER THEN 'Owned'
           WHEN t.reporter = $USER THEN 'Reported'
           ELSE 'Commented' END) AS __group__,
         t.id AS ticket, t.summary, t.component, t.version, t.milestone,
         t.type AS type, t.priority, t.time AS created,
         t.changetime AS _changetime, t.description AS _description,
         t.reporter AS _reporter
    FROM ticket t
    LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
    WHERE t.status <> 'closed' AND
          (t.owner = $USER OR t.reporter = $USER OR
           EXISTS (SELECT * FROM ticket_change tc
                   WHERE tc.ticket = t.id AND tc.author = $USER AND
                         tc.field = 'comment'))
    ORDER BY (COALESCE(t.owner, '') = $USER AND t.status = 'accepted') DESC,
             COALESCE(t.owner, '') = $USER DESC,
             COALESCE(t.reporter, '') = $USER DESC,
             CAST(p.value AS integer), t.milestone, t.type, t.time

description:
  This report demonstrates the use of the automatically set
  USER dynamic variable, replaced with the username of the
  logged in user when executed.


title: Geschlossene Tickets
query:
  SELECT p.value AS __color__,
         (CASE
           WHEN t.owner = $USER AND t.status = 'accepted' THEN 'Accepted'
           WHEN t.owner = $USER THEN 'Owned'
           WHEN t.reporter = $USER THEN 'Reported'
           ELSE 'Commented' END) AS __group__,
         t.id AS ticket, t.summary, t.component, t.version, t.milestone,
         t.type AS type, t.priority, t.time AS created,
         t.changetime AS _changetime, t.description AS _description,
         t.reporter AS _reporter
    FROM ticket t
    LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
    WHERE t.status = 'closed' AND
          (t.owner = $USER OR t.reporter = $USER OR
           EXISTS (SELECT * FROM ticket_change tc
                   WHERE tc.ticket = t.id AND tc.author = $USER AND
                         tc.field = 'comment'))
    ORDER BY t.changetime DESC,
             CAST(p.value AS integer), t.milestone, t.type, t.time


title: Nächste 7 Tage
query:
  SELECT p.value AS __color__,
         (CASE
           WHEN t.owner = $USER AND t.status = 'accepted' THEN 'Accepted'
           WHEN t.owner = $USER THEN 'Owned'
           WHEN t.reporter = $USER THEN 'Reported'
           ELSE 'Commented' END) AS __group__,
         t.id AS ticket, t.summary, t.component, t.version, t.milestone,
         t.type AS type, t.priority, t.time AS created,
         t.changetime AS _changetime, t.description AS _description,
         t.reporter AS _reporter,
         tc.value AS due
  FROM ticket t
  LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
  LEFT JOIN ticket_custom tc ON tc.ticket = t.id AND tc.name = 'due'
  WHERE t.status <> 'closed'
    AND tc.value >= DATE('now')
    AND tc.value <= DATE('now', '+7 days')
  ORDER BY tc.value ASC, CAST(p.value AS integer), t.milestone, t.type, t.time


title: Nächste 3 Tage
query:
  SELECT p.value AS __color__,
         (CASE
           WHEN t.owner = $USER AND t.status = 'accepted' THEN 'Accepted'
           WHEN t.owner = $USER THEN 'Owned'
           WHEN t.reporter = $USER THEN 'Reported'
           ELSE 'Commented' END) AS __group__,
         t.id AS ticket, t.summary, t.component, t.version, t.milestone,
         t.type AS type, t.priority, t.time AS created,
         t.changetime AS _changetime, t.description AS _description,
         t.reporter AS _reporter,
         tc.value AS due
  FROM ticket t
  LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
  LEFT JOIN ticket_custom tc ON tc.ticket = t.id AND tc.name = 'due'
  WHERE t.status <> 'closed'
    AND tc.value >= DATE('now')
    AND tc.value <= DATE('now', '+3 days')
  ORDER BY tc.value ASC, CAST(p.value AS integer), t.milestone, t.type, t.time


title: Nächste 14 Tage
query:
  SELECT p.value AS __color__,
         (CASE
           WHEN t.owner = $USER AND t.status = 'accepted' THEN 'Accepted'
           WHEN t.owner = $USER THEN 'Owned'
           WHEN t.reporter = $USER THEN 'Reported'
           ELSE 'Commented' END) AS __group__,
         t.id AS ticket, t.summary, t.component, t.version, t.milestone,
         t.type AS type, t.priority, t.time AS created,
         t.changetime AS _changetime, t.description AS _description,
         t.reporter AS _reporter,
         tc.value AS due
  FROM ticket t
  LEFT JOIN enum p ON p.name = t.priority AND p.type = 'priority'
  LEFT JOIN ticket_custom tc ON tc.ticket = t.id AND tc.name = 'due'
  WHERE t.status <> 'closed'
    AND tc.value >= DATE('now')
    AND tc.value <= DATE('now', '+14 days')
  ORDER BY tc.value ASC, CAST(p.value AS integer), t.milestone, t.type, t.time


